@unbrained/pm-cli 2026.6.23 → 2026.6.24

package/dist/core/extensions/version-compat.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @module core/extensions/version-compat
+ *
+ * Single source of truth for extension-manifest version-bound compatibility.
+ *
+ * An extension manifest may declare an inclusive `pm_min_version` lower bound and
+ * an inclusive `pm_max_version` upper bound. At load time the
+ * {@link ../extensions/loader.js | loader} compares them against the running pm
+ * CLI version and skips (or warns about) an extension that falls outside the
+ * supported window. The comparison and the per-bound status semantics live here
+ * so the runtime loader and the author-time SDK helper
+ * (`checkExtensionManifestCompatibility`) share one implementation and can never
+ * drift — the same "agrees with the loader by construction" guarantee the
+ * declarative authoring helpers (`describeExtensionBlueprint`,
+ * `deriveExtensionCapabilities`) already provide.
+ *
+ * The functions here are pure: they take an already-resolved current version
+ * (the loader resolves it from `package.json`; the SDK caller supplies a target
+ * version) and return structured outcomes. Warning-string formatting and
+ * version resolution stay with the loader; finding/message presentation stays
+ * with the SDK.
+ */
+import type { PmMaxVersionExceededMode } from "./extension-types.js";
+/** The two inclusive manifest version bounds pm evaluates at load time. */
+export type PmVersionBoundKind = "pm_min_version" | "pm_max_version";
+/**
+ * The outcome of evaluating a single manifest version bound against a pm version.
+ *
+ * - `absent`: the bound is not declared — nothing to enforce.
+ * - `ok`: the bound is declared and satisfied by the current version.
+ * - `invalid`: the declared bound is malformed (unparseable, or a range prefix on
+ *   `pm_max_version`); the loader treats the extension as incompatible and skips it.
+ * - `unchecked`: the bound is well-formed but cannot be compared against the
+ *   current version (the current version is unknown or not comparable); the
+ *   extension still loads, with an advisory warning.
+ * - `unmet`: the current version is older than the inclusive `pm_min_version`
+ *   lower bound; the loader skips the extension (only emitted for `pm_min_version`).
+ * - `exceeded`: the current version is newer than the inclusive `pm_max_version`
+ *   upper bound and the exceeded mode is `block`; the loader skips the extension
+ *   (only emitted for `pm_max_version`).
+ * - `exceeded_warn`: the current version is newer than `pm_max_version` but the
+ *   exceeded mode is `warn`, so the extension loads with an advisory warning
+ *   (only emitted for `pm_max_version`).
+ */
+export type PmVersionBoundStatus = "absent" | "ok" | "invalid" | "unchecked" | "unmet" | "exceeded" | "exceeded_warn";
+/**
+ * The structured result of evaluating one manifest version bound, consumed by the
+ * loader (to format its `extension_pm_*_version_*` warning strings) and the SDK
+ * (to build author-time compatibility findings).
+ */
+export interface PmVersionBoundEvaluation {
+    /** Which bound this evaluation describes. */
+    kind: PmVersionBoundKind;
+    /** The classified outcome of comparing the bound against the current version. */
+    status: PmVersionBoundStatus;
+    /** Whether the bound permits the extension to load (`false` only for `invalid`/`unmet`/`exceeded`). */
+    allowed: boolean;
+    /** The declared bound value, verbatim; the empty string when the bound is absent. */
+    required: string;
+    /** The current version compared against, or `null` when it could not be resolved. */
+    current: string | null;
+}
+/**
+ * Parse a comparable release string into numeric segments, or `null` when it is
+ * not an interpretable dotted-numeric version.
+ *
+ * Leniently strips a leading inclusive-minimum `>=` and an optional `v` prefix
+ * (so `engines.pm`-style `">=2026.5.31"` and `"v1.2.3"` both parse), then drops
+ * any build/pre-release suffix and keeps the leading dotted-numeric release.
+ */
+export declare function parseComparableVersion(value: string): number[] | null;
+/**
+ * Compare two comparable version strings segment by segment.
+ *
+ * Returns `1` when `currentVersion` is greater, `-1` when it is smaller, `0` when
+ * equal, and `null` when either side is not an interpretable version (so callers
+ * can classify the comparison as `unchecked`). Missing trailing segments are
+ * treated as `0`, so `1.2` and `1.2.0` compare equal.
+ */
+export declare function compareComparableVersions(currentVersion: string, otherVersion: string): number | null;
+/**
+ * Evaluate a manifest `pm_min_version` inclusive lower bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`; a blank, non-string, or unparseable bound is
+ * `invalid`; an unknown or incomparable current version is `unchecked`; a current
+ * version below the bound is `unmet`; otherwise the bound is satisfied (`ok`).
+ * `currentVersion` is `null` when the loader could not resolve the running CLI
+ * version.
+ */
+export declare function evaluatePmMinVersionBound(required: unknown, currentVersion: string | null): PmVersionBoundEvaluation;
+/**
+ * Evaluate a manifest `pm_max_version` inclusive upper bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`. A blank or non-string bound is `invalid`. The
+ * upper bound must be an exact version: a range prefix (`<`/`>`/`=`/`~`/`^`) is
+ * rejected as `invalid`, because
+ * {@link parseComparableVersion} leniently strips a leading `>=` for
+ * `engines.pm` min-version compatibility and would otherwise turn a range-like
+ * `">=2026.6.1"` into an inclusive max and wrongly block newer CLIs. An
+ * unparseable bound is `invalid`; an unknown or incomparable current version is
+ * `unchecked`; a current version above the bound is `exceeded` (or
+ * `exceeded_warn` when `exceededMode` is `warn`, so the extension still loads
+ * during a controlled upgrade window); otherwise the bound is satisfied (`ok`).
+ */
+export declare function evaluatePmMaxVersionBound(required: unknown, currentVersion: string | null, exceededMode: PmMaxVersionExceededMode): PmVersionBoundEvaluation;

package/dist/core/extensions/version-compat.js

@@ -0,0 +1,130 @@
+
+!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]="9675b93b-da90-574d-a6cf-ea7448b40600")}catch(e){}}();
+function formatVersionBoundValue(value) {
+    return typeof value === "string" ? value : String(value);
+}
+/**
+ * Parse a comparable release string into numeric segments, or `null` when it is
+ * not an interpretable dotted-numeric version.
+ *
+ * Leniently strips a leading inclusive-minimum `>=` and an optional `v` prefix
+ * (so `engines.pm`-style `">=2026.5.31"` and `"v1.2.3"` both parse), then drops
+ * any build/pre-release suffix and keeps the leading dotted-numeric release.
+ */
+export function parseComparableVersion(value) {
+    const normalized = value.trim().replace(/^>=\s*/, "").replace(/^v/i, "");
+    const release = normalized.split(/[+-]/, 1)[0];
+    if (!/^\d+(?:[.-]\d+)*$/.test(release)) {
+        return null;
+    }
+    return release.split(/[.-]/).map((part) => Number(part));
+}
+/**
+ * Compare two comparable version strings segment by segment.
+ *
+ * Returns `1` when `currentVersion` is greater, `-1` when it is smaller, `0` when
+ * equal, and `null` when either side is not an interpretable version (so callers
+ * can classify the comparison as `unchecked`). Missing trailing segments are
+ * treated as `0`, so `1.2` and `1.2.0` compare equal.
+ */
+export function compareComparableVersions(currentVersion, otherVersion) {
+    const currentParts = parseComparableVersion(currentVersion);
+    const otherParts = parseComparableVersion(otherVersion);
+    if (!currentParts || !otherParts) {
+        return null;
+    }
+    const width = Math.max(currentParts.length, otherParts.length);
+    for (let index = 0; index < width; index += 1) {
+        const current = currentParts[index] ?? 0;
+        const other = otherParts[index] ?? 0;
+        if (current > other) {
+            return 1;
+        }
+        if (current < other) {
+            return -1;
+        }
+    }
+    return 0;
+}
+/**
+ * Evaluate a manifest `pm_min_version` inclusive lower bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`; a blank, non-string, or unparseable bound is
+ * `invalid`; an unknown or incomparable current version is `unchecked`; a current
+ * version below the bound is `unmet`; otherwise the bound is satisfied (`ok`).
+ * `currentVersion` is `null` when the loader could not resolve the running CLI
+ * version.
+ */
+export function evaluatePmMinVersionBound(required, currentVersion) {
+    if (required === undefined || required === null) {
+        return { kind: "pm_min_version", status: "absent", allowed: true, required: "", current: currentVersion };
+    }
+    const declared = formatVersionBoundValue(required);
+    if (typeof required !== "string" || declared.trim().length === 0) {
+        return { kind: "pm_min_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (!parseComparableVersion(declared)) {
+        return { kind: "pm_min_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (currentVersion === null) {
+        return { kind: "pm_min_version", status: "unchecked", allowed: true, required: declared, current: null };
+    }
+    const comparison = compareComparableVersions(currentVersion, declared);
+    if (comparison === null) {
+        return { kind: "pm_min_version", status: "unchecked", allowed: true, required: declared, current: currentVersion };
+    }
+    if (comparison < 0) {
+        return { kind: "pm_min_version", status: "unmet", allowed: false, required: declared, current: currentVersion };
+    }
+    return { kind: "pm_min_version", status: "ok", allowed: true, required: declared, current: currentVersion };
+}
+/**
+ * Evaluate a manifest `pm_max_version` inclusive upper bound against the current
+ * pm version.
+ *
+ * An omitted bound is `absent`. A blank or non-string bound is `invalid`. The
+ * upper bound must be an exact version: a range prefix (`<`/`>`/`=`/`~`/`^`) is
+ * rejected as `invalid`, because
+ * {@link parseComparableVersion} leniently strips a leading `>=` for
+ * `engines.pm` min-version compatibility and would otherwise turn a range-like
+ * `">=2026.6.1"` into an inclusive max and wrongly block newer CLIs. An
+ * unparseable bound is `invalid`; an unknown or incomparable current version is
+ * `unchecked`; a current version above the bound is `exceeded` (or
+ * `exceeded_warn` when `exceededMode` is `warn`, so the extension still loads
+ * during a controlled upgrade window); otherwise the bound is satisfied (`ok`).
+ */
+export function evaluatePmMaxVersionBound(required, currentVersion, exceededMode) {
+    if (required === undefined || required === null) {
+        return { kind: "pm_max_version", status: "absent", allowed: true, required: "", current: currentVersion };
+    }
+    const declared = formatVersionBoundValue(required);
+    if (typeof required !== "string" || declared.trim().length === 0) {
+        return { kind: "pm_max_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (/^[<>=~^]/.test(declared.trim()) || !parseComparableVersion(declared)) {
+        return { kind: "pm_max_version", status: "invalid", allowed: false, required: declared, current: currentVersion };
+    }
+    if (currentVersion === null) {
+        return { kind: "pm_max_version", status: "unchecked", allowed: true, required: declared, current: null };
+    }
+    const comparison = compareComparableVersions(currentVersion, declared);
+    if (comparison === null) {
+        return { kind: "pm_max_version", status: "unchecked", allowed: true, required: declared, current: currentVersion };
+    }
+    if (comparison > 0) {
+        if (exceededMode === "warn") {
+            return {
+                kind: "pm_max_version",
+                status: "exceeded_warn",
+                allowed: true,
+                required: declared,
+                current: currentVersion,
+            };
+        }
+        return { kind: "pm_max_version", status: "exceeded", allowed: false, required: declared, current: currentVersion };
+    }
+    return { kind: "pm_max_version", status: "ok", allowed: true, required: declared, current: currentVersion };
+}
+//# sourceMappingURL=version-compat.js.map
+//# debugId=9675b93b-da90-574d-a6cf-ea7448b40600

package/dist/core/extensions/version-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compat.js","sources":["core/extensions/version-compat.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/version-compat\n *\n * Single source of truth for extension-manifest version-bound compatibility.\n *\n * An extension manifest may declare an inclusive `pm_min_version` lower bound and\n * an inclusive `pm_max_version` upper bound. At load time the\n * {@link ../extensions/loader.js | loader} compares them against the running pm\n * CLI version and skips (or warns about) an extension that falls outside the\n * supported window. The comparison and the per-bound status semantics live here\n * so the runtime loader and the author-time SDK helper\n * (`checkExtensionManifestCompatibility`) share one implementation and can never\n * drift — the same \"agrees with the loader by construction\" guarantee the\n * declarative authoring helpers (`describeExtensionBlueprint`,\n * `deriveExtensionCapabilities`) already provide.\n *\n * The functions here are pure: they take an already-resolved current version\n * (the loader resolves it from `package.json`; the SDK caller supplies a target\n * version) and return structured outcomes. Warning-string formatting and\n * version resolution stay with the loader; finding/message presentation stays\n * with the SDK.\n */\nimport type { PmMaxVersionExceededMode } from \"./extension-types.js\";\n\n/** The two inclusive manifest version bounds pm evaluates at load time. */\nexport type PmVersionBoundKind = \"pm_min_version\" | \"pm_max_version\";\n\n/**\n * The outcome of evaluating a single manifest version bound against a pm version.\n *\n * - `absent`: the bound is not declared — nothing to enforce.\n * - `ok`: the bound is declared and satisfied by the current version.\n * - `invalid`: the declared bound is malformed (unparseable, or a range prefix on\n *   `pm_max_version`); the loader treats the extension as incompatible and skips it.\n * - `unchecked`: the bound is well-formed but cannot be compared against the\n *   current version (the current version is unknown or not comparable); the\n *   extension still loads, with an advisory warning.\n * - `unmet`: the current version is older than the inclusive `pm_min_version`\n *   lower bound; the loader skips the extension (only emitted for `pm_min_version`).\n * - `exceeded`: the current version is newer than the inclusive `pm_max_version`\n *   upper bound and the exceeded mode is `block`; the loader skips the extension\n *   (only emitted for `pm_max_version`).\n * - `exceeded_warn`: the current version is newer than `pm_max_version` but the\n *   exceeded mode is `warn`, so the extension loads with an advisory warning\n *   (only emitted for `pm_max_version`).\n */\nexport type PmVersionBoundStatus =\n  | \"absent\"\n  | \"ok\"\n  | \"invalid\"\n  | \"unchecked\"\n  | \"unmet\"\n  | \"exceeded\"\n  | \"exceeded_warn\";\n\n/**\n * The structured result of evaluating one manifest version bound, consumed by the\n * loader (to format its `extension_pm_*_version_*` warning strings) and the SDK\n * (to build author-time compatibility findings).\n */\nexport interface PmVersionBoundEvaluation {\n  /** Which bound this evaluation describes. */\n  kind: PmVersionBoundKind;\n  /** The classified outcome of comparing the bound against the current version. */\n  status: PmVersionBoundStatus;\n  /** Whether the bound permits the extension to load (`false` only for `invalid`/`unmet`/`exceeded`). */\n  allowed: boolean;\n  /** The declared bound value, verbatim; the empty string when the bound is absent. */\n  required: string;\n  /** The current version compared against, or `null` when it could not be resolved. */\n  current: string | null;\n}\n\nfunction formatVersionBoundValue(value: unknown): string {\n  return typeof value === \"string\" ? value : String(value);\n}\n\n/**\n * Parse a comparable release string into numeric segments, or `null` when it is\n * not an interpretable dotted-numeric version.\n *\n * Leniently strips a leading inclusive-minimum `>=` and an optional `v` prefix\n * (so `engines.pm`-style `\">=2026.5.31\"` and `\"v1.2.3\"` both parse), then drops\n * any build/pre-release suffix and keeps the leading dotted-numeric release.\n */\nexport function parseComparableVersion(value: string): number[] | null {\n  const normalized = value.trim().replace(/^>=\\s*/, \"\").replace(/^v/i, \"\");\n  const release = normalized.split(/[+-]/, 1)[0];\n  if (!/^\\d+(?:[.-]\\d+)*$/.test(release)) {\n    return null;\n  }\n  return release.split(/[.-]/).map((part) => Number(part));\n}\n\n/**\n * Compare two comparable version strings segment by segment.\n *\n * Returns `1` when `currentVersion` is greater, `-1` when it is smaller, `0` when\n * equal, and `null` when either side is not an interpretable version (so callers\n * can classify the comparison as `unchecked`). Missing trailing segments are\n * treated as `0`, so `1.2` and `1.2.0` compare equal.\n */\nexport function compareComparableVersions(currentVersion: string, otherVersion: string): number | null {\n  const currentParts = parseComparableVersion(currentVersion);\n  const otherParts = parseComparableVersion(otherVersion);\n  if (!currentParts || !otherParts) {\n    return null;\n  }\n  const width = Math.max(currentParts.length, otherParts.length);\n  for (let index = 0; index < width; index += 1) {\n    const current = currentParts[index] ?? 0;\n    const other = otherParts[index] ?? 0;\n    if (current > other) {\n      return 1;\n    }\n    if (current < other) {\n      return -1;\n    }\n  }\n  return 0;\n}\n\n/**\n * Evaluate a manifest `pm_min_version` inclusive lower bound against the current\n * pm version.\n *\n * An omitted bound is `absent`; a blank, non-string, or unparseable bound is\n * `invalid`; an unknown or incomparable current version is `unchecked`; a current\n * version below the bound is `unmet`; otherwise the bound is satisfied (`ok`).\n * `currentVersion` is `null` when the loader could not resolve the running CLI\n * version.\n */\nexport function evaluatePmMinVersionBound(\n  required: unknown,\n  currentVersion: string | null,\n): PmVersionBoundEvaluation {\n  if (required === undefined || required === null) {\n    return { kind: \"pm_min_version\", status: \"absent\", allowed: true, required: \"\", current: currentVersion };\n  }\n  const declared = formatVersionBoundValue(required);\n  if (typeof required !== \"string\" || declared.trim().length === 0) {\n    return { kind: \"pm_min_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (!parseComparableVersion(declared)) {\n    return { kind: \"pm_min_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (currentVersion === null) {\n    return { kind: \"pm_min_version\", status: \"unchecked\", allowed: true, required: declared, current: null };\n  }\n  const comparison = compareComparableVersions(currentVersion, declared);\n  if (comparison === null) {\n    return { kind: \"pm_min_version\", status: \"unchecked\", allowed: true, required: declared, current: currentVersion };\n  }\n  if (comparison < 0) {\n    return { kind: \"pm_min_version\", status: \"unmet\", allowed: false, required: declared, current: currentVersion };\n  }\n  return { kind: \"pm_min_version\", status: \"ok\", allowed: true, required: declared, current: currentVersion };\n}\n\n/**\n * Evaluate a manifest `pm_max_version` inclusive upper bound against the current\n * pm version.\n *\n * An omitted bound is `absent`. A blank or non-string bound is `invalid`. The\n * upper bound must be an exact version: a range prefix (`<`/`>`/`=`/`~`/`^`) is\n * rejected as `invalid`, because\n * {@link parseComparableVersion} leniently strips a leading `>=` for\n * `engines.pm` min-version compatibility and would otherwise turn a range-like\n * `\">=2026.6.1\"` into an inclusive max and wrongly block newer CLIs. An\n * unparseable bound is `invalid`; an unknown or incomparable current version is\n * `unchecked`; a current version above the bound is `exceeded` (or\n * `exceeded_warn` when `exceededMode` is `warn`, so the extension still loads\n * during a controlled upgrade window); otherwise the bound is satisfied (`ok`).\n */\nexport function evaluatePmMaxVersionBound(\n  required: unknown,\n  currentVersion: string | null,\n  exceededMode: PmMaxVersionExceededMode,\n): PmVersionBoundEvaluation {\n  if (required === undefined || required === null) {\n    return { kind: \"pm_max_version\", status: \"absent\", allowed: true, required: \"\", current: currentVersion };\n  }\n  const declared = formatVersionBoundValue(required);\n  if (typeof required !== \"string\" || declared.trim().length === 0) {\n    return { kind: \"pm_max_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (/^[<>=~^]/.test(declared.trim()) || !parseComparableVersion(declared)) {\n    return { kind: \"pm_max_version\", status: \"invalid\", allowed: false, required: declared, current: currentVersion };\n  }\n  if (currentVersion === null) {\n    return { kind: \"pm_max_version\", status: \"unchecked\", allowed: true, required: declared, current: null };\n  }\n  const comparison = compareComparableVersions(currentVersion, declared);\n  if (comparison === null) {\n    return { kind: \"pm_max_version\", status: \"unchecked\", allowed: true, required: declared, current: currentVersion };\n  }\n  if (comparison > 0) {\n    if (exceededMode === \"warn\") {\n      return {\n        kind: \"pm_max_version\",\n        status: \"exceeded_warn\",\n        allowed: true,\n        required: declared,\n        current: currentVersion,\n      };\n    }\n    return { kind: \"pm_max_version\", status: \"exceeded\", allowed: false, required: declared, current: currentVersion };\n  }\n  return { kind: \"pm_max_version\", status: \"ok\", allowed: true, required: declared, current: currentVersion };\n}\n"],"names":[],"mappings":";;AAyEA,SAAS,uBAAuB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,cAAsB,EAAE,YAAoB;IACpF,MAAM,YAAY,GAAG,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,sBAAsB,CAAC,YAAY,CAAC,CAAC;IACxD,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC/D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,OAAO,GAAG,KAAK,EAAE,CAAC;YACpB,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,EAAE,CAAC;YACpB,OAAO,CAAC,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAiB,EACjB,cAA6B;IAE7B,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC5G,CAAC;IACD,MAAM,QAAQ,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACpH,CAAC;IACD,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACpH,CAAC;IACD,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3G,CAAC;IACD,MAAM,UAAU,GAAG,yBAAyB,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACvE,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrH,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IAClH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC9G,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAiB,EACjB,cAA6B,EAC7B,YAAsC;IAEtC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC5G,CAAC;IACD,MAAM,QAAQ,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACpH,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACpH,CAAC;IACD,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3G,CAAC;IACD,MAAM,UAAU,GAAG,yBAAyB,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACvE,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrH,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,IAAI,YAAY,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO;gBACL,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,eAAe;gBACvB,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,QAAQ;gBAClB,OAAO,EAAE,cAAc;aACxB,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC9G,CAAC","debugId":"9675b93b-da90-574d-a6cf-ea7448b40600"}

package/dist/sdk/compose.d.ts

@@ -27,6 +27,8 @@
  */
 import type { AfterCommandHook, BeforeCommandHook, CommandDefinition, CommandOverride, ExtensionApi, ExtensionCapability, ExtensionManifest, ExtensionServiceName, Exporter, FlagDefinition, ImportExportRegistrationOptions, Importer, OnIndexHook, OnReadHook, OnWriteHook, OutputRendererFormat, ParserOverride, PreflightOverride, RendererOverride, SchemaFieldDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SearchProviderDefinition, ServiceOverride, VectorStoreAdapterDefinition } from "../core/extensions/loader.js";
 import type { ExtensionActivationSummary } from "../core/extensions/activation-summary.js";
+import type { PmMaxVersionExceededMode } from "../core/extensions/extension-types.js";
+import { type PmVersionBoundKind } from "../core/extensions/version-compat.js";
 /**
  * Documents the extension module payload exchanged by command, SDK, and package integrations.
  *
@@ -41,8 +43,8 @@ export interface ExtensionModule {
      *
      * The authoritative manifest remains on-disk `manifest.json`; this field is
      * useful when authors want colocated metadata for tooling/tests. Type it with
-     * {@link defineExtensionManifest} for full contract checking in plain
-     * JavaScript packages.
+     * {@link defineExtensionManifest} for full contract checking at the definition
+     * site.
      */
     manifest?: ExtensionManifest;
     activate(api: ExtensionApi): void | Promise<void>;
@@ -158,6 +160,24 @@ export interface ExtensionBlueprint {
     /** Optional teardown hook copied onto the produced module verbatim. */
     deactivate?: () => void | Promise<void>;
 }
+/**
+ * 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 declare function defineExtensionBlueprint<TBlueprint extends ExtensionBlueprint>(blueprint: TBlueprint): TBlueprint;
 /**
  * Assemble an {@link ExtensionModule} from a declarative {@link ExtensionBlueprint}.
  *
@@ -175,6 +195,44 @@ export interface ExtensionBlueprint {
  * the same activation diagnostic either way.
  */
 export declare function composeExtension(blueprint: ExtensionBlueprint): ExtensionModule;
+/**
+ * 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 declare function mergeExtensionBlueprints(...blueprints: ExtensionBlueprint[]): ExtensionBlueprint;
 /**
  * Compute the minimal least-privilege capability set a {@link ExtensionBlueprint}
  * exercises, sorted and de-duplicated.
@@ -295,3 +353,284 @@ export interface ExtensionBlueprintLintResult {
  * the imperative `activate` escape hatch is invisible to this static check.
  */
 export declare function lintExtensionBlueprint(blueprint: ExtensionBlueprint, options?: LintExtensionBlueprintOptions): ExtensionBlueprintLintResult;
+/**
+ * The author-supplied identity fields {@link synthesizeExtensionManifest} cannot
+ * derive from a blueprint: every {@link ExtensionManifest} field except the
+ * generated `capabilities`.
+ *
+ * The blueprint determines `capabilities` (the surfaces it registers) and nothing
+ * else, so `name`/`version`/`entry`/`priority` and any optional metadata
+ * (engines, permissions, provenance, version floors/ceilings, sandbox profile,
+ * manifest version, activation, legacy aliases) are the author's to supply here.
+ */
+export interface SynthesizeExtensionManifestIdentity extends Omit<ExtensionManifest, "capabilities"> {
+    /**
+     * Extra capabilities to grant beyond the blueprint's derived set, for surfaces
+     * registered through the blueprint's imperative `activate` escape hatch that
+     * static derivation cannot see (e.g. a renderer wired in `activate`). Each is
+     * legacy-alias resolved and normalized like a declared manifest capability;
+     * unknown names are dropped (the synthesized manifest is validated at load).
+     */
+    additionalCapabilities?: readonly string[];
+}
+/**
+ * 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 declare function synthesizeExtensionManifest(blueprint: ExtensionBlueprint, identity: SynthesizeExtensionManifestIdentity): ExtensionManifest;
+/**
+ * The two generated halves of a shippable extension package, returned by
+ * {@link composeExtensionPackage}.
+ */
+export interface ExtensionPackage {
+    /**
+     * The runtime {@link ExtensionModule} to export as the package entry's default
+     * export. Its `manifest` mirror is set to the same {@link ExtensionPackage.manifest}
+     * object, so the in-module metadata and the on-disk manifest never diverge.
+     */
+    module: ExtensionModule;
+    /**
+     * The complete least-privilege {@link ExtensionManifest} to write as the
+     * package's `manifest.json`, with `capabilities` derived from the blueprint.
+     */
+    manifest: ExtensionManifest;
+}
+/**
+ * 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 declare function composeExtensionPackage(blueprint: ExtensionBlueprint, identity: SynthesizeExtensionManifestIdentity): ExtensionPackage;
+/**
+ * The target a {@link checkExtensionManifestCompatibility} call evaluates a
+ * manifest's version bounds against.
+ */
+export interface ExtensionManifestCompatibilityTarget {
+    /**
+     * The pm CLI version to check the manifest against, e.g. the running CLI's
+     * `version` or a version floor a package commits to supporting. Plain
+     * dotted-numeric (`2026.6.23`) or `v`-prefixed values are compared; anything
+     * uninterpretable yields an `unchecked` finding rather than a false verdict.
+     */
+    pmVersion: string;
+    /**
+     * How a `pm_max_version` overrun is treated, mirroring the runtime
+     * `extensions.policy.pm_max_version_exceeded_mode`. `"block"` (the default)
+     * reports an exceeded upper bound as a blocking incompatibility; `"warn"`
+     * reports it as a non-blocking advisory, matching an operator who relaxed the
+     * gate during a CLI upgrade window.
+     */
+    pmMaxVersionExceededMode?: PmMaxVersionExceededMode;
+}
+/**
+ * The manifest fields {@link checkExtensionManifestCompatibility} evaluates.
+ *
+ * Values are intentionally `unknown` rather than `string` so an author can
+ * preflight the same malformed blank/non-string bounds (e.g. read from a JSON
+ * manifest) the loader's manifest parser rejects as `extension_manifest_invalid`.
+ */
+export interface ExtensionManifestCompatibilityManifest {
+    /** Inclusive lower pm CLI version bound from `manifest.json`. */
+    pm_min_version?: unknown;
+    /** Inclusive upper pm CLI version bound from `manifest.json`. */
+    pm_max_version?: unknown;
+}
+/**
+ * The machine-readable kind of an {@link ExtensionManifestCompatibilityFinding},
+ * one per `<bound>_<outcome>` the loader can reach. Each mirrors a loader
+ * `extension_pm_*_version_*` warning: `*_invalid`/`*_unmet`/`*_exceeded` block the
+ * load, while `*_unchecked`/`*_exceeded_warn` are advisory (the extension still
+ * loads).
+ */
+export type ExtensionManifestCompatibilityCode = "pm_min_version_invalid" | "pm_min_version_unchecked" | "pm_min_version_unmet" | "pm_max_version_invalid" | "pm_max_version_unchecked" | "pm_max_version_exceeded" | "pm_max_version_exceeded_warn";
+/**
+ * A single version-bound issue {@link checkExtensionManifestCompatibility} found
+ * when evaluating a manifest against a target pm version.
+ */
+export interface ExtensionManifestCompatibilityFinding {
+    /** The machine-readable {@link ExtensionManifestCompatibilityCode} for programmatic handling. */
+    code: ExtensionManifestCompatibilityCode;
+    /** `error` when the bound blocks the load against the target version, `warning` when it is advisory. */
+    severity: "error" | "warning";
+    /** Which manifest bound produced the finding. */
+    constraint: PmVersionBoundKind;
+    /** The declared bound value, verbatim. */
+    required: string;
+    /** The target pm version the bound was evaluated against. */
+    current: string;
+    /** Human-readable explanation of the outcome and its effect on loading. */
+    message: string;
+}
+/**
+ * The structured result of {@link checkExtensionManifestCompatibility}.
+ */
+export interface ExtensionManifestCompatibilityResult {
+    /** `true` when no `error`-severity finding blocks the load against the target version. */
+    compatible: boolean;
+    /** Every bound finding, lower bound before upper bound; empty when both bounds are absent or satisfied. */
+    findings: ExtensionManifestCompatibilityFinding[];
+    /** The target pm version the manifest was checked against, echoed back for messaging. */
+    pmVersion: string;
+}
+/**
+ * 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 declare function checkExtensionManifestCompatibility(manifest: ExtensionManifestCompatibilityManifest, target: ExtensionManifestCompatibilityTarget): ExtensionManifestCompatibilityResult;
+/**
+ * Options for {@link preflightExtension} and
+ * {@link ../sdk/testing.js#assertExtensionPreflight}. Every field is optional:
+ * each one a check enables, so an author opts into exactly the stages whose
+ * inputs they can supply.
+ */
+export interface PreflightExtensionOptions {
+    /**
+     * The author-supplied identity fields the blueprint cannot determine
+     * (`name`/`version`/`entry`/`priority`, version bounds, etc.). Provide them to
+     * have preflight {@link synthesizeExtensionManifest | synthesize} the complete
+     * least-privilege manifest and include it in the report; the synthesized
+     * version bounds then feed the {@link PreflightExtensionOptions.target | target}
+     * compatibility check. Omit to skip manifest synthesis.
+     */
+    identity?: SynthesizeExtensionManifestIdentity;
+    /**
+     * The pm CLI version (and optional max-version overrun mode) to evaluate the
+     * manifest's `pm_min_version`/`pm_max_version` bounds against. Provide it to run
+     * {@link checkExtensionManifestCompatibility} against the synthesized manifest
+     * (or, absent an `identity`, the blueprint's in-module `manifest` mirror). Omit
+     * to skip the version-compatibility check.
+     */
+    target?: ExtensionManifestCompatibilityTarget;
+    /**
+     * The capabilities the package's `manifest.json` declares, reconciled against
+     * the surfaces the blueprint exercises. Passed straight to
+     * {@link lintExtensionBlueprint}; when omitted it falls back to
+     * `blueprint.manifest.capabilities`, so the blueprint's in-module mirror is
+     * linted by default.
+     */
+    declaredCapabilities?: readonly string[];
+}
+/** Which preflight stage produced an {@link ExtensionPreflightFinding}. */
+export type ExtensionPreflightFindingSource = "blueprint" | "compatibility";
+/**
+ * A single finding in an {@link ExtensionPreflightReport}, flattened from one of
+ * the underlying stages and tagged with its {@link ExtensionPreflightFindingSource}
+ * so a consolidated report stays traceable to the check that raised it.
+ */
+export interface ExtensionPreflightFinding {
+    /** The stage that produced the finding: blueprint lint or version compatibility. */
+    source: ExtensionPreflightFindingSource;
+    /** Whether the finding blocks publish/activation (`error`) or is advisory (`warning`). */
+    severity: ExtensionBlueprintLintSeverity;
+    /** The underlying stage's machine-readable code, for programmatic handling. */
+    code: ExtensionBlueprintLintCode | ExtensionManifestCompatibilityCode;
+    /** The underlying stage's human-readable explanation, verbatim. */
+    message: string;
+}
+/**
+ * The consolidated result of {@link preflightExtension}: every author-time stage's
+ * structured output plus a flattened, source-tagged finding list.
+ */
+export interface ExtensionPreflightReport {
+    /** `true` when no `error`-severity finding appears across any stage (warnings still pass). */
+    ok: boolean;
+    /** The least-privilege capability set the blueprint exercises (from {@link deriveExtensionCapabilities}). */
+    capabilities: ExtensionCapability[];
+    /** The full {@link lintExtensionBlueprint} result (structural + capability-drift findings). */
+    blueprint: ExtensionBlueprintLintResult;
+    /** The manifest synthesized from `options.identity`, or `null` when no identity was supplied. */
+    manifest: ExtensionManifest | null;
+    /** The {@link checkExtensionManifestCompatibility} result, or `null` when no `options.target` was supplied. */
+    compatibility: ExtensionManifestCompatibilityResult | null;
+    /**
+     * Every finding from all stages, blueprint-lint findings before compatibility
+     * findings, each tagged by `source`. This is the consolidated, curated view: when
+     * `options.identity` synthesizes the manifest without an explicit
+     * `declaredCapabilities` set, capability-drift findings the lint raised against the
+     * blueprint's now-superseded in-module `manifest` mirror are omitted here (the raw
+     * `blueprint` result still carries them).
+     */
+    findings: ExtensionPreflightFinding[];
+}
+/**
+ * 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 declare function preflightExtension(blueprint: ExtensionBlueprint, options?: PreflightExtensionOptions): ExtensionPreflightReport;