@unbrained/pm-cli 2026.6.22 → 2026.6.24

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]="98dee6b5-4a5f-552f-a6f9-6db6525de5a8")}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 { checkExtensionManifestCompatibility, describeExtensionBlueprint, lintExtensionBlueprint, preflightExtension, } 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,265 @@ 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;
+}
+/**
+ * Strictly assert a manifest's `capabilities` equal the least-privilege set a
+ * declarative {@link ExtensionBlueprint} exercises, throwing on any drift in
+ * either direction.
+ *
+ * This is the strict bookend to the lenient {@link assertExtensionBlueprint}:
+ * where that helper fails only on an *undeclared* capability (the `error`-severity
+ * `extension_capability_missing` activation crash) and merely *warns* on an unused
+ * one, this assertion fails on **both** — an undeclared capability (`missing`) and
+ * a declared-but-unused one (`unused`) — so a hand-maintained `manifest.json` stays
+ * exactly the set the blueprint requires. Drop it into a package's
+ * `node:test`/Vitest suite to guard against capability drift in CI, the natural
+ * companion to {@link ../sdk/compose.js#synthesizeExtensionManifest} (assert what
+ * you would otherwise generate). Only `capabilities` are reconciled because that is
+ * the one manifest field a blueprint determines.
+ *
+ * The reconciliation is returned on success so a test can still inspect advisory
+ * warnings (duplicate command, empty surface) without failing on them.
+ */
+export function assertExtensionManifestMatchesBlueprint(manifest, blueprint) {
+    // Coerce a malformed/absent capabilities field to an explicit empty declared set
+    // so an untyped `.js` caller gets a deterministic `missing` list rather than the
+    // lint silently falling back to the blueprint's in-module manifest mirror.
+    const declaredCapabilities = Array.isArray(manifest.capabilities) ? manifest.capabilities : [];
+    const result = lintExtensionBlueprint(blueprint, { declaredCapabilities });
+    // `declared` is guaranteed non-null here: we always hand lint an array, so it
+    // never takes its "no declared set" branch. The cast drops the unreachable null.
+    const declared = result.declared;
+    const declaredSet = new Set(declared);
+    const usedSet = new Set(result.used);
+    const missing = result.used.filter((capability) => !declaredSet.has(capability));
+    const unused = declared.filter((capability) => !usedSet.has(capability));
+    if (missing.length > 0 || unused.length > 0) {
+        const parts = [];
+        if (missing.length > 0) {
+            parts.push(`missing [${missing.join(", ")}] (the blueprint registers ${missing.length === 1 ? "a surface" : "surfaces"} requiring ${missing.length === 1 ? "it" : "them"}; activation throws extension_capability_missing)`);
+        }
+        if (unused.length > 0) {
+            parts.push(`unused [${unused.join(", ")}] (declared but no surface exercises ${unused.length === 1 ? "it" : "them"}; drop for least privilege)`);
+        }
+        throw new Error(`Manifest capabilities do not match the blueprint: ${parts.join("; ")}. ` +
+            "Set capabilities to synthesizeExtensionManifest(blueprint, identity).capabilities to stay in sync.");
+    }
+    return { used: result.used, declared, missing, unused, findings: result.findings };
+}
+/**
+ * Assert an extension manifest's declared version bounds permit it to load on a
+ * target pm CLI version, throwing when a bound blocks the load.
+ *
+ * This is the throwing CI/test counterpart to
+ * {@link ../sdk/compose.js#checkExtensionManifestCompatibility}: it runs the same
+ * author-time version-bound analysis and fails on any blocking incompatibility — a
+ * malformed bound (`*_invalid`), a `pm_min_version` the target is below
+ * (`pm_min_version_unmet`), or a `block`-mode `pm_max_version` the target exceeds
+ * (`pm_max_version_exceeded`). Advisory `warning` findings (`*_unchecked`, or a
+ * `warn`-mode `pm_max_version_exceeded_warn`) never throw, because the loader
+ * would still load the extension. Pin it to the pm version a package commits to
+ * supporting so a too-tight or malformed bound fails the package's own suite, not
+ * a user's install. The full compatibility result is returned on success so a test
+ * can still inspect advisory warnings.
+ */
+export function assertExtensionManifestCompatible(manifest, target) {
+    const result = checkExtensionManifestCompatibility(manifest, target);
+    const blocking = result.findings.filter((finding) => finding.severity === "error");
+    if (blocking.length > 0) {
+        throw new Error(`Extension manifest is not compatible with pm ${result.pmVersion}: ${blocking
+            .map((finding) => finding.message)
+            .join("; ")}`);
+    }
+    return result;
+}
+/**
+ * Preflight a declarative {@link ExtensionBlueprint} through every author-time
+ * check in one test, throwing if any stage produced an `error`-severity finding.
+ *
+ * This is the throwing CI/test bookend over
+ * {@link ../sdk/compose.js#preflightExtension} — the single guard that replaces
+ * chaining {@link assertExtensionBlueprint}, {@link assertExtensionManifestMatchesBlueprint},
+ * and {@link assertExtensionManifestCompatible} in a package's
+ * `node:test`/Vitest suite. It runs the same consolidated analysis (always lints
+ * the blueprint; synthesizes the manifest when `options.identity` is given; checks
+ * version bounds when `options.target` is given) and throws one error listing every
+ * blocking finding tagged by its `source:code`. Advisory `warning` findings (an
+ * unused capability, a duplicate command, an `*_unchecked` bound) never throw,
+ * matching the underlying stages. The full {@link ExtensionPreflightReport} is
+ * returned on success so a test can still inspect those warnings, the synthesized
+ * manifest, and the derived capability set without failing on them.
+ */
+export function assertExtensionPreflight(blueprint, options = {}) {
+    const report = preflightExtension(blueprint, options);
+    if (!report.ok) {
+        const errors = report.findings.filter((finding) => finding.severity === "error");
+        throw new Error(`Extension failed preflight with ${errors.length} ${errors.length === 1 ? "error" : "errors"}:\n` +
+            errors.map((finding) => `  - [${finding.source}:${finding.code}] ${finding.message}`).join("\n"));
+    }
+    return report;
+}
+/**
+ * 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=98dee6b5-4a5f-552f-a6f9-6db6525de5a8