@unbrained/pm-cli 2026.6.21 → 2026.6.22

package/docs/SDK.md

@@ -74,6 +74,20 @@ Command/action contract exports:
 Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 
 - `activateExtensionForTest`
+- `deactivateExtensionForTest`
+- `runRegisteredCommandForTest`
+- `runRegisteredHookForTest`
+- `runRegisteredParserOverrideForTest`
+- `runRegisteredPreflightOverrideForTest`
+- `runRegisteredCommandOverrideForTest`
+- `runRegisteredRendererOverrideForTest`
+- `runRegisteredServiceOverrideForTest`
+- `runRegisteredSearchProviderForTest`
+- `runRegisteredVectorStoreAdapterForTest`
+- `runRegisteredMigrationForTest`
+- `runRegisteredImporterForTest`
+- `runRegisteredExporterForTest`
+- `assertExtensionDeactivated`
 - `assertPackageManifest`
 - `assertRegisteredCommandContract`
 - `assertRegisteredFlags`
@@ -90,6 +104,109 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredItemType`
 - `assertRegisteredServiceOverride`
 - `assertRegisteredMigration`
+- `assertExtensionCapabilityUsage`
+
+`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.
 
 Commander option contract exports:
 
@@ -116,6 +233,13 @@ 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`
@@ -282,6 +406,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 +434,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
@@ -457,6 +607,80 @@ 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.
 
+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 +809,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.22",
   "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