@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/docs/SDK.md

@@ -1,5 +1,429 @@
 # SDK
 
+The supported programmatic surface is `@unbrained/pm-cli/sdk`.
+
+Use this package for extension authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations.
+
+## Install
+
+```bash
+npm install @unbrained/pm-cli
+```
+
+## Core Exports
+
+### Extension authoring
+
+- `defineExtension`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
+- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+- `EXTENSION_POLICY_MODES`
+- `EXTENSION_POLICY_SURFACES`
+- `EXTENSION_TRUST_MODES`
+- `EXTENSION_SANDBOX_PROFILES`
+
+### Command and action contracts
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+### Runtime contract constants
+
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
+- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
+- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
+- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
+
+### Type guards
+
+- `isPmToolAction`
+- `isPmExtensionCapabilityContract`
+- `isPmExtensionServiceNameContract`
+- `isPmExtensionPolicyModeContract`
+- `isPmExtensionPolicySurfaceContract`
+
+## Capability Mapping
+
+- `commands` -> `registerCommand`
+- `schema` -> `registerFlags`, `registerItemFields`, `registerItemTypes`, `registerMigration`
+- `importers` -> `registerImporter`, `registerExporter`
+- `search` -> `registerSearchProvider`, `registerVectorStoreAdapter`
+- `hooks` -> `api.hooks.*`
+- `parser` -> `registerParser`
+- `preflight` -> `registerPreflight`
+- `services` -> `registerService`
+- `renderers` -> `registerRenderer`
+
+## Extension Example
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "release audit",
+      action: "release-audit",
+      description: "Collect release-readiness diagnostics.",
+      intent: "Produce deterministic gate payloads for CI.",
+      flags: [{ long: "--strict", description: "Enable strict gate mode." }],
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+        strict: context.options.strict === true,
+      }),
+    });
+  },
+});
+```
+
+## Contracts-First Automation
+
+Use runtime contracts for extension-aware schemas:
+
+```bash
+pm contracts --json
+pm contracts --schema-only --json
+pm contracts --command extension --flags-only --json
+pm contracts --action create --schema-only --json
+```
+
+Minimal script pattern:
+
+```ts
+import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
+import { spawnSync } from "node:child_process";
+
+const action = "extension-reload";
+if (!isPmToolAction(action)) throw new Error("Unsupported action");
+const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
+console.log(contract.required, contract.optional);
+
+const result = spawnSync("pm", ["contracts", "--json"], { encoding: "utf8" });
+if (result.status !== 0) throw new Error(result.stderr);
+```
+
+## Compatibility Metadata
+
+`pm contracts --json` includes compatibility metadata for extension integrations:
+
+- `extension_contracts.trust_modes`
+- `extension_contracts.sandbox_profiles`
+- `extension_contracts.manifest_versions`
+- `extension_contracts.compatibility`
+- `action_availability[].policy_state`
+
+Current compatibility model:
+
+- manifest current: `v2`
+- supported previous: `v1`
+- strategy: `versioned_breaking`
+
+## Runnable Examples
+
+- `docs/examples/sdk-contract-consumer/`
+- `docs/examples/sdk-app-embedding/`
+- `docs/examples/ci/`
+
+## Related Docs
+
+- `docs/EXTENSIONS.md`
+- `docs/CLAUDE_CODE_PLUGIN.md`
+# SDK
+
+The supported programmatic surface is `@unbrained/pm-cli/sdk`.
+
+Use this for:
+
+- extension authoring (`defineExtension`)
+- command/action schema discovery (`PM_TOOL_PARAMETERS_SCHEMA`)
+- runtime action contracts (`PM_TOOL_ACTION_PARAMETER_CONTRACTS`)
+- capability/policy/trust/sandbox contract constants
+
+Do not import private `src/core/...` modules from external integrations.
+
+## Install
+
+```bash
+npm install @unbrained/pm-cli
+```
+
+## Key Exports
+
+### Extension Authoring
+
+- `defineExtension`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_POLICY_MODES`
+- `EXTENSION_POLICY_SURFACES`
+- `EXTENSION_TRUST_MODES`
+- `EXTENSION_SANDBOX_PROFILES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
+- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+
+### Command/Action Contracts
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+### Extension Runtime Contract Constants
+
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
+- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
+- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
+- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
+
+### Type Guards
+
+- `isPmToolAction`
+- `isPmExtensionCapabilityContract`
+- `isPmExtensionServiceNameContract`
+- `isPmExtensionPolicyModeContract`
+- `isPmExtensionPolicySurfaceContract`
+
+## Extension Example
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "release audit",
+      action: "release-audit",
+      description: "Collect release-readiness diagnostics.",
+      intent: "Produce deterministic gate payloads for CI.",
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+      }),
+    });
+  },
+});
+```
+
+## Contracts-First Automation Pattern
+
+```ts
+import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
+import { spawnSync } from "node:child_process";
+
+const action = "extension-reload";
+if (!isPmToolAction(action)) throw new Error("Unsupported action");
+const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
+console.log(contract.required, contract.optional);
+
+const contracts = spawnSync("pm", ["contracts", "--json"], { encoding: "utf8" });
+if (contracts.status !== 0) throw new Error(contracts.stderr);
+```
+
+## Runtime Metadata Added For v2
+
+`pm contracts --json` now includes richer extension metadata:
+
+- `extension_contracts.trust_modes`
+- `extension_contracts.sandbox_profiles`
+- `extension_contracts.manifest_versions`
+- `extension_contracts.compatibility`
+- `action_availability[].policy_state` for extension-backed actions
+
+Use these fields to gate CI and to route compatibility behavior in embedded runtimes.
+
+## Versioned-Breaking Compatibility
+
+Current contract compatibility model:
+
+- `manifest` current: `v2`
+- supported previous: `v1`
+- strategy: `versioned_breaking`
+
+Recommended migration flow:
+
+1. read runtime contracts (`pm contracts --json`)
+2. branch behavior by compatibility metadata
+3. migrate manifests/policy to v2
+4. enforce trust/sandbox policy gates in CI
+
+## Runnable Examples
+
+- contracts consumer: `docs/examples/sdk-contract-consumer/`
+- app embedding runner: `docs/examples/sdk-app-embedding/`
+- CI gates: `docs/examples/ci/`
+
+## Related Docs
+
+- `docs/EXTENSIONS.md`
+- `docs/CLAUDE_CODE_PLUGIN.md`
+# SDK
+
+The stable integration surface is `@unbrained/pm-cli/sdk`. Use it for extension authoring, action/flag contract discovery, and deterministic app/CI automation.
+
+## Install
+
+```bash
+npm install @unbrained/pm-cli
+```
+
+```ts
+import {
+  defineExtension,
+  EXTENSION_CAPABILITIES,
+  EXTENSION_POLICY_MODES,
+  EXTENSION_POLICY_SURFACES,
+  PM_TOOL_ACTIONS,
+  PM_TOOL_PARAMETERS_SCHEMA,
+  PM_TOOL_ACTION_PARAMETER_CONTRACTS,
+  PM_EXTENSION_CAPABILITY_CONTRACTS,
+  PM_EXTENSION_SERVICE_NAME_CONTRACTS,
+  PM_EXTENSION_POLICY_MODE_CONTRACTS,
+  PM_EXTENSION_POLICY_SURFACE_CONTRACTS,
+  isPmToolAction,
+  isPmExtensionCapabilityContract,
+} from "@unbrained/pm-cli/sdk";
+```
+
+## What Is Exported
+
+Core authoring exports:
+
+- `defineExtension`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_POLICY_MODES`
+- `EXTENSION_POLICY_SURFACES`
+
+Command/action contract exports:
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+Extension runtime contract exports:
+
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
+- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
+
+Type guards:
+
+- `isPmToolAction(value)`
+- `isPmExtensionCapabilityContract(value)`
+- `isPmExtensionServiceNameContract(value)`
+- `isPmExtensionPolicyModeContract(value)`
+- `isPmExtensionPolicySurfaceContract(value)`
+
+## Capability Mapping
+
+- `commands` -> `registerCommand`
+- `schema` -> `registerFlags`, `registerItemFields`, `registerItemTypes`, `registerMigration`
+- `importers` -> `registerImporter`, `registerExporter`
+- `search` -> `registerSearchProvider`, `registerVectorStoreAdapter`
+- `hooks` -> `api.hooks.*`
+- `parser` -> `registerParser`
+- `preflight` -> `registerPreflight`
+- `services` -> `registerService`
+- `renderers` -> `registerRenderer`
+
+## Extension Authoring Example
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "release audit",
+      action: "release-audit",
+      description: "Collect release readiness diagnostics.",
+      intent: "provide deterministic audit payloads for CI gates",
+      examples: ["pm release audit --strict"],
+      failure_hints: ["Run pm extension --doctor --detail deep --trace on activation failures."],
+      flags: [{ long: "--strict", description: "Enable strict gate mode." }],
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+        strict: context.options.strict === true,
+      }),
+    });
+  },
+});
+```
+
+## Programmatic Contracts (App/Script)
+
+Use runtime `pm contracts` for extension-aware schemas:
+
+```bash
+pm contracts --json
+pm contracts --schema-only --json
+pm contracts --command extension --flags-only --json
+pm contracts --action create --schema-only --json
+```
+
+The result includes:
+
+- `actions`: runtime-invocable action list
+- `action_availability`: invocable/disabled reasons
+- `schema`: strict action-scoped JSON schema
+- `command_flags`: merged core + extension + runtime field flags
+- `extension_contracts`: capabilities/services/policy mode/surface contract metadata
+
+## Robust Script Pattern
+
+See runnable example: `docs/examples/sdk-contract-consumer/inspect-contracts.mjs`.
+
+Minimal pattern:
+
+1. Read contracts JSON.
+2. Validate action exists in `actions`.
+3. Validate required fields with `PM_TOOL_ACTION_PARAMETER_CONTRACTS`.
+4. Execute the action only after preflight passes.
+
+## CI/CD Pattern
+
+Recommended gate sequence:
+
+```bash
+pnpm build
+pm contracts --schema-only --json > /tmp/pm-contracts.json
+pm extension --doctor --project --detail summary --strict-exit
+node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts
+node scripts/run-tests.mjs coverage
+```
+
+Reference workflow file:
+
+- `docs/examples/ci/github-actions-pm-extension-gate.yml`
+
+## Pi / Tooling Compatibility
+
+For provider-safe schemas, use `PM_PI_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs.
+
+The bundled Pi wrapper (`.pi/extensions/pm-cli/index.js`) consumes this schema directly to reduce contract drift.
+
+## Related Docs
+
+- `docs/EXTENSIONS.md`
+- `docs/examples/starter-extension/README.md`
+- `docs/examples/sdk-contract-consumer/README.md`
+# SDK
+
 The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension authoring and command-contract introspection. Do not import internal `src/core/...` modules from extensions.
 
 ## Agent Quick Context
@@ -7,6 +431,7 @@ The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension au
 - Primary import: `@unbrained/pm-cli/sdk`.
 - Runtime extension lifecycle is documented in [Extensions](EXTENSIONS.md).
 - Exact command/action contracts are available through `pm contracts`.
+- Local deep-dive routing is available through `pm guide sdk --depth deep`.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -144,8 +569,8 @@ export default defineExtension({
       name: "example-search",
       async query(context) {
         return context.documents
-          .filter((doc) => doc.front_matter.title?.toLowerCase().includes(context.query.toLowerCase()))
-          .map((doc) => ({ id: doc.front_matter.id, score: 0.5, matched_fields: ["title"] }));
+          .filter((doc) => doc.metadata.title?.toLowerCase().includes(context.query.toLowerCase()))
+          .map((doc) => ({ id: doc.metadata.id, score: 0.5, matched_fields: ["title"] }));
       },
     });
   },
@@ -166,6 +591,22 @@ pm contracts --action create --schema-only --json
 
 Use the runtime command because active extensions can add command/action metadata.
 
+## CLI Simplification Migration
+
+The conservative full-surface simplification pass updated invocation parsing and error envelopes. Integration details are documented in:
+
+- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
+
+For SDK and automation consumers, the key runtime change is the optional `recovery` object in CLI usage/error JSON payloads:
+
+- `attempted_command`
+- `normalized_args`
+- `provided_fields`
+- `missing`
+- `suggested_retry`
+
+Treat `recovery.suggested_retry` as the first-choice deterministic replay command when present.
+
 ## Authoring Pattern
 
 - Keep handlers deterministic and JSON-like.
@@ -178,5 +619,6 @@ Use the runtime command because active extensions can add command/action metadat
 ## Related Docs
 
 - [Extensions](EXTENSIONS.md)
+- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
 - [Architecture](ARCHITECTURE.md)
 - [starter extension](examples/starter-extension/README.md)

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