@unbrained/pm-cli 2026.6.21 → 2026.6.23

package/docs/SDK.md

@@ -36,6 +36,8 @@ Source of truth:
 Common authoring exports:
 
 - `defineExtension`
+- `composeExtension` / `deriveExtensionCapabilities`
+- `describeExtensionBlueprint` (static surface map of a blueprint) / `lintExtensionBlueprint` (author-time preflight)
 - `EXTENSION_CAPABILITIES`
 - `EXTENSION_CAPABILITY_CONTRACT`
 - `EXTENSION_CAPABILITY_CONTRACT_VERSION`
@@ -48,6 +50,14 @@ Common authoring exports:
 - `createPmCliExpectedError`
 - `isPmCliExpectedError`
 
+Registration builders (`define*`, zero-cost identity — see [Authoring Builders](#authoring-builders)):
+
+- `defineCommand` / `defineFlag` / `defineItemType` / `defineItemField` / `defineMigration`
+- `defineSearchProvider` / `defineVectorStoreAdapter`
+- `defineCommandOverride` / `defineParserOverride` / `definePreflightOverride` / `defineServiceOverride` / `defineRendererOverride`
+- `defineImporter` / `defineExporter`
+- `defineBeforeCommandHook` / `defineAfterCommandHook` / `defineOnWriteHook` / `defineOnReadHook` / `defineOnIndexHook`
+
 Package manifest exports:
 
 - `PM_PACKAGE_RESOURCE_KINDS` (`extensions`, `docs`, `examples`, `assets`, `prompts`)
@@ -73,7 +83,22 @@ Command/action contract exports:
 
 Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 
+- `createExtensionTestHarness`
 - `activateExtensionForTest`
+- `deactivateExtensionForTest`
+- `runRegisteredCommandForTest`
+- `runRegisteredHookForTest`
+- `runRegisteredParserOverrideForTest`
+- `runRegisteredPreflightOverrideForTest`
+- `runRegisteredCommandOverrideForTest`
+- `runRegisteredRendererOverrideForTest`
+- `runRegisteredServiceOverrideForTest`
+- `runRegisteredSearchProviderForTest`
+- `runRegisteredVectorStoreAdapterForTest`
+- `runRegisteredMigrationForTest`
+- `runRegisteredImporterForTest`
+- `runRegisteredExporterForTest`
+- `assertExtensionDeactivated`
 - `assertPackageManifest`
 - `assertRegisteredCommandContract`
 - `assertRegisteredFlags`
@@ -90,6 +115,171 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredItemType`
 - `assertRegisteredServiceOverride`
 - `assertRegisteredMigration`
+- `assertExtensionCapabilityUsage`
+- `assertExtensionBlueprint` (throwing preflight; pairs with `lintExtensionBlueprint`)
+- `describeExtensionActivation`
+- `describeExtensionBlueprint` / `lintExtensionBlueprint` (also surfaced here for the full author → describe → preflight → test loop)
+
+`createExtensionTestHarness(module, options)` is the recommended entry point and
+the ergonomic capstone over every standalone helper below: it activates the
+module once and returns a fluent `ExtensionTestHarness` whose `assert*`/`run*`
+methods are pre-bound to the correct activation sub-registry, so a package author
+never threads `activation.registrations` vs `activation.commands` vs
+`activation.hooks` (etc.) by hand — picking the wrong one is a common footgun that
+surfaces as a confusing `available: (none)` error. Write
+`const ext = await createExtensionTestHarness(module, { capabilities: ["commands"] })`,
+then `ext.assertCommandContract({ command })`, `await ext.runCommand({ command })`,
+and `await ext.deactivate()`. The methods do not use `this`, so they remain safe
+to destructure (`const { runCommand } = ext;`), and the raw `ext.activation`
+stays public as an escape hatch to the standalone helpers for any surface a
+convenience method does not cover.
+
+`assertExtensionCapabilityUsage(activation, { declared })` is the least-privilege
+counterpart of the per-surface `assertRegistered*` helpers: pass the same
+capabilities as your `manifest.capabilities` and it fails the test when the
+manifest grants a capability the extension never registers against. Use
+`allowUnused` for capabilities a runtime registers only behind a config flag.
+
+`deactivateExtensionForTest(module, options)` is the teardown counterpart to
+`activateExtensionForTest`: it runs pm's real `deactivateExtensions` engine
+(including the bounded per-hook timeout and best-effort failure capture) over the
+module and returns the `ExtensionDeactivationResult`, so a package can prove its
+`deactivate` releases the resources `activate` opened. `assertExtensionDeactivated(result)`
+asserts the single-extension happy path (one extension deactivated, none failed)
+by default; pass `{ deactivated, failed }` to assert other counts. Forward the
+`activation` result and `deactivateTimeoutMs` to mirror real host teardown.
+
+`runRegisteredCommandForTest(activation.commands, { command, args, options, global, pmRoot })`
+is the "invoke" verb that completes the package-author testing loop —
+`activateExtensionForTest` → `assertRegisteredCommandContract` → **run** →
+`deactivateExtensionForTest`. It dispatches a registered command handler through
+pm's real engine and returns the `CommandHandlerResult`, so a test can assert
+*behavior* (`result.result`) rather than only that the command is wired. The
+`CommandHandlerContext` is built with agent-safe global defaults
+(`{ json: true, quiet: true, noPager: true }`) that callers may override. A clean
+run yields `{ handled: true, result, warnings: [] }`; a handler that throws a
+non-exit error yields `{ handled: false, warnings: [code], errorMessage }` so the
+failure can be asserted, while one that throws an error carrying a numeric
+`exitCode` propagates the throw. An unregistered command throws a descriptive
+error listing the available handler command paths. Because
+`registerImporter`/`registerExporter` register handlers under `"<name> import"` /
+`"<name> export"`, the same helper exercises importer and exporter handlers too.
+
+The remaining runtime surfaces an extension can register have matching invoke
+helpers, so the "invoke" verb covers the whole command pipeline — not just
+command handlers:
+
+- `runRegisteredHookForTest(activation.hooks, { kind, context })` fires every
+  registered lifecycle hook of a `kind` (`before_command` | `after_command` |
+  `on_read` | `on_write` | `on_index`) through pm's real hook runner and returns
+  the warnings array (`[]` = clean; a thrown hook contributes one
+  `extension_hook_failed:*` warning while the others still run). The `context` is
+  type-safe per `kind`.
+- `runRegisteredParserOverrideForTest(activation.parsers, context)` returns the
+  rewritten `ParserOverrideResult` (args/options/global the override produces
+  before dispatch).
+- `runRegisteredPreflightOverrideForTest(activation.preflight, context)` returns
+  the `PreflightOverrideResult` (the migration/format gate decision).
+- `runRegisteredCommandOverrideForTest(activation.commands, context)` returns the
+  `CommandOverrideResult` (the transformed command result payload).
+- `runRegisteredRendererOverrideForTest(activation.renderers, context)` returns
+  the `RendererOverrideResult` (the custom string rendered for an output format).
+- `runRegisteredServiceOverrideForTest(activation.services, context)` returns the
+  `ServiceOverrideResult` (how the override handles an internal service payload).
+
+Each override helper guards that a matching override is registered for the target
+(command / format / service), so a typo surfaces as a descriptive error rather
+than a silent `overridden: false` / `handled: false`.
+
+The *executable registration* surfaces — search providers, vector store
+adapters, schema migrations, importers, and exporters — also have invoke helpers,
+so every executable register\* method has both an `assertRegistered*` and a
+`runRegistered*ForTest` counterpart. Each exercises the real registered behavior,
+not a re-implementation, but along two execution paths that mirror how the host
+runs them. Providers, adapters, and migrations are resolved through the same
+runtime resolver the host uses and invoked via their `runtime_definition` (the
+clone that preserves live functions). Importers and exporters have no standalone
+`runtime_definition` — `registerImporter`/`registerExporter` wrap their handler
+into a command path, so their helpers resolve by name and dispatch through the
+command runner instead, returning a `CommandHandlerResult`:
+
+- `runRegisteredSearchProviderForTest(activation.registrations, { provider, operation, context })`
+  resolves a registered provider by name (case-insensitive, last registration
+  wins) and invokes one `operation` — `query`, `embed`, `embedBatch`,
+  `queryExpansion`, or `rerank` — returning that operation's result. The
+  `context` and return type are inferred from `operation`, and the camelCase /
+  snake_case spellings the host accepts (`embedBatch`/`embed_batch`,
+  `queryExpansion`/`query_expansion`) both resolve.
+- `runRegisteredVectorStoreAdapterForTest(activation.registrations, { adapter, operation, context })`
+  resolves a registered adapter by name and invokes `query` (returns
+  `VectorStoreQueryHit[]`), `upsert`, or `delete`.
+- `runRegisteredMigrationForTest(activation.registrations, { migration, extensionName?, pmRoot? })`
+  resolves a registered migration by id and invokes its `run` with a context
+  mirroring the host's (`command: "migration"`, the registering extension's
+  layer/name, the supplied `pmRoot`, and the migration's normalized status),
+  returning whatever `run` returns. Unlike the host — which skips applied
+  migrations and folds a throw into a warning — it always invokes `run` and lets a
+  throw propagate, so both success and failure are assertable.
+- `runRegisteredImporterForTest(activation, { importer, extensionName?, args?, options?, global?, pmRoot? })`
+  and `runRegisteredExporterForTest(activation, { exporter, ... })` resolve a
+  registered importer/exporter by name, derive the `"<name> import"` /
+  `"<name> export"` command path internally — so authors never hand-build it — and
+  validate that the name is genuinely a registered importer/exporter before
+  dispatching. They take the whole `activation` because resolution spans two
+  sub-registries (`registrations` proves it exists, `commands` holds the wrapped
+  handler), and they return the command runner's `CommandHandlerResult` verbatim,
+  so `handled`/`warnings`/`errorMessage` semantics and `exitCode` propagation match
+  invoking the importer/exporter as a command.
+
+Each surface helper guards that the named provider / adapter / migration /
+importer / exporter is registered (and, for providers and adapters, implements the
+requested operation), so a typo surfaces as a descriptive error rather than a
+silent no-op. All invoke helpers are `async`, so a test always `await`s them.
+
+`describeExtensionActivation(activation, { extensionName })` is the **describe**
+(enumerate-all) verb that complements the `assertRegistered*` (verify-one) and
+`runRegistered*ForTest` (invoke-one) helpers. The activation result already
+carries per-surface *counts*; this returns the *names*. It walks every
+sub-registry once and returns a flat `ExtensionActivationSummary` whose arrays
+are de-duplicated and locale-sorted (except `hooks`, emitted in canonical
+lifecycle order to mirror `hook_counts`) of every registered surface's
+identifiers — command paths, hook kinds, item-type /
+field names, migration ids, importer / exporter / provider / adapter names,
+overridden service names and renderer formats, flag target-commands, and the
+preflight-override count — plus the `capabilities` those surfaces exercise. Two
+uses:
+
+```ts
+import { describeExtensionActivation } from "@unbrained/pm-cli/sdk/testing";
+
+const summary = describeExtensionActivation(activation);
+// Least-privilege check: assert the WHOLE registration surface in one deepEqual.
+assert.deepEqual(summary.commands, ["greet hello"]);
+assert.deepEqual(summary.hooks, ["after_command"]);
+assert.deepEqual(summary.capabilities, ["commands", "hooks"]);
+```
+
+Without `extensionName` the summary unions every extension in the activation;
+with it (matched case-insensitively after trimming, like
+`collectUsedExtensionCapabilities`) only that extension's registrations
+contribute. The three command fields capture distinct dimensions and can
+overlap: `commands` lists definitions declared via `registerCommand(definition)`,
+`command_handlers` lists every command path backed by an extension handler (a
+superset that also includes the synthesized `"<name> import"` / `"<name> export"`
+importer/exporter paths), and `command_overrides` lists built-in commands
+replaced via `registerCommand(name, override)`. For agents, one call returns the
+entire surface instead of traversing fifteen-plus sub-registries — keeping the context
+window lean ("project management = context management").
+
+The same verb is reachable from the CLI and MCP without writing a test:
+`pm extension describe [name]` / `pm package describe [name]` (and `pm_run` with
+`action: "extension"`/`"package"` and `describe: true`) activate the workspace's
+extensions and return each loaded extension's `ExtensionActivationSummary` under
+`details.extensions[].surfaces`, plus a deduplicated `details.union`. Omit the name
+to map every loaded package; pass one to scope to it. This is the agent-facing answer
+to "what does this installed package add to my context?" — distinct from
+`pm package doctor` (errors/policy) and `pm package manage` (update metadata), which
+report only command/action paths, not the full registration surface.
 
 Commander option contract exports:
 
@@ -116,9 +306,17 @@ Extension runtime contract exports:
 - `PM_EXTENSION_TRUST_MODE_CONTRACTS`
 - `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
 
+Least-privilege capability reconciliation exports (map declared capabilities to
+the registration surfaces a package actually exercises at activation):
+
+- `EXTENSION_CAPABILITY_REGISTRATION_SURFACES`
+- `collectUsedExtensionCapabilities`
+- `reconcileExtensionCapabilityUsage`
+
 Common types:
 
 - `ExtensionApi`
+- `ExtensionActivationSummary`
 - `ExtensionManifest`
 - `ExtensionManifestEngines`
 - `CommandDefinition`
@@ -196,26 +394,18 @@ assertPackageManifest(manifest, {
 ```
 
 Package tests can also assert extension registrations without importing private
-loader internals. Use `activateExtensionForTest` plus the targeted assertion for
-the surface your package owns:
+loader internals. Prefer `createExtensionTestHarness` — its `assert*`/`run*`
+methods bind to the right sub-registry for you:
 
 ```ts
-import {
-  activateExtensionForTest,
-  assertRegisteredCommandContract,
-  assertRegisteredFlags,
-} from "@unbrained/pm-cli/sdk/testing";
+import { createExtensionTestHarness } from "@unbrained/pm-cli/sdk/testing";
 
-const activation = await activateExtensionForTest(extensionModule);
+const ext = await createExtensionTestHarness(extensionModule, { capabilities: ["commands", "schema"] });
 
-assertRegisteredCommandContract(activation.registrations, {
-  command: "incident triage",
-  flags: ["--severity"],
-});
-assertRegisteredFlags(activation.registrations, {
-  targetCommand: "list",
-  flags: ["--incident-filter"],
-});
+ext.assertCommandContract({ command: "incident triage", flags: ["--severity"] });
+ext.assertFlags({ targetCommand: "list", flags: ["--incident-filter"] });
+const { result } = await ext.runCommand({ command: "incident triage", options: { severity: "high" } });
+await ext.deactivate();
 ```
 
 For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat and avoids advanced schema constructs such as root `oneOf`.
@@ -282,6 +472,16 @@ Manifest:
   "version": "0.1.0",
   "entry": "./index.js",
   "pm_min_version": "2026.5.31",
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": false,
+    "fs_write": false,
+    "network": false,
+    "env_read": false,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["commands"]
 }
 ```
@@ -300,11 +500,27 @@ Manifest typing also accepts optional `engines` metadata:
 ```
 
 Use `pm_min_version` for the loader gate. Keep `engines` as package-manager and tooling metadata.
+For pure command packages, keep `trusted: true`, `sandbox_profile: "strict"`, and all six permissions set to `false`; relax only the permission keys the package actually needs and verify the result with `pm package doctor --project --detail deep --trace`.
 
 For a complete commands-capability package that combines `registerCommand`,
 `registerFlags`, and `registerParser`, see the first-party
 [pm-command-kit exemplar](../packages/pm-command-kit/README.md).
 
+For a generated starter, use `pm package init ./my-package`. Pass
+`--capability hooks` to scaffold a command plus an `afterCommand` lifecycle
+reactor and a runnable `node:test` file that exercises
+`activateExtensionForTest`, `assertRegisteredHook`, `runRegisteredHookForTest`,
+and `deactivateExtensionForTest`. Pass `--capability search` to scaffold a
+command plus a deterministic search provider/vector-store adapter pair and a
+runnable `node:test` file that exercises `assertRegisteredSearchProvider`,
+`assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and
+`runRegisteredVectorStoreAdapterForTest`. Pass `--capability importers` to
+scaffold paired import/export commands with example flag metadata and a runnable
+`node:test` file that exercises `assertRegisteredImporter`,
+`assertRegisteredExporter`, `runRegisteredImporterForTest`, and
+`runRegisteredExporterForTest`; the generated manifest declares both `importers`
+and `schema` because extension flag metadata is schema-governed.
+
 ## Self-Identity and Lifecycle
 
 `activate(api)` receives a read-only `api.extension` describing the extension it
@@ -410,6 +626,153 @@ import { createPmCliExpectedError } from "@unbrained/pm-cli/sdk/runtime";
 
 `PM_CLI_PACKAGE_ROOT` is reserved for first-party packages bundled inside this repository. Those packages use it to locate the running CLI's `dist/sdk/runtime.js` before they are installed as independent npm packages. External packages must not depend on `PM_CLI_PACKAGE_ROOT`, `dist/` paths, or `src/core/...`; declare `@unbrained/pm-cli` as a dependency or peer dependency and import the public SDK subpaths instead. When pm installs a registry package, it links that dependency to the running host CLI so the package gets the active SDK without downloading a second CLI copy into the project.
 
+## Authoring Builders
+
+Tracked: [pm-12tj](../.agents/pm/features/pm-12tj.toon) (design rationale: ADR [pm-3mph](../.agents/pm/decisions/pm-3mph.toon)).
+
+The `define*` builders are the authoring half of the `author → register → test`
+loop: they type a registration definition where you write it, before it ever
+reaches `api.register*`. Each is a zero-cost identity function (it returns its
+argument unchanged), exactly like `defineExtension` and the wider
+`defineConfig`/`defineComponent` ecosystem convention — the value is entirely at
+the type level.
+
+This matters most in **plain-JavaScript packages** (the default `pm package init`
+scaffold). A bare `const cmd = { ... }` is unchecked because JS has no type
+annotations; wrapping it in a builder restores full contract checking and infers
+the nested handler's `context` parameter through the editor's TypeScript language
+service. It also lets you colocate, export, reuse, and unit-test a definition
+apart from `activate`:
+
+```js
+import { defineCommand, defineAfterCommandHook } from "@unbrained/pm-cli/sdk";
+
+// `context` is inferred even though this is a .js file with no annotations.
+export const greetCommand = defineCommand({
+  name: "greet hello",
+  action: "greet-hello",
+  description: "Say hello.",
+  run: (context) => ({ greeting: `hi ${context.args[0] ?? "world"}` }),
+});
+
+export const auditHook = defineAfterCommandHook((context) => {
+  if (!context.ok) return;
+  // react to context.affected — "project management = context management"
+});
+
+export function activate(api) {
+  api.registerCommand(greetCommand);
+  api.hooks.afterCommand(auditHook);
+}
+```
+
+Object-definition builders (`defineExtensionManifest`, `defineCommand`,
+`defineFlag`, `defineItemType`, `defineItemField`, `defineMigration`,
+`defineSearchProvider`, `defineVectorStoreAdapter`) preserve the narrow literal
+type. `defineExtensionManifest` additionally contract-checks the in-module
+manifest mirror where it is authored and pairs with `deriveExtensionCapabilities`
+(see [Declarative Authoring](#declarative-authoring)). Function-definition
+builders (`defineCommandOverride`, `defineParserOverride`,
+`definePreflightOverride`, `defineServiceOverride`, `defineRendererOverride`,
+`defineImporter`, `defineExporter`, and the five hook builders
+`defineBeforeCommandHook` / `defineAfterCommandHook` / `defineOnWriteHook` /
+`defineOnReadHook` / `defineOnIndexHook`) are non-generic so a bare arrow's
+parameter is contextually typed instead of falling back to `any`. The
+[`assertRegistered*`](#testing-helpers) helpers below verify these same
+definitions once registered.
+
+## Declarative Authoring
+
+Tracked: [pm-iqq0](../.agents/pm/features/pm-iqq0.toon).
+
+`composeExtension` is the capstone of the `author → register → test` loop. Instead
+of hand-wiring each `api.register*` call inside an imperative `activate(api)`
+body — calling the right method, in the right order, without forgetting one —
+describe **what** to register as a plain `ExtensionBlueprint` object and let the
+SDK generate the `activate` for you. Every field is optional; populate the
+surfaces you use (ideally with `define*`-authored definitions) and leave the rest
+out:
+
+```js
+import { composeExtension, defineCommand, deriveExtensionCapabilities } from "@unbrained/pm-cli/sdk";
+
+const echo = defineCommand({
+  name: "command-kit echo",
+  action: "command-kit-echo",
+  description: "Echo a message as structured output.",
+  run: (context) => ({ message: context.args.join(" ") }),
+});
+
+const blueprint = {
+  commands: [echo],
+  parsers: { "command-kit echo": (context) => ({ options: context.options }) },
+  flags: { list: [{ long: "--kit-note", value_type: "string", value_name: "text" }] },
+};
+
+// The generated `activate` registers commands → overrides → flags → parsers →
+// renderers → services → preflights → item types → item fields → migrations →
+// search providers → vector store adapters → importers → exporters → hooks, then
+// awaits any imperative `activate` you also pass (an escape hatch run last).
+export default composeExtension(blueprint);
+```
+
+`deriveExtensionCapabilities(blueprint)` returns the exact least-privilege
+capability set the blueprint exercises (sorted, de-duplicated), so you can author
+`manifest.json` `capabilities` with zero declared-but-unused or used-but-undeclared
+drift. It is the author-time inverse of the runtime
+[`reconcileExtensionCapabilityUsage`](#capability-requirements) check, and the set
+it returns is the set `composeExtension`'s generated `activate` requires — they
+agree by construction:
+
+```js
+deriveExtensionCapabilities(blueprint); // ["commands", "parser", "schema"]
+```
+
+The blueprint's record-keyed fields (`commandOverrides`, `flags`, `parsers`,
+`renderers`, `services`) map a routing key to its handler, mirroring the
+two-argument `api.register*` overloads; `hooks` groups the five lifecycle kinds.
+`composeExtension` is a pure assembler: it does not validate definitions —
+per-surface contract enforcement stays in `api.register*` and the loader, so a
+malformed definition surfaces the same activation diagnostic as a hand-written
+`activate`. The bundled first-party packages intentionally keep import-free
+hand-written `activate` bodies so they load in extension-only installs; reach for
+`composeExtension` in npm package-mode authoring where the SDK is a dependency.
+
+### Author-time introspection and preflight
+
+Tracked: [pm-tlpv](../.agents/pm/features/pm-tlpv.toon),
+[pm-9ect](../.agents/pm/features/pm-9ect.toon),
+[pm-4oio](../.agents/pm/decisions/pm-4oio.toon).
+
+Two pure, no-activation helpers complete the loop, so a blueprint is fully
+inspectable and verifiable before it is ever loaded — the author-time inverse of
+the runtime guardrails (the same discipline as `deriveExtensionCapabilities`
+inverting [`reconcileExtensionCapabilityUsage`](#capability-requirements)):
+
+```js
+import { describeExtensionBlueprint, lintExtensionBlueprint } from "@unbrained/pm-cli/sdk";
+
+// describeExtensionBlueprint returns the same ExtensionActivationSummary shape as
+// the runtime describeExtensionActivation — but from the blueprint data alone, no
+// activation. It is to the named surfaces what deriveExtensionCapabilities is to
+// the capability set.
+describeExtensionBlueprint(blueprint).command_handlers; // ["command-kit echo", ...]
+
+// lintExtensionBlueprint preflights for the footguns activation would otherwise
+// surface late: a capability a surface exercises but the manifest omits is an
+// `error` (the loader throws extension_capability_missing); a declared-but-unused
+// capability, a duplicate command, a command/override conflict, and a present-but-
+// empty surface are `warning`s. Pass declaredCapabilities or set manifest.capabilities.
+const report = lintExtensionBlueprint(blueprint, { declaredCapabilities: ["commands", "parser", "schema"] });
+report.ok;       // false if any error-severity finding
+report.findings; // [{ code, severity, message, capability?/command?/field? }, ...]
+```
+
+Both read only the declarative data, so the imperative `activate` escape hatch is
+invisible to them — a blueprint that registers everything through that hatch
+summarizes as empty and lints clean. In a package test, `assertExtensionBlueprint`
+(below) turns the lint into a one-line CI guard.
+
 ## Testing Helpers
 
 Package tests can assert registration contracts without depending on Vitest-specific
@@ -457,6 +820,96 @@ guardrails, but it does not discover files or install packages. Use it for unit
 tests of extension registration shape; keep `pm package doctor` and runtime
 contracts in integration tests.
 
+For declarative (`composeExtension`) packages, `assertExtensionBlueprint(blueprint, options?)`
+is the `assert*` family member that preflights the blueprint *without* activating
+it — it runs `lintExtensionBlueprint` and throws if any finding is error-severity
+(today: a capability a surface exercises but the declared set omits, which would
+fail activation with `extension_capability_missing`). It returns the full
+`ExtensionBlueprintLintResult` on success so a test can still inspect advisory
+warnings:
+
+```ts
+import { assertExtensionBlueprint } from "@unbrained/pm-cli/sdk/testing";
+
+// Throws if the blueprint and its declared capabilities have drifted; otherwise
+// returns the lint result (including any non-blocking warnings) for inspection.
+const report = assertExtensionBlueprint(blueprint);
+```
+
+Invoke a registered command handler to assert its behavior (not just that it was
+registered). `runRegisteredCommandForTest` dispatches through pm's real engine and
+returns the `CommandHandlerResult`:
+
+```ts
+import { runRegisteredCommandForTest } from "@unbrained/pm-cli/sdk/testing";
+
+const invocation = await runRegisteredCommandForTest(activation.commands, {
+  command: "hello",
+  options: { name: "ada" },
+});
+
+// invocation.handled === true; invocation.result is the handler's return value.
+```
+
+Importers and exporters get dedicated name-based helpers so tests never hand-build
+the `"<name> import"` / `"<name> export"` command path. Pass the whole `activation`
+and the registration name:
+
+```ts
+import { runRegisteredImporterForTest, runRegisteredExporterForTest } from "@unbrained/pm-cli/sdk/testing";
+
+const imported = await runRegisteredImporterForTest(activation, {
+  importer: "csv",
+  options: { rows: 3 },
+});
+const exported = await runRegisteredExporterForTest(activation, { exporter: "csv" });
+
+// Both return a CommandHandlerResult: imported.result is the importer's return value.
+```
+
+Fire a registered lifecycle hook to assert its behavior (the `context` is
+type-safe per `kind`). A clean run returns `[]`; a hook that throws contributes a
+single `extension_hook_failed:*` warning while the others still run:
+
+```ts
+import { runRegisteredHookForTest } from "@unbrained/pm-cli/sdk/testing";
+
+const warnings = await runRegisteredHookForTest(activation.hooks, {
+  kind: "after_command",
+  context: { command: "close", args: ["pm-1a2b"], pm_root: "", ok: true },
+});
+// warnings === [] when every after_command hook ran cleanly.
+```
+
+The override surfaces have parallel invoke helpers that delegate to pm's real
+runners and return the override result verbatim, after guarding that a matching
+override is registered for the target (command / format / service):
+
+```ts
+import {
+  runRegisteredParserOverrideForTest,
+  runRegisteredCommandOverrideForTest,
+  runRegisteredRendererOverrideForTest,
+  runRegisteredServiceOverrideForTest,
+  runRegisteredPreflightOverrideForTest,
+} from "@unbrained/pm-cli/sdk/testing";
+
+const parsed = await runRegisteredParserOverrideForTest(activation.parsers, {
+  command: "deploy",
+  args: ["staging"],
+  options: {},
+  global: {},
+  pm_root: "",
+});
+// parsed.overridden === true; parsed.context holds the rewritten args/options.
+
+const rendered = await runRegisteredRendererOverrideForTest(activation.renderers, {
+  format: "toon",
+  result: { id: "pm-1a2b" },
+});
+// rendered.rendered is the custom string the override produced.
+```
+
 Assert a command registration contract:
 
 ```ts
@@ -585,6 +1038,39 @@ Together these complete the SDK assertion surface: every extension `register*`
 method now has a matching `assertRegistered*` helper, so packages can prove any
 registration without importing private registry internals.
 
+The three executable registration surfaces add `runRegistered*ForTest` invoke
+helpers on top of those assertions, so a package can exercise the real behavior of
+a custom provider, adapter, or migration:
+
+```ts
+import {
+  runRegisteredSearchProviderForTest,
+  runRegisteredVectorStoreAdapterForTest,
+  runRegisteredMigrationForTest,
+} from "@unbrained/pm-cli/sdk/testing";
+
+// Invoke a registered provider's semantic query (or embed / embedBatch /
+// queryExpansion / rerank); the result type follows `operation`.
+const hits = await runRegisteredSearchProviderForTest(activation.registrations, {
+  provider: "semantic-local",
+  operation: "query",
+  context: { query: "calendar", mode: "semantic", tokens: ["calendar"], options: {}, settings, documents },
+});
+
+// Invoke a registered adapter's upsert / query / delete.
+await runRegisteredVectorStoreAdapterForTest(activation.registrations, {
+  adapter: "pinecone",
+  operation: "upsert",
+  context: { points: [{ id: "pm-1", vector }], settings },
+});
+
+// Invoke a registered migration's run with a host-shaped context.
+await runRegisteredMigrationForTest(activation.registrations, {
+  migration: "backfill-severity",
+  pmRoot,
+});
+```
+
 The bundled `pm-lifecycle-hooks` package is the first-party hooks exemplar. It
 declares only the `hooks` capability and registers a default-inert `afterCommand`
 hook, so package authors can copy a lifecycle pattern that does not write files,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.21",
+  "version": "2026.6.23",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -133,7 +133,7 @@
   },
   "devDependencies": {
     "@sentry/cli": "^3.5.1",
-    "@types/node": "^25.9.3",
+    "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "esbuild": "0.28.1",
     "tsx": "^4.22.4",

package/dist/cli-bundle/chunks/activity-CIHV64UC.js

@@ -1,18 +0,0 @@
-import {
-  _testOnly,
-  runActivity
-} from "./chunk-5IDI42VV.js";
-import "./chunk-RVHYI7SL.js";
-import "./chunk-HIP7WVTL.js";
-import "./chunk-B473GZWW.js";
-import "./chunk-SX75ADBK.js";
-import "./chunk-7D3SAQXM.js";
-import "./chunk-QGG32QHW.js";
-import "./chunk-FRUFKWNK.js";
-import "./chunk-YCJX76PW.js";
-import "./chunk-HMOADQVT.js";
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=activity-CIHV64UC.js.map