@unbrained/pm-cli 2026.6.22 → 2026.6.24

package/dist/sdk/compose.js

@@ -0,0 +1,841 @@
+
+!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]="376f0804-a437-515f-a653-485531d98f13")}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";
+/**
+ * Typed identity helper for extension module exports.
+ *
+ * Use as:
+ * `export default defineExtension({ activate(api) { ... } })`
+ *
+ * Reach for {@link composeExtension} instead when you would rather declare the
+ * registrations as data than wire them imperatively in `activate`.
+ */
+export function defineExtension(module) {
+    return module;
+}
+/**
+ * Typed identity helper for a (partial) {@link ExtensionBlueprint} authored as its
+ * own module — the typed entry point of the modular declarative-authoring loop.
+ *
+ * It is the natural companion to {@link mergeExtensionBlueprints}: when an
+ * extension's surface is split across files — a commands module, a search module,
+ * a hooks module — wrap each fragment so it is contract-checked *at its definition
+ * site* (with editor completion), exactly as {@link defineExtension} types a whole
+ * module and {@link defineExtensionManifest} types a manifest. It returns its
+ * argument unchanged, preserving the literal type
+ * so the fragment composes into {@link mergeExtensionBlueprints},
+ * {@link composeExtension}, or {@link composeExtensionPackage} with no loss of
+ * inference.
+ *
+ * Use as:
+ * `export const commandsModule = defineExtensionBlueprint({ commands: [...] })`
+ */
+export function defineExtensionBlueprint(blueprint) {
+    return blueprint;
+}
+/**
+ * Assemble an {@link ExtensionModule} from a declarative {@link ExtensionBlueprint}.
+ *
+ * The returned module's `activate` registers every populated surface through the
+ * matching `api.register*` method in a deterministic order (commands → overrides
+ * → flags → parsers → renderers → services → preflights → item types → item
+ * fields → migrations → search providers → vector store adapters → importers →
+ * exporters → hooks), then awaits the blueprint's optional imperative `activate`
+ * so it can layer on anything the declarative form cannot express. `manifest`
+ * and `deactivate` are copied onto the module verbatim.
+ *
+ * This is a pure assembler: it does not validate the definitions. Per-surface
+ * contract enforcement stays in `api.register*` (and the loader), exactly as it
+ * does for hand-written `activate` bodies, so a malformed definition surfaces
+ * the same activation diagnostic either way.
+ */
+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 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);
+        }
+        // `?? {}` (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);
+        }
+        await blueprint.activate?.(api);
+    };
+    // Truthy checks (rather than `!== undefined`) so an explicit `null` mirror or
+    // teardown is treated as absent instead of copied onto the module.
+    const module = { activate };
+    if (blueprint.manifest) {
+        module.manifest = blueprint.manifest;
+    }
+    if (blueprint.deactivate) {
+        module.deactivate = blueprint.deactivate;
+    }
+    return module;
+}
+/**
+ * Concatenate the populated entries of an array surface across blueprints,
+ * preserving argument order. Returns `undefined` when no blueprint contributes
+ * any entry, so {@link mergeExtensionBlueprints} omits the field instead of
+ * emitting an empty array. `?? []` tolerates an explicit `null` field (e.g. from a
+ * blueprint hydrated across an untyped boundary) exactly as {@link composeExtension} does.
+ */
+function mergeArraySurface(surfaces) {
+    const merged = surfaces.flatMap((surface) => surface ?? []);
+    return merged.length > 0 ? merged : undefined;
+}
+/**
+ * Shallow-merge single-handler record surfaces (`commandOverrides`, `parsers`,
+ * `renderers`, `services`) with last-defined-wins precedence on a key collision,
+ * exactly like spreading the records in argument order. Returns `undefined` when
+ * no blueprint contributes any key.
+ */
+function mergeHandlerRecord(surfaces) {
+    const merged = Object.assign({}, ...surfaces.map((surface) => surface ?? {}));
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Merge `flags` records by concatenating every blueprint's flag array for a shared
+ * target command, mirroring the additive `api.registerFlags` semantics so each
+ * module's flags reach the command. Returns `undefined` when no blueprint declares
+ * any flags.
+ */
+function mergeFlagRecord(surfaces) {
+    const merged = {};
+    for (const surface of surfaces) {
+        for (const [command, flags] of Object.entries(surface ?? {})) {
+            // `flags` is the record's array value, never nullish in-type — `composeExtension`
+            // likewise passes it to `registerFlags` unguarded — so it is spread directly.
+            merged[command] = [...(merged[command] ?? []), ...flags];
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+const EXTENSION_BLUEPRINT_HOOK_KEYS = [
+    "beforeCommand",
+    "afterCommand",
+    "onWrite",
+    "onRead",
+    "onIndex",
+];
+// Compile-time exhaustiveness guard: adding a hook field must update the canonical
+// merge order above, and stale keys cannot remain in that list.
+const EXTENSION_BLUEPRINT_HOOK_KEY_COVERAGE = {};
+void EXTENSION_BLUEPRINT_HOOK_KEY_COVERAGE;
+function assignMergedHookSurface(merged, surfaces, key) {
+    const hookArrays = surfaces.map((hooks) => hooks?.[key]);
+    const value = mergeArraySurface(hookArrays);
+    if (value !== undefined) {
+        const typedMerged = merged;
+        typedMerged[key] = value;
+    }
+}
+/**
+ * Merge the nested `hooks` surface by concatenating each lifecycle kind's array in
+ * canonical order. Returns `undefined` when no blueprint registers any hook.
+ */
+function mergeHookSurfaces(surfaces) {
+    const merged = {};
+    for (const key of EXTENSION_BLUEPRINT_HOOK_KEYS) {
+        assignMergedHookSurface(merged, surfaces, key);
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Merge several partial {@link ExtensionBlueprint}s into one, so an extension's
+ * surface can be authored *modularly* — a commands module, a search module, a
+ * hooks module — and combined into a single blueprint to feed
+ * {@link composeExtension}, {@link composeExtensionPackage},
+ * {@link synthesizeExtensionManifest}, {@link describeExtensionBlueprint}, or
+ * {@link preflightExtension}.
+ *
+ * The merge is pure and deterministic and never mutates an input. Each surface
+ * combines the way its underlying `api.register*` call composes:
+ *
+ * - **Array surfaces** — `commands`, `preflights`, `itemTypes`, `itemFields`,
+ *   `migrations`, `searchProviders`, `vectorStoreAdapters`, `importers`,
+ *   `exporters` — concatenate in argument order.
+ * - **`flags`** concatenates the flag arrays of any shared target command,
+ *   mirroring additive `api.registerFlags`: every module's flags reach the command.
+ * - **Single-handler records** — `commandOverrides`, `parsers`, `renderers`,
+ *   `services` — follow last-defined-wins precedence on a key collision, exactly
+ *   like spreading the records in argument order; a later module deliberately
+ *   overrides an earlier one's handler for that key.
+ * - **`hooks`** concatenates each lifecycle kind's array in canonical order.
+ * - The imperative **`activate`** escape hatches chain in argument order (each
+ *   awaited), so every module's escape-hatch wiring still runs.
+ * - The **`deactivate`** teardown hooks chain in *reverse* argument order (LIFO),
+ *   releasing resources in the inverse of acquisition. Teardown is best-effort:
+ *   a throwing hook does not strand later modules' cleanup — every hook runs and
+ *   teardown failures are re-thrown afterwards (as the original error for one
+ *   failure, or an `AggregateError` for several).
+ * - The **`manifest`** mirror is last-defined-wins.
+ *
+ * Because `composeExtension` and the derive/lint/describe helpers are pure readers
+ * of this data, a merged blueprint behaves exactly as a hand-written one: a command
+ * two modules both define survives as a duplicate in the merged `commands` array
+ * and {@link lintExtensionBlueprint} flags it, just as it would in one file. An
+ * empty field is omitted rather than emitted empty, so merging zero blueprints
+ * returns an empty blueprint (`{}`).
+ */
+export function mergeExtensionBlueprints(...blueprints) {
+    const merged = {};
+    const assign = (key, value) => {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    };
+    assign("commands", mergeArraySurface(blueprints.map((blueprint) => blueprint.commands)));
+    assign("commandOverrides", mergeHandlerRecord(blueprints.map((blueprint) => blueprint.commandOverrides)));
+    assign("flags", mergeFlagRecord(blueprints.map((blueprint) => blueprint.flags)));
+    assign("parsers", mergeHandlerRecord(blueprints.map((blueprint) => blueprint.parsers)));
+    assign("renderers", mergeHandlerRecord(blueprints.map((blueprint) => blueprint.renderers)));
+    assign("services", mergeHandlerRecord(blueprints.map((blueprint) => blueprint.services)));
+    assign("preflights", mergeArraySurface(blueprints.map((blueprint) => blueprint.preflights)));
+    assign("itemTypes", mergeArraySurface(blueprints.map((blueprint) => blueprint.itemTypes)));
+    assign("itemFields", mergeArraySurface(blueprints.map((blueprint) => blueprint.itemFields)));
+    assign("migrations", mergeArraySurface(blueprints.map((blueprint) => blueprint.migrations)));
+    assign("searchProviders", mergeArraySurface(blueprints.map((blueprint) => blueprint.searchProviders)));
+    assign("vectorStoreAdapters", mergeArraySurface(blueprints.map((blueprint) => blueprint.vectorStoreAdapters)));
+    assign("importers", mergeArraySurface(blueprints.map((blueprint) => blueprint.importers)));
+    assign("exporters", mergeArraySurface(blueprints.map((blueprint) => blueprint.exporters)));
+    assign("hooks", mergeHookSurfaces(blueprints.map((blueprint) => blueprint.hooks)));
+    // Last-defined-wins for the in-module manifest mirror: a later module's identity
+    // supersedes an earlier one's, matching the single-handler record precedence.
+    let manifest;
+    for (const blueprint of blueprints) {
+        if (blueprint.manifest) {
+            manifest = blueprint.manifest;
+        }
+    }
+    assign("manifest", manifest);
+    // Imperative escape hatches chain forward (acquisition order); teardown chains
+    // in reverse (LIFO), so resources release in the inverse of acquisition.
+    const hasActivates = blueprints.some((blueprint) => blueprint.activate);
+    assign("activate", hasActivates
+        ? async (api) => {
+            for (const blueprint of blueprints) {
+                if (blueprint.activate) {
+                    await blueprint.activate(api);
+                }
+            }
+        }
+        : undefined);
+    const hasDeactivates = blueprints.some((blueprint) => blueprint.deactivate);
+    assign("deactivate", hasDeactivates
+        ? async () => {
+            // Teardown is best-effort across modules: a throwing `deactivate` must
+            // not strand a later module's cleanup, so every hook runs (in reverse,
+            // LIFO) and failures are surfaced after cleanup completes.
+            const errors = [];
+            for (const blueprint of [...blueprints].reverse()) {
+                if (!blueprint.deactivate) {
+                    continue;
+                }
+                try {
+                    await blueprint.deactivate();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                if (errors.length > 1) {
+                    throw new AggregateError(errors, "Multiple extension blueprint deactivate hooks failed.");
+                }
+                throw errors[0];
+            }
+        }
+        : undefined);
+    return merged;
+}
+/**
+ * Blueprint registration fields whose presence implies a capability, paired with
+ * the capability each grants. Mirrors `EXTENSION_CAPABILITY_REGISTRATION_SURFACES`
+ * so a blueprint's derived capabilities exactly match what the loader enforces
+ * when {@link composeExtension}'s generated `activate` calls `api.register*`.
+ *
+ * `hooks` is handled separately (it is a nested object, not an array/record of
+ * registrations) and so is intentionally absent from this table.
+ */
+const BLUEPRINT_FIELD_CAPABILITIES = [
+    ["commands", "commands"],
+    ["commandOverrides", "commands"],
+    ["flags", "schema"],
+    ["itemTypes", "schema"],
+    ["itemFields", "schema"],
+    ["migrations", "schema"],
+    ["parsers", "parser"],
+    ["renderers", "renderers"],
+    ["services", "services"],
+    ["preflights", "preflight"],
+    ["searchProviders", "search"],
+    ["vectorStoreAdapters", "search"],
+    ["importers", "importers"],
+    ["exporters", "importers"],
+];
+function hasEntries(value) {
+    // `!value` treats both `null` and `undefined` as "no entries", so an untyped
+    // JavaScript author cannot crash capability derivation with an explicit null
+    // field — `Object.keys(null)` would otherwise throw.
+    if (!value) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    return Object.keys(value).length > 0;
+}
+/**
+ * Compute the minimal least-privilege capability set a {@link ExtensionBlueprint}
+ * exercises, sorted and de-duplicated.
+ *
+ * Use it to author `manifest.json` `capabilities` exactly — declaring nothing the
+ * extension does not use and nothing it does. It is the author-time inverse of
+ * the runtime `reconcileExtensionCapabilityUsage` reconciliation: derive the set
+ * here before activation rather than detecting drift after it. A blueprint with
+ * no registration surfaces returns an empty array.
+ */
+export function deriveExtensionCapabilities(blueprint) {
+    const capabilities = new Set();
+    for (const [field, capability] of BLUEPRINT_FIELD_CAPABILITIES) {
+        if (hasEntries(blueprint[field])) {
+            capabilities.add(capability);
+        }
+    }
+    // A command definition carrying its own inline `flags` registers them through
+    // `registerCommand`, which asserts the `schema` capability independently of the
+    // top-level `flags` record. Mirror that here so the derived set still matches
+    // what activation enforces when a command declares flags inline and the
+    // blueprint has no separate `flags` field. `!== undefined` (not a truthiness or
+    // length check) matches the loader's exact guard, including an empty inline array.
+    if ((blueprint.commands ?? []).some((command) => command.flags !== undefined)) {
+        capabilities.add("schema");
+    }
+    // `?? {}` keeps an explicit `hooks: null` from throwing, mirroring composeExtension.
+    const hooks = blueprint.hooks ?? {};
+    if ([hooks.beforeCommand, hooks.afterCommand, hooks.onWrite, hooks.onRead, hooks.onIndex].some(hasEntries)) {
+        capabilities.add("hooks");
+    }
+    return [...capabilities].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Blueprint hook fields paired with the lifecycle kind each registers, ordered to
+ * match `ExtensionActivationResult.hook_counts` (and the runtime
+ * {@link ../core/extensions/activation-summary.js#describeExtensionActivation}'s
+ * `hooks` ordering) so a blueprint summary's `hooks` list reads in the same
+ * canonical order, not alphabetically.
+ */
+const BLUEPRINT_HOOK_FIELD_TO_KIND = [
+    ["beforeCommand", "before_command"],
+    ["afterCommand", "after_command"],
+    ["onWrite", "on_write"],
+    ["onRead", "on_read"],
+    ["onIndex", "on_index"],
+];
+/** De-duplicate and locale-sort a list of identifiers, mirroring the runtime summary. */
+function sortUnique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Compute, without activating, the exact {@link ExtensionActivationSummary} that
+ * {@link composeExtension}'s generated `activate` would produce for a blueprint.
+ *
+ * This is the author-time inverse of the runtime
+ * {@link ../core/extensions/activation-summary.js#describeExtensionActivation}:
+ * the runtime verb walks an *activated* registry, while this one reads the
+ * declarative {@link ExtensionBlueprint} data directly, so an author or agent can
+ * preview the full named surface map (commands, overrides, handlers, hooks, item
+ * types/fields, importers/exporters, search/vector adapters, parser/service/
+ * renderer overrides, flag-target commands, and the preflight count) with no
+ * loading, activation, or side effects. It is to the named surfaces what
+ * {@link deriveExtensionCapabilities} is to the capability set.
+ *
+ * Fidelity is by construction: command paths are normalized with the same
+ * `normalizeCommandName` the loader applies, and importer/exporter handler paths
+ * are synthesized as `normalizeCommandName("<name> import|export")`, exactly as
+ * `registerImporter`/`registerExporter` do. A parity test pins this output equal
+ * to `describeExtensionActivation` over the same composed-and-activated blueprint.
+ *
+ * The one surface it cannot reflect is the blueprint's optional imperative
+ * `activate` escape hatch — arbitrary code a static reader cannot inspect. A
+ * blueprint that registers everything through that hatch summarizes as empty.
+ */
+export function describeExtensionBlueprint(blueprint) {
+    const commandPaths = (blueprint.commands ?? []).map((command) => normalizeCommandName(command.name));
+    const importerPaths = (blueprint.importers ?? []).map((entry) => normalizeCommandName(`${entry.name} import`));
+    const exporterPaths = (blueprint.exporters ?? []).map((entry) => normalizeCommandName(`${entry.name} export`));
+    // A command definition with inline `flags` registers a flag target under its own
+    // path in addition to any top-level `flags` record, so union both sources.
+    const flagCommands = [
+        ...Object.keys(blueprint.flags ?? {}).map((command) => normalizeCommandName(command)),
+        ...(blueprint.commands ?? [])
+            .filter((command) => command.flags !== undefined)
+            .map((command) => normalizeCommandName(command.name)),
+    ];
+    const hooks = blueprint.hooks ?? {};
+    return {
+        capabilities: deriveExtensionCapabilities(blueprint),
+        commands: sortUnique(commandPaths),
+        command_overrides: sortUnique(Object.keys(blueprint.commandOverrides ?? {}).map((command) => normalizeCommandName(command))),
+        // command_handlers is a superset of commands that also carries the synthesized
+        // importer/exporter command paths, but never the override-only paths.
+        command_handlers: sortUnique([...commandPaths, ...importerPaths, ...exporterPaths]),
+        hooks: BLUEPRINT_HOOK_FIELD_TO_KIND.filter(([field]) => (hooks[field]?.length ?? 0) > 0).map(([, kind]) => kind),
+        flag_commands: sortUnique(flagCommands),
+        item_types: sortUnique((blueprint.itemTypes ?? []).map((type) => type.name)),
+        item_fields: sortUnique((blueprint.itemFields ?? []).map((field) => field.name)),
+        // id-less migrations register but carry no identifier, so they are omitted —
+        // exactly as describeExtensionActivation drops them from its `migrations` list.
+        migrations: sortUnique((blueprint.migrations ?? []).flatMap((migration) => (typeof migration.id === "string" ? [migration.id] : []))),
+        importers: sortUnique((blueprint.importers ?? []).map((entry) => normalizeCommandName(entry.name))),
+        exporters: sortUnique((blueprint.exporters ?? []).map((entry) => normalizeCommandName(entry.name))),
+        search_providers: sortUnique((blueprint.searchProviders ?? []).map((provider) => provider.name)),
+        vector_store_adapters: sortUnique((blueprint.vectorStoreAdapters ?? []).map((adapter) => adapter.name)),
+        parser_overrides: sortUnique(Object.keys(blueprint.parsers ?? {}).map((command) => normalizeCommandName(command))),
+        service_overrides: sortUnique(Object.keys(blueprint.services ?? {}).map((service) => String(service).trim().toLowerCase())),
+        renderer_overrides: sortUnique(Object.keys(blueprint.renderers ?? {}).map((format) => String(format).trim().toLowerCase())),
+        preflight_overrides: (blueprint.preflights ?? []).length,
+    };
+}
+/**
+ * The blueprint registration fields a lint flags as a dead "empty surface" when
+ * present but empty. Mirrors {@link BlueprintRegistrationField} so adding a new
+ * registration surface forces a decision here too; `hooks` is handled separately
+ * because it is a nested object rather than an array/record of registrations.
+ */
+const BLUEPRINT_LINTABLE_SURFACE_FIELDS = [
+    "commands",
+    "commandOverrides",
+    "flags",
+    "parsers",
+    "renderers",
+    "services",
+    "preflights",
+    "itemTypes",
+    "itemFields",
+    "migrations",
+    "searchProviders",
+    "vectorStoreAdapters",
+    "importers",
+    "exporters",
+];
+/** Normalize a raw declared-capability list to known capabilities only (legacy-alias aware, sorted, de-duplicated). */
+function normalizeDeclaredCapabilities(capabilities) {
+    const known = new Set();
+    for (const capability of capabilities) {
+        // Resolve a legacy alias (e.g. migration/validation → schema) exactly as the
+        // loader does before reconciliation — the author's raw manifest input has not
+        // been loader-normalized yet, so failing to resolve it here would misreport an
+        // alias-satisfied capability as undeclared. Fall back to a canonical known
+        // name; unknown capabilities are a separate diagnostic and are dropped so a
+        // typo is not misreported as "unused".
+        const normalized = resolveLegacyExtensionCapabilityAlias(capability) ?? normalizeKnownExtensionCapability(capability);
+        if (normalized !== null) {
+            known.add(normalized);
+        }
+    }
+    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.
+ */
+export function lintExtensionBlueprint(blueprint, options = {}) {
+    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({
+                code: "manifest_capabilities_absent",
+                severity: "warning",
+                message: `Blueprint exercises ${used.length === 1 ? "capability" : "capabilities"} [${used.join(", ")}] but declares none; set capabilities to deriveExtensionCapabilities(blueprint) so the manifest grant matches.`,
+            });
+        }
+    }
+    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,
+                });
+            }
+        }
+        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.
+    const commandPathCounts = new Map();
+    for (const command of blueprint.commands ?? []) {
+        const path = normalizeCommandName(command.name);
+        commandPathCounts.set(path, (commandPathCounts.get(path) ?? 0) + 1);
+    }
+    for (const [path, count] of commandPathCounts) {
+        if (count > 1) {
+            findings.push({
+                code: "duplicate_command",
+                severity: "warning",
+                message: `Command "${path}" is declared ${count} times in commands; the later registration shadows the earlier one at dispatch.`,
+                command: path,
+            });
+        }
+    }
+    // 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)) {
+            findings.push({
+                code: "command_override_conflict",
+                severity: "warning",
+                message: `Command "${path}" is declared both as a new command definition and as a command override; register one or the other.`,
+                command: path,
+            });
+        }
+    }
+    // Registration fields present on the blueprint but contributing nothing.
+    for (const field of BLUEPRINT_LINTABLE_SURFACE_FIELDS) {
+        if (field in blueprint && !hasEntries(blueprint[field])) {
+            findings.push({
+                code: "empty_surface",
+                severity: "warning",
+                message: `Blueprint field "${field}" is present but empty; remove it or populate it.`,
+                field,
+            });
+        }
+    }
+    if ("hooks" in blueprint) {
+        const hooks = blueprint.hooks ?? {};
+        const registersHook = [hooks.beforeCommand, hooks.afterCommand, hooks.onWrite, hooks.onRead, hooks.onIndex].some(hasEntries);
+        if (!registersHook) {
+            findings.push({
+                code: "empty_surface",
+                severity: "warning",
+                message: `Blueprint field "hooks" is present but registers no lifecycle hooks; remove it or populate it.`,
+                field: "hooks",
+            });
+        }
+    }
+    return {
+        ok: findings.every((finding) => finding.severity !== "error"),
+        findings,
+        used,
+        declared,
+    };
+}
+/**
+ * Generate a complete, least-privilege {@link ExtensionManifest} from a
+ * declarative {@link ExtensionBlueprint} and the author's identity fields.
+ *
+ * This is the *generate* verb that completes the declarative authoring loop
+ * (`compose → derive → describe/lint → synthesize`). Where
+ * {@link defineExtensionManifest} only *types* a hand-written manifest and
+ * {@link deriveExtensionCapabilities} computes only the capability set, this
+ * function assembles the whole manifest: it copies every author-supplied identity
+ * field verbatim and fills `capabilities` with `deriveExtensionCapabilities`
+ * unioned with any {@link SynthesizeExtensionManifestIdentity.additionalCapabilities | additionalCapabilities},
+ * sorted and de-duplicated. The author writes the blueprint once and never
+ * hand-syncs `manifest.capabilities` — declaring nothing the extension does not
+ * use and nothing it does.
+ *
+ * It is a pure assembler: it neither validates the blueprint definitions (that
+ * stays in `api.register*` at activation) nor the identity fields (the loader
+ * validates the on-disk manifest). Pair it with
+ * {@link ../sdk/testing.js#assertExtensionManifestMatchesBlueprint} to guard a
+ * hand-maintained `manifest.json` against drift in CI.
+ */
+export function synthesizeExtensionManifest(blueprint, identity) {
+    const { additionalCapabilities, ...manifestIdentity } = identity;
+    // `Array.isArray` keeps a non-array value (or an omitted field) crossing an
+    // untyped boundary from crashing the spread, mirroring the rest of the SDK.
+    const extra = Array.isArray(additionalCapabilities) ? normalizeDeclaredCapabilities(additionalCapabilities) : [];
+    const capabilities = [...new Set([...deriveExtensionCapabilities(blueprint), ...extra])].sort((left, right) => left.localeCompare(right));
+    return { ...manifestIdentity, capabilities };
+}
+/**
+ * Assemble both halves of a shippable extension package from one declarative
+ * {@link ExtensionBlueprint} and the author's identity fields — the author-once
+ * capstone of the declarative loop.
+ *
+ * Where {@link composeExtension} produces only the runtime module and
+ * {@link synthesizeExtensionManifest} produces only the manifest, this unifies
+ * them: it synthesizes the complete least-privilege manifest from the blueprint
+ * and identity, then composes the module with that synthesized manifest set as its
+ * authoritative in-module `manifest` mirror. Both halves are therefore generated
+ * from a single source and cannot drift — the module's `manifest` is the very
+ * object returned as `manifest`. Export `module` as the package entry's default
+ * export and write `manifest` as `manifest.json`.
+ *
+ * It is a pure assembler with no validation, loading, or filesystem access,
+ * exactly like the two functions it composes; pair it with
+ * {@link preflightExtension} (or {@link ../sdk/testing.js#assertExtensionPreflight})
+ * for the author-time verify step. Use {@link mergeExtensionBlueprints} first to
+ * assemble the blueprint modularly, then this to ship it.
+ */
+export function composeExtensionPackage(blueprint, identity) {
+    const manifest = synthesizeExtensionManifest(blueprint, identity);
+    const module = composeExtension({ ...blueprint, manifest });
+    return { module, manifest };
+}
+/** Map a non-trivial bound evaluation to a compatibility finding, or `null` when the bound is absent or satisfied. */
+function toCompatibilityFinding(evaluation, pmVersion) {
+    if (evaluation.status === "absent" || evaluation.status === "ok") {
+        return null;
+    }
+    const code = `${evaluation.kind}_${evaluation.status}`;
+    let message;
+    switch (code) {
+        case "pm_min_version_invalid":
+            message = `pm_min_version "${evaluation.required}" is not a valid version; the extension is treated as incompatible and the loader skips it.`;
+            break;
+        case "pm_min_version_unchecked":
+            message = `pm_min_version "${evaluation.required}" could not be compared against pm ${pmVersion}; compatibility is unverified.`;
+            break;
+        case "pm_min_version_unmet":
+            message = `Requires pm >= ${evaluation.required} but the target is pm ${pmVersion}; the loader skips the extension.`;
+            break;
+        case "pm_max_version_invalid":
+            message = `pm_max_version "${evaluation.required}" is not a valid inclusive upper bound (version ranges are not allowed); the extension is treated as incompatible and the loader skips it.`;
+            break;
+        case "pm_max_version_unchecked":
+            message = `pm_max_version "${evaluation.required}" could not be compared against pm ${pmVersion}; compatibility is unverified.`;
+            break;
+        case "pm_max_version_exceeded":
+            message = `Allows pm <= ${evaluation.required} but the target is pm ${pmVersion}; the loader skips the extension.`;
+            break;
+        case "pm_max_version_exceeded_warn":
+            message = `Target pm ${pmVersion} is newer than pm_max_version ${evaluation.required}, but the "warn" exceeded mode lets it load with a warning.`;
+            break;
+    }
+    return {
+        code,
+        severity: evaluation.allowed ? "warning" : "error",
+        constraint: evaluation.kind,
+        required: evaluation.required,
+        current: pmVersion,
+        message,
+    };
+}
+/**
+ * Check, without loading anything, whether an extension manifest's declared
+ * version bounds permit it to load on a given pm CLI version.
+ *
+ * This is the author-time inverse of the loader's runtime version gate: where the
+ * loader resolves the *installed* CLI version (asynchronously, from `package.json`)
+ * and emits `extension_pm_*_version_*` warnings, this pure synchronous function
+ * takes the {@link ExtensionManifestCompatibilityTarget.pmVersion | target version}
+ * the author supplies and returns structured findings. Both share the
+ * {@link ../core/extensions/version-compat.js | version-compat core}, so the
+ * author-time verdict and the runtime decision agree by construction — a package
+ * author can pin a CI test to the pm version they support and catch a too-tight
+ * `pm_min_version`, a malformed `pm_max_version`, or an upper bound a newer CLI
+ * would exceed, long before publishing.
+ *
+ * `compatible` is `true` only when no bound blocks the load (`*_invalid`,
+ * `*_unmet`, and a `block`-mode `*_exceeded`); `*_unchecked` (an uninterpretable
+ * bound or target) and a `warn`-mode `*_exceeded_warn` are advisory `warning`
+ * findings that still load. Pair it with
+ * {@link ../sdk/testing.js#assertExtensionManifestCompatible} to fail CI on a
+ * blocking incompatibility.
+ */
+export function checkExtensionManifestCompatibility(manifest, target) {
+    const minEvaluation = evaluatePmMinVersionBound(manifest.pm_min_version, target.pmVersion);
+    const maxEvaluation = evaluatePmMaxVersionBound(manifest.pm_max_version, target.pmVersion, target.pmMaxVersionExceededMode ?? "block");
+    const findings = [];
+    const minFinding = toCompatibilityFinding(minEvaluation, target.pmVersion);
+    if (minFinding !== null) {
+        findings.push(minFinding);
+    }
+    const maxFinding = toCompatibilityFinding(maxEvaluation, target.pmVersion);
+    if (maxFinding !== null) {
+        findings.push(maxFinding);
+    }
+    return {
+        compatible: minEvaluation.allowed && maxEvaluation.allowed,
+        findings,
+        pmVersion: target.pmVersion,
+    };
+}
+/**
+ * The lint codes whose verdict depends on the *declared* capability set rather
+ * than the blueprint's structure. {@link preflightExtension} drops these from its
+ * consolidated view when it synthesizes the manifest from an `identity` without an
+ * explicit declared set, because the synthesized manifest — not the blueprint's
+ * stale in-module `manifest` mirror — is what the package ships, so a drift against
+ * the mirror is a false positive. Structural codes (`duplicate_command`,
+ * `command_override_conflict`, `empty_surface`) are never suppressed.
+ */
+const CAPABILITY_DRIFT_LINT_CODES = new Set([
+    "capability_undeclared",
+    "capability_unused",
+    "manifest_capabilities_absent",
+]);
+/**
+ * Preflight a declarative {@link ExtensionBlueprint} through every author-time
+ * check in one call, returning a single consolidated {@link ExtensionPreflightReport}.
+ *
+ * This is the author-time capstone — the static analog of
+ * {@link ../sdk/testing.js#createExtensionTestHarness}, which unified the
+ * runtime-test helpers. Instead of chaining {@link lintExtensionBlueprint},
+ * {@link synthesizeExtensionManifest}, and {@link checkExtensionManifestCompatibility}
+ * (and reconciling their separate results) before publishing a package, an author
+ * runs `preflightExtension(blueprint, { identity, target })` and reads one report:
+ *
+ * - the blueprint is always linted (structural footguns + capability drift);
+ * - when `options.identity` is given, the complete least-privilege manifest is
+ *   synthesized and returned, so the author never hand-syncs `capabilities`;
+ * - when `options.target` is given, the synthesized manifest's version bounds
+ *   (or, absent an identity, the blueprint's in-module `manifest` mirror) are
+ *   checked against that pm version.
+ *
+ * It is pure and side-effect-free — no loading, activation, or filesystem access,
+ * exactly like the stages it composes — so it is safe in any author-time or CI
+ * context. The per-stage structured results are exposed unmodified
+ * (`report.blueprint`/`manifest`/`compatibility`) alongside the flattened,
+ * source-tagged `report.findings`; `report.ok` is `false` if any stage produced an
+ * `error`-severity finding. The flattened `findings` are curated for the author-once
+ * flow: once an `identity` synthesizes the manifest (and no explicit
+ * `declaredCapabilities` was pinned), the synthesized manifest — not the blueprint's
+ * in-module `manifest` mirror — is what ships, so capability-drift findings the lint
+ * raised against that mirror are false positives and are omitted from
+ * `report.findings` (the raw `report.blueprint` result still reports them). Pair it
+ * with {@link ../sdk/testing.js#assertExtensionPreflight} to fail CI in one line.
+ */
+export function preflightExtension(blueprint, options = {}) {
+    const blueprintResult = lintExtensionBlueprint(blueprint, { declaredCapabilities: options.declaredCapabilities });
+    const manifest = options.identity ? synthesizeExtensionManifest(blueprint, options.identity) : null;
+    // Compatibility evaluates the bounds the package will ship: the synthesized
+    // manifest when an identity drives generation, else the blueprint's in-module
+    // manifest mirror, else an empty manifest (no bounds → trivially compatible).
+    const compatibility = options.target
+        ? checkExtensionManifestCompatibility(manifest ?? blueprint.manifest ?? {}, options.target)
+        : null;
+    // When preflight synthesizes the manifest from an identity (and the caller did not
+    // pin an explicit declaredCapabilities set), the blueprint lint reconciled against
+    // the blueprint's in-module `manifest` mirror — which the synthesized manifest
+    // supersedes. Capability-drift findings against that stale mirror are false
+    // positives in the consolidated view (a missing capability would even flip `ok` to
+    // false though the synthesized manifest declares it), so drop them; structural
+    // findings are unaffected and the raw lint result on `report.blueprint` keeps all of
+    // them. An explicit declaredCapabilities set is a deliberate "check exactly this"
+    // request, so it is never suppressed.
+    const suppressCapabilityDrift = manifest !== null && options.declaredCapabilities === undefined;
+    const blueprintFindings = suppressCapabilityDrift
+        ? blueprintResult.findings.filter((finding) => !CAPABILITY_DRIFT_LINT_CODES.has(finding.code))
+        : blueprintResult.findings;
+    const findings = [
+        ...blueprintFindings.map((finding) => ({
+            source: "blueprint",
+            severity: finding.severity,
+            code: finding.code,
+            message: finding.message,
+        })),
+        ...(compatibility?.findings ?? []).map((finding) => ({
+            source: "compatibility",
+            severity: finding.severity,
+            code: finding.code,
+            message: finding.message,
+        })),
+    ];
+    return {
+        ok: findings.every((finding) => finding.severity !== "error"),
+        capabilities: blueprintResult.used,
+        blueprint: blueprintResult,
+        manifest,
+        compatibility,
+        findings,
+    };
+}
+//# sourceMappingURL=compose.js.map
+//# debugId=376f0804-a437-515f-a653-485531d98f13