@unbrained/pm-cli 2026.5.10 → 2026.5.12

package/docs/MIGRATION_CLI_SIMPLIFICATION.md

@@ -0,0 +1,64 @@
+# CLI Simplification Migration (Conservative Full-Surface Pass)
+
+This note documents behavioral and output-shape changes introduced in the conservative CLI simplification pass.
+
+## What Changed
+
+### 1) Command invocation normalization before Commander parse
+
+`pm` now normalizes invocation tokens before Commander parses them:
+
+- long-flag shape normalization (`--foo_bar` / camel variants -> canonical kebab flags)
+- high-confidence typo normalization for long flags
+- `key=value` / `key:value` promotion into canonical `--flag value` tokens when unambiguous
+- legacy `pm extension <action>` shorthand normalization to explicit action flags
+
+Normalization runs across command families and preserves a normalization trace for diagnostics and recovery.
+
+### 2) Setup-agnostic PM root discovery
+
+`resolvePmRoot()` precedence is now:
+
+1. explicit `--path`
+2. `PM_PATH`
+3. upward discovery of initialized `.agents/pm` roots (must contain `settings.json`)
+4. local default (`<cwd>/.agents/pm`)
+
+If you need the old local-only behavior from nested directories, pass an explicit path (`--path .agents/pm`).
+
+### 3) Structured recovery bundles in CLI error output
+
+Error payloads now include optional `recovery` metadata in text and JSON guidance surfaces:
+
+- `attempted_command`
+- `normalized_args`
+- `provided_fields`
+- `missing`
+- `suggested_retry`
+
+Automation should read this bundle for deterministic retries instead of rebuilding retries from free-form error text.
+
+### 4) Legacy `none`/`null` compatibility in create/update
+
+For deterministic compatibility:
+
+- scalar `none` / `null` values on unset-capable fields are reinterpreted as `--unset <field>`
+- repeatable `none` / `null` values are reinterpreted as their matching `--clear-*` action
+- mixed legacy clear token + concrete repeatable payloads remain rejected (ambiguous input)
+
+## Migration Guidance for Automation
+
+- **Prefer contracts first**: keep using `pm contracts --json` and command-scoped flag contracts.
+- **Consume `recovery` directly**: treat `recovery.suggested_retry` as first-choice replay command.
+- **Do not hardcode old error envelopes**: parsers should tolerate additional fields (`recovery`) and richer guidance text.
+- **Avoid relying on local cwd-only root resolution**: pass `--path` explicitly when wrappers need fixed data roots.
+- **Update none/null assumptions**: if your tests expected hard failures for pure `none`/`null` clear intents, update them to expect deterministic clear/unset behavior.
+
+## Verification Checklist
+
+- `tests/unit/bootstrap-args.spec.ts`
+- `tests/unit/store-paths.spec.ts`
+- `tests/integration/help-runtime.spec.ts`
+- `tests/unit/create-command.spec.ts`
+- `tests/unit/update-command.spec.ts`
+

package/docs/QUICKSTART.md

@@ -23,10 +23,10 @@ pm --version
 For updates, use the registry package again:
 
 ```bash
-npm install -g @unbrained/pm-cli@latest
+pm upgrade --cli-only
 ```
 
-Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `bash scripts/install.sh --repair` from a checkout or uninstall the package before reinstalling from npm.
+`pm upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm.
 
 For one-off use:
 
@@ -34,6 +34,14 @@ For one-off use:
 npx @unbrained/pm-cli --help
 ```
 
+Optional first-party packages are installable on demand:
+
+```bash
+pm install '*' --project
+pm install all --project
+pm package doctor --project --detail summary
+```
+
 ## Initialize a Repository
 
 ```bash

package/docs/README.md

@@ -21,8 +21,7 @@ pm guide release --json
 | New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
-| Extension author | [Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
-| Pi user | [Pi Package](PI_PACKAGE.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
+| Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm guide commands` | [Command Reference](COMMANDS.md#machine-contracts), then `pm contracts --json` |
 
@@ -34,9 +33,8 @@ pm guide release --json
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
-- [Extensions](EXTENSIONS.md) - runtime extension lifecycle and API reference.
+- [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
-- [Pi Package](PI_PACKAGE.md) - official Pi package install, native tool, skills, prompts, and workflows.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
@@ -49,7 +47,7 @@ pm guide release --json
 | `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
 | `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
 | `sdk` | [SDK](SDK.md), [Architecture](ARCHITECTURE.md) |
-| `extensions` | [Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
+| `extensions`, `packages` | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
 | `skills` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*` |
 | `harnesses` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md` |
 | `release` | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md) |
@@ -68,7 +66,7 @@ Community files:
 2. Use [Command Reference](COMMANDS.md) for command families, not exhaustive flag memory.
 3. Use `pm <command> --help --json` or `pm contracts --command <name> --flags-only --json` for exact flags.
 4. Use [Architecture](ARCHITECTURE.md) only when changing internals or debugging behavior.
-5. Use [SDK](SDK.md) and [Extensions](EXTENSIONS.md) only when authoring or troubleshooting extensions.
+5. Use [SDK](SDK.md) and [Packages and Extensions](EXTENSIONS.md) only when authoring or troubleshooting packages/extensions.
 
 ## Tracker References
 

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_PROVIDER_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+`PM_TOOL_ACTIONS` includes the package lifecycle actions and `upgrade`, so agents and apps can discover `pm upgrade` through `pm contracts` instead of hard-coding flags.
+
+### 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 package --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 = "package-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_PROVIDER_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_PROVIDER_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 package 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 package --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 package 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`
+
+## Tooling Compatibility
+
+For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs. Agent-specific adapters should consume this SDK export from their own packages instead of adding agent runtime code to the main `pm` CLI.
+
+## 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
@@ -36,6 +460,10 @@ Common authoring exports:
 - `EXTENSION_CAPABILITY_CONTRACT`
 - `EXTENSION_CAPABILITY_CONTRACT_VERSION`
 - `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+- `PM_PACKAGE_RESOURCE_KINDS`
+- `PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS`
+- `readPmPackageManifest`
+- `collectPackageExtensionDirectories`
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
@@ -167,6 +595,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.
@@ -179,5 +623,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