Core-SDK-Referenz

@pubm/core ist die programmatische API hinter der pubm-CLI. Diese Seite deckt die oeffentlichen Identifikatoren ab, die aus dem Paket-Root exportiert werden:

import { ... } from "@pubm/core";

Das Paket liefert Typdeklarationen sowie ESM- und CJS-Entry-Points. In den aktuellen Paketmetadaten ist node >= 24 festgelegt.

Installation

npm install @pubm/core
pnpm add @pubm/core
bun add @pubm/core

Release-Pipeline

pubm(options)

Fuehrt dieselbe Release-Pipeline aus, die auch die CLI antreibt.

import { pubm } from "@pubm/core";

await pubm({
  version: "patch",
  dryRun: true,
  tag: "next",
});

pubm() erwartet ein Options-Objekt. Die wichtigsten Felder sind:

Feld	Typ	Zweck
version	string	Erforderliches Release-Ziel wie patch, minor, major oder eine explizite SemVer.
dryRun	boolean	Zeigt den Task-Plan an, ohne Git-Zustand zu ändern oder zu veröffentlichen.
mode	"local" | "ci"	Ausführungsmodus: local (interaktiv) oder ci (nicht interaktiv, tag-basiert).
prepare	boolean	Fuehrt nur die Vorbereitungsphase aus (Validierung und Publish-Checks im Dry-Run).
publish	boolean	Fuehrt nur die Publish-Phase aus (Veröffentlichung vom neuesten Tag).
releaseDraft	boolean	Erstellt einen Draft-GitHub-Release statt eines veröffentlichten Releases.
branch	string	Verlangt einen bestimmten Branch vor dem Veröffentlichen.
anyBranch	boolean	Deaktiviert die Branch-Prüfung für einen Lauf.
tag	string	Veröffentlicht unter einem Dist-Tag wie latest, next oder beta.
packages	PackageConfig[]	Überschreibt automatisch gefundene Pakete.

Für Config-getriebene Releases laedt pubm() automatisch pubm.config.*, loest die Paket-Erkennung auf und verbindet die Plugins, bevor der Task-Graph ausgeführt wird.

Config-Helfer

Diese Helfer sind die wichtigsten Einstiegsstellen für Code, der pubm.config.* lesen oder validieren will.

Export	Art	Zweck
defineConfig	function	Typisierter Helfer zum Schreiben von pubm.config.ts.
loadConfig	function	Laedt pubm.config.* von der Festplatte und gibt PubmConfig | null zurück.
resolveConfig	function	Wendet Standardwerte an, entdeckt Pakete automatisch und normalisiert private Registries.
PubmConfig	type	Form der vom Benutzer geschriebenen Config.
ResolvedPubmConfig	type	Vollstaendig aufgeloeste Config, die resolveConfig() zurückgibt.
PackageConfig	type	Paketbezogener Config-Eintrag für Discovery und Publish-Planung.

import { defineConfig, loadConfig, resolveConfig } from "@pubm/core";

export default defineConfig({
  packages: [{ path: "packages/core" }],
});

const config = await loadConfig(process.cwd());
const resolved = config ? await resolveConfig(config, process.cwd()) : null;

PackageConfig ist der Ort, an dem du pro Paket Registries, Ecosystem, Build-Command oder Test-Command überschreiben kannst:

type PackageConfig = {
  path: string;
  registries?: Array<"npm" | "jsr" | "crates" | string | PrivateRegistryConfig>;
  ecosystem?: "js" | "rust";
  buildCommand?: string;
  testCommand?: string;
};

Plugin-API

Nutze die Plugin-Exports, wenn du die Publish-Pipeline um benutzerdefinierte Registries, Ecosystems, Lifecycle-Hooks oder CLI-Befehle erweitern willst.

Export	Art	Zweck
PubmPlugin	type	Oberster Plugin-Vertrag.
PluginHooks	type	Lifecycle-Hooks wie beforeBuild, afterPublish, onError, afterRelease und Asset-Pipeline-Hooks.
HookFn / ErrorHookFn / AfterReleaseHookFn	type	Hook-Signaturen.
PluginCommand / PluginSubcommand / PluginCommandOption	type	Modell für benutzerdefinierte CLI-Befehle von Plugins.
PluginRunner	class	Hilfsklasse, die Hooks ausführt und Registries/Ecosystems aus geladenen Plugins sammelt. Stellt außerdem collectCredentials() und collectChecks() bereit, um Credential-Deskriptoren und Preflight-Checks aus allen registrierten Plugins zu sammeln.
PluginCredential	type	Deklarativer Deskriptor für ein Token oder Secret, das ein Plugin benötigt. Siehe Plugin-API-Referenz.
PluginCheck	type	Deskriptor für einen Preflight-Check, den ein Plugin beiträgt. Siehe Plugin-API-Referenz.
PluginTaskContext	type	listr2-unabhaengiger Wrapper für PluginCheck.task. Stellt output, title und prompt() bereit.
GhSecretEntry	type	Ein Eintrag aus den GitHub-Secret-Sync-Helfern: { secretName: string; token: string }.
collectPluginCredentials	function	Sammelt PluginCredential[] aus allen in der Config registrierten Plugins und löst ihre Werte auf.
injectPluginTokensToEnv	function	Schreibt aufgeloeste Plugin-Tokenwerte in process.env, damit spaetere Publish-Schritte sie wie normale Umgebungsvariablen lesen können.
ReleaseContext	type	Release-Metadaten für afterRelease-Hooks. Enthält packageName, version, tag, releaseUrl und assets.
ReleaseAsset	type	Ein hochgeladenes Asset: name, url, sha256 und strukturiertes platform.
ParsedPlatform	type	Strukturierte Plattforminfo: raw, os, arch, vendor, abi, variant.
PreparedAsset	type	Asset nach Komprimierung und Hashing, bereit für den Upload.
TransformedAsset	type	Asset nach dem transformAsset-Hook, vor der Komprimierung.
CompressedAsset	type	Asset nach dem compressAsset-Schritt, vor der Benennung.
UploadedAsset	type	Asset nach dem Upload mit url und target.
ResolvedAsset	type	Asset nach dem Glob-Matching mit geparsten Plattforminformationen.

import { defineConfig, type PubmPlugin } from "@pubm/core";

const plugin: PubmPlugin = {
  name: "announce",
  hooks: {
    afterPublish(ctx) {
      console.log("published", ctx.version);
    },
  },
};

export default defineConfig({
  plugins: [plugin],
});

Asset-Pipeline

Diese Exporte treiben die Release-Asset-Pipeline an und sind für Plugin-Autoren und eigenes Tooling nuetzlich.

Export	Art	Zweck
parsePlatform	function	Analysiert OS, Architektur, ABI, Variante und Vendor aus einem Pfadsegment-String anhand der eingebauten Tabellen.
runAssetPipeline	function	Fuehrt die komplette Asset-Pipeline (resolve, transform, compress, name, hash, checksums) für eine aufgeloeste Config und ein Hook-Set aus.

import { parsePlatform, runAssetPipeline } from "@pubm/core";

// Einen Pfadsegment- oder Capture-String parsen
const platform = parsePlatform("darwin-arm64");
// { raw: "darwin-arm64", os: "darwin", arch: "arm64" }

const platform2 = parsePlatform("x86_64-unknown-linux-gnu");
// { raw: "x86_64-unknown-linux-gnu", os: "linux", arch: "x64", vendor: "unknown", abi: "gnu" }

Asset-Pipeline-Typen:

import type {
  ParsedPlatform,
  ReleaseContext,
  ReleaseAsset,
  ResolvedAsset,
  TransformedAsset,
  CompressedAsset,
  PreparedAsset,
  UploadedAsset,
} from "@pubm/core";

Siehe Release Assets und Asset Pipeline Hooks für die Anwendungsleitfaeden.

Changeset- und Versionshelfer

Die Changeset-Exports helfen dir, eigenes Tooling rund um .pubm/changesets zu bauen.

Export	Art	Zweck
readChangesets / parseChangeset	functions	.pubm/changesets/*.md lesen und parsen.
getStatus	function	Ausstehende Changesets pro Paket zusammenfassen.
discoverCurrentVersions / discoverPackageInfos	functions	Aktuelle Paketnamen und -versionen aus dem Workspace lesen.
calculateVersionBumps	function	Naechste Versionen aus aktuellen Versionen plus ausstehenden Changesets berechnen.
generateChangesetId / generateChangesetContent / writeChangeset	functions	Neue Changeset-Dateien erzeugen.
buildChangelogEntries / generateChangelog / writeChangelogToFile	functions	Changelog-Ausgabe aus Changesets erzeugen.
migrateFromChangesets	function	Alte .changeset/-Daten nach .pubm/ kopieren.
deleteChangesetFiles	function	Verbrauchte Changeset-Dateien entfernen.
parseChangelogSection	function	Einen Changelog-Abschnitt wieder in strukturierte Daten parsen.

Wichtige zugehörige Typen:

Typ	Zweck
Changeset	Geparste .md-Datei mit id, summary und Paket-Release-Eintraegen.
Release	Ein Paket-Sprung-Eintrag innerhalb eines Changesets.
BumpType	"patch" | "minor" | "major".
Status / PackageStatus	Aggregierter ausstehender Status aus getStatus().
VersionBump	Ergebnis der Versionsplanung aus calculateVersionBumps().
ChangelogEntry / DependencyUpdate	Eingaben für das Rendern des Changelogs.
PackageVersionInfo	Paketname, Version und Pfad, die von Discovery-Helfern zurückgegeben werden.
MigrationResult	Ergebnisobjekt von migrateFromChangesets().

import {
  calculateVersionBumps,
  discoverCurrentVersions,
  getStatus,
} from "@pubm/core";

const currentVersions = await discoverCurrentVersions(process.cwd());
const status = getStatus(process.cwd());
const nextVersions = calculateVersionBumps(currentVersions, process.cwd());

Monorepo- und Workspace-Helfer

Diese Exporte sind nuetzlich, wenn du dieselbe Workspace-Erkennung brauchst, die pubm intern verwendet.

Export	Art	Zweck
detectWorkspace	function	Erkennt pnpm-, npm-, Yarn-, Bun-, Cargo- oder Deno-Workspaces aus Repository-Dateien.
discoverPackages	function	Findet publishbare Pakete automatisch und leitet Registries/Ecosystems ab.
buildDependencyGraph	function	Baut einen internen Abhängigkeitsgraphen aus Paketmetadaten.
topologicalSort	function	Sortiert Graphknoten so, dass Abhängigkeiten zuerst kommen.
resolveGroups	function	Loest fixed/linked-Gruppen gegen eine gefundene Paketliste auf.
applyFixedGroup / applyLinkedGroup	functions	Wendet Gruppensemantik auf die Versionsplanung an.
Git	class	Schlanke Huelle um Git-Befehle, die für Release-Automatisierung genutzt werden.

Wichtige zugehörige Typen:

Typ	Zweck
WorkspaceInfo	Workspace-Typ plus Include-/Exclude-Muster.
DiscoverOptions	Eingabe für discoverPackages().
DiscoveredPackage	Automatisch erkanntes Paket mit Pfad, Registries und Ecosystem.
PackageNode	Eingabeknoten für den Aufbau des Abhängigkeitsgraphen.

import {
  buildDependencyGraph,
  discoverPackages,
  topologicalSort,
} from "@pubm/core";

const discovered = await discoverPackages({ cwd: process.cwd() });

const graph = buildDependencyGraph([
  {
    name: "@acme/core",
    version: "1.0.0",
    path: "packages/core",
    dependencies: { "@acme/utils": "^1.0.0" },
  },
  {
    name: "@acme/utils",
    version: "1.0.0",
    path: "packages/utils",
    dependencies: {},
  },
]);

const ordered = topologicalSort(graph);

Validierungs- und Utility-Helfer

Das Paket-Root exportiert außerdem die folgenden Helfer für Tooling-Integrationen.

Export	Art	Zweck
validateEntryPoints	function	Prüft main, module, types, exports und bin-Pfade in einem Paket-Manifest.
detectExtraneousFiles	function	Markiert Dateien, die normalerweise nicht in Publish-Artefakten landen sollten.
getPackageJson	function	Liest das nächste package.json, optional mit jsr.json-Fallback.
replaceVersion / replaceVersionAtPath	functions	Schreibt Paketversionen in Manifests um.
version	function	Liest die aktuelle Paketversion aus package.json, jsr.json oder deno.json / deno.jsonc.
generateSnapshotVersion	function	Baut Snapshot-Versionen aus base, tag, timestamp und optional commit.
loadTokensFromDb	function	Laedt gespeicherte Registry-Tokens und beachtet passende Umgebungsvariablen.
syncGhSecrets	function	Schiebt Registry-Tokens über gh secret set in GitHub Secrets.
exec	function	Startet einen Subprozess und faengt stdout/stderr ab.
getPackageManager	function	Erkennt den Workspace-Paketmanager anhand der Lockfiles.
detectRuntime / isBun	functions	Erkennt die aktuelle Runtime.
notifyNewVersion	function	Prüft, ob es eine neuere veröffentlichte pubm-Version gibt, und gibt ein Update-Banner aus.
consoleError	function	Formatiert und gibt pubm-Fehler aus.
PUBM_VERSION / PUBM_ENGINES	constants	Paketmetadaten, die zur Laufzeit verfügbar sind.

Wichtige zugehörige Typen:

Typ	Zweck
EntryPointError	Eintrag für Validierungsergebnisse bei defekten Manifest-Pfaden.
ExtraneousFile	Eintrag für Validierungsergebnisse bei Dateien, die nicht veröffentlicht werden sollten.
SnapshotOptions	Eingabe für generateSnapshotVersion().
Runtime	"node" | "bun".

import {
  generateSnapshotVersion,
  loadTokensFromDb,
  validateEntryPoints,
} from "@pubm/core";

const nextSnapshot = generateSnapshotVersion({
  baseVersion: "1.4.0",
  tag: "snapshot",
  commit: "abc1234",
  template: "{base}-{tag}-{timestamp}-{commit}",
});

const entryPointErrors = validateEntryPoints(
  {
    main: "./dist/index.js",
    types: "./dist/index.d.ts",
  },
  process.cwd(),
);

const tokens = loadTokensFromDb(["npm", "jsr"]);

Export-Richtlinie

Diese Seite dokumentiert die stabile Oberflaeche, die heute aus dem Paket-Root exportiert wird. Interne Dateien unter packages/core/src/** koennen vorhanden sein, aber wenn sie nicht aus @pubm/core erneut exportiert werden, solltest du sie als private Implementierungsdetails behandeln.