Plugin-API-Referenz

Das Plugin-System erlaubt es dir, pubm zu erweitern, ohne die Kern-Publish-Pipeline zu forken.

PubmPlugin

export interface PubmPlugin {
  name: string;
  registries?: PackageRegistry[];
  ecosystems?: Ecosystem[];
  hooks?: PluginHooks;
  commands?: PluginCommand[];
  credentials?: (ctx: PubmContext) => PluginCredential[];
  checks?: (ctx: PubmContext) => PluginCheck[];
}

• credentials - gibt die Liste der Tokens zurück, die dieses Plugin benötigt. pubm ruft das beim Initialisieren einmal auf, fragt fehlende Tokens ab, injiziert sie in die Umgebung und synchronisiert sie bei --ci-prepare mit GitHub Secrets.
• checks - gibt Preflight-Checks zurück, die zusammen mit den Kernphasen für Voraussetzungen und Bedingungen laufen. Jeder Check legt über sein Feld phase fest, wann er ausgeführt wird.

Hooks

export interface PluginHooks {
  // Lifecycle-Hooks
  beforeTest?: HookFn;
  afterTest?: HookFn;
  beforeBuild?: HookFn;
  afterBuild?: HookFn;
  beforeVersion?: HookFn;
  afterVersion?: HookFn;
  beforePublish?: HookFn;
  afterPublish?: HookFn;
  beforePush?: HookFn;
  afterPush?: HookFn;
  afterRelease?: AfterReleaseHookFn;
  onError?: ErrorHookFn;
  onSuccess?: HookFn;

  // Asset-Pipeline-Hooks
  resolveAssets?: AssetPipelineHooks["resolveAssets"];
  transformAsset?: AssetPipelineHooks["transformAsset"];
  compressAsset?: AssetPipelineHooks["compressAsset"];
  nameAsset?: AssetPipelineHooks["nameAsset"];
  generateChecksums?: AssetPipelineHooks["generateChecksums"];
  uploadAssets?: AssetPipelineHooks["uploadAssets"];
}

Asset-Pipeline-Hooks

Sechs Hooks erlauben es Plugins, jede Stufe der Release-Asset-Pipeline abzufangen. Sie laufen zwischen dem Build-Schritt und dem Upload in den GitHub Release.

Hook	Wann er laeuft	Input -> Output
resolveAssets	Nach dem Glob-Matching	ResolvedAsset[] -> ResolvedAsset[]
transformAsset	Pro Asset, vor der Komprimierung	ResolvedAsset -> TransformedAsset | TransformedAsset[]
compressAsset	Pro Asset, ersetzt die eingebaute Komprimierung	TransformedAsset -> CompressedAsset
nameAsset	Pro Asset, nach der Komprimierung	CompressedAsset -> string
generateChecksums	Nachdem alle Assets benannt und gehasht wurden	PreparedAsset[] -> PreparedAsset[]
uploadAssets	Nach dem GitHub-Release-Upload	PreparedAsset[] -> UploadedAsset[]

Wenn mehrere Plugins denselben Asset-Pipeline-Hook registrieren, werden sie in Registrierungsreihenfolge verkettet. uploadAssets ist die Ausnahme: Jedes Plugin erhält dieselbe Eingabe unabhängig, und alle Ergebnisse werden zusammengefuehrt.

Lies Asset Pipeline Hooks für vollständige Signaturen, Beispiele und Kompositionsregeln.

Hook-Signaturen

type HookFn = (ctx: PubmContext) => Promise<void> | void;
type ErrorHookFn = (ctx: PubmContext, error: Error) => Promise<void> | void;
type AfterReleaseHookFn = (
  ctx: PubmContext,
  releaseCtx: ReleaseContext,
) => Promise<void> | void;

PubmContext

Hooks erhalten den aktuellen Pipeline-Kontext:

export interface PubmContext {
  readonly config: ResolvedPubmConfig;
  readonly options: ResolvedOptions;
  readonly cwd: string;
  runtime: {
    tag: string;
    promptEnabled: boolean;
    cleanWorkingTree: boolean;
    pluginRunner: PluginRunner;
    versionPlan?: VersionPlan;
    releaseContext?: ReleaseContext;
    tempDir?: string;
    pluginTokens?: Record<string, string>;
  };
}

Wichtige Felder:

• ctx.config - aufgeloeste pubm-Config (Pakete, Registries, Plugins, releaseAssets usw.)
• ctx.options - aufgeloeste CLI-Optionen (Version, Tag, Mode, dryRun usw.)
• ctx.cwd - Arbeitsverzeichnis
• ctx.runtime - veraenderbarer Runtime-Zustand (Version-Plan, temporäres Verzeichnis usw.)
• ctx.runtime.pluginTokens - Map der aufgeloesten Plugin-Credentials, indiziert über PluginCredential.key. Wird nach dem Sammeln der Credentials befüllt und steht danach in allen Hooks zur Verfügung.

Rollback-API

Plugins koennen Rollback-Aktionen registrieren, die automatisch ausgefuehrt werden, wenn die Publish-Pipeline fehlschlaegt. Die Aktionen werden in LIFO-Reihenfolge (Last-in, First-out) ausgefuehrt.

Registriere Rollback-Aktionen mit ctx.runtime.rollback.add() in jedem Hook:

hooks: {
  afterVersion: async (ctx) => {
    // Perform side effect
    const backup = readFileSync(filePath, "utf-8");
    modifyFile(filePath);

    // Register rollback to undo it
    ctx.runtime.rollback.add({
      label: `Restore ${filePath}`,
      fn: async () => {
        writeFileSync(filePath, backup, "utf-8");
      },
    });
  },
}

RollbackAction

Eigenschaft	Typ	Beschreibung
label	string	Menschlich lesbare Beschreibung, die waehrend des Rollbacks angezeigt wird
fn	(ctx: PubmContext) => Promise<void>	Asynchrone Funktion, die den Seiteneffekt rueckgaengig macht
confirm	boolean?	Wenn true, wird im TTY-Modus vor der Ausfuehrung eine Bestaetigung angefordert. In CI wird automatisch ausgefuehrt.

PluginCredential

Deklarativer Deskriptor für ein Token oder Secret, das ein Plugin benötigt.

export interface PluginCredential {
  key: string;
  env: string;
  label: string;
  tokenUrl?: string;
  tokenUrlLabel?: string;
  ghSecretName?: string;
  required?: boolean;
  resolve?: () => Promise<string | null>;
  validate?: (token: string, task: PluginTaskContext) => Promise<boolean>;
}

Feld	Typ	Beschreibung
key	string	Interner Bezeichner, über den der Wert in ctx.runtime.pluginTokens nachgeschlagen wird.
env	string	Name der Umgebungsvariable, die das Token in CI bereitstellt.
label	string	Menschlich lesbares Label für interaktive Prompts.
tokenUrl	string	Optionale URL, unter der Benutzer das Token erstellen können.
tokenUrlLabel	string	Optionales Anzeigelabel für tokenUrl.
ghSecretName	string	Name des GitHub Secrets, das dieses Token bei --ci-prepare erhalten soll.
required	boolean	Wenn true, meldet pubm einen Fehler, falls das Credential nicht aufgeloest werden kann. Standard ist true.
resolve	function	Optionaler eigener Resolver ohne Argumente, der Promise<string | null> zurückgibt. Wird vor Keyring/Prompt-Fallback aufgerufen.
validate	function	Optionaler Token-Validator. Erhält das aufgeloeste Token und einen PluginTaskContext; gibt false zurück, um erneut zu fragen.

Aufloesungsreihenfolge: env-Umgebungsvariable -> resolve() -> Keyring (SecureStore) -> interaktiver Prompt.

PluginCheck

Deskriptor für einen Preflight-Check, den ein Plugin beiträgt.

export interface PluginCheck {
  title: string;
  phase: "prerequisites" | "conditions";
  task: (ctx: PubmContext, task: PluginTaskContext) => Promise<void> | void;
}

Feld	Typ	Beschreibung
title	string	Beschriftung in der Aufgabenliste.
phase	"prerequisites" | "conditions"	Zeitpunkt der Ausführung: "prerequisites" läuft vor Netzwerkanfragen, "conditions" nach bestätigter Registry-Konnektivität.
task	function	Implementierung des Checks. Wirf einen Fehler, um den Check fehlschlagen zu lassen.

PluginTaskContext

Ein listr2-unabhaengiger Wrapper, der als zweites Argument an PluginCheck.task übergeben wird.

export interface PluginTaskContext {
  output: string;
  title: string;
  prompt<T = unknown>(options: {
    type: string;
    message: string;
    [key: string]: unknown;
  }): Promise<T>;
}

• output - zeigt eine Statuszeile unterhalb des Check-Titels in der Aufgabenliste an.
• title - aendert den Aufgabentitel dynamisch.
• prompt() - fuehrt einen enquirer-Prompt aus. Verfügbar im interaktiven Modus.

Beispiel

const notifyPlugin = {
  name: "notify-plugin",
  hooks: {
    async afterPublish(ctx) {
      const label =
        ctx.versions && ctx.versions.size > 0
          ? [...ctx.versions].map(([name, version]) => `${name}@${version}`).join(", ")
          : `v${ctx.version}`;

      console.log(`Published ${label}`);
    },
  },
};

Benutzerdefinierte Befehle

export interface PluginCommand {
  name: string;
  description: string;
  subcommands?: PluginSubcommand[];
}

export interface PluginSubcommand {
  name: string;
  description: string;
  options?: PluginCommandOption[];
  action: (args: Record<string, unknown>) => Promise<void>;
}

Benutzerdefinierte Registries und Ecosystems

Verwende benutzerdefinierte Registries, wenn du ein weiteres Publish-Ziel brauchst. Verwende benutzerdefinierte Ecosystems, wenn du pubm beibringen willst, wie Versionsdaten für einen anderen Pakettyp gelesen und geschrieben werden.

Verwandte Doku

• Konfiguration
• Coding Agent Integration
• Offizielle Plugins