@unbrained/pm-cli 2026.5.10 → 2026.5.11

package/docs/examples/ci/github-actions-pm-extension-gate.yml

@@ -0,0 +1,53 @@
+name: pm-extension-gate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  extension-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Export contracts (schema + flags)
+        run: |
+          pm contracts --schema-only --json > contracts-schema.json
+          pm contracts --command extension --flags-only --json > contracts-extension-flags.json
+          pm contracts --json > contracts-runtime.json
+
+      - name: Verify extension contract compatibility metadata
+        run: |
+          node -e 'const fs=require("node:fs");const c=JSON.parse(fs.readFileSync("contracts-runtime.json","utf8"));if(!c.extension_contracts?.compatibility){throw new Error("missing extension compatibility metadata");}'
+
+      - name: Reload extensions
+        run: pm extension --reload --project --json
+
+      - name: Extension governance diagnostics gate
+        run: pm extension --doctor --project --detail summary --strict-exit
+
+      - name: Unit tests
+        run: node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts tests/unit/extension-loader.spec.ts tests/unit/extension-command.spec.ts
+
+      - name: Coverage
+        run: node scripts/run-tests.mjs coverage

package/docs/examples/ci/gitlab-ci-pm-extension-gate.yml

@@ -0,0 +1,41 @@
+image: node:22
+
+stages:
+  - build
+  - contracts
+  - extension_gate
+  - test
+
+before_script:
+  - corepack enable
+  - corepack prepare pnpm@10 --activate
+  - pnpm install --frozen-lockfile
+
+build:
+  stage: build
+  script:
+    - pnpm build
+
+contracts:
+  stage: contracts
+  script:
+    - node dist/cli.js contracts --schema-only --json > contracts-schema.json
+    - node dist/cli.js contracts --command extension --flags-only --json > contracts-extension-flags.json
+    - node dist/cli.js contracts --json > contracts-runtime.json
+  artifacts:
+    paths:
+      - contracts-schema.json
+      - contracts-extension-flags.json
+      - contracts-runtime.json
+
+extension_gate:
+  stage: extension_gate
+  script:
+    - node dist/cli.js extension --reload --project --json
+    - node dist/cli.js extension --doctor --project --detail summary --strict-exit --json
+
+test:
+  stage: test
+  script:
+    - node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts tests/unit/extension-loader.spec.ts tests/unit/extension-command.spec.ts
+    - node scripts/run-tests.mjs coverage

package/docs/examples/ci/jenkins-pm-extension-gate.Jenkinsfile

@@ -0,0 +1,45 @@
+pipeline {
+  agent any
+
+  tools {
+    nodejs "node-22"
+  }
+
+  stages {
+    stage("Install") {
+      steps {
+        sh "corepack enable"
+        sh "corepack prepare pnpm@10 --activate"
+        sh "pnpm install --frozen-lockfile"
+      }
+    }
+
+    stage("Build") {
+      steps {
+        sh "pnpm build"
+      }
+    }
+
+    stage("Contracts") {
+      steps {
+        sh "node dist/cli.js contracts --schema-only --json > contracts-schema.json"
+        sh "node dist/cli.js contracts --command extension --flags-only --json > contracts-extension-flags.json"
+        sh "node dist/cli.js contracts --json > contracts-runtime.json"
+      }
+    }
+
+    stage("Extension Gate") {
+      steps {
+        sh "node dist/cli.js extension --reload --project --json"
+        sh "node dist/cli.js extension --doctor --project --detail summary --strict-exit --json"
+      }
+    }
+
+    stage("Tests") {
+      steps {
+        sh "node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts tests/unit/extension-loader.spec.ts tests/unit/extension-command.spec.ts"
+        sh "node scripts/run-tests.mjs coverage"
+      }
+    }
+  }
+}

package/docs/examples/policy-restricted-extension/README.md

@@ -0,0 +1,74 @@
+# Policy-Restricted Extension Example
+
+This example demonstrates governance policy behavior with real registrations.
+
+The extension declares:
+
+- `commands` (handler registration)
+- `hooks` (beforeCommand)
+- `services` (output_format override)
+
+You can enforce policy so command/hooks remain allowed while service override is blocked.
+
+## Run It
+
+From repository root:
+
+```bash
+mkdir -p .agents/pm/extensions
+cp -R docs/examples/policy-restricted-extension .agents/pm/extensions/policy-restricted-extension
+cd .agents/pm/extensions/policy-restricted-extension
+npm install
+cd -
+pm extension --install --project .agents/pm/extensions/policy-restricted-extension
+```
+
+Add policy in `.agents/pm/settings.json`:
+
+```json
+{
+  "extensions": {
+    "policy": {
+      "mode": "enforce",
+      "trust_mode": "enforce",
+      "require_provenance": true,
+      "trusted_extensions": ["policy-restricted-extension"],
+      "default_sandbox_profile": "restricted",
+      "allowed_extensions": ["policy-restricted-extension"],
+      "blocked_extensions": [],
+      "allowed_capabilities": [],
+      "blocked_capabilities": [],
+      "allowed_surfaces": [],
+      "blocked_surfaces": ["services.override"],
+      "allowed_commands": [],
+      "blocked_commands": [],
+      "allowed_actions": [],
+      "blocked_actions": [],
+      "allowed_services": [],
+      "blocked_services": ["output_format"],
+      "extension_overrides": [
+        {
+          "name": "policy-restricted-extension",
+          "require_trusted": true,
+          "require_provenance": true,
+          "sandbox_profile": "strict"
+        }
+      ]
+    }
+  }
+}
+```
+
+Then validate:
+
+```bash
+pm extension --doctor --project --detail summary
+pm policy demo
+```
+
+Expected behavior:
+
+- `pm policy demo` still works (command handler allowed).
+- `extension --doctor` includes `extension_policy_blocked_registration`.
+- `details.triage.policy_blocked_count` is greater than `0`.
+- trust/provenance contract fields are visible in `pm contracts --json` metadata.

package/docs/examples/policy-restricted-extension/index.js

@@ -0,0 +1,21 @@
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "policy demo",
+      action: "policy-demo",
+      description: "Emit a deterministic payload to validate policy-gated activation.",
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+        source: "policy-restricted-extension",
+      }),
+    });
+
+    api.hooks.beforeCommand(() => {});
+
+    // This registration is intentionally useful for policy demos.
+    api.registerService("output_format", (payload) => payload);
+  },
+});

package/docs/examples/policy-restricted-extension/manifest.json

@@ -0,0 +1,21 @@
+{
+  "name": "policy-restricted-extension",
+  "version": "0.1.0",
+  "entry": "./index.js",
+  "manifest_version": 2,
+  "trusted": true,
+  "provenance": {
+    "source": "docs/examples/policy-restricted-extension",
+    "verified": true
+  },
+  "sandbox_profile": "restricted",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": false,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
+  "capabilities": ["commands", "hooks", "services"]
+}

package/docs/examples/policy-restricted-extension/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "policy-restricted-extension",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@unbrained/pm-cli": "latest"
+  }
+}

package/docs/examples/sdk-app-embedding/README.md

@@ -0,0 +1,39 @@
+# SDK App Embedding Example
+
+This example demonstrates a simple app-style wrapper that:
+
+1. validates an action using SDK contracts
+2. checks runtime availability (`pm contracts --json`)
+3. executes a safe command mapping
+4. emits a structured JSON payload for CI/services
+
+## Files
+
+- `package.json`
+- `run-embedded-pm.mjs`
+
+## Run
+
+```bash
+cp -R docs/examples/sdk-app-embedding /tmp/pm-sdk-app-embedding
+cd /tmp/pm-sdk-app-embedding
+
+# During local development against this repository:
+PM_CLI_REPO_ROOT=/absolute/path/to/pm-cli
+npm install "$PM_CLI_REPO_ROOT"
+
+# Run extension reload flow
+node run-embedded-pm.mjs extension-reload
+```
+
+## What It Returns
+
+The script returns JSON with:
+
+- `action`
+- resolved command invocation
+- required/optional parameter contracts
+- `policy_state` from action availability
+- command result payload
+
+This pattern is useful for backend workers, CI jobs, or orchestrators that must remain contract-safe across SDK/CLI upgrades.

package/docs/examples/sdk-app-embedding/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "pm-sdk-app-embedding-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node run-embedded-pm.mjs",
+    "reload": "node run-embedded-pm.mjs extension-reload"
+  }
+}

package/docs/examples/sdk-app-embedding/run-embedded-pm.mjs

@@ -0,0 +1,61 @@
+import { spawnSync } from "node:child_process";
+import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
+
+function runPm(args) {
+  const completed = spawnSync("pm", args, {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      NO_COLOR: "1",
+    },
+  });
+  if (completed.status !== 0) {
+    const stderr = (completed.stderr ?? "").trim();
+    throw new Error(stderr.length > 0 ? stderr : `pm ${args.join(" ")} failed with exit code ${completed.status}`);
+  }
+  const stdout = (completed.stdout ?? "").trim();
+  return stdout.length > 0 ? JSON.parse(stdout) : {};
+}
+
+function resolveCommandForAction(action) {
+  const commandMap = {
+    "extension-reload": ["extension", "--reload", "--project", "--json"],
+    "extension-doctor": ["extension", "--doctor", "--project", "--detail", "summary", "--json"],
+    contracts: ["contracts", "--json"],
+  };
+  return commandMap[action] ?? [action, "--json"];
+}
+
+const requestedAction = (process.argv[2] ?? "extension-reload").trim().toLowerCase();
+if (!isPmToolAction(requestedAction)) {
+  throw new Error(`Unsupported pm action "${requestedAction}".`);
+}
+
+const contracts = runPm(["contracts", "--json"]);
+const actionAvailability = Array.isArray(contracts.action_availability)
+  ? contracts.action_availability.find((entry) => entry?.action === requestedAction) ?? null
+  : null;
+if (actionAvailability?.available === false) {
+  throw new Error(
+    `Action "${requestedAction}" is not available in this runtime (${actionAvailability.disabled_reason ?? "unknown_reason"}).`,
+  );
+}
+
+const actionContract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[requestedAction];
+const command = resolveCommandForAction(requestedAction);
+const commandResult = runPm(command);
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      action: requestedAction,
+      command: `pm ${command.join(" ")}`,
+      required_parameters: actionContract.required ?? [],
+      optional_parameters: actionContract.optional ?? [],
+      policy_state: actionAvailability?.policy_state ?? null,
+      result: commandResult,
+    },
+    null,
+    2,
+  )}\n`,
+);

package/docs/examples/sdk-contract-consumer/README.md

@@ -0,0 +1,57 @@
+# SDK Contracts Consumer Example
+
+This example shows how to consume `pm` contracts programmatically in a script and validate action payload requirements before execution.
+
+## Files
+
+- `package.json` -> installs `@unbrained/pm-cli` and script aliases
+- `inspect-contracts.mjs` -> loads contracts + SDK helpers and prints required/optional parameter metadata
+
+## Run
+
+```bash
+cp -R docs/examples/sdk-contract-consumer /tmp/pm-sdk-contract-consumer
+cd /tmp/pm-sdk-contract-consumer
+# Local checkout (recommended while iterating on unreleased SDK changes):
+PM_CLI_REPO_ROOT=/absolute/path/to/pm-cli
+npm install "$PM_CLI_REPO_ROOT"
+
+# Or use a published release once available:
+# npm install @unbrained/pm-cli@latest
+
+node inspect-contracts.mjs create
+```
+
+Expected output shape:
+
+```json
+{
+  "action": "create",
+  "required_parameters": ["title", "description", "type", "status", "priority", "message"],
+  "optional_parameters": ["template", "createMode", "schedulePreset"],
+  "any_of_required_groups": [],
+  "runtime_available": true,
+  "policy_state": null,
+  "compatibility": {
+    "current": "v2",
+    "previous": ["v1"],
+    "breaking_strategy": "versioned_breaking"
+  },
+  "manifest_versions": [1, 2]
+}
+```
+
+You can inspect any action:
+
+```bash
+node inspect-contracts.mjs update
+node inspect-contracts.mjs extension
+node inspect-contracts.mjs extension-reload
+```
+
+## Why This Pattern Works
+
+- Uses `isPmToolAction()` for strict action validation.
+- Uses `PM_TOOL_ACTION_PARAMETER_CONTRACTS` for deterministic required/optional metadata.
+- Uses runtime `pm contracts --json` so extension-provided actions and command availability are reflected.
+- Includes policy-state and compatibility metadata so CI/app callers can gate behavior during v1 -> v2 migrations.

package/docs/examples/sdk-contract-consumer/inspect-contracts.mjs

@@ -0,0 +1,47 @@
+import { spawnSync } from "node:child_process";
+import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
+
+function runPmContracts() {
+  const completed = spawnSync("pm", ["contracts", "--json"], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      NO_COLOR: "1",
+    },
+  });
+  if (completed.status !== 0) {
+    const stderr = (completed.stderr ?? "").trim();
+    throw new Error(stderr.length > 0 ? stderr : `pm contracts failed with exit code ${completed.status}`);
+  }
+  return JSON.parse(completed.stdout ?? "{}");
+}
+
+const requestedAction = (process.argv[2] ?? "create").trim().toLowerCase();
+if (!isPmToolAction(requestedAction)) {
+  throw new Error(`Unsupported pm action "${requestedAction}".`);
+}
+
+const contracts = runPmContracts();
+const availableActions = Array.isArray(contracts.actions) ? contracts.actions : [];
+if (!availableActions.includes(requestedAction)) {
+  throw new Error(`Action "${requestedAction}" is not currently invocable in this runtime.`);
+}
+const actionAvailability = Array.isArray(contracts.action_availability)
+  ? contracts.action_availability.find((entry) => entry?.action === requestedAction) ?? null
+  : null;
+const extensionContracts =
+  contracts.extension_contracts && typeof contracts.extension_contracts === "object" ? contracts.extension_contracts : null;
+
+const actionContract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[requestedAction];
+const payload = {
+  action: requestedAction,
+  required_parameters: actionContract.required ?? [],
+  optional_parameters: actionContract.optional ?? [],
+  any_of_required_groups: actionContract.anyOfRequired ?? [],
+  runtime_available: actionAvailability?.available === true,
+  policy_state: actionAvailability?.policy_state ?? null,
+  compatibility: extensionContracts?.compatibility ?? null,
+  manifest_versions: extensionContracts?.manifest_versions ?? [],
+};
+
+process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);

package/docs/examples/sdk-contract-consumer/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "pm-sdk-contract-consumer-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "inspect:create": "node inspect-contracts.mjs create",
+    "inspect:update": "node inspect-contracts.mjs update",
+    "inspect:reload": "node inspect-contracts.mjs extension-reload"
+  }
+}

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

@@ -1,62 +1,77 @@
-# Starter Extension
+# Starter Extension (Runnable Example)
 
-This example demonstrates all extension capability categories through the public SDK import `@unbrained/pm-cli/sdk`.
+This example is a full capability reference extension. It intentionally demonstrates every extension capability surface, including parser/preflight/services/search/schema hooks.
 
-## Agent Quick Context
+Use it to learn APIs, then narrow capabilities for production extensions.
 
-- Copy this folder when you need a complete capability reference.
-- Use `pm extension init ./my-extension` when you need a smaller scaffold.
-- Keep production extensions narrower than this example.
+## Contents
 
-Related docs:
+- `manifest.json` -> extension metadata/capabilities
+- `package.json` -> local dependency metadata
+- `index.js` -> capability demonstrations
 
-- [Extensions](../../EXTENSIONS.md)
-- [SDK](../../SDK.md)
+## End-to-End Run
 
-## Files
-
-| File | Purpose |
-|------|---------|
-| `manifest.json` | declares extension metadata and capabilities |
-| `package.json` | declares local package metadata and SDK dependency |
-| `index.js` | registers examples for each capability category |
-
-## Capability Coverage
-
-| Capability | Example surface |
-|------------|-----------------|
-| `commands` | `api.registerCommand(...)` |
-| `parser` | `api.registerParser(...)` |
-| `preflight` | `api.registerPreflight(...)` |
-| `services` | `api.registerService(...)` |
-| `renderers` | `api.registerRenderer(...)` |
-| `hooks` | command, read, write, and index hooks |
-| `schema` | item fields, item types, migrations |
-| `importers` | importer and exporter registration |
-| `search` | search provider and vector adapter |
-
-## Quick Start
-
-Copy into an extension root:
+From repository root:
 
 ```bash
+# 1) Copy into project extension root
 mkdir -p .agents/pm/extensions
 cp -R docs/examples/starter-extension .agents/pm/extensions/starter-extension
+
+# 2) Install dependencies for the copied extension
 cd .agents/pm/extensions/starter-extension
 npm install
+cd -
+
+# 3) Install/activate in project scope
+pm extension --install --project .agents/pm/extensions/starter-extension
+
+# 4) Run a starter command
+pm starter ping --name "agent"
+
+# 5) Reload extension modules after edits
+pm extension --reload --project
+
+# 6) Optional watch-mode semantics
+pm extension --reload --project --watch
+
+# 7) Verify runtime health
+pm extension --doctor --project --detail summary
 ```
 
-Activate and test from the repository root:
+Expected outcomes:
+
+- `pm starter ping` returns deterministic output (plain text when starter service overrides output formatting).
+- `extension --doctor` shows `details.summary.status` as `ok` or `warn`.
+- If `warn`, inspect `details.summary.warning_codes` and `details.triage.remediation`.
+- `extension --reload` returns deterministic load/activation diagnostics for cache-busted imports.
+
+## Policy-Restricted Variant
+
+To test governance controls with this extension:
+
+1. Set `settings.extensions.policy.mode` to `warn` or `enforce`.
+2. Block one surface (for example `commands.override`).
+3. Re-run `pm extension --doctor --detail summary`.
+
+You should see `extension_policy_*` warnings and policy counters in `details.triage`.
+
+## CI-Friendly Verification Commands
 
 ```bash
-pm extension activate starter-extension --project
-pm starter ping --name "agent"
-pm extension doctor --detail summary
+pm contracts --command extension --flags-only --json
+pm extension --doctor --project --detail summary --strict-exit
+node scripts/run-tests.mjs test -- tests/unit/extension-loader.spec.ts tests/unit/extension-command.spec.ts
 ```
 
 ## Notes
 
-- This starter is for learning and scaffold reference.
-- Real extensions should declare only the capabilities they need.
-- Keep service, parser, and preflight overrides narrow and well tested.
-- Return deterministic JSON-like objects from command handlers.
+- Keep production manifests minimal: only declare capabilities you need.
+- Prefer command metadata (`action`, `examples`, `failure_hints`) for machine+human diagnostics.
+- Keep parser/preflight/service overrides narrow and deterministic.
+
+## Related Examples
+
+- `docs/examples/policy-restricted-extension/README.md`
+- `docs/examples/sdk-contract-consumer/README.md`

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

@@ -3,6 +3,21 @@
   "version": "0.1.0",
   "description": "SDK-first starter extension demonstrating all pm extension capabilities.",
   "entry": "./index.js",
+  "manifest_version": 2,
+  "trusted": true,
+  "provenance": {
+    "source": "docs/examples/starter-extension",
+    "verified": true
+  },
+  "sandbox_profile": "none",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": [
     "commands",
     "parser",

package/marketplace.json

@@ -1,5 +1,5 @@
 {
-  "name": "pm-cli",
+  "name": "pm",
   "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
   "owner": {
     "name": "unbrained",
@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "pm-cli",
-      "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, hybrid TUI task tracking, session context injection, and a coordination subagent for git-based project management without leaving Claude Code.",
-      "version": "1.2.0",
+      "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
+      "version": "1.3.0",
       "source": "./plugins/pm-cli-claude",
       "author": {
         "name": "unbrained",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.10",
+  "version": "2026.5.11",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",