Plugin System API

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/plugin/runner.ts
• packages/core/src/plugin/index.ts
• plugins/pubm-plugin/skills/create-plugin/references/plugin-api.md
• packages/core/tests/unit/plugin/runner.test.ts
• plugins/pubm-plugin/skills/create-plugin/SKILL.md
• packages/core/src/tasks/phases/version.ts

The Plugin System API in pubm provides a robust framework for extending the publishing pipeline. It allows developers to hook into various stages of the release lifecycle, register custom CLI commands, manage credentials, and implement preflight checks. By utilizing a factory function pattern, plugins can be easily configured and integrated into the project's pubm.config.ts.

The system is designed to handle complex workflows, including monorepo support and multi-registry publishing. It ensures reliability through a sequential hook execution model and a dedicated Rollback API that handles failures gracefully by reversing side effects in reverse order of their creation.
Sources: plugins/pubm-plugin/skills/create-plugin/references/plugin-api.md:1-10, packages/core/src/index.ts:18-20

Core Architecture and Lifecycle

The central component of the plugin system is the PluginRunner, which manages the registration and execution of plugins. Plugins are defined by the PubmPlugin interface and are executed sequentially based on their registration order in the configuration.

Plugin Execution Flow

The following diagram illustrates the sequential execution of lifecycle hooks within the pubm pipeline.

Lifecycle Hooks Reference

Hook	Signature	Description
beforeVersion	HookFn	Runs before the version bump occurs. Used for pre-version validation.
afterVersion	HookFn	Runs after manifest updates. Ideal for syncing versions to external files.
afterRelease	AfterReleaseHookFn	Triggered after GitHub release creation. Receives ReleaseContext.
onError	ErrorHookFn	Executed on pipeline failure. Receives the Error object.
onSuccess	HookFn	Executed after a fully successful publishing pipeline.
Sources: plugins/pubm-plugin/skills/create-plugin/references/plugin-api.md:127-145, packages/core/src/tasks/phases/version.ts:40-42

Credential and Check Management

Plugins can declare necessary credentials and preflight checks to ensure the environment is correctly configured before any irreversible actions are taken.

Plugin Credentials

The credentials property allows plugins to define tokens or secrets. pubm resolves these through environment variables, custom resolvers, the system keyring, or interactive prompts. Resolved tokens are stored in ctx.runtime.pluginTokens.

interface PluginCredential {
  key: string;           // Internal identifier
  env: string;           // Environment variable name for CI
  label: string;         // Human-readable prompt label
  ghSecretName?: string; // GitHub Secret name for sync
  required?: boolean;    // Default: true
  resolve?: () => Promise<string | null>;
  validate?: (token: string, task: PluginTaskContext) => Promise<boolean>;
}

Sources: plugins/pubm-plugin/skills/create-plugin/references/plugin-api.md:16-40

Preflight Checks

PluginCheck structures allow plugins to perform validations during the prerequisites (local env) or conditions (network/permissions) phases.

Rollback API

The Rollback API is a critical safety feature. Plugins can register RollbackAction objects during any hook execution. If the pipeline fails, pubm executes these actions in Last-In, First-Out (LIFO) order.

Rollback Action Structure

Property	Type	Description
label	string	Description shown in the terminal during rollback.
fn	Async Function	The logic to reverse a side effect.
confirm	boolean	If true, prompts the user before executing in TTY mode.

Example Implementation:

hooks: {
  afterVersion: async (ctx) => {
    // Perform side effect
    const backup = readFileSync(filePath, "utf-8");
    
    ctx.runtime.rollback.add({
      label: `Restore ${filePath}`,
      fn: async () => {
        writeFileSync(filePath, backup, "utf-8");
      },
    });
  },
}

Sources: plugins/pubm-plugin/skills/create-plugin/references/plugin-api.md:180-210, packages/core/src/tasks/phases/version.ts:60-65

Asset Pipeline Hooks

For projects distributing binaries, plugins can intercept the asset pipeline to resolve, transform, compress, or upload release assets.

• resolveAssets: Discovers files to be included as assets.
• transformAsset: Modifies asset files (e.g., stripping symbols).
• uploadAssets: Concatenates results from multiple plugins to various targets (GitHub, S3, etc.).
  Sources: packages/core/tests/unit/plugin/runner.test.ts:133-320, plugins/pubm-plugin/skills/create-plugin/SKILL.md:20-35

Plugin Authoring Patterns

Plugins are typically authored using a factory function pattern. This allows the plugin to accept configuration options while returning a valid PubmPlugin object.

Implementation Checklist

1. Name: Use a unique identifier (e.g., @pubm/plugin-name).
2. ESM: Always use ECMAScript Modules ("type": "module").
3. Peer Dependencies: List @pubm/core as a peer dependency to ensure compatibility.
4. Commands: Optionally register CLI subcommands under the pubm namespace.

export function myPlugin(options: MyOptions): PubmPlugin {
  return {
    name: "my-plugin",
    hooks: {
      onSuccess: async (ctx) => {
        // Implementation
      },
    },
    commands: [{
      name: "my-tool",
      description: "Plugin-specific command",
      subcommands: [...]
    }]
  };
}

Sources: plugins/pubm-plugin/skills/create-plugin/SKILL.md:70-100, plugins/pubm-plugin/skills/create-plugin/references/plugin-api.md:258-285

Summary

The pubm Plugin System API provides a structured way to inject custom logic into the release process. By leveraging sequential hooks, a robust credential resolution system, and a LIFO-based rollback mechanism, it ensures that extensions are both powerful and safe. Whether managing Homebrew formulae or syncing versions to non-standard files, the API provides the necessary context and control for complex publishing requirements.