@unbrained/pm-cli 2026.6.23 → 2026.6.30

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!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]="7c9e6f67-48e5-5952-a7a7-341aafa36244")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a323e13b-37e3-5ec6-bc21-1ab78e0b30b9")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -15,6 +15,7 @@ import { resolveGlobalPmRoot } from "../store/paths.js";
 import { asRecordLoose } from "../shared/primitives.js";
 import { flattenFlagListValue, isFlagDefaultValueCoercible, resolveFlagValueKind } from "./flag-value-types.js";
 import { KNOWN_ITEM_FIELD_TYPES, normalizeItemFieldType, suggestKnownItemFieldType } from "./item-field-types.js";
+import { compareComparableVersions, evaluatePmMaxVersionBound, evaluatePmMinVersionBound, parseComparableVersion, } from "./version-compat.js";
 // Cohesive helper groups now live in sibling modules. They are imported for the
 // discovery/activation code that stays here and re-exported below so existing
 // import sites (sdk/index.ts, commands/extension.ts, health.ts, tests, …) keep
@@ -563,33 +564,6 @@ function formatUnknownError(error) {
     }
     return String(error);
 }
-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));
-}
-function compareComparableVersions(currentVersion, minimumVersion) {
-    const currentParts = parseComparableVersion(currentVersion);
-    const minimumParts = parseComparableVersion(minimumVersion);
-    if (!currentParts || !minimumParts) {
-        return null;
-    }
-    const width = Math.max(currentParts.length, minimumParts.length);
-    for (let index = 0; index < width; index += 1) {
-        const current = currentParts[index] ?? 0;
-        const minimum = minimumParts[index] ?? 0;
-        if (current > minimum) {
-            return 1;
-        }
-        if (current < minimum) {
-            return -1;
-        }
-    }
-    return 0;
-}
 async function readCurrentPmCliVersion() {
     try {
         const packageRoot = resolvePmPackageRootFromModule(import.meta.url, ["../../.."]);
@@ -605,87 +579,50 @@ function resolveCurrentPmCliVersion() {
     currentPmCliVersionPromise ??= readCurrentPmCliVersion();
     return currentPmCliVersionPromise;
 }
-async function evaluatePmMinVersionCompatibility(layer, manifest) {
-    if (typeof manifest.pm_min_version !== "string" || manifest.pm_min_version.trim().length === 0) {
-        return { allowed: true };
-    }
-    if (!parseComparableVersion(manifest.pm_min_version)) {
-        return {
-            allowed: false,
-            warning: `extension_pm_min_version_invalid:${layer}:${manifest.name}:required=${manifest.pm_min_version}`,
-        };
-    }
-    const currentVersion = await resolveCurrentPmCliVersion();
-    if (!currentVersion) {
-        return {
-            allowed: true,
-            warning: `extension_pm_min_version_unchecked:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=unknown`,
-        };
+function formatPmVersionCompatibilityWarning(layer, manifest, evaluation) {
+    const current = evaluation.current ?? "unknown";
+    if (evaluation.kind === "pm_min_version") {
+        switch (evaluation.status) {
+            case "invalid":
+                return `extension_pm_min_version_invalid:${layer}:${manifest.name}:required=${evaluation.required}`;
+            case "unchecked":
+                return `extension_pm_min_version_unchecked:${layer}:${manifest.name}:required=${evaluation.required}:current=${current}`;
+            case "unmet":
+                return `extension_pm_min_version_unmet:${layer}:${manifest.name}:required=${evaluation.required}:current=${current}`;
+            default:
+                return undefined;
+        }
     }
-    const comparison = compareComparableVersions(currentVersion, manifest.pm_min_version);
-    if (comparison === null) {
-        return {
-            allowed: true,
-            warning: `extension_pm_min_version_unchecked:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=${currentVersion}`,
-        };
+    switch (evaluation.status) {
+        case "invalid":
+            return `extension_pm_max_version_invalid:${layer}:${manifest.name}:allowed=${evaluation.required}`;
+        case "unchecked":
+            return `extension_pm_max_version_unchecked:${layer}:${manifest.name}:allowed=${evaluation.required}:current=${current}`;
+        case "exceeded_warn":
+            return `extension_pm_max_version_exceeded_warn:${layer}:${manifest.name}:allowed=${evaluation.required}:current=${current}`;
+        case "exceeded":
+            return `extension_pm_max_version_exceeded:${layer}:${manifest.name}:allowed=${evaluation.required}:current=${current}`;
+        default:
+            return undefined;
     }
-    if (comparison < 0) {
-        return {
-            allowed: false,
-            warning: `extension_pm_min_version_unmet:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=${currentVersion}`,
-        };
+}
+async function evaluatePmMinVersionCompatibility(layer, manifest) {
+    // Resolve the current CLI version only when a bound is declared, so the common
+    // no-bound case never reads package.json.
+    if (manifest.pm_min_version === undefined) {
+        return { allowed: true };
     }
-    return { allowed: true };
+    const evaluation = evaluatePmMinVersionBound(manifest.pm_min_version, await resolveCurrentPmCliVersion());
+    const warning = formatPmVersionCompatibilityWarning(layer, manifest, evaluation);
+    return warning ? { allowed: evaluation.allowed, warning } : { allowed: evaluation.allowed };
 }
 async function evaluatePmMaxVersionCompatibility(layer, manifest, exceededMode) {
-    if (typeof manifest.pm_max_version !== "string" || manifest.pm_max_version.trim().length === 0) {
+    if (manifest.pm_max_version === undefined) {
         return { allowed: true };
     }
-    // An upper bound must be an exact version. parseComparableVersion leniently strips a
-    // leading ">=" (for engines.pm min-version compat), which would turn a range-like
-    // ">=2026.6.1" into an inclusive max and wrongly block newer CLIs — reject range prefixes.
-    if (/^[<>=~^]/.test(manifest.pm_max_version.trim())) {
-        return {
-            allowed: false,
-            warning: `extension_pm_max_version_invalid:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}`,
-        };
-    }
-    if (!parseComparableVersion(manifest.pm_max_version)) {
-        return {
-            allowed: false,
-            warning: `extension_pm_max_version_invalid:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}`,
-        };
-    }
-    const currentVersion = await resolveCurrentPmCliVersion();
-    if (!currentVersion) {
-        return {
-            allowed: true,
-            warning: `extension_pm_max_version_unchecked:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=unknown`,
-        };
-    }
-    const comparison = compareComparableVersions(currentVersion, manifest.pm_max_version);
-    if (comparison === null) {
-        return {
-            allowed: true,
-            warning: `extension_pm_max_version_unchecked:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
-        };
-    }
-    if (comparison > 0) {
-        // pm-k5e8: `extensions.policy.pm_max_version_exceeded_mode` (default "block",
-        // per-layer overridable) relaxes this to warn-only so operators can keep
-        // pinned extensions loading during a CLI upgrade window.
-        if (exceededMode === "warn") {
-            return {
-                allowed: true,
-                warning: `extension_pm_max_version_exceeded_warn:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
-            };
-        }
-        return {
-            allowed: false,
-            warning: `extension_pm_max_version_exceeded:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
-        };
-    }
-    return { allowed: true };
+    const evaluation = evaluatePmMaxVersionBound(manifest.pm_max_version, await resolveCurrentPmCliVersion(), exceededMode);
+    const warning = formatPmVersionCompatibilityWarning(layer, manifest, evaluation);
+    return warning ? { allowed: evaluation.allowed, warning } : { allowed: evaluation.allowed };
 }
 async function fingerprintPath(pathToInspect) {
     try {
@@ -1241,6 +1178,115 @@ function validateMigrationDefinition(definition) {
         throw new TypeError("registerMigration definition.run must be a function when provided");
     }
 }
+/**
+ * The seven array-valued dimensions a {@link ProjectProfileDefinition} stages.
+ * Each is "optional-by-emptiness": an omitted dimension normalizes to an empty
+ * array so the profile planner can iterate every dimension unconditionally.
+ */
+const PROJECT_PROFILE_DIMENSIONS = [
+    "types",
+    "statuses",
+    "fields",
+    "workflows",
+    "config",
+    "templates",
+    "packages",
+];
+/**
+ * Validates the field shapes the profile planner, `pm profile show/apply/lint`,
+ * and `describeProjectProfile` dereference without re-checking, so a structurally
+ * well-formed but type-violating extension entry (e.g. a workflow whose `type` is
+ * a number, or whose `allowed_transitions` is not an array) is rejected here
+ * rather than crashing a downstream consumer. Dimensions whose consumers already
+ * coerce or gracefully reject malformed values (statuses, fields, config) need no
+ * shape check. The `entry` is an already-confirmed non-null object.
+ */
+function validateProjectProfileEntryShape(dimension, index, entry) {
+    const at = `registerProfile profile.${dimension}[${index}]`;
+    if (dimension === "types") {
+        if (entry.name !== undefined && typeof entry.name !== "string") {
+            throw new TypeError(`${at}.name must be a string when provided`);
+        }
+        return;
+    }
+    if (dimension === "workflows") {
+        if (typeof entry.type !== "string") {
+            throw new TypeError(`${at}.type must be a string`);
+        }
+        if (!Array.isArray(entry.allowed_transitions)) {
+            throw new TypeError(`${at}.allowed_transitions must be an array`);
+        }
+        for (const [pairIndex, pair] of entry.allowed_transitions.entries()) {
+            if (!Array.isArray(pair)) {
+                throw new TypeError(`${at}.allowed_transitions[${pairIndex}] must be a [from, to] array`);
+            }
+        }
+        return;
+    }
+    if (dimension === "templates") {
+        if (typeof entry.name !== "string") {
+            throw new TypeError(`${at}.name must be a string`);
+        }
+        if (typeof entry.options !== "object" || entry.options === null || Array.isArray(entry.options)) {
+            throw new TypeError(`${at}.options must be an object`);
+        }
+        return;
+    }
+    if (dimension === "packages") {
+        if (typeof entry.spec !== "string") {
+            throw new TypeError(`${at}.spec must be a string`);
+        }
+    }
+}
+function validateProjectProfileDefinition(profile) {
+    const record = asRegistrationRecord("registerProfile profile", profile);
+    assertNonEmptyString("registerProfile profile.name", record.name);
+    assertNonEmptyString("registerProfile profile.title", record.title);
+    if (record.summary !== undefined && typeof record.summary !== "string") {
+        throw new TypeError("registerProfile profile.summary must be a string when provided");
+    }
+    for (const dimension of PROJECT_PROFILE_DIMENSIONS) {
+        const value = record[dimension];
+        if (value === undefined) {
+            continue;
+        }
+        if (!Array.isArray(value)) {
+            throw new TypeError(`registerProfile profile.${dimension} must be an array when provided`);
+        }
+        // Each dimension entry must be a non-null object: a primitive or null entry
+        // (e.g. `statuses: [null]`, `types: [42]`) survives an array-only check but
+        // crashes the profile planner and `pm profile show` when they read `entry.id`
+        // / `entry.key` / `entry.type` later. Reject it at the registration boundary.
+        for (const [index, entry] of value.entries()) {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                throw new TypeError(`registerProfile profile.${dimension}[${index}] must be an object`);
+            }
+            // Beyond "is an object", validate the specific field shapes consumers
+            // dereference so a type-violating entry can never crash the planner, the
+            // `pm profile` surfaces, or describeProjectProfile downstream.
+            validateProjectProfileEntryShape(dimension, index, entry);
+        }
+    }
+}
+/**
+ * Fills an already-validated profile snapshot's optional surfaces — an absent
+ * `summary` becomes an empty string and every omitted dimension an empty array —
+ * so the stored definition always has the full {@link ProjectProfileDefinition}
+ * shape the profile planner and `pm profile` resolution rely on. It runs after
+ * validation on the cloned snapshot, so it only ever supplies missing defaults
+ * and never has to coerce an invalid type (those are already rejected).
+ */
+function applyProjectProfileDefaults(profile) {
+    if (profile.summary === undefined) {
+        profile.summary = "";
+    }
+    for (const dimension of PROJECT_PROFILE_DIMENSIONS) {
+        if (profile[dimension] === undefined) {
+            profile[dimension] = [];
+        }
+    }
+    return profile;
+}
 function attachRuntimeDefinition(entry, runtimeDefinition) {
     Object.defineProperty(entry, "runtime_definition", {
         value: runtimeDefinition,
@@ -1548,6 +1594,24 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
             definition: normalizeRegistrationRecord("registerMigration definition", definition),
         }, runtimeDefinition));
     };
+    const registerProfile = (profile) => {
+        assertExtensionCapability(extension, "schema", "registerProfile");
+        if (!allowRegistration("schema.profiles", "registerProfile", "schema")) {
+            return;
+        }
+        // Snapshot first, then validate and default the snapshot: cloning resolves
+        // any getters once into plain data decoupled from the caller's object, so
+        // validation and storage operate on the same value — a getter cannot present
+        // one value to validation and another to the registry. Defaults are applied
+        // only after validation, so an invalid type is rejected, not silently coerced.
+        const snapshot = cloneRuntimeRegistrationValue(profile);
+        validateProjectProfileDefinition(snapshot);
+        registrations.profiles.push({
+            layer: extension.layer,
+            name: extension.name,
+            profile: applyProjectProfileDefaults(snapshot),
+        });
+    };
     const applyImportExportCommandMetadata = (method, commandPath, options) => {
         if (options === undefined) {
             return;
@@ -1752,6 +1816,7 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
         registerItemFields,
         registerItemTypes,
         registerMigration,
+        registerProfile,
         registerRenderer,
         registerImporter,
         registerExporter,
@@ -1777,6 +1842,7 @@ function getRegistrationCounts(registrations) {
         item_fields: itemFieldCount,
         item_types: itemTypeCount,
         migrations: registrations.migrations.length,
+        profiles: registrations.profiles.length,
         importers: registrations.importers.length,
         exporters: registrations.exporters.length,
         search_providers: registrations.search_providers.length,
@@ -1997,4 +2063,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=7c9e6f67-48e5-5952-a7a7-341aafa36244
+//# debugId=a323e13b-37e3-5ec6-bc21-1ab78e0b30b9