@unbrained/pm-cli 2026.6.22 → 2026.6.23

package/dist/sdk/testing.d.ts

@@ -4,8 +4,13 @@
  * Defines public SDK APIs and package-author helpers for Testing.
  */
 import type { AfterCommandHookContext, BeforeCommandHookContext, CommandHandlerResult, CommandOverrideContext, CommandOverrideResult, ExtensionActivationResult, ExtensionCapability, ExtensionCommandRegistry, ExtensionDeactivationResult, ExtensionGovernancePolicy, ExtensionHookRegistry, ExtensionLayer, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceName, ExtensionServiceRegistry, FlagDefinition, OnIndexHookContext, OnReadHookContext, OnWriteHookContext, OutputRendererFormat, ParserOverrideContext, ParserOverrideResult, PreflightOverrideContext, PreflightOverrideResult, RegisteredExtensionCommandDefinition, RegisteredExtensionCommandOverride, RegisteredExtensionExporter, RegisteredExtensionFlagDefinitions, RegisteredExtensionImporter, RegisteredExtensionParserOverride, RegisteredExtensionPreflightOverride, RegisteredExtensionRendererOverride, RegisteredExtensionSchemaFieldDefinitions, RegisteredExtensionSchemaItemTypeDefinitions, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverrideContext, RendererOverrideResult, SchemaFieldDefinition, SchemaItemTypeDefinition, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderQueryContext, SearchProviderQueryExpansionContext, SearchProviderQueryExpansionResult, SearchProviderQueryResult, SearchProviderRerankContext, SearchProviderRerankResult, ServiceOverrideContext, ServiceOverrideResult, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext } from "../core/extensions/loader.js";
+import { describeExtensionBlueprint, lintExtensionBlueprint } from "./compose.js";
+import type { ExtensionBlueprint, ExtensionBlueprintLintCode, ExtensionBlueprintLintFinding, ExtensionBlueprintLintResult, ExtensionBlueprintLintSeverity, LintExtensionBlueprintOptions } from "./compose.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { PmPackageManifest, PmPackageResourceKind } from "../core/packages/manifest.js";
+export { describeExtensionActivation, type DescribeExtensionActivationOptions, type ExtensionActivationSummary, } from "../core/extensions/activation-summary.js";
+export { describeExtensionBlueprint, lintExtensionBlueprint };
+export type { ExtensionBlueprint, ExtensionBlueprintLintCode, ExtensionBlueprintLintFinding, ExtensionBlueprintLintResult, ExtensionBlueprintLintSeverity, LintExtensionBlueprintOptions, };
 /**
  * Documents the activate extension for test options payload exchanged by command, SDK, and package integrations.
  */
@@ -803,4 +808,145 @@ export declare function assertRegisteredMigration(registrations: ExtensionRegist
  * declared/used/unused breakdown for further assertions.
  */
 export declare function assertExtensionCapabilityUsage(activation: ExtensionActivationResult, expectation: ExtensionCapabilityUsageExpectation): ExtensionCapabilityUsageAssertion;
-export {};
+/**
+ * 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 declare function assertExtensionBlueprint(blueprint: ExtensionBlueprint, options?: LintExtensionBlueprintOptions): ExtensionBlueprintLintResult;
+/**
+ * A fluent, single-extension test fixture returned by
+ * {@link createExtensionTestHarness}.
+ *
+ * Every method binds one of the standalone SDK testing helpers to the correct
+ * sub-registry of a single {@link ExtensionActivationResult}, so a package author
+ * never threads `activation.registrations` vs `activation.commands` vs
+ * `activation.hooks` (etc.) by hand — picking the wrong sub-registry is a common
+ * footgun that surfaces as a confusing `available: (none)` error. Methods do not
+ * use `this`; they close over the activation, so they remain safe to destructure
+ * (`const { runCommand, assertCommandContract } = harness;`).
+ *
+ * The `assert*` methods verify registration wiring (returning the matched
+ * registration); the `run*` methods invoke a registered surface through pm's real
+ * dispatch engine (returning its runtime result); {@link deactivate} runs the real
+ * teardown engine. The raw {@link activation} stays public as an escape hatch to
+ * the standalone helpers for any surface not covered by a convenience method.
+ */
+export interface ExtensionTestHarness {
+    /** The in-memory extension module supplied to {@link createExtensionTestHarness}. */
+    readonly module: unknown;
+    /** Resolved extension name (manifest name, explicit override, or `"test-extension"`). */
+    readonly name: string;
+    /** Layer recorded for the in-memory extension (defaults to `"project"`). */
+    readonly layer: ExtensionLayer;
+    /** The underlying activation result; use it to reach standalone helpers directly. */
+    readonly activation: ExtensionActivationResult;
+    /** Bound {@link assertRegisteredCommandContract} over `activation.registrations`. */
+    assertCommandContract(expectation: RegisteredCommandContractExpectation): RegisteredCommandContractAssertion;
+    /** Bound {@link assertRegisteredFlags} over `activation.registrations`. */
+    assertFlags(expectation: RegisteredFlagsExpectation): RegisteredExtensionFlagDefinitions;
+    /** Bound {@link assertRegisteredItemField} over `activation.registrations`. */
+    assertItemField(expectation: RegisteredItemFieldExpectation): RegisteredItemFieldAssertion;
+    /** Bound {@link assertRegisteredItemType} over `activation.registrations`. */
+    assertItemType(expectation: RegisteredItemTypeExpectation): RegisteredItemTypeAssertion;
+    /** Bound {@link assertRegisteredHook} over `activation.hooks`. */
+    assertHook<TKind extends RegisteredHookKind>(expectation: RegisteredHookExpectation & {
+        kind: TKind;
+    }): ExtensionHookRegistry[(typeof HOOK_KIND_TO_REGISTRY_FIELD)[TKind]][number];
+    /** Bound {@link assertRegisteredCommandOverride} over `activation.commands`. */
+    assertCommandOverride(expectation: RegisteredCommandOverrideExpectation): RegisteredExtensionCommandOverride;
+    /** Bound {@link assertRegisteredParserOverride} over `activation.parsers`. */
+    assertParserOverride(expectation: RegisteredParserOverrideExpectation): RegisteredExtensionParserOverride;
+    /** Bound {@link assertRegisteredPreflightOverride} over `activation.preflight`. */
+    assertPreflightOverride(expectation?: RegisteredPreflightOverrideExpectation): RegisteredExtensionPreflightOverride;
+    /** Bound {@link assertRegisteredRendererOverride} over `activation.renderers`. */
+    assertRendererOverride(expectation: RegisteredRendererOverrideExpectation): RegisteredExtensionRendererOverride;
+    /** Bound {@link assertRegisteredServiceOverride} over `activation.services`. */
+    assertServiceOverride(expectation: RegisteredServiceOverrideExpectation): RegisteredExtensionServiceOverride;
+    /** Bound {@link assertRegisteredSearchProvider} over `activation.registrations`. */
+    assertSearchProvider(expectation: RegisteredSearchProviderExpectation): RegisteredExtensionSearchProvider;
+    /** Bound {@link assertRegisteredVectorStoreAdapter} over `activation.registrations`. */
+    assertVectorStoreAdapter(expectation: RegisteredVectorStoreAdapterExpectation): RegisteredExtensionVectorStoreAdapter;
+    /** Bound {@link assertRegisteredImporter} over `activation.registrations`. */
+    assertImporter(expectation: RegisteredImporterExpectation): RegisteredExtensionImporter;
+    /** Bound {@link assertRegisteredExporter} over `activation.registrations`. */
+    assertExporter(expectation: RegisteredExporterExpectation): RegisteredExtensionExporter;
+    /** Bound {@link assertRegisteredMigration} over `activation.registrations`. */
+    assertMigration(expectation: RegisteredMigrationExpectation): RegisteredExtensionSchemaMigrationDefinition;
+    /** Bound {@link assertExtensionCapabilityUsage} over the whole `activation`. */
+    assertCapabilityUsage(expectation: ExtensionCapabilityUsageExpectation): ExtensionCapabilityUsageAssertion;
+    /** Bound {@link runRegisteredCommandForTest} over `activation.commands`. */
+    runCommand(options: RunRegisteredCommandForTestOptions): Promise<CommandHandlerResult>;
+    /** Bound {@link runRegisteredHookForTest} over `activation.hooks`. */
+    runHook(options: RunRegisteredHookForTestOptions): Promise<string[]>;
+    /** Bound {@link runRegisteredCommandOverrideForTest} over `activation.commands`. */
+    runCommandOverride(context: CommandOverrideContext): Promise<CommandOverrideResult>;
+    /** Bound {@link runRegisteredParserOverrideForTest} over `activation.parsers`. */
+    runParserOverride(context: ParserOverrideContext): Promise<ParserOverrideResult>;
+    /** Bound {@link runRegisteredPreflightOverrideForTest} over `activation.preflight`. */
+    runPreflightOverride(context: PreflightOverrideContext): Promise<PreflightOverrideResult>;
+    /** Bound {@link runRegisteredRendererOverrideForTest} over `activation.renderers`. */
+    runRendererOverride(context: RendererOverrideContext): Promise<RendererOverrideResult>;
+    /** Bound {@link runRegisteredServiceOverrideForTest} over `activation.services`. */
+    runServiceOverride(context: ServiceOverrideContext): Promise<ServiceOverrideResult>;
+    /** Bound {@link runRegisteredSearchProviderForTest} over `activation.registrations`. */
+    runSearchProvider<Operation extends keyof SearchProviderOperationContexts>(options: {
+        provider: string;
+        operation: Operation;
+        context: SearchProviderOperationContexts[Operation];
+    }): Promise<SearchProviderOperationResults[Operation]>;
+    /** Bound {@link runRegisteredVectorStoreAdapterForTest} over `activation.registrations`. */
+    runVectorStoreAdapter<Operation extends keyof VectorStoreAdapterOperationContexts>(options: {
+        adapter: string;
+        operation: Operation;
+        context: VectorStoreAdapterOperationContexts[Operation];
+    }): Promise<VectorStoreAdapterOperationResults[Operation]>;
+    /** Bound {@link runRegisteredMigrationForTest} over `activation.registrations`. */
+    runMigration(options: RunRegisteredMigrationForTestOptions): Promise<unknown>;
+    /** Bound {@link runRegisteredImporterForTest} over the whole `activation`. */
+    runImporter(options: RunRegisteredImporterForTestOptions): Promise<CommandHandlerResult>;
+    /** Bound {@link runRegisteredExporterForTest} over the whole `activation`. */
+    runExporter(options: RunRegisteredExporterForTestOptions): Promise<CommandHandlerResult>;
+    /**
+     * Bound {@link deactivateExtensionForTest} — runs the real teardown engine for
+     * this harness's module, forwarding its resolved `name`/`layer`/`activation` so
+     * the skip-key matches and a never-initialized extension is not deactivated.
+     */
+    deactivate(options?: {
+        deactivateTimeoutMs?: number;
+    }): Promise<ExtensionDeactivationResult>;
+}
+/**
+ * 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 declare function createExtensionTestHarness(module: unknown, options?: ActivateExtensionForTestOptions): Promise<ExtensionTestHarness>;

package/dist/sdk/testing.js

@@ -1,10 +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]="7a8097be-5b9f-5313-9ac3-6120d2fce878")}catch(e){}}();
+!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",
@@ -971,5 +985,168 @@ export function assertExtensionCapabilityUsage(activation, expectation) {
     }
     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=7a8097be-5b9f-5313-9ac3-6120d2fce878
+//# debugId=9ca86b28-8f2c-5dd3-bdf0-85d3f60e6197