@unbrained/pm-cli 2026.3.12 → 2026.5.1

package/docs/RELEASING.md

@@ -1,8 +1,8 @@
 # Releasing `@unbrained/pm-cli`
 
-This repository uses a tag-driven GitHub Actions release pipeline that publishes to npm and creates a GitHub Release.
+This repository uses a tag-driven GitHub Actions pipeline that publishes to npm and creates a GitHub Release. The pipeline uses standard GitHub Actions, repository or environment secrets, artifacts, and npm provenance; it does not require paid GitHub features or paid-only environment protection rules.
 
-## Version policy
+## Version Policy
 
 `pm-cli` uses a calendar SemVer-compatible scheme:
 
@@ -14,24 +14,40 @@ Examples:
 - First release on 2026-03-09: `2026.3.9`
 - Second release on 2026-03-09: `2026.3.9-2`
 
-Use:
+Use this to compute the next expected release version from the npm registry:
 
 ```bash
 pnpm version:next
 ```
 
-to compute the next expected release version from the npm registry.
+The release workflow enforces the package version, tag name, calendar date, and npm registry sequencing before publishing.
 
-## One-time GitHub setup
+## One-Time Setup
 
-- Create GitHub Environment `release`
-- Add environment secret `NPM_TOKEN` (npm automation token with publish rights for `@unbrained/pm-cli`)
+- Add `NPM_TOKEN` as a GitHub Environment or repository secret named `NPM_TOKEN`.
+- If using an Environment named `release`, keep it free-feature compatible: no paid-only reviewer or deployment-protection requirements.
+- Ensure `GITHUB_TOKEN` has the default workflow permission needed by `permissions: contents: write` for GitHub Release creation.
+- Keep npm two-factor settings compatible with automation tokens and provenance publishing.
+- Keep `package.json` repository, homepage, and bugs URLs aligned with the canonical GitHub source repository (`https://github.com/unbraind/pm-cli`); npm provenance validation rejects mismatched repository metadata.
 
-## Release checklist
+## Local Release Checklist
 
-1) Update `package.json` version and `CHANGELOG.md`
+1. Confirm the next version:
 
-2) Run release gates locally:
+```bash
+pnpm version:next
+```
+
+2. Update `package.json`, `pnpm-lock.yaml`, and `CHANGELOG.md`.
+
+3. Generate release notes locally from changelog + pm tracker data:
+
+```bash
+pnpm build
+pnpm release:notes -- --version "$(node -p 'require("./package.json").version')" --output /tmp/pm-cli-release-notes.md
+```
+
+4. Run local release gates:
 
 ```bash
 pnpm install
@@ -39,27 +55,60 @@ pnpm build
 pnpm typecheck
 pnpm test
 pnpm test:coverage
+node scripts/run-tests.mjs coverage
 pnpm version:check
 pnpm security:scan
 pnpm smoke:npx
 ```
 
-3) Commit and tag:
+5. Verify previous-version tracker compatibility before tagging. Use a temporary project with the previously published package, create representative items, then run the current build against the same sandboxed `PM_PATH` and `PM_GLOBAL_PATH`. Confirm item count, fields, linked files/docs/tests, comments, close metadata, health, and history drift checks remain intact.
+
+6. Commit, push, tag, and push the tag:
 
 ```bash
-git tag v<version>
 git push origin main
+git tag v<version>
 git push origin v<version>
 ```
 
-4) Verify Actions:
+## Release Workflow
+
+`.github/workflows/release.yml` runs on `v*.*.*` tags and performs:
+
+- full-history checkout for previous-tag and release-note generation
+- pnpm install with frozen lockfile
+- version policy and tag guard
+- secret leak scan
+- build, typecheck, test coverage, and sandboxed pm coverage
+- npm pack dry run and npx tarball smoke test
+- generated release notes from `CHANGELOG.md` plus sanitized `pm` tracker metadata
+- coverage and release-note artifact uploads
+- `npm publish --access public --provenance`
+- GitHub Release creation using the generated release-note body
+
+Monitor with:
+
+```bash
+gh run list --workflow Release --limit 5
+gh run watch <run-id> --exit-status
+```
+
+## Post-Release Verification
+
+After the workflow succeeds, verify all distribution paths:
+
+```bash
+npm view @unbrained/pm-cli@<version> version dist.integrity dist.unpackedSize --json
+npx --yes @unbrained/pm-cli@<version> --version
+bunx @unbrained/pm-cli@<version> --version
+gh release view v<version> --json tagName,name,isDraft,isPrerelease,url
+```
 
-- `CI` passes for commit
-- `Release` workflow passes for tag
-- npm package published at `@unbrained/pm-cli`
-- GitHub Release created with generated notes
+The `pm` executable name remains unchanged even though the npm package is scoped.
 
-## Notes
+## Failure Handling
 
 - Do not run manual `npm publish`; publishing is owned by `.github/workflows/release.yml`.
-- Release workflow enforces tag/version alignment and calendar version sequencing before publish.
+- If local gates fail, fix the code/docs/tests and rerun the checklist before tagging.
+- If the tag workflow fails before npm publish, fix the issue, move the tag only after confirming no package was published, and rerun the workflow.
+- If npm publish succeeds but GitHub Release creation fails, rerun only the release creation after confirming the tag and package are correct.

package/docs/SDK.md

@@ -0,0 +1,123 @@
+# pm SDK Guide
+
+This guide documents the public SDK surface for extension authors.
+
+Primary import:
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+```
+
+Use this document for SDK/API contracts. Use `docs/EXTENSIONS.md` for full runtime lifecycle behavior and `pm extension --init ./my-extension` for starter scaffold generation.
+
+## Import Surfaces
+
+- `@unbrained/pm-cli/sdk`: stable extension authoring API and CLI contract exports.
+- `@unbrained/pm-cli/cli`: runtime CLI module entrypoint. This path is for runtime module resolution, not a typed library API; its declaration file intentionally exports no symbols.
+
+## Public SDK Exports
+
+Source of truth:
+
+- `src/sdk/index.ts`
+- `src/sdk/cli-contracts.ts`
+
+### Extension authoring values
+
+- `defineExtension(...)`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
+- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+
+### CLI/action contract values
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- all exported `...FLAG_CONTRACTS`, `...OPTION_CONTRACTS`, and `...COMMANDER_*_CONTRACTS` arrays from `src/sdk/cli-contracts.ts`
+
+### CLI/action contract helpers
+
+- `withFlagAliasMetadata(...)`
+- `toCompletionFlagString(...)`
+- `readFirstStringFromCommanderOptions(...)`
+- `readStringArrayFromCommanderOptions(...)`
+
+### Key type exports
+
+- extension capability/types: `ExtensionCapability`, `PmToolAction`, `PmExtensionCapabilityContract`, `PmExtensionServiceNameContract`
+- command/flag/type helpers: `CommandDefinition`, `ExtensionCommandArgumentDefinition`, `FlagDefinition`, `SchemaFieldDefinition`, `SchemaItemTypeDefinition`
+- runtime extension API types: `ExtensionApi`, `ExtensionManifest`, lifecycle hook context types, importer/exporter contexts, search provider types, vector adapter types
+- shared command/settings types: `GlobalOptions`, `PmSettings`
+
+## Capability Requirements (Quick Reference)
+
+Declare capabilities in `manifest.json`; runtime gating is strict.
+
+- `registerCommand(...)`: requires `commands`
+- `registerCommand({ flags: [...] })` and `registerFlags(...)`: require `schema`
+- `registerItemFields(...)`, `registerItemTypes(...)`, `registerMigration(...)`: require `schema`
+- `registerImporter(...)` and `registerExporter(...)`: require `importers`
+- `registerParser(...)`: requires `parser`
+- `registerPreflight(...)`: requires `preflight`
+- `registerService(...)`: requires `services`
+- `registerRenderer(...)`: requires `renderers`
+- lifecycle hooks (`beforeCommand`, `afterCommand`, `onWrite`, `onRead`, `onIndex`): require `hooks`
+- `registerSearchProvider(...)` and `registerVectorStoreAdapter(...)`: require `search`
+
+## Minimal Extension
+
+`manifest.json`:
+
+```json
+{
+  "name": "hello-extension",
+  "version": "0.1.0",
+  "entry": "./index.js",
+  "capabilities": ["commands"]
+}
+```
+
+`index.js`:
+
+```js
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "hello",
+      run: async () => ({ ok: true, message: "hello from sdk extension" }),
+    });
+  },
+});
+```
+
+## Typed Authoring Highlights
+
+The SDK provides explicit interfaces for key surfaces including:
+
+- `CommandDefinition` and `ExtensionCommandArgumentDefinition`
+- `FlagDefinition`
+- `SchemaFieldDefinition`, `SchemaItemTypeDefinition`, `SchemaMigrationDefinition`
+- `ImportExportContext`
+- `SearchProviderDefinition`, `SearchProviderQueryContext`, `SearchProviderHit`
+- `VectorStoreAdapterDefinition`, `VectorStoreQueryContext`, `VectorStoreUpsertContext`
+
+These interfaces intentionally allow additive metadata (`[key: string]: unknown`) where extension-defined metadata is expected.
+
+## Recommended Authoring Pattern
+
+- keep command handlers deterministic and JSON-like
+- keep renderer/service overrides narrow to specific command paths
+- prefer additive hooks and schema fields over global behavior changes
+- ship one extension folder with `manifest.json`, an entry module, and package metadata/dependencies
+
+## Related Docs
+
+- full extension lifecycle/runtime reference: `docs/EXTENSIONS.md`
+- architecture internals: `docs/ARCHITECTURE.md`
+- complete starter scaffold: `docs/examples/starter-extension/`

package/docs/examples/starter-extension/README.md

@@ -0,0 +1,48 @@
+# Starter Extension (All 9 Capabilities)
+
+This example demonstrates a single extension that uses the public SDK only:
+`@unbrained/pm-cli/sdk`.
+
+It is intentionally small and "feature complete" as a reference scaffold.
+
+## Files
+
+- `manifest.json` declares all 9 capabilities.
+- `package.json` declares the SDK dependency.
+- `index.js` registers one or more examples for each capability.
+
+## Capability Coverage
+
+1. `commands` - `api.registerCommand(...)` + `api.registerFlags(...)`
+2. `parser` - `api.registerParser(...)`
+3. `preflight` - `api.registerPreflight(...)`
+4. `services` - `api.registerService(...)`
+5. `renderers` - `api.registerRenderer(...)`
+6. `hooks` - `api.hooks.beforeCommand/afterCommand/onWrite/onRead/onIndex`
+7. `schema` - `api.registerItemFields/registerItemTypes/registerMigration`
+8. `importers` - `api.registerImporter/registerExporter`
+9. `search` - `api.registerSearchProvider/registerVectorStoreAdapter`
+
+## Quick Start
+
+1. Copy this folder into an extension root:
+   - project: `.agents/pm/extensions/starter-extension`
+   - global: `~/.pm-cli/extensions/starter-extension`
+2. Install dependencies in that copied folder:
+
+```bash
+npm install
+```
+
+3. Activate and test:
+
+```bash
+pm extension --activate --project starter-extension
+pm starter ping --name "agent"
+```
+
+## Notes
+
+- This starter is for learning and scaffolding, not production behavior.
+- Keep service/renderer overrides narrowly scoped in real extensions.
+- Prefer returning deterministic JSON-like objects from handlers.

package/docs/examples/starter-extension/index.js

@@ -0,0 +1,191 @@
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+const runtimeState = {
+  beforeCommandCount: 0,
+  afterCommandCount: 0,
+  onWriteCount: 0,
+  onReadCount: 0,
+  onIndexCount: 0,
+};
+
+function asRecord(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  return {};
+}
+
+function asString(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+
+function stableJson(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return JSON.stringify({ error: "non_serializable_payload" }, null, 2);
+  }
+}
+
+export default defineExtension({
+  activate(api) {
+    // commands
+    api.registerCommand({
+      name: "starter ping",
+      description: "Return a deterministic starter-extension response.",
+      intent: "Verify extension activation and show SDK registration patterns.",
+      examples: ["pm starter ping --name agent --uppercase"],
+      run: async (context) => {
+        const options = asRecord(context.options);
+        const rawName = asString(options.name, "agent").trim();
+        return {
+          ok: true,
+          source: "starter-extension",
+          command: context.command,
+          hello: rawName.length > 0 ? rawName : "agent",
+          hook_counts: {
+            before: runtimeState.beforeCommandCount,
+            after: runtimeState.afterCommandCount,
+            write: runtimeState.onWriteCount,
+            read: runtimeState.onReadCount,
+            index: runtimeState.onIndexCount,
+          },
+        };
+      },
+    });
+
+    // schema (registerFlags currently routes through schema capability)
+    api.registerFlags("starter ping", [
+      { long: "--name", value_name: "text", description: "Name to include in the response." },
+      { long: "--uppercase", description: "Render hello in uppercase via output_format service override." },
+    ]);
+
+    // parser
+    api.registerParser("starter ping", async (context) => {
+      const options = { ...asRecord(context.options) };
+      if (typeof options.name === "string") {
+        options.name = options.name.trim();
+      }
+      return { options };
+    });
+
+    // preflight
+    api.registerPreflight((context) => {
+      if (context.command !== "starter ping") {
+        return {};
+      }
+      return {
+        run_extension_migrations: false,
+      };
+    });
+
+    // services
+    api.registerService("output_format", (context) => {
+      if (context.command !== "starter ping") {
+        return context.payload;
+      }
+      const payload = asRecord(context.payload);
+      const result = asRecord(payload.result);
+      const options = asRecord(context.options);
+      const uppercase = options.uppercase === true;
+      const helloRaw = asString(result.hello, "agent");
+      const hello = uppercase ? helloRaw.toUpperCase() : helloRaw;
+      return `starter_service_output hello=${hello} command=${asString(context.command, "")}`;
+    });
+
+    // renderers
+    api.registerRenderer("json", (context) => stableJson(context.result));
+    api.registerRenderer("toon", (context) => {
+      const result = asRecord(context.result);
+      const hooks = asRecord(result.hook_counts);
+      return [
+        "starter_ping",
+        `hello: ${asString(result.hello, "agent")}`,
+        `command: ${asString(result.command, "")}`,
+        `hooks.before: ${String(hooks.before ?? 0)}`,
+        `hooks.after: ${String(hooks.after ?? 0)}`,
+      ].join("\n");
+    });
+
+    // hooks
+    api.hooks.beforeCommand(() => {
+      runtimeState.beforeCommandCount += 1;
+    });
+    api.hooks.afterCommand(() => {
+      runtimeState.afterCommandCount += 1;
+    });
+    api.hooks.onWrite(() => {
+      runtimeState.onWriteCount += 1;
+    });
+    api.hooks.onRead(() => {
+      runtimeState.onReadCount += 1;
+    });
+    api.hooks.onIndex(() => {
+      runtimeState.onIndexCount += 1;
+    });
+
+    // schema
+    api.registerItemFields([
+      {
+        name: "starter_context",
+        type: "string",
+        optional: true,
+      },
+    ]);
+    api.registerItemTypes([
+      {
+        name: "Experiment",
+        folder: "experiments",
+        aliases: ["exp"],
+        required_create_fields: ["description"],
+      },
+    ]);
+    api.registerMigration({
+      id: "starter-extension-noop-migration",
+      description: "No-op migration to demonstrate schema migration registration.",
+      status: "applied",
+      mandatory: false,
+      run: async () => ({ applied: true }),
+    });
+
+    // importers
+    api.registerImporter("starter-json", async (context) => ({
+      imported: true,
+      source: "starter-extension",
+      input: asRecord(context),
+    }));
+    api.registerExporter("starter-json", async (context) => ({
+      exported: true,
+      source: "starter-extension",
+      output: asRecord(context),
+    }));
+
+    // search
+    api.registerSearchProvider({
+      name: "starter-search",
+      kind: "example",
+      query: async (context) => {
+        const query = asString(asRecord(context).query, "").trim();
+        if (!query) {
+          return [];
+        }
+        return [
+          {
+            id: "starter-result-1",
+            score: 1,
+            title: "Starter Search Result",
+            snippet: `Echo match for: ${query}`,
+            source: "starter-extension",
+          },
+        ];
+      },
+    });
+    api.registerVectorStoreAdapter({
+      name: "starter-vector-adapter",
+      kind: "example",
+      upsert: async () => ({ upserted: 0 }),
+      query: async () => [],
+      delete: async () => ({ deleted: 0 }),
+    });
+  },
+});

package/docs/examples/starter-extension/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "starter-extension",
+  "version": "0.1.0",
+  "description": "SDK-first starter extension demonstrating all pm extension capabilities.",
+  "entry": "./index.js",
+  "capabilities": [
+    "commands",
+    "parser",
+    "preflight",
+    "services",
+    "renderers",
+    "hooks",
+    "schema",
+    "importers",
+    "search"
+  ]
+}

package/docs/examples/starter-extension/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@pm-cli/starter-extension",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Reference extension starter using @unbrained/pm-cli/sdk",
+  "dependencies": {
+    "@unbrained/pm-cli": "^2026.3.12"
+  }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.3.12",
+  "version": "2026.5.1",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
   "homepage": "https://github.com/unbraind/pm-cli#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/unbraind/pm-cli.git"
+    "url": "git+https://github.com/unbraind/pm-cli.git"
   },
   "bugs": {
     "url": "https://github.com/unbraind/pm-cli/issues"
@@ -15,14 +15,37 @@
   "bin": {
     "pm": "dist/cli.js"
   },
+  "types": "dist/sdk/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js",
+      "default": "./dist/sdk/index.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js",
+      "default": "./dist/sdk/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/main.d.ts",
+      "import": "./dist/cli/main.js",
+      "default": "./dist/cli/main.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist/**",
     "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
     "LICENSE",
     "AGENTS.md",
     "PRD.md",
     "docs/**",
-    ".pi/extensions/pm-cli/index.ts",
+    ".agents/pm/extensions/**",
     "scripts/install.sh",
     "scripts/install.ps1"
   ],
@@ -35,6 +58,7 @@
     "test:coverage": "pnpm build && vitest run --coverage",
     "version:check": "node scripts/release-version.mjs check",
     "version:next": "node scripts/release-version.mjs next",
+    "release:notes": "node scripts/generate-release-notes.mjs",
     "security:scan": "node scripts/check-secrets.mjs",
     "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
     "prepublishOnly": "pnpm build"
@@ -59,21 +83,24 @@
   "dependencies": {
     "@toon-format/toon": "latest",
     "commander": "latest",
+    "fast-glob": "^3.3.3",
     "fast-json-patch": "latest",
     "undici": "latest",
     "zod": "latest"
   },
   "devDependencies": {
     "@types/node": "latest",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.5",
     "c8": "^11.0.0",
     "tsx": "latest",
     "typescript": "latest",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.5"
   },
   "pnpm": {
     "overrides": {
-      "rollup": ">=4.59.0"
+      "rollup": ">=4.59.0",
+      "brace-expansion": ">=5.0.5",
+      "vite": "7.3.2"
     }
   }
 }