Referencia de la API de plugins

El sistema de plugins te permite ampliar pubm sin bifurcar el pipeline principal de publicación.

PubmPlugin

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

• credentials - devuelve la lista de tokens que este plugin necesita. pubm la llama una vez durante la inicialización para pedir los tokens faltantes, inyectarlos en el entorno y sincronizarlos con GitHub Secrets cuando se ejecuta --ci-prepare.
• checks - devuelve checks de preflight que se ejecutan junto con las fases principales de prerrequisitos y condiciones. Cada check declara cuándo debe ejecutarse mediante su campo phase.

Hooks

export interface PluginHooks {
  // Hooks de ciclo de vida
  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 del asset pipeline
  resolveAssets?: AssetPipelineHooks["resolveAssets"];
  transformAsset?: AssetPipelineHooks["transformAsset"];
  compressAsset?: AssetPipelineHooks["compressAsset"];
  nameAsset?: AssetPipelineHooks["nameAsset"];
  generateChecksums?: AssetPipelineHooks["generateChecksums"];
  uploadAssets?: AssetPipelineHooks["uploadAssets"];
}

Hooks del asset pipeline

Seis hooks permiten a los plugins interceptar cada etapa del asset pipeline de releases. Se ejecutan entre el build step y la subida al GitHub Release.

Hook	Cuándo se ejecuta	Entrada → Salida
resolveAssets	Después del glob matching	ResolvedAsset[] → ResolvedAsset[]
transformAsset	Por asset, antes de la compresión	ResolvedAsset → TransformedAsset | TransformedAsset[]
compressAsset	Por asset, sustituye la compresión integrada	TransformedAsset → CompressedAsset
nameAsset	Por asset, después de la compresión	CompressedAsset → string
generateChecksums	Después de que todos los assets estén nombrados y con hash	PreparedAsset[] → PreparedAsset[]
uploadAssets	Después de subir al GitHub Release	PreparedAsset[] → UploadedAsset[]

Cuando varios plugins registran el mismo hook del asset pipeline, se encadenan en el orden de registro. uploadAssets es la excepción: cada plugin recibe la misma entrada de forma independiente y todos los resultados se concatenan.

Lee Asset Pipeline Hooks para ver firmas completas, ejemplos y reglas de composición.

Firmas de 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

Los hooks reciben el contexto actual del 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>;
  };
}

Campos clave:

• ctx.config - configuración de pubm resuelta (packages, registries, plugins, releaseAssets, etc.)
• ctx.options - opciones de CLI resueltas (version, tag, mode, dryRun, etc.)
• ctx.cwd - directorio de trabajo
• ctx.runtime - estado mutable en runtime (version plan, temp directory, etc.)
• ctx.runtime.pluginTokens - mapa de valores de credenciales de plugin resueltas, indexado por PluginCredential.key. Se rellena después del paso de recolección de credenciales y queda disponible en todos los hooks posteriores.

API de rollback

Los plugins pueden registrar acciones de rollback que se ejecutan automaticamente cuando el pipeline de publicacion falla. Las acciones se ejecutan en orden LIFO (ultimo en entrar, primero en salir).

Registra acciones de rollback usando ctx.runtime.rollback.add() dentro de cualquier 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

Propiedad	Tipo	Descripcion
label	string	Descripcion legible que se muestra durante el rollback
fn	(ctx: PubmContext) => Promise<void>	Funcion asincrona que revierte el efecto secundario
confirm	boolean?	Si es true, solicita confirmacion en modo TTY antes de ejecutar. Se ejecuta automaticamente en CI.

PluginCredential

Descriptor declarativo para un token o secret que un plugin necesita.

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

Campo	Tipo	Descripción
key	string	Identificador interno usado para buscar el valor en ctx.runtime.pluginTokens.
env	string	Nombre de la variable de entorno que aporta el token en CI.
label	string	Etiqueta legible que se muestra en los prompts interactivos.
tokenUrl	string	URL opcional donde el usuario puede crear el token.
tokenUrlLabel	string	Etiqueta opcional para mostrar tokenUrl.
ghSecretName	string	Nombre del GitHub Secret que debe almacenar este token durante la sincronización con --ci-prepare.
required	boolean	Cuando es true, pubm falla si no puede resolver la credencial. El valor por defecto es true.
resolve	function	Resolver personalizado opcional sin argumentos que devuelve Promise<string | null>. Se llama antes del fallback a keyring/prompt.
validate	function	Validador opcional del token. Recibe el token resuelto y un PluginTaskContext; devuelve false para volver a pedirlo.

Orden de resolución: variable de entorno env -> resolve() -> keyring (SecureStore) -> prompt interactivo.

PluginCheck

Descriptor de un check de preflight aportado por un plugin.

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

Campo	Tipo	Descripción
title	string	Etiqueta que se muestra en la UI de lista de tareas.
phase	"prerequisites" | "conditions"	Momento de ejecución: "prerequisites" corre antes de las llamadas de red; "conditions" después de confirmar la conectividad con el registry.
task	function	Implementación del check. Lanza un error para hacerlo fallar.

PluginTaskContext

Wrapper agnóstico de listr2 que se pasa como segundo argumento a PluginCheck.task.

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

• output - muestra una línea de estado debajo del título del check en la UI de tareas.
• title - modifica dinámicamente el título de la tarea.
• prompt() - ejecuta un prompt de enquirer. Solo está disponible en modo interactivo.

Ejemplo

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}`);
    },
  },
};

Comandos personalizados

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 y ecosistemas personalizados

Usa registries personalizados cuando necesites otro destino de publicación. Usa ecosistemas personalizados cuando necesites enseñarle a pubm a leer y escribir versiones para otro tipo de paquete.

Documentación relacionada

• Configuration
• Coding Agent Integration
• Official Plugins