@unbrained/pm-cli 2026.6.21 → 2026.6.23

package/dist/sdk/testing.js

@@ -1,7 +1,24 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cdb9b0c1-6fbc-5b77-bcd0-c4630a719641")}catch(e){}}();
-import { activateExtensions } from "../core/extensions/loader.js";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9ca86b28-8f2c-5dd3-bdf0-85d3f60e6197")}catch(e){}}();
+import { activateExtensions, deactivateExtensions, runAfterCommandHooks, runBeforeCommandHooks, runCommandHandler, runCommandOverride, runOnIndexHooks, runOnReadHooks, runOnWriteHooks, runParserOverride, runPreflightOverride, runRendererOverride, runServiceOverride, } from "../core/extensions/loader.js";
 import { createDefaultExtensionGovernancePolicy } from "../core/extensions/extension-types.js";
+import { getMigrationRuntimeDefinition, resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
+import { collectUsedExtensionCapabilities } from "../core/extensions/capability-usage.js";
+import { normalizeKnownExtensionCapability } from "../core/extensions/extension-capability-aliases.js";
+import { describeExtensionBlueprint, lintExtensionBlueprint } from "./compose.js";
+// `describeExtensionActivation` is the `describe` (enumerate-all) verb that
+// pairs with the `assert*` (verify-one) and `run*` (invoke-one) helpers below.
+// It lives in core (it walks the same registries the loader populates) and is
+// surfaced here so package authors get the whole testing surface from the
+// `@unbrained/pm-cli/sdk/testing` subpath.
+export { describeExtensionActivation, } from "../core/extensions/activation-summary.js";
+// `composeExtension`'s author-time companions: describe a blueprint's surface map
+// and preflight it for capability drift / duplicate / empty-surface footguns
+// without activating. Surfaced through the `@unbrained/pm-cli/sdk/testing` subpath
+// so a package author gets the full author → describe → preflight → test loop here,
+// alongside the assert*/run* helpers; `assertExtensionBlueprint` below is the
+// throwing assertion that pairs with the non-throwing `lintExtensionBlueprint`.
+export { describeExtensionBlueprint, lintExtensionBlueprint };
 const HOOK_KIND_TO_REGISTRY_FIELD = {
     before_command: "beforeCommand",
     after_command: "afterCommand",
@@ -69,6 +86,10 @@ function readTestExtensionManifest(module) {
     }
     return {};
 }
+function resolveTestExtensionName(manifest, explicitName) {
+    return (explicitName ??
+        (typeof manifest.name === "string" && manifest.name.trim().length > 0 ? manifest.name.trim() : "test-extension"));
+}
 function readTestExtensionCapabilities(manifest, options) {
     if (Array.isArray(options.capabilities)) {
         return [...options.capabilities];
@@ -79,18 +100,14 @@ function readTestExtensionCapabilities(manifest, options) {
     return [];
 }
 /**
- * Activate one in-memory extension module for package tests.
- *
- * This uses pm's real registration validation and activation engine while
- * avoiding private loader imports, filesystem manifests, or workspace setup.
+ * Build the synthetic single-extension {@link ExtensionLoadResult} shared by the
+ * activate/deactivate test helpers, so both stay aligned with the loader's load
+ * contract as it evolves. The `loaded` entry mirrors the real on-disk shape
+ * (including `capabilities` and the compatibility fields) while leaving
+ * filesystem paths empty, since the module is supplied in memory.
  */
-export async function activateExtensionForTest(module, options = {}) {
-    const manifest = readTestExtensionManifest(module);
-    const name = options.name ??
-        (typeof manifest.name === "string" && manifest.name.trim().length > 0 ? manifest.name.trim() : "test-extension");
-    const layer = options.layer ?? "project";
-    const capabilities = readTestExtensionCapabilities(manifest, options);
-    return activateExtensions({
+function buildSingleExtensionLoadResult(module, manifest, identity) {
+    return {
         disabled_by_flag: false,
         roots: { global: "", project: "" },
         configured_enabled: [],
@@ -98,19 +115,19 @@ export async function activateExtensionForTest(module, options = {}) {
         discovered: [],
         effective: [],
         warnings: [],
-        policy: options.policy ?? createDefaultExtensionGovernancePolicy(),
+        policy: identity.policy,
         failed: [],
         loaded: [
             {
-                layer,
+                layer: identity.layer,
                 directory: "",
                 manifest_path: "",
-                name,
+                name: identity.name,
                 version: typeof manifest.version === "string" ? manifest.version : "0.0.0",
                 entry: typeof manifest.entry === "string" ? manifest.entry : "./index.js",
                 priority: typeof manifest.priority === "number" ? manifest.priority : 0,
                 entry_path: "",
-                capabilities,
+                capabilities: identity.capabilities,
                 manifest_version: typeof manifest.manifest_version === "number" ? manifest.manifest_version : undefined,
                 pm_min_version: typeof manifest.pm_min_version === "string" ? manifest.pm_min_version : undefined,
                 pm_max_version: typeof manifest.pm_max_version === "string" ? manifest.pm_max_version : undefined,
@@ -123,8 +140,427 @@ export async function activateExtensionForTest(module, options = {}) {
                 module,
             },
         ],
+    };
+}
+/**
+ * Activate one in-memory extension module for package tests.
+ *
+ * This uses pm's real registration validation and activation engine while
+ * avoiding private loader imports, filesystem manifests, or workspace setup.
+ */
+export async function activateExtensionForTest(module, options = {}) {
+    const manifest = readTestExtensionManifest(module);
+    return activateExtensions(buildSingleExtensionLoadResult(module, manifest, {
+        name: resolveTestExtensionName(manifest, options.name),
+        layer: options.layer ?? "project",
+        capabilities: readTestExtensionCapabilities(manifest, options),
+        policy: options.policy ?? createDefaultExtensionGovernancePolicy(),
+    }));
+}
+/**
+ * Deactivate one in-memory extension module for package tests — the teardown
+ * counterpart to {@link activateExtensionForTest}.
+ *
+ * Runs pm's real `deactivateExtensions` engine (including its bounded per-hook
+ * timeout and best-effort failure capture) over a single synthetic load entry,
+ * so authors can prove an extension's `deactivate` releases the resources its
+ * `activate` opened — without importing private loader internals or staging a
+ * workspace. Resolve `name`/`layer` the same way {@link activateExtensionForTest}
+ * does so a forwarded `activation` result skips a failed extension correctly.
+ */
+export async function deactivateExtensionForTest(module, options = {}) {
+    const manifest = readTestExtensionManifest(module);
+    return deactivateExtensions(buildSingleExtensionLoadResult(module, manifest, {
+        name: resolveTestExtensionName(manifest, options.name),
+        layer: options.layer ?? "project",
+        capabilities: readTestExtensionCapabilities(manifest, {}),
+        policy: createDefaultExtensionGovernancePolicy(),
+    }), options.activation, options.deactivateTimeoutMs === undefined ? {} : { deactivate_timeout_ms: options.deactivateTimeoutMs });
+}
+/**
+ * Invoke a registered extension command handler and return its real
+ * {@link CommandHandlerResult} so package tests can assert on behavior — not
+ * just that the command was registered.
+ *
+ * This is the "invoke" verb that completes the package-author testing loop:
+ * `activateExtensionForTest` → `assertRegisteredCommandContract` → **run** →
+ * `deactivateExtensionForTest`. It runs pm's real handler-dispatch engine
+ * (`runCommandHandler`) over `activation.commands`, building the
+ * `CommandHandlerContext` with agent-safe global defaults
+ * (`{ json: true, quiet: true, noPager: true }`) that callers may override.
+ *
+ * Because `registerImporter`/`registerExporter` register their handlers under
+ * the `"<name> import"` / `"<name> export"` command paths, this same helper
+ * exercises importer and exporter handlers too.
+ *
+ * Throws a descriptive error (listing the available handler command paths) when
+ * no handler is registered for `command`, since that is a wiring/typo bug in the
+ * test rather than a behavior under test. When a handler is found, the result is
+ * returned verbatim: a clean run yields `{ handled: true, result, warnings: [] }`,
+ * while a handler that throws a non-exit error yields
+ * `{ handled: false, warnings: [code], errorMessage }` so the failure can be
+ * asserted. A handler that throws an error carrying a numeric `exitCode`
+ * propagates the throw, matching runtime semantics.
+ */
+export async function runRegisteredCommandForTest(commands, options) {
+    const command = normalizeSdkCommandName(options.command);
+    if (command.length === 0) {
+        throw new Error("Expected command name must be a non-empty string");
+    }
+    const hasHandler = commands.handlers.some((entry) => entry.command === command);
+    if (!hasHandler) {
+        const available = sortedUnique(commands.handlers.map((entry) => entry.command));
+        throw new Error(`Expected a registered command handler for "${command}" to invoke. Available command handlers: ${formatAvailable(available)}`);
+    }
+    return runCommandHandler(commands, {
+        command,
+        args: options.args ? [...options.args] : [],
+        options: options.options ? { ...options.options } : {},
+        global: { json: true, quiet: true, noPager: true, ...options.global },
+        pm_root: options.pmRoot ?? "",
+    });
+}
+/**
+ * Fire every registered lifecycle hook of a given `kind` through pm's real hook
+ * runner and return the warnings array so package tests can assert on behavior —
+ * not just that a hook was registered.
+ *
+ * This is the hook counterpart to {@link runRegisteredCommandForTest}, extending
+ * the package-author "invoke" verb to the `api.hooks.*` surface. Pass the
+ * `ExtensionHookRegistry` from `activateExtensionForTest(...).hooks` together with
+ * the lifecycle `kind` and a synthetic context. Hooks observe their inputs via a
+ * cloned context snapshot (mutations never leak back to the caller), so the
+ * observable signal is twofold: any side effects the hook performs, and the
+ * returned warnings. A clean run returns `[]`; a hook that throws contributes one
+ * `extension_hook_failed:<layer>:<name>:<hookName>` warning, mirroring runtime
+ * dispatch which isolates a failing hook without aborting the others.
+ *
+ * Throws a descriptive error (listing the hook kinds that do have registrations)
+ * when no hook of `kind` is registered, since firing a hook the extension never
+ * registered is a wiring/typo bug in the test rather than a behavior under test.
+ */
+export async function runRegisteredHookForTest(hooks, options) {
+    if (hooks[HOOK_KIND_TO_REGISTRY_FIELD[options.kind]].length === 0) {
+        const populatedKinds = sortedUnique(Object.keys(HOOK_KIND_TO_REGISTRY_FIELD).filter((kind) => hooks[HOOK_KIND_TO_REGISTRY_FIELD[kind]].length > 0));
+        throw new Error(`Expected a registered "${options.kind}" hook to invoke. Hook kinds with registrations: ${formatAvailable(populatedKinds)}`);
+    }
+    switch (options.kind) {
+        case "before_command":
+            return runBeforeCommandHooks(hooks, options.context);
+        case "after_command":
+            return runAfterCommandHooks(hooks, options.context);
+        case "on_read":
+            return runOnReadHooks(hooks, options.context);
+        case "on_write":
+            return runOnWriteHooks(hooks, options.context);
+        case "on_index":
+            return runOnIndexHooks(hooks, options.context);
+    }
+}
+/**
+ * Invoke a registered parser override through pm's real runner and return the
+ * resolved {@link ParserOverrideResult}, so package tests can assert the rewritten
+ * args/options/global an override produces for a command before dispatch.
+ *
+ * Guards that a parser override is registered for the (normalized) target command
+ * before delegating: without a match `runParserOverride` would silently return
+ * `overridden: false`, hiding a typo'd command name in the test. When a match
+ * exists the result is returned verbatim — `overridden: true` with the rewritten
+ * context on success, or `overridden: false` with an
+ * `extension_parser_override_failed:*` warning when the override throws.
+ */
+export async function runRegisteredParserOverrideForTest(parsers, context) {
+    const command = normalizeSdkCommandName(context.command);
+    if (!parsers.overrides.some((entry) => entry.command === command)) {
+        throw new Error(`Expected a registered parser override for command "${command}" to invoke. Available parser override commands: ${formatAvailable(sortedUnique(parsers.overrides.map((entry) => entry.command)))}`);
+    }
+    return runParserOverride(parsers, context);
+}
+/**
+ * Invoke the active preflight override through pm's real runner and return the
+ * resolved {@link PreflightOverrideResult}, so package tests can assert the
+ * migration/format gate decision an override yields.
+ *
+ * Unlike command-scoped overrides, the runtime applies the **last** registered
+ * preflight override regardless of command, so this helper guards only that at
+ * least one preflight override is registered before delegating. The result is
+ * returned verbatim — `overridden: true` with the adjusted decision on success,
+ * or `overridden: false` with an `extension_preflight_override_failed:*` warning
+ * when the override throws.
+ */
+export async function runRegisteredPreflightOverrideForTest(preflight, context) {
+    if (preflight.overrides.length === 0) {
+        throw new Error("Expected a registered preflight override to invoke, but none are registered.");
+    }
+    return runPreflightOverride(preflight, context);
+}
+/**
+ * Invoke a registered command-result override through pm's real runner and return
+ * the resolved {@link CommandOverrideResult}, so package tests can assert how an
+ * override transforms a command's result payload.
+ *
+ * Accepts the same `ExtensionCommandRegistry` exposed as
+ * `activateExtensionForTest(...).commands` (it carries both handlers and
+ * overrides). Guards that an override is registered for the (normalized) target
+ * command before delegating, so a typo'd command name surfaces as a clear error
+ * rather than a silent `overridden: false`. The result is returned verbatim —
+ * including the `extension_command_override_async_unsupported:*` warning the
+ * runtime emits when an override returns a Promise (command overrides are
+ * synchronous), or an `extension_command_override_failed:*` warning on throw.
+ */
+export async function runRegisteredCommandOverrideForTest(commands, context) {
+    const command = normalizeSdkCommandName(context.command);
+    if (!commands.overrides.some((entry) => entry.command === command)) {
+        throw new Error(`Expected a registered command override for command "${command}" to invoke. Available command override commands: ${formatAvailable(sortedUnique(commands.overrides.map((entry) => entry.command)))}`);
+    }
+    return runCommandOverride(commands, context);
+}
+/**
+ * Invoke a registered renderer override through pm's real runner and return the
+ * resolved {@link RendererOverrideResult}, so package tests can assert the custom
+ * string an override renders for a given output `format`.
+ *
+ * Guards that a renderer override is registered for `context.format` before
+ * delegating, so a wrong format surfaces as a clear error rather than a silent
+ * `overridden: false`. The result is returned verbatim — `overridden: true` with
+ * the rendered string on success, or `overridden: false` (with an
+ * `extension_renderer_invalid_result:*` / `extension_renderer_failed:*` warning
+ * where applicable) when the override returns a non-string or throws.
+ */
+export async function runRegisteredRendererOverrideForTest(renderers, context) {
+    if (!renderers.overrides.some((entry) => entry.format === context.format)) {
+        throw new Error(`Expected a registered renderer override for format "${context.format}" to invoke. Available renderer override formats: ${formatAvailable(sortedUnique(renderers.overrides.map((entry) => entry.format)))}`);
+    }
+    return runRendererOverride(renderers, context);
+}
+/**
+ * Invoke a registered service override through pm's real runner and return the
+ * resolved {@link ServiceOverrideResult}, so package tests can assert how an
+ * override handles an internal service payload (e.g. `output_format`).
+ *
+ * Guards that a service override is registered for `context.service` before
+ * delegating, so a wrong service name surfaces as a clear error rather than a
+ * silent `handled: false`. The result is returned verbatim — `handled: true` with
+ * the override's result when it claims the payload, or `handled: false` with the
+ * original payload (and any `extension_service_override_*` warnings) otherwise.
+ */
+export async function runRegisteredServiceOverrideForTest(services, context) {
+    if (!services.overrides.some((entry) => entry.service === context.service)) {
+        throw new Error(`Expected a registered service override for service "${context.service}" to invoke. Available service override services: ${formatAvailable(sortedUnique(services.overrides.map((entry) => entry.service)))}`);
+    }
+    return runServiceOverride(services, context);
+}
+/**
+ * Maps each search-provider operation to the runtime-definition keys that may
+ * hold its function, in priority order. The host accepts both camelCase and
+ * snake_case spellings for the multi-word operations, so this helper mirrors that
+ * by trying `embedBatch` before `embed_batch` and `queryExpansion` before
+ * `query_expansion`.
+ */
+const SEARCH_PROVIDER_OPERATION_DEFINITION_KEYS = {
+    query: ["query"],
+    embed: ["embed"],
+    embedBatch: ["embedBatch", "embed_batch"],
+    queryExpansion: ["queryExpansion", "query_expansion"],
+    rerank: ["rerank"],
+};
+/**
+ * Invoke an operation of a registered search provider through the same name
+ * resolution the host uses and return the operation's result, so package tests
+ * can assert a custom provider's runtime behavior — not just that it registered.
+ *
+ * This is the search-provider counterpart to {@link runRegisteredCommandForTest},
+ * extending the package-author "invoke" verb to the `api.registerSearchProvider`
+ * surface. Pass the `ExtensionRegistrationRegistry` from
+ * `activateExtensionForTest(...).registrations`, the registered provider name, the
+ * `operation` to exercise (`query`, `embed`, `embedBatch`, `queryExpansion`, or
+ * `rerank`), and a synthetic context. The provider is resolved via
+ * {@link resolveRegisteredSearchProvider} (case-insensitive, last registration
+ * wins) and the operation is invoked on its `runtime_definition` — the clone that
+ * preserves live functions, matching what the runtime dispatches.
+ *
+ * Throws a descriptive error listing the available providers when the name is not
+ * registered, and a separate error when the resolved provider does not implement
+ * the requested operation, since invoking an absent provider/operation is a
+ * wiring bug in the test rather than a behavior under test.
+ */
+export async function runRegisteredSearchProviderForTest(registrations, options) {
+    const registration = resolveRegisteredSearchProvider(registrations, options.provider);
+    if (!registration) {
+        const available = sortedUnique(registrations.search_providers.map((entry) => entry.definition.name));
+        throw new Error(`Expected a registered search provider "${options.provider}" to invoke. Available search providers: ${formatAvailable(available)}`);
+    }
+    const runtimeDefinition = registration.runtime_definition;
+    const operationFn = SEARCH_PROVIDER_OPERATION_DEFINITION_KEYS[options.operation]
+        .map((key) => runtimeDefinition[key])
+        .find((value) => typeof value === "function");
+    if (typeof operationFn !== "function") {
+        throw new Error(`Registered search provider "${options.provider}" does not implement the "${options.operation}" operation.`);
+    }
+    return (await operationFn(options.context));
+}
+/**
+ * Invoke an operation of a registered vector store adapter through the same name
+ * resolution the host uses and return the operation's result, so package tests
+ * can assert a custom adapter's runtime behavior — not just that it registered.
+ *
+ * This is the vector-store counterpart to {@link runRegisteredSearchProviderForTest}.
+ * Pass the `ExtensionRegistrationRegistry` from
+ * `activateExtensionForTest(...).registrations`, the registered adapter name, the
+ * `operation` to exercise (`query`, `upsert`, or `delete`), and a synthetic
+ * context. The adapter is resolved via {@link resolveRegisteredVectorStoreAdapter}
+ * (case-insensitive, last registration wins) and the operation is invoked on its
+ * `runtime_definition` — the clone that preserves live functions, matching what
+ * the runtime dispatches.
+ *
+ * Throws a descriptive error listing the available adapters when the name is not
+ * registered, and a separate error when the resolved adapter does not implement
+ * the requested operation.
+ */
+export async function runRegisteredVectorStoreAdapterForTest(registrations, options) {
+    const registration = resolveRegisteredVectorStoreAdapter(registrations, options.adapter);
+    if (!registration) {
+        const available = sortedUnique(registrations.vector_store_adapters.map((entry) => entry.definition.name));
+        throw new Error(`Expected a registered vector store adapter "${options.adapter}" to invoke. Available vector store adapters: ${formatAvailable(available)}`);
+    }
+    const operationFn = registration.runtime_definition[options.operation];
+    if (typeof operationFn !== "function") {
+        throw new Error(`Registered vector store adapter "${options.adapter}" does not implement the "${options.operation}" operation.`);
+    }
+    return (await operationFn(options.context));
+}
+/**
+ * Invoke a registered schema migration's `run` function through the same runtime
+ * definition the host executes and return its result, so package tests can assert
+ * a migration's behavior — not just that it registered.
+ *
+ * This completes the package-author "invoke" verb across every executable
+ * registration surface. The migration is resolved by id via
+ * {@link assertRegisteredMigration} (which throws a descriptive "available
+ * migrations" error when absent), then `run` is invoked on its
+ * `runtime_definition` with a context mirroring the one
+ * `executeRegisteredRuntimeMigrations` builds at runtime: the resolved id,
+ * `command: "migration"`, the registering extension's layer/name, the supplied
+ * `pmRoot`, and the migration's normalized status. Unlike the runtime — which
+ * skips already-applied migrations and folds a throw into a warning — this helper
+ * always invokes `run` and lets a throw propagate, so authors can assert both the
+ * success result and failure via rejection.
+ *
+ * Throws when the resolved migration declares no `run` function, since invoking a
+ * runless migration is a wiring bug in the test rather than a behavior under test.
+ */
+export async function runRegisteredMigrationForTest(registrations, options) {
+    const migration = assertRegisteredMigration(registrations, {
+        migration: options.migration,
+        extensionName: options.extensionName,
+    });
+    const run = getMigrationRuntimeDefinition(migration).run;
+    if (typeof run !== "function") {
+        throw new Error(`Registered migration "${options.migration}" does not implement a run function to invoke.`);
+    }
+    const declaredStatus = migration.definition.status;
+    const context = {
+        id: migration.definition.id,
+        command: "migration",
+        layer: migration.layer,
+        extension: migration.name,
+        pm_root: options.pmRoot ?? "",
+        status: (typeof declaredStatus === "string" ? declaredStatus.trim().toLowerCase() : "") || "pending",
+    };
+    return await run(context);
+}
+/**
+ * Invoke a registered extension importer through pm's real handler-dispatch
+ * engine and return its {@link CommandHandlerResult}, so package tests can assert
+ * an importer's behavior — not just that it registered.
+ *
+ * This is the importer counterpart to {@link runRegisteredCommandForTest},
+ * extending the package-author "invoke" verb to the `api.registerImporter`
+ * surface. Because `registerImporter(name, fn)` wraps `fn` into a command handler
+ * at the `"<name> import"` path, invoking it through `runRegisteredCommandForTest`
+ * requires the author to know that naming convention and to remember that an
+ * importer is reachable as a command at all. This helper closes both gaps: it
+ * accepts the registered importer name directly, validates via
+ * {@link assertRegisteredImporter} that it is genuinely a registered importer
+ * (not merely some command parked at that path), derives the command path, and
+ * dispatches through the same engine.
+ *
+ * The full activation result is required because importer execution spans two
+ * sub-registries: `registrations.importers` proves the importer exists, while
+ * `commands` holds the wrapped handler. The result is returned verbatim from the
+ * command engine: a clean run yields `{ handled: true, result, warnings: [] }`
+ * (where `result` is the importer's return value), a non-exit throw yields
+ * `{ handled: false, warnings: [code], errorMessage }`, and an error carrying a
+ * numeric `exitCode` propagates — matching runtime import semantics.
+ *
+ * Throws a descriptive "available importers" error (via `assertRegisteredImporter`)
+ * when no importer matches, since that is a wiring/typo bug in the test rather
+ * than a behavior under test.
+ */
+export async function runRegisteredImporterForTest(activation, options) {
+    const importer = assertRegisteredImporter(activation.registrations, {
+        importer: options.importer,
+        extensionName: options.extensionName,
+    });
+    return runRegisteredCommandForTest(activation.commands, {
+        command: `${importer.importer} import`,
+        args: options.args,
+        options: options.options,
+        global: options.global,
+        pmRoot: options.pmRoot,
     });
 }
+/**
+ * Invoke a registered extension exporter through pm's real handler-dispatch
+ * engine and return its {@link CommandHandlerResult}, so package tests can assert
+ * an exporter's behavior — not just that it registered.
+ *
+ * This is the exporter counterpart to {@link runRegisteredImporterForTest} and
+ * the final surface in the package-author "invoke" verb. Because
+ * `registerExporter(name, fn)` wraps `fn` into a command handler at the
+ * `"<name> export"` path, this helper accepts the registered exporter name
+ * directly, validates via {@link assertRegisteredExporter} that it is genuinely a
+ * registered exporter, derives the command path, and dispatches through the same
+ * engine. See {@link runRegisteredImporterForTest} for the full activation
+ * rationale and return semantics (which apply identically here).
+ *
+ * Throws a descriptive "available exporters" error (via `assertRegisteredExporter`)
+ * when no exporter matches, since that is a wiring/typo bug in the test rather
+ * than a behavior under test.
+ */
+export async function runRegisteredExporterForTest(activation, options) {
+    const exporter = assertRegisteredExporter(activation.registrations, {
+        exporter: options.exporter,
+        extensionName: options.extensionName,
+    });
+    return runRegisteredCommandForTest(activation.commands, {
+        command: `${exporter.exporter} export`,
+        args: options.args,
+        options: options.options,
+        global: options.global,
+        pmRoot: options.pmRoot,
+    });
+}
+/**
+ * Assert that an {@link ExtensionDeactivationResult} reports the expected clean
+ * teardown counts, throwing a descriptive error otherwise. Defaults assert the
+ * single-extension happy path — exactly one extension deactivated and none
+ * failed. Returns the result so assertions can chain.
+ */
+export function assertExtensionDeactivated(result, expectation = {}) {
+    const expectedDeactivated = expectation.deactivated ?? 1;
+    if (result.deactivated !== expectedDeactivated) {
+        throw new Error(`Expected ${expectedDeactivated} extension${expectedDeactivated === 1 ? "" : "s"} to deactivate cleanly, ` +
+            `but ${result.deactivated} did.`);
+    }
+    const expectedFailed = expectation.failed ?? 0;
+    if (result.failed.length !== expectedFailed) {
+        const detail = result.failed.map((failure) => `${failure.layer}:${failure.name} (${failure.error})`).join(", ");
+        throw new Error(`Expected ${expectedFailed} teardown failure${expectedFailed === 1 ? "" : "s"}, ` +
+            `but observed ${result.failed.length}${detail.length > 0 ? `: ${detail}` : ""}.`);
+    }
+    return result;
+}
 /**
  * Assert that a normalized package manifest advertises expected package
  * resources. Pair with `readPmPackageManifest(packageRoot)` in package tests.
@@ -512,5 +948,205 @@ export function assertRegisteredMigration(registrations, expectation) {
     }));
     throw new Error(`Expected migration "${expectedMigration}"${extensionNameSuffix(expectation.extensionName)} to be registered. Available migrations: ${formatAvailable(available)}`);
 }
+/**
+ * Assert that an activated extension declares no capability it never uses
+ * (least privilege). Pass the same capabilities as `manifest.capabilities` via
+ * `expectation.declared`; the helper computes what the extension actually
+ * registered against and throws when any declared capability is unused.
+ *
+ * This is the package-test counterpart of the advisory
+ * `extension_capability_unused` warning `pm package doctor` emits, letting an
+ * author catch an over-broad manifest at `npm test` time. Returns the
+ * declared/used/unused breakdown for further assertions.
+ */
+export function assertExtensionCapabilityUsage(activation, expectation) {
+    const toKnownCapabilitySet = (capabilities, field) => {
+        const known = new Set();
+        for (const capability of capabilities) {
+            const normalized = normalizeKnownExtensionCapability(capability);
+            if (normalized === null) {
+                throw new Error(`Expected ${field} capability "${capability}" to be a known extension capability. ` +
+                    "Use canonical capability names (see manifest.capabilities).");
+            }
+            known.add(normalized);
+        }
+        return known;
+    };
+    const declared = [...toKnownCapabilitySet(expectation.declared, "declared")].sort((left, right) => left.localeCompare(right));
+    const allowUnused = toKnownCapabilitySet(expectation.allowUnused ?? [], "allowUnused");
+    const used = collectUsedExtensionCapabilities(activation, { extensionName: expectation.extensionName });
+    const usedSet = new Set(used);
+    const unused = declared.filter((capability) => !usedSet.has(capability) && !allowUnused.has(capability));
+    if (unused.length > 0) {
+        const scopeSuffix = extensionNameSuffix(expectation.extensionName);
+        throw new Error(`Expected every declared capability${scopeSuffix} to be exercised, but [${unused.join(", ")}] ${unused.length === 1 ? "is" : "are"} declared yet never registered against. ` +
+            `Remove ${unused.length === 1 ? "it" : "them"} from manifest.capabilities for least privilege, ` +
+            "or pass allowUnused for capabilities registered only behind a runtime flag.");
+    }
+    return { declared, used, unused };
+}
+/**
+ * Preflight a declarative {@link ExtensionBlueprint} in a test, throwing if it has
+ * any `error`-severity issue (today: capability the blueprint exercises but the
+ * declared set omits, which would fail activation with `extension_capability_missing`).
+ *
+ * The throwing counterpart to {@link lintExtensionBlueprint} and the `assert*`
+ * family member for declarative authoring: drop `assertExtensionBlueprint(blueprint)`
+ * into a package's `node:test`/Vitest suite to fail CI before the blueprint is
+ * ever activated. The full {@link ExtensionBlueprintLintResult} is returned on
+ * success so a test can still inspect advisory warnings (unused capability,
+ * duplicate command, empty surface) without failing on them.
+ */
+export function assertExtensionBlueprint(blueprint, options = {}) {
+    const result = lintExtensionBlueprint(blueprint, options);
+    if (!result.ok) {
+        const errors = result.findings.filter((finding) => finding.severity === "error");
+        throw new Error(`Extension blueprint failed preflight with ${errors.length} ${errors.length === 1 ? "error" : "errors"}:\n` +
+            errors.map((finding) => `  - [${finding.code}] ${finding.message}`).join("\n"));
+    }
+    return result;
+}
+/**
+ * Activate one in-memory extension module and return a fluent
+ * {@link ExtensionTestHarness} that binds every SDK testing helper to the right
+ * sub-registry of the resulting activation.
+ *
+ * This is the ergonomic capstone over the standalone helpers: instead of
+ * `activateExtensionForTest(module)` followed by repeatedly threading
+ * `activation.registrations` / `activation.commands` / `activation.hooks` into
+ * each `assertRegistered*` / `runRegistered*` call, an author writes
+ * `const ext = await createExtensionTestHarness(module, { capabilities });` and
+ * then `ext.assertCommandContract(...)`, `await ext.runCommand(...)`,
+ * `await ext.deactivate()` — never needing to know pm's internal registry layout.
+ *
+ * `name` and `layer` are resolved exactly as {@link activateExtensionForTest}
+ * resolves them, and captured so {@link ExtensionTestHarness.deactivate} forwards
+ * a matching skip-key. Activation runs pm's real validation/activation engine, so
+ * every bound helper exercises real wiring and dispatch — not mocks.
+ *
+ * Fails fast: if the module does not activate cleanly (e.g. a registration is
+ * dropped because the manifest omits the required capability), this throws a
+ * descriptive error listing each failure instead of returning a harness whose
+ * registries are empty — which would otherwise surface later as the confusing
+ * `available: (none)` assertion error this helper exists to prevent. Tests that
+ * deliberately exercise a *failed* activation should call
+ * {@link activateExtensionForTest} directly and inspect `activation.failed`.
+ */
+export async function createExtensionTestHarness(module, options = {}) {
+    const manifest = readTestExtensionManifest(module);
+    const name = resolveTestExtensionName(manifest, options.name);
+    const layer = options.layer ?? "project";
+    const activation = await activateExtensionForTest(module, options);
+    if (activation.failed.length > 0) {
+        const detail = activation.failed
+            .map((failure) => {
+            const missingCapability = failure.trace?.missing_capability;
+            const reason = missingCapability ? `${failure.error}; missing capability "${missingCapability}"` : failure.error;
+            return `${failure.layer}:${failure.name} (${reason})`;
+        })
+            .join(", ");
+        throw new Error(`createExtensionTestHarness could not activate the extension cleanly: ${detail}. ` +
+            "Declare the required capability in the manifest (or pass it via options.capabilities), " +
+            "or use activateExtensionForTest directly to inspect a failed activation.");
+    }
+    return {
+        module,
+        name,
+        layer,
+        activation,
+        assertCommandContract(expectation) {
+            return assertRegisteredCommandContract(activation.registrations, expectation);
+        },
+        assertFlags(expectation) {
+            return assertRegisteredFlags(activation.registrations, expectation);
+        },
+        assertItemField(expectation) {
+            return assertRegisteredItemField(activation.registrations, expectation);
+        },
+        assertItemType(expectation) {
+            return assertRegisteredItemType(activation.registrations, expectation);
+        },
+        assertHook(expectation) {
+            return assertRegisteredHook(activation.hooks, expectation);
+        },
+        assertCommandOverride(expectation) {
+            return assertRegisteredCommandOverride(activation.commands, expectation);
+        },
+        assertParserOverride(expectation) {
+            return assertRegisteredParserOverride(activation.parsers, expectation);
+        },
+        assertPreflightOverride(expectation) {
+            return assertRegisteredPreflightOverride(activation.preflight, expectation);
+        },
+        assertRendererOverride(expectation) {
+            return assertRegisteredRendererOverride(activation.renderers, expectation);
+        },
+        assertServiceOverride(expectation) {
+            return assertRegisteredServiceOverride(activation.services, expectation);
+        },
+        assertSearchProvider(expectation) {
+            return assertRegisteredSearchProvider(activation.registrations, expectation);
+        },
+        assertVectorStoreAdapter(expectation) {
+            return assertRegisteredVectorStoreAdapter(activation.registrations, expectation);
+        },
+        assertImporter(expectation) {
+            return assertRegisteredImporter(activation.registrations, expectation);
+        },
+        assertExporter(expectation) {
+            return assertRegisteredExporter(activation.registrations, expectation);
+        },
+        assertMigration(expectation) {
+            return assertRegisteredMigration(activation.registrations, expectation);
+        },
+        assertCapabilityUsage(expectation) {
+            return assertExtensionCapabilityUsage(activation, expectation);
+        },
+        runCommand(runOptions) {
+            return runRegisteredCommandForTest(activation.commands, runOptions);
+        },
+        runHook(runOptions) {
+            return runRegisteredHookForTest(activation.hooks, runOptions);
+        },
+        runCommandOverride(context) {
+            return runRegisteredCommandOverrideForTest(activation.commands, context);
+        },
+        runParserOverride(context) {
+            return runRegisteredParserOverrideForTest(activation.parsers, context);
+        },
+        runPreflightOverride(context) {
+            return runRegisteredPreflightOverrideForTest(activation.preflight, context);
+        },
+        runRendererOverride(context) {
+            return runRegisteredRendererOverrideForTest(activation.renderers, context);
+        },
+        runServiceOverride(context) {
+            return runRegisteredServiceOverrideForTest(activation.services, context);
+        },
+        runSearchProvider(runOptions) {
+            return runRegisteredSearchProviderForTest(activation.registrations, runOptions);
+        },
+        runVectorStoreAdapter(runOptions) {
+            return runRegisteredVectorStoreAdapterForTest(activation.registrations, runOptions);
+        },
+        runMigration(runOptions) {
+            return runRegisteredMigrationForTest(activation.registrations, runOptions);
+        },
+        runImporter(runOptions) {
+            return runRegisteredImporterForTest(activation, runOptions);
+        },
+        runExporter(runOptions) {
+            return runRegisteredExporterForTest(activation, runOptions);
+        },
+        deactivate(deactivateOptions = {}) {
+            return deactivateExtensionForTest(module, {
+                name,
+                layer,
+                activation,
+                deactivateTimeoutMs: deactivateOptions.deactivateTimeoutMs,
+            });
+        },
+    };
+}
 //# sourceMappingURL=testing.js.map
-//# debugId=cdb9b0c1-6fbc-5b77-bcd0-c4630a719641
+//# debugId=9ca86b28-8f2c-5dd3-bdf0-85d3f60e6197