@unbrained/pm-cli 2026.6.30 → 2026.7.1

package/dist/sdk/compose.js

@@ -1,5 +1,5 @@
 
-!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]="fa377459-0629-5c62-a22b-a21485250792")}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]="ef101a7b-f751-5242-8a7b-099f2a969a46")}catch(e){}}();
 import { normalizeKnownExtensionCapability, resolveLegacyExtensionCapabilityAlias, } from "../core/extensions/extension-capability-aliases.js";
 import { normalizeCommandName } from "../core/extensions/extension-runtime-helpers.js";
 import { evaluatePmMaxVersionBound, evaluatePmMinVersionBound, } from "../core/extensions/version-compat.js";
@@ -35,6 +35,96 @@ export function defineExtension(module) {
 export function defineExtensionBlueprint(blueprint) {
     return blueprint;
 }
+/**
+ * Register a blueprint's command-layer surfaces — fresh command definitions,
+ * command overrides, flag tables, and parser/renderer/service overrides — in the
+ * deterministic order {@link composeExtension} documents.
+ */
+function registerBlueprintCommandSurfaces(api, blueprint) {
+    for (const command of blueprint.commands ?? []) {
+        api.registerCommand(command);
+    }
+    for (const [command, override] of Object.entries(blueprint.commandOverrides ?? {})) {
+        api.registerCommand(command, override);
+    }
+    for (const [targetCommand, flags] of Object.entries(blueprint.flags ?? {})) {
+        api.registerFlags(targetCommand, flags);
+    }
+    for (const [command, override] of Object.entries(blueprint.parsers ?? {})) {
+        api.registerParser(command, override);
+    }
+    for (const [format, renderer] of Object.entries(blueprint.renderers ?? {})) {
+        api.registerRenderer(format, renderer);
+    }
+    for (const [service, override] of Object.entries(blueprint.services ?? {})) {
+        api.registerService(service, override);
+    }
+}
+/**
+ * Register a blueprint's schema-layer surfaces — preflight overrides, item types,
+ * item fields, schema migrations, and project profiles — preserving the
+ * batch-registration semantics of `registerItemTypes`/`registerItemFields`
+ * (only invoked when at least one entry is present).
+ */
+function registerBlueprintSchemaSurfaces(api, blueprint) {
+    for (const override of blueprint.preflights ?? []) {
+        api.registerPreflight(override);
+    }
+    const itemTypes = blueprint.itemTypes ?? [];
+    if (itemTypes.length > 0) {
+        api.registerItemTypes(itemTypes);
+    }
+    const itemFields = blueprint.itemFields ?? [];
+    if (itemFields.length > 0) {
+        api.registerItemFields(itemFields);
+    }
+    for (const migration of blueprint.migrations ?? []) {
+        api.registerMigration(migration);
+    }
+    for (const profile of blueprint.profiles ?? []) {
+        api.registerProfile(profile);
+    }
+}
+/**
+ * Register a blueprint's retrieval and interchange surfaces — search providers,
+ * vector store adapters, importers, and exporters — passing each importer's and
+ * exporter's optional registration options through verbatim.
+ */
+function registerBlueprintRetrievalSurfaces(api, blueprint) {
+    for (const provider of blueprint.searchProviders ?? []) {
+        api.registerSearchProvider(provider);
+    }
+    for (const adapter of blueprint.vectorStoreAdapters ?? []) {
+        api.registerVectorStoreAdapter(adapter);
+    }
+    for (const entry of blueprint.importers ?? []) {
+        api.registerImporter(entry.name, entry.importer, entry.options);
+    }
+    for (const entry of blueprint.exporters ?? []) {
+        api.registerExporter(entry.name, entry.exporter, entry.options);
+    }
+}
+/**
+ * Register a blueprint's lifecycle hooks in canonical order
+ * (beforeCommand → afterCommand → onWrite → onRead → onIndex).
+ */
+function registerBlueprintHooks(api, hooks) {
+    for (const hook of hooks.beforeCommand ?? []) {
+        api.hooks.beforeCommand(hook);
+    }
+    for (const hook of hooks.afterCommand ?? []) {
+        api.hooks.afterCommand(hook);
+    }
+    for (const hook of hooks.onWrite ?? []) {
+        api.hooks.onWrite(hook);
+    }
+    for (const hook of hooks.onRead ?? []) {
+        api.hooks.onRead(hook);
+    }
+    for (const hook of hooks.onIndex ?? []) {
+        api.hooks.onIndex(hook);
+    }
+}
 /**
  * Assemble an {@link ExtensionModule} from a declarative {@link ExtensionBlueprint}.
  *
@@ -53,73 +143,14 @@ export function defineExtensionBlueprint(blueprint) {
  */
 export function composeExtension(blueprint) {
     const activate = async (api) => {
-        for (const command of blueprint.commands ?? []) {
-            api.registerCommand(command);
-        }
-        for (const [command, override] of Object.entries(blueprint.commandOverrides ?? {})) {
-            api.registerCommand(command, override);
-        }
-        for (const [targetCommand, flags] of Object.entries(blueprint.flags ?? {})) {
-            api.registerFlags(targetCommand, flags);
-        }
-        for (const [command, override] of Object.entries(blueprint.parsers ?? {})) {
-            api.registerParser(command, override);
-        }
-        for (const [format, renderer] of Object.entries(blueprint.renderers ?? {})) {
-            api.registerRenderer(format, renderer);
-        }
-        for (const [service, override] of Object.entries(blueprint.services ?? {})) {
-            api.registerService(service, override);
-        }
-        for (const override of blueprint.preflights ?? []) {
-            api.registerPreflight(override);
-        }
-        const itemTypes = blueprint.itemTypes ?? [];
-        if (itemTypes.length > 0) {
-            api.registerItemTypes(itemTypes);
-        }
-        const itemFields = blueprint.itemFields ?? [];
-        if (itemFields.length > 0) {
-            api.registerItemFields(itemFields);
-        }
-        for (const migration of blueprint.migrations ?? []) {
-            api.registerMigration(migration);
-        }
-        for (const profile of blueprint.profiles ?? []) {
-            api.registerProfile(profile);
-        }
-        for (const provider of blueprint.searchProviders ?? []) {
-            api.registerSearchProvider(provider);
-        }
-        for (const adapter of blueprint.vectorStoreAdapters ?? []) {
-            api.registerVectorStoreAdapter(adapter);
-        }
-        for (const entry of blueprint.importers ?? []) {
-            api.registerImporter(entry.name, entry.importer, entry.options);
-        }
-        for (const entry of blueprint.exporters ?? []) {
-            api.registerExporter(entry.name, entry.exporter, entry.options);
-        }
+        registerBlueprintCommandSurfaces(api, blueprint);
+        registerBlueprintSchemaSurfaces(api, blueprint);
+        registerBlueprintRetrievalSurfaces(api, blueprint);
         // `?? {}` (rather than a `!== undefined` guard) so an explicit `hooks: null`
         // crossing an untyped boundary (e.g. a blueprint hydrated from JSON) is
         // treated the same as omitting it, instead of throwing on the first
         // `hooks.beforeCommand` access.
-        const hooks = blueprint.hooks ?? {};
-        for (const hook of hooks.beforeCommand ?? []) {
-            api.hooks.beforeCommand(hook);
-        }
-        for (const hook of hooks.afterCommand ?? []) {
-            api.hooks.afterCommand(hook);
-        }
-        for (const hook of hooks.onWrite ?? []) {
-            api.hooks.onWrite(hook);
-        }
-        for (const hook of hooks.onRead ?? []) {
-            api.hooks.onRead(hook);
-        }
-        for (const hook of hooks.onIndex ?? []) {
-            api.hooks.onIndex(hook);
-        }
+        registerBlueprintHooks(api, blueprint.hooks ?? {});
         await blueprint.activate?.(api);
     };
     // Truthy checks (rather than `!== undefined`) so an explicit `null` mirror or
@@ -545,34 +576,14 @@ function normalizeDeclaredCapabilities(capabilities) {
     return [...known].sort((left, right) => left.localeCompare(right));
 }
 /**
- * Preflight a declarative {@link ExtensionBlueprint} at author time, returning the
- * structured issues that would otherwise only surface at activation.
- *
- * It is the author-time inverse of the runtime extension guardrails — pure data
- * analysis with no loading, activation, or side effects:
- *
- * - capability drift in both directions: a capability a surface exercises but the
- *   declared set omits is an `error` (the loader throws `extension_capability_missing`
- *   at activation); a declared capability no surface exercises is a `warning` (the
- *   author-time form of the `pm package doctor` `extension_capability_unused` note,
- *   making this the static inverse of `reconcileExtensionCapabilityUsage`).
- * - structural footguns: a command path declared twice (`duplicate_command`), a
- *   path declared as both a command and an override (`command_override_conflict`),
- *   and a registration field present but empty (`empty_surface`).
- *
- * The declared set is taken from `options.declaredCapabilities` or, failing that,
- * `blueprint.manifest.capabilities`; with neither, capability reconciliation is
- * skipped and a single `manifest_capabilities_absent` warning suggests adopting
- * {@link deriveExtensionCapabilities}. Like {@link describeExtensionBlueprint},
- * the imperative `activate` escape hatch is invisible to this static check.
+ * Reconcile a blueprint's exercised capabilities against its declared set: a
+ * used-but-undeclared capability is an `error` (activation throws
+ * `extension_capability_missing`), a declared-but-unused one a `warning`, and a
+ * wholly absent declared set (`declared === null`) yields the single
+ * `manifest_capabilities_absent` adoption hint.
  */
-export function lintExtensionBlueprint(blueprint, options = {}) {
+function collectBlueprintCapabilityFindings(used, declared) {
     const findings = [];
-    const used = deriveExtensionCapabilities(blueprint);
-    // A non-array declared source (an untyped `.js` author's malformed manifest, or
-    // a missing field) is treated as "no declared set" rather than "declares nothing".
-    const declaredSource = options.declaredCapabilities ?? blueprint.manifest?.capabilities;
-    const declared = Array.isArray(declaredSource) ? normalizeDeclaredCapabilities(declaredSource) : null;
     if (declared === null) {
         if (used.length > 0) {
             findings.push({
@@ -581,32 +592,40 @@ export function lintExtensionBlueprint(blueprint, options = {}) {
                 message: `Blueprint exercises ${used.length === 1 ? "capability" : "capabilities"} [${used.join(", ")}] but declares none; set capabilities to deriveExtensionCapabilities(blueprint) so the manifest grant matches.`,
             });
         }
+        return findings;
     }
-    else {
-        const declaredSet = new Set(declared);
-        const usedSet = new Set(used);
-        for (const capability of used) {
-            if (!declaredSet.has(capability)) {
-                findings.push({
-                    code: "capability_undeclared",
-                    severity: "error",
-                    message: `Blueprint exercises capability "${capability}" but it is absent from the declared capabilities; activation throws extension_capability_missing — add "${capability}" to the manifest capabilities.`,
-                    capability,
-                });
-            }
+    const declaredSet = new Set(declared);
+    const usedSet = new Set(used);
+    for (const capability of used) {
+        if (!declaredSet.has(capability)) {
+            findings.push({
+                code: "capability_undeclared",
+                severity: "error",
+                message: `Blueprint exercises capability "${capability}" but it is absent from the declared capabilities; activation throws extension_capability_missing — add "${capability}" to the manifest capabilities.`,
+                capability,
+            });
         }
-        for (const capability of declared) {
-            if (!usedSet.has(capability)) {
-                findings.push({
-                    code: "capability_unused",
-                    severity: "warning",
-                    message: `Capability "${capability}" is declared but no blueprint surface exercises it; drop it to keep the manifest least-privilege (pm package doctor reports this as extension_capability_unused).`,
-                    capability,
-                });
-            }
+    }
+    for (const capability of declared) {
+        if (!usedSet.has(capability)) {
+            findings.push({
+                code: "capability_unused",
+                severity: "warning",
+                message: `Capability "${capability}" is declared but no blueprint surface exercises it; drop it to keep the manifest least-privilege (pm package doctor reports this as extension_capability_unused).`,
+                capability,
+            });
         }
     }
-    // Duplicate command paths within the declared command definitions.
+    return findings;
+}
+/**
+ * Detect structural command footguns in a blueprint: a command path declared
+ * more than once (`duplicate_command`, the later registration shadowing the
+ * earlier at dispatch) and a path declared both as a fresh command definition
+ * and as an override (`command_override_conflict`).
+ */
+function collectBlueprintCommandFindings(blueprint) {
+    const findings = [];
     const commandPathCounts = new Map();
     for (const command of blueprint.commands ?? []) {
         const path = normalizeCommandName(command.name);
@@ -622,7 +641,6 @@ export function lintExtensionBlueprint(blueprint, options = {}) {
             });
         }
     }
-    // A command path declared as both a fresh definition and an override.
     const overridePaths = new Set(Object.keys(blueprint.commandOverrides ?? {}).map((command) => normalizeCommandName(command)));
     for (const path of commandPathCounts.keys()) {
         if (overridePaths.has(path)) {
@@ -634,7 +652,15 @@ export function lintExtensionBlueprint(blueprint, options = {}) {
             });
         }
     }
-    // Registration fields present on the blueprint but contributing nothing.
+    return findings;
+}
+/**
+ * Flag blueprint registration fields that are present but contribute nothing —
+ * an empty array/record surface, or a `hooks` object registering no lifecycle
+ * hook — each reported as an `empty_surface` warning (fields first, then hooks).
+ */
+function collectBlueprintEmptySurfaceFindings(blueprint) {
+    const findings = [];
     for (const field of BLUEPRINT_LINTABLE_SURFACE_FIELDS) {
         if (field in blueprint && !hasEntries(blueprint[field])) {
             findings.push({
@@ -657,6 +683,46 @@ export function lintExtensionBlueprint(blueprint, options = {}) {
             });
         }
     }
+    return findings;
+}
+/**
+ * Preflight a declarative {@link ExtensionBlueprint} at author time, returning the
+ * structured issues that would otherwise only surface at activation.
+ *
+ * It is the author-time inverse of the runtime extension guardrails — pure data
+ * analysis with no loading, activation, or side effects:
+ *
+ * - capability drift in both directions: a capability a surface exercises but the
+ *   declared set omits is an `error` (the loader throws `extension_capability_missing`
+ *   at activation); a declared capability no surface exercises is a `warning` (the
+ *   author-time form of the `pm package doctor` `extension_capability_unused` note,
+ *   making this the static inverse of `reconcileExtensionCapabilityUsage`).
+ * - structural footguns: a command path declared twice (`duplicate_command`), a
+ *   path declared as both a command and an override (`command_override_conflict`),
+ *   and a registration field present but empty (`empty_surface`).
+ *
+ * The declared set is taken from `options.declaredCapabilities` or, failing that,
+ * `blueprint.manifest.capabilities`; with neither, capability reconciliation is
+ * skipped and a single `manifest_capabilities_absent` warning suggests adopting
+ * {@link deriveExtensionCapabilities}. Like {@link describeExtensionBlueprint},
+ * the imperative `activate` escape hatch is invisible to this static check. The
+ * findings are assembled from the per-dimension collectors
+ * ({@link collectBlueprintCapabilityFindings}, {@link collectBlueprintCommandFindings},
+ * {@link collectBlueprintEmptySurfaceFindings}) in that detection order.
+ */
+export function lintExtensionBlueprint(blueprint, options = {}) {
+    const used = deriveExtensionCapabilities(blueprint);
+    // A non-array declared source (an untyped `.js` author's malformed manifest, or
+    // a missing field) is treated as "no declared set" rather than "declares nothing".
+    const declaredSource = options.declaredCapabilities ?? blueprint.manifest?.capabilities;
+    const declared = Array.isArray(declaredSource) ? normalizeDeclaredCapabilities(declaredSource) : null;
+    // Findings accumulate in detection order: capability drift, then command
+    // duplicates/conflicts, then empty surfaces.
+    const findings = [
+        ...collectBlueprintCapabilityFindings(used, declared),
+        ...collectBlueprintCommandFindings(blueprint),
+        ...collectBlueprintEmptySurfaceFindings(blueprint),
+    ];
     return {
         ok: findings.every((finding) => finding.severity !== "error"),
         findings,
@@ -888,4 +954,4 @@ export function preflightExtension(blueprint, options = {}) {
     };
 }
 //# sourceMappingURL=compose.js.map
-//# debugId=fa377459-0629-5c62-a22b-a21485250792
+//# debugId=ef101a7b-f751-5242-8a7b-099f2a969a46