Référence de l'API des plugins

Le système de plugins vous permet d’étendre pubm sans forker le pipeline de publication central.

PubmPlugin

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

• credentials - renvoie la liste des tokens dont ce plugin a besoin. pubm l’appelle une fois à l’initialisation pour demander les tokens manquants, les injecter dans l’environnement et les synchroniser vers GitHub Secrets lors d’un --ci-prepare.
• checks - renvoie des checks de preflight exécutés avec les phases principales de prérequis et de conditions. Chaque check déclare son moment d’exécution via son champ phase.

Hooks

export interface PluginHooks {
  // Hooks de cycle de vie
  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;

  // Hooks du pipeline d'artefacts
  resolveAssets?: AssetPipelineHooks["resolveAssets"];
  transformAsset?: AssetPipelineHooks["transformAsset"];
  compressAsset?: AssetPipelineHooks["compressAsset"];
  nameAsset?: AssetPipelineHooks["nameAsset"];
  generateChecksums?: AssetPipelineHooks["generateChecksums"];
  uploadAssets?: AssetPipelineHooks["uploadAssets"];
}

Hooks du pipeline d’artefacts

Six hooks permettent aux plugins d’intercepter chaque étape du pipeline d’artefacts de release. Ils s’exécutent entre l’étape de build et l’upload vers GitHub Release.

Hook	Quand il s’exécute	Entrée → Sortie
resolveAssets	Après la correspondance glob	ResolvedAsset[] → ResolvedAsset[]
transformAsset	Par artefact, avant la compression	ResolvedAsset → TransformedAsset | TransformedAsset[]
compressAsset	Par artefact, remplace la compression intégrée	TransformedAsset → CompressedAsset
nameAsset	Par artefact, après la compression	CompressedAsset → string
generateChecksums	Après que tous les artefacts ont été nommés et hachés	PreparedAsset[] → PreparedAsset[]
uploadAssets	Après l’upload vers GitHub Release	PreparedAsset[] → UploadedAsset[]

Lorsque plusieurs plugins enregistrent le même hook du pipeline d’artefacts, ils sont chaînés dans l’ordre d’enregistrement. uploadAssets est une exception : chaque plugin reçoit la même entrée indépendamment et tous les résultats sont concaténés.

Lisez Hooks du pipeline d’artefacts pour les signatures complètes, les exemples et les règles de composition.

Signatures des hooks

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

Les hooks reçoivent le contexte courant du pipeline :

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>;
  };
}

Champs clés :

• ctx.config - config pubm résolue (packages, registries, plugins, releaseAssets, etc.)
• ctx.options - options CLI résolues (version, tag, mode, dryRun, etc.)
• ctx.cwd - répertoire de travail
• ctx.runtime - état runtime mutable (plan de version, répertoire temporaire, etc.)
• ctx.runtime.pluginTokens - map des valeurs de credentials de plugin résolues, indexée par PluginCredential.key. Elle est remplie après l’étape de collecte des credentials et reste disponible dans tous les hooks suivants.

API de rollback

Les plugins peuvent enregistrer des actions de rollback qui s’exécutent automatiquement lorsque le pipeline de publication échoue. Les actions sont exécutées dans l’ordre LIFO (dernier entré, premier sorti).

Enregistrez des actions de rollback avec ctx.runtime.rollback.add() dans n’importe quel 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

Propriété	Type	Description
label	string	Description lisible affichée pendant le rollback
fn	(ctx: PubmContext) => Promise<void>	Fonction asynchrone qui annule l’effet de bord
confirm	boolean?	Si true, demande une confirmation en mode TTY avant l’exécution. S’exécute automatiquement en CI.

PluginCredential

Descripteur déclaratif pour un token ou secret dont un plugin a besoin.

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>;
}

Champ	Type	Description
key	string	Identifiant interne utilisé pour retrouver la valeur dans ctx.runtime.pluginTokens.
env	string	Nom de la variable d’environnement qui fournit le token en CI.
label	string	Libellé lisible affiché dans les invites interactives.
tokenUrl	string	URL optionnelle où l’utilisateur peut créer le token.
tokenUrlLabel	string	Libellé d’affichage optionnel pour tokenUrl.
ghSecretName	string	Nom du GitHub Secret qui doit contenir ce token lors de la synchro --ci-prepare.
required	boolean	Quand la valeur est true, pubm échoue si le credential ne peut pas être résolu. La valeur par défaut est true.
resolve	function	Resolver personnalisé optionnel sans argument, qui retourne Promise<string | null>. Appelé avant le fallback keyring/prompt.
validate	function	Validateur optionnel du token. Reçoit le token résolu et un PluginTaskContext; retourne false pour redemander la valeur.

Ordre de résolution : variable d’environnement env -> resolve() -> keyring (SecureStore) -> invite interactive.

PluginCheck

Descripteur d’un check de preflight apporté par un plugin.

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

Champ	Type	Description
title	string	Libellé affiché dans l’interface de liste de tâches.
phase	"prerequisites" | "conditions"	Moment d’exécution : "prerequisites" s’exécute avant les appels réseau ; "conditions" après validation de la connectivité au registry.
task	function	Implémentation du check. Lancez une erreur pour le faire échouer.

PluginTaskContext

Wrapper agnostique à listr2 passé en second argument à PluginCheck.task.

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

• output - affiche une ligne d’état sous le titre du check dans l’interface de tâches.
• title - modifie dynamiquement le titre de la tâche.
• prompt() - lance une invite enquirer. Disponible uniquement en mode interactif.

Exemple

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(`Publié ${label}`);
    },
  },
};

Commandes personnalisées

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>;
}

Registries et écosystèmes personnalisés

Utilisez des registries personnalisés lorsque vous avez besoin d’une autre destination de publication. Utilisez des écosystèmes personnalisés lorsque vous devez apprendre à pubm comment lire et écrire les versions pour un autre type de package.

Documents liés

• Configuration
• Intégration des agents de code
• Plugins officiels