create-plugin

name: create-plugin description: Scaffold and guide creation of a new pubm plugin package allowed-tools: - Bash - Read - Write - Edit - Glob - Grep - AskUserQuestion

Create pubm Plugin

Create a new pubm plugin, from an inline hook to a full publishable package.

Workflow

1. Gather Plugin Info

Use AskUserQuestion to collect:

1. Plugin name (kebab-case, without plugin- prefix). Example: slack-notify, sentry-release
2. One-line description of what the plugin does
3. Which hooks to use (multi-select from the list below)
4. Whether it needs CLI commands (pubm subcommands)

Available hooks (see references/plugin-api.md for details):

2. Choose Plugin Form

Use AskUserQuestion to ask which form they want:

Then follow the matching section below.

Form A: Config Inline

Add the plugin factory function and its invocation directly in pubm.config.ts. No new files are created.

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

function {camelName}(): PubmPlugin {
  return {
    name: "{name}",
    hooks: {
      {selectedHook}: async (ctx) => {
        // TODO: Implement {selectedHook} logic
      },
    },
  };
}

export default defineConfig({
  // ...existing config...
  plugins: [
    // ...existing plugins...
    {camelName}(),
  ],
});

If the plugin needs options, define an inline interface above the function:

interface {PascalName}Options {
  // options here
}

function {camelName}(options: {PascalName}Options): PubmPlugin {
  // ...
}

After adding, skip to Step: Present Next Steps.

Form B: Single File

Create a single .ts file with the factory function. Let the user choose the file location; suggest plugins/{name}.ts or src/plugins/{name}.ts.

plugins/{name}.ts

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

export interface {PascalName}Options {
  // TODO: Define your plugin options here
}

export function {camelName}(options: {PascalName}Options): PubmPlugin {
  return {
    name: "{name}",
    hooks: {
      {selectedHook}: async (ctx) => {
        // TODO: Implement {selectedHook} logic
      },
    },
  };
}

If afterRelease is selected, use the special signature:

afterRelease: async (ctx, releaseCtx) => {
  // releaseCtx has: { releaseUrl, tagName, releaseName }
},

If onError is selected, use the error signature:

onError: async (ctx, error) => {
  // error is the Error that caused the failure
},

Then register in pubm.config.ts:

import { defineConfig } from "@pubm/core";
import { {camelName} } from "./plugins/{name}.js";

export default defineConfig({
  // ...existing config...
  plugins: [
    // ...existing plugins...
    {camelName}({ /* options */ }),
  ],
});

After creating, skip to Step: Present Next Steps.

Form C: Package

Create packages/plugins/plugin-{name}/ with full boilerplate.

package.json

{
  "name": "@pubm/plugin-{name}",
  "version": "0.0.1",
  "type": "module",
  "description": "{description}",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "files": ["dist/"],
  "scripts": {
    "build": "bun build src/index.ts --outdir dist --target node --format esm && bunx tsc --project tsconfig.build.json",
    "check": "biome check",
    "typecheck": "tsc --noEmit",
    "test": "vitest --run",
    "coverage": "vitest --run --coverage"
  },
  "peerDependencies": {
    "@pubm/core": ">=0.3.6"
  },
  "license": "Apache-2.0",
  "publishConfig": {
    "access": "public"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/syi0808/pubm.git",
    "directory": "packages/plugins/plugin-{name}"
  }
}

tsconfig.json

{
  "extends": "../../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "src",
    "outDir": "dist",
    "paths": {
      "@pubm/core": ["../../core/src/index.ts"]
    }
  },
  "references": [{ "path": "../../core" }],
  "include": ["src/**/*.ts"],
  "exclude": ["tests", "dist", "node_modules"]
}

tsconfig.build.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "emitDeclarationOnly": true,
    "declaration": true,
    "declarationDir": "dist",
    "paths": {}
  }
}

vitest.config.mts

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    include: ["tests/**/*.{test,spec}.?(c|m)[jt]s?(x)"],
    setupFiles: ["tests/setup.ts"],
    pool: "forks",
    testTimeout: 30000,
    passWithNoTests: true,
  },
});

src/types.ts

export interface {PascalName}Options {
  // TODO: Define your plugin options here
}

src/index.ts

Generate based on selected hooks. Pattern:

import type { PubmPlugin } from "@pubm/core";
import type { {PascalName}Options } from "./types.js";

export type { {PascalName}Options } from "./types.js";

export function {camelName}(options: {PascalName}Options): PubmPlugin {
  return {
    name: "{name}",
    hooks: {
      {selectedHook}: async (ctx) => {
        // TODO: Implement {selectedHook} logic
      },
    },
  };
}

If afterRelease is selected, use the special signature:

afterRelease: async (ctx, releaseCtx) => {
  // releaseCtx has: { releaseUrl, tagName, releaseName }
},

If onError is selected, use the error signature:

onError: async (ctx, error) => {
  // error is the Error that caused the failure
},

If CLI commands are needed, add a commands property:

commands: [
  {
    name: "{name}",
    description: "{description}",
    subcommands: [
      {
        name: "init",
        description: "Initialize {name} configuration",
        options: [],
        action: async (args) => {
          // TODO: Implement command
        },
      },
    ],
  },
],

tests/setup.ts

import { afterEach, vi } from "vitest";

afterEach(() => {
  vi.restoreAllMocks();
  vi.unstubAllGlobals();
});

tests/unit/plugin.test.ts

import { describe, expect, it } from "vitest";
import { {camelName} } from "../../src/index.js";

describe("{name} plugin", () => {
  it("should return a valid PubmPlugin", () => {
    const plugin = {camelName}({});
    expect(plugin.name).toBe("{name}");
    expect(plugin.hooks).toBeDefined();
  });

  // Add hook-specific tests:
  // it("should have {selectedHook} hook", () => {
  //   const plugin = {camelName}({});
  //   expect(plugin.hooks?.{selectedHook}).toBeTypeOf("function");
  // });
});

Package-only: Register in Workspace

Check the root package.json for the workspaces field. If it uses a glob like packages/plugins/*, the new package is already covered. Otherwise, add the plugin path.

Package-only: Install Dependencies

Run bun install from the repo root to link the new package.

Package-only: Verify Scaffold

Run in sequence:

cd packages/plugins/plugin-{name} && bun run build && bun run test

Step: Present Next Steps

After creation, tell the user:

1. Implement hook logic in the plugin source
2. Define options (if not already done)
3. Add tests (for Package form: in tests/unit/ and tests/integration/)
4. Register the plugin in pubm.config.ts (if not already done):

   import { defineConfig } from "@pubm/core";
   import { {camelName} } from "@pubm/plugin-{name}";
   
   export default defineConfig({
     plugins: [
       {camelName}({ /* options */ }),
     ],
   });
   

5. Refer to references/plugin-api.md for the full plugin API

Naming Conventions

Convert the user-provided {name} (kebab-case) to:

• PascalName: slack-notify → SlackNotify
• camelName: slack-notify → slackNotify
• Package name: @pubm/plugin-{name}
• Directory: packages/plugins/plugin-{name}

Constraints

• Always use the factory function pattern (function returning PubmPlugin)
• Always use @pubm/core as a peer dependency (Package form), never a regular dependency
• Always use ESM ("type": "module")
• Follow the existing plugin structure exactly (same scripts, tsconfig, vitest config)
• Do not add dependencies beyond @pubm/core unless the user explicitly requests them

References

• references/plugin-api.md -- Complete PubmPlugin interface and hook reference