@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/dist/core/extensions/item-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"item-fields.js","sources":["core/extensions/item-fields.ts"],"sourceRoot":"/","sourcesContent":["import type { ExtensionRegistrationRegistry } from \"./loader.js\";\n\nfunction normalizeFieldName(value: unknown): string | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const normalized = value.trim();\n  return normalized.length > 0 ? normalized : null;\n}\n\nfunction normalizeFieldType(value: unknown): \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const normalized = value.trim().toLowerCase();\n  if (\n    normalized === \"string\" ||\n    normalized === \"number\" ||\n    normalized === \"boolean\" ||\n    normalized === \"array\" ||\n    normalized === \"object\"\n  ) {\n    return normalized;\n  }\n  return null;\n}\n\nfunction cloneFieldValue<T>(value: T): T {\n  try {\n    return structuredClone(value);\n  } catch {\n    return value;\n  }\n}\n\nfunction isValidFieldType(value: unknown, expectedType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\"): boolean {\n  if (expectedType === \"string\") {\n    return typeof value === \"string\";\n  }\n  if (expectedType === \"number\") {\n    return typeof value === \"number\" && Number.isFinite(value);\n  }\n  if (expectedType === \"boolean\") {\n    return typeof value === \"boolean\";\n  }\n  if (expectedType === \"array\") {\n    return Array.isArray(value);\n  }\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isAllowedFieldValue(value: unknown, allowed: unknown[] | undefined): boolean {\n  if (!allowed || allowed.length === 0) {\n    return true;\n  }\n  return allowed.some((candidate) => Object.is(candidate, value));\n}\n\nexport function applyRegisteredItemFieldDefaultsAndValidation(\n  frontMatter: Record<string, unknown>,\n  registrations: ExtensionRegistrationRegistry | null,\n): void {\n  if (!registrations) {\n    return;\n  }\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      if (!fieldName) {\n        continue;\n      }\n      if (!(fieldName in frontMatter) && Object.prototype.hasOwnProperty.call(definition, \"default\")) {\n        frontMatter[fieldName] = cloneFieldValue(definition.default);\n      }\n\n      const currentValue = frontMatter[fieldName];\n      if (currentValue === undefined) {\n        continue;\n      }\n      const expectedType = normalizeFieldType(definition.type);\n      if (expectedType && !isValidFieldType(currentValue, expectedType)) {\n        throw new TypeError(`Item field \"${fieldName}\" must be of type ${expectedType}`);\n      }\n\n      const allowedValues = Array.isArray(definition.values) ? definition.values : undefined;\n      if (!isAllowedFieldValue(currentValue, allowedValues)) {\n        throw new TypeError(`Item field \"${fieldName}\" must match one of the configured allowed values`);\n      }\n    }\n  }\n}\n"],"names":[],"mappings":"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","debugId":"ded4c408-642b-51bb-8f35-b66db506ce14"}
+{"version":3,"file":"item-fields.js","sources":["core/extensions/item-fields.ts"],"sourceRoot":"/","sourcesContent":["import type { ExtensionRegistrationRegistry } from \"./loader.js\";\nimport { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\nconst RESERVED_ITEM_FIELD_NAMES = new Set(FRONT_MATTER_KEY_ORDER);\n\nfunction normalizeFieldName(value: unknown): string | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const normalized = value.trim();\n  return normalized.length > 0 ? normalized : null;\n}\n\nfunction normalizeFieldType(value: unknown): \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const normalized = value.trim().toLowerCase();\n  if (\n    normalized === \"string\" ||\n    normalized === \"number\" ||\n    normalized === \"boolean\" ||\n    normalized === \"array\" ||\n    normalized === \"object\"\n  ) {\n    return normalized;\n  }\n  return null;\n}\n\nfunction cloneFieldValue<T>(value: T): T {\n  try {\n    return structuredClone(value);\n  } catch {\n    return value;\n  }\n}\n\nfunction parseFieldAssignment(raw: string): { key: string; value: string } {\n  const trimmed = raw.trim();\n  const separatorIndex = trimmed.indexOf(\"=\");\n  if (separatorIndex <= 0) {\n    throw new PmCliError(`--field entries must use name=value syntax, received: ${raw}`, EXIT_CODE.USAGE);\n  }\n  const key = trimmed.slice(0, separatorIndex).trim();\n  const value = trimmed.slice(separatorIndex + 1);\n  if (key.length === 0) {\n    throw new PmCliError(\"--field entries require a non-empty field name\", EXIT_CODE.USAGE);\n  }\n  return { key, value };\n}\n\nfunction parseJsonFieldValue(raw: string, fieldName: string, expectedType: \"array\" | \"object\"): unknown {\n  try {\n    const parsed = JSON.parse(raw);\n    if (expectedType === \"array\" && Array.isArray(parsed)) {\n      return parsed;\n    }\n    if (expectedType === \"object\" && typeof parsed === \"object\" && parsed !== null && !Array.isArray(parsed)) {\n      return parsed;\n    }\n  } catch {\n    // Fall through to the typed usage error below.\n  }\n  throw new PmCliError(`--field ${fieldName}=... must be valid JSON ${expectedType}`, EXIT_CODE.USAGE);\n}\n\nfunction coerceRegisteredFieldValue(fieldName: string, fieldType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\", raw: string): unknown {\n  if (fieldType === \"string\") {\n    return raw;\n  }\n  if (fieldType === \"number\") {\n    const trimmed = raw.trim();\n    if (trimmed.length === 0) {\n      throw new PmCliError(`--field ${fieldName}=... must be a number`, EXIT_CODE.USAGE);\n    }\n    const parsed = Number(trimmed);\n    if (!Number.isFinite(parsed)) {\n      throw new PmCliError(`--field ${fieldName}=... must be a number`, EXIT_CODE.USAGE);\n    }\n    return parsed;\n  }\n  if (fieldType === \"boolean\") {\n    const normalized = raw.trim().toLowerCase();\n    if (normalized === \"true\" || normalized === \"1\" || normalized === \"yes\") {\n      return true;\n    }\n    if (normalized === \"false\" || normalized === \"0\" || normalized === \"no\") {\n      return false;\n    }\n    throw new PmCliError(`--field ${fieldName}=... must be one of true|false|1|0|yes|no`, EXIT_CODE.USAGE);\n  }\n  return parseJsonFieldValue(raw, fieldName, fieldType);\n}\n\nfunction collectRegisteredFieldDefinitions(\n  registrations: ExtensionRegistrationRegistry | null,\n): Map<string, { name: string; type: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" }> {\n  const definitions = new Map<string, { name: string; type: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" }>();\n  if (!registrations) {\n    return definitions;\n  }\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      const fieldType = normalizeFieldType(definition.type);\n      if (!fieldName || !fieldType) {\n        continue;\n      }\n      const existing = definitions.get(fieldName);\n      if (existing && existing.type !== fieldType) {\n        throw new PmCliError(\n          `Extension item field \"${fieldName}\" is declared with conflicting types: ${existing.type}, ${fieldType}`,\n          EXIT_CODE.USAGE,\n          {\n            code: \"extension_item_field_type_conflict\",\n            nextSteps: [\"Make every active extension declaration for this field use the same type.\"],\n          },\n        );\n      }\n      definitions.set(fieldName, { name: fieldName, type: fieldType });\n    }\n  }\n  return definitions;\n}\n\nfunction assertNotReservedItemFieldName(fieldName: string): void {\n  if (!RESERVED_ITEM_FIELD_NAMES.has(fieldName)) {\n    return;\n  }\n  throw new PmCliError(`Extension item field \"${fieldName}\" collides with reserved item metadata`, EXIT_CODE.USAGE, {\n    code: \"extension_item_field_reserved\",\n    nextSteps: [\"Rename the extension item field, preferably with an extension-specific prefix.\"],\n  });\n}\n\nexport function collectRegisteredItemFieldNames(registrations: ExtensionRegistrationRegistry | null): string[] {\n  return [...collectRegisteredFieldDefinitions(registrations).keys()].sort((left, right) => left.localeCompare(right));\n}\n\nexport function parseRegisteredItemFieldAssignments(\n  rawFields: string[] | undefined,\n  registrations: ExtensionRegistrationRegistry | null,\n): Record<string, unknown> {\n  if (!rawFields || rawFields.length === 0) {\n    return {};\n  }\n  const definitions = collectRegisteredFieldDefinitions(registrations);\n  const values: Record<string, unknown> = {};\n  for (const raw of rawFields) {\n    const { key, value } = parseFieldAssignment(raw);\n    const definition = definitions.get(key);\n    if (!definition) {\n      const known = [...definitions.keys()].sort((left, right) => left.localeCompare(right));\n      throw new PmCliError(`--field ${key} is not declared by an active extension item-field registration`, EXIT_CODE.USAGE, {\n        code: \"extension_item_field_unknown\",\n        recovery: { provided_fields: known },\n        nextSteps: known.length > 0\n          ? [`Use one of the declared fields: ${known.join(\", \")}`]\n          : [\"Activate an extension that calls registerItemFields before setting extension fields.\"],\n      });\n    }\n    assertNotReservedItemFieldName(definition.name);\n    values[definition.name] = coerceRegisteredFieldValue(definition.name, definition.type, value);\n  }\n  return values;\n}\n\nfunction isValidFieldType(value: unknown, expectedType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\"): boolean {\n  if (expectedType === \"string\") {\n    return typeof value === \"string\";\n  }\n  if (expectedType === \"number\") {\n    return typeof value === \"number\" && Number.isFinite(value);\n  }\n  if (expectedType === \"boolean\") {\n    return typeof value === \"boolean\";\n  }\n  if (expectedType === \"array\") {\n    return Array.isArray(value);\n  }\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isAllowedFieldValue(value: unknown, allowed: unknown[] | undefined): boolean {\n  if (!allowed || allowed.length === 0) {\n    return true;\n  }\n  return allowed.some((candidate) => Object.is(candidate, value));\n}\n\nexport function applyRegisteredItemFieldDefaultsAndValidation(\n  frontMatter: Record<string, unknown>,\n  registrations: ExtensionRegistrationRegistry | null,\n  options: { skipDefaultFields?: ReadonlySet<string> } = {},\n): void {\n  if (!registrations) {\n    return;\n  }\n  collectRegisteredFieldDefinitions(registrations);\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      if (!fieldName) {\n        continue;\n      }\n      assertNotReservedItemFieldName(fieldName);\n      if (\n        !(fieldName in frontMatter) &&\n        !options.skipDefaultFields?.has(fieldName) &&\n        Object.prototype.hasOwnProperty.call(definition, \"default\")\n      ) {\n        frontMatter[fieldName] = cloneFieldValue(definition.default);\n      }\n\n      const currentValue = frontMatter[fieldName];\n      if (currentValue === undefined) {\n        continue;\n      }\n      const expectedType = normalizeFieldType(definition.type);\n      if (expectedType && !isValidFieldType(currentValue, expectedType)) {\n        throw new TypeError(`Item field \"${fieldName}\" must be of type ${expectedType}`);\n      }\n\n      const allowedValues = Array.isArray(definition.values) ? definition.values : undefined;\n      if (!isAllowedFieldValue(currentValue, allowedValues)) {\n        throw new TypeError(`Item field \"${fieldName}\" must match one of the configured allowed values`);\n      }\n    }\n  }\n}\n"],"names":[],"mappings":"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","debugId":"60ed024d-4341-5166-bd9e-abed9b240b11"}

package/dist/core/extensions/loader.js

@@ -1,10 +1,11 @@
 
-!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]="4fba8687-0797-5479-afc8-12f1a2e5a954")}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]="c1d2f70f-a61e-585b-bfee-5401b41545f8")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { pathExists } from "../fs/fs-utils.js";
 import { isPathWithinDirectory } from "../fs/path-utils.js";
+import { resolvePmPackageRootFromModule } from "../packages/root.js";
 import { resolveGlobalPmRoot } from "../store/paths.js";
 import { asRecordLoose } from "../shared/primitives.js";
 // Cohesive helper groups now live in sibling modules. They are imported for the
@@ -21,6 +22,7 @@ export { runBeforeCommandHooks, runAfterCommandHooks, runOnWriteHooks, runOnRead
 import { KNOWN_EXTENSION_SERVICE_NAMES, createDefaultExtensionGovernancePolicy, } from "./extension-types.js";
 export * from "./extension-types.js";
 const DEFAULT_EXTENSION_PRIORITY = 100;
+let currentPmCliVersionPromise = null;
 /* Types now in extension-types.ts - re-exported via `export * from "./extension-types.js"` above */
 const DEFAULT_EXTENSION_POLICY = Object.freeze(createDefaultExtensionGovernancePolicy());
 let extensionReloadEpoch = 0;
@@ -28,6 +30,37 @@ export function nextExtensionReloadToken(seed = Date.now()) {
     extensionReloadEpoch += 1;
     return `${extensionReloadEpoch}-${seed}`;
 }
+function parseOptionalManifestString(candidate, field) {
+    const value = candidate[field];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return null;
+    }
+    return value.trim();
+}
+function parseManifestEngines(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const enginesRecord = asRecordLoose(value);
+    if (!enginesRecord) {
+        return null;
+    }
+    const engines = {};
+    for (const key of Object.keys(enginesRecord).sort((left, right) => left.localeCompare(right))) {
+        if (key.trim().length === 0) {
+            return null;
+        }
+        const engineValue = enginesRecord[key];
+        if (typeof engineValue !== "string" || engineValue.trim().length === 0) {
+            return null;
+        }
+        engines[key.trim()] = engineValue.trim();
+    }
+    return Object.keys(engines).length > 0 ? engines : undefined;
+}
 function parseManifest(raw) {
     if (typeof raw !== "object" || raw === null) {
         return null;
@@ -56,6 +89,18 @@ function parseManifest(raw) {
         }
         manifestVersion = candidate.manifest_version;
     }
+    const pmMinVersion = parseOptionalManifestString(candidate, "pm_min_version");
+    if (pmMinVersion === null) {
+        return null;
+    }
+    const pmMaxVersion = parseOptionalManifestString(candidate, "pm_max_version");
+    if (pmMaxVersion === null) {
+        return null;
+    }
+    const engines = parseManifestEngines(candidate.engines);
+    if (engines === null) {
+        return null;
+    }
     let trusted;
     if ("trusted" in candidate && candidate.trusted !== undefined && candidate.trusted !== null) {
         if (typeof candidate.trusted !== "boolean") {
@@ -147,16 +192,43 @@ function parseManifest(raw) {
         capabilities = normalizedCapabilities.capabilities;
         legacyCapabilityAliases = normalizedCapabilities.legacy_aliases;
     }
+    let activation;
+    if ("activation" in candidate && candidate.activation !== undefined && candidate.activation !== null) {
+        const activationRecord = asRecordLoose(candidate.activation);
+        if (!activationRecord) {
+            return null;
+        }
+        const rawCommands = activationRecord.commands;
+        if (rawCommands !== undefined && rawCommands !== null) {
+            if (!Array.isArray(rawCommands) || rawCommands.some((value) => typeof value !== "string")) {
+                return null;
+            }
+            const commands = [
+                ...new Set(rawCommands
+                    .map((value) => normalizeCommandName(value))
+                    .filter((value) => value.length > 0)),
+            ].sort((left, right) => left.localeCompare(right));
+            if (commands.length > 0) {
+                activation = {
+                    commands,
+                };
+            }
+        }
+    }
     return {
         name: candidate.name.trim(),
         version: candidate.version.trim(),
         entry: candidate.entry.trim(),
         priority,
         manifest_version: manifestVersion,
+        pm_min_version: pmMinVersion,
+        pm_max_version: pmMaxVersion,
+        engines,
         trusted,
         provenance,
         sandbox_profile: sandboxProfile,
         permissions,
+        activation,
         capabilities,
         legacy_capability_aliases: legacyCapabilityAliases.length > 0 ? legacyCapabilityAliases : undefined,
     };
@@ -203,11 +275,19 @@ function summarizeCandidate(candidate) {
         priority: candidate.manifest.priority,
         entry_path: candidate.entry_path,
         manifest_version: candidate.manifest.manifest_version,
+        pm_min_version: candidate.manifest.pm_min_version,
+        pm_max_version: candidate.manifest.pm_max_version,
+        engines: candidate.manifest.engines,
         trusted: candidate.manifest.trusted,
         provenance: candidate.manifest.provenance,
         sandbox_profile: candidate.manifest.sandbox_profile,
         permissions: candidate.manifest.permissions,
         capabilities: [...candidate.manifest.capabilities],
+        activation: candidate.manifest.activation
+            ? {
+                commands: [...(candidate.manifest.activation.commands ?? [])],
+            }
+            : undefined,
     };
 }
 function sortCandidates(candidates) {
@@ -316,6 +396,18 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
     else if (!entryExists) {
         extensionWarnings.push(`extension_entry_missing:${layer}:${manifest.name}`);
     }
+    const pmVersionCompatibility = await evaluatePmMinVersionCompatibility(layer, manifest);
+    if (pmVersionCompatibility.warning) {
+        extensionWarnings.push(pmVersionCompatibility.warning);
+    }
+    const pmMaxVersionCompatibility = await evaluatePmMaxVersionCompatibility(layer, manifest);
+    if (pmMaxVersionCompatibility.warning) {
+        extensionWarnings.push(pmMaxVersionCompatibility.warning);
+    }
+    const extensionReady = entryWithinDirectory &&
+        entryExists &&
+        pmVersionCompatibility.allowed &&
+        pmMaxVersionCompatibility.allowed;
     return {
         diagnostic: {
             layer,
@@ -327,10 +419,10 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
             priority: manifest.priority,
             entry_path: entryPath,
             enabled: enabledForLoad,
-            status: entryWithinDirectory && entryExists ? "ok" : "warn",
+            status: extensionReady ? "ok" : "warn",
         },
         warnings: extensionWarnings,
-        candidate: entryWithinDirectory && entryExists && enabledForLoad
+        candidate: extensionReady && enabledForLoad
             ? {
                 layer,
                 directory,
@@ -416,6 +508,122 @@ 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, ["../../.."]);
+        const raw = await fs.readFile(path.join(packageRoot, "package.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === "string" && parsed.version.trim().length > 0 ? parsed.version.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+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`,
+        };
+    }
+    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}`,
+        };
+    }
+    if (comparison < 0) {
+        return {
+            allowed: false,
+            warning: `extension_pm_min_version_unmet:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=${currentVersion}`,
+        };
+    }
+    return { allowed: true };
+}
+async function evaluatePmMaxVersionCompatibility(layer, manifest) {
+    if (typeof manifest.pm_max_version !== "string" || manifest.pm_max_version.trim().length === 0) {
+        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}`,
+        };
+    }
+    // follow-up: pm-4gw6 recommends a future settings toggle to relax this default-BLOCK to warn-only per layer.
+    if (comparison > 0) {
+        return {
+            allowed: false,
+            warning: `extension_pm_max_version_exceeded:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
+        };
+    }
+    return { allowed: true };
+}
 async function fingerprintPath(pathToInspect) {
     try {
         const stats = await fs.stat(pathToInspect);
@@ -843,7 +1051,15 @@ function assertExtensionCapability(extension, capability, method) {
         return;
     }
     if (!declared.has(capability)) {
-        throw new TypeError(`${method} requires capability '${capability}' in extension manifest capabilities`);
+        throw createRegistrationValidationError(`${method} requires capability '${capability}' in extension manifest capabilities`, {
+            method,
+            registration_index: -1,
+            capability,
+            missing_capability: capability,
+            expected_schema: `"capabilities": [..., "${capability}"]`,
+            received: extension.capabilities ?? [],
+            hint: `Add "${capability}" to ${extension.name} manifest capabilities, or remove the ${method} registration call.`,
+        });
     }
 }
 function createExtensionApi(extension, hooks, commands, parsers, preflight, services, renderers, registrations, activationWarnings, policy) {
@@ -1101,7 +1317,54 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
             definition: normalizeRegistrationRecord("registerMigration definition", definition),
         }, runtimeDefinition));
     };
-    const registerImporter = (name, importer) => {
+    const applyImportExportCommandMetadata = (method, commandPath, options) => {
+        if (options === undefined) {
+            return;
+        }
+        if (typeof options !== "object" || options === null || Array.isArray(options)) {
+            throw new TypeError(`${method} options must be an object when provided`);
+        }
+        assertOptionalStringField(`${method} options.action`, options.action);
+        assertOptionalStringField(`${method} options.description`, options.description);
+        assertOptionalStringField(`${method} options.intent`, options.intent);
+        const action = resolveCommandDefinitionAction(commandPath, options.action);
+        const examples = normalizeOptionalStringArrayField(`${method} options.examples`, options.examples);
+        const failureHints = normalizeOptionalStringArrayField(`${method} options.failure_hints`, options.failure_hints);
+        const argumentsDefinition = normalizeCommandDefinitionArguments(options.arguments);
+        if (options.flags !== undefined) {
+            assertExtensionCapability(extension, "schema", `${method} options.flags`);
+            // Route metadata flags through the same surface-policy gate as registerFlags so
+            // enforce-mode policies blocking schema.flags are honored even when importers are allowed.
+            if (allowRegistration("schema.flags", `${method} options.flags`, "schema")) {
+                validateFlagDefinitions(options.flags);
+                registrations.flags.push({
+                    layer: extension.layer,
+                    name: extension.name,
+                    target_command: commandPath,
+                    flags: normalizeRegistrationRecordList(`${method} options.flags`, options.flags),
+                });
+            }
+        }
+        const registration = {
+            layer: extension.layer,
+            name: extension.name,
+            command: commandPath,
+            action,
+            examples,
+            failure_hints: failureHints,
+            arguments: argumentsDefinition,
+        };
+        const description = options.description?.trim();
+        if (description) {
+            registration.description = description;
+        }
+        const intent = options.intent?.trim();
+        if (intent) {
+            registration.intent = intent;
+        }
+        registrations.commands.push(registration);
+    };
+    const registerImporter = (name, importer, options) => {
         assertExtensionCapability(extension, "importers", "registerImporter");
         if (!allowRegistration("importers.importer", "registerImporter", "importers")) {
             return;
@@ -1109,6 +1372,9 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
         const normalizedName = normalizeRegistrationName(assertNonEmptyString("registerImporter name", name));
         assertFunctionHandler("registerImporter importer", importer);
         const commandPath = toRegistrationCommandPath(normalizedName, "import");
+        // Validate and register optional command metadata before mutating the registry
+        // so an invalid options object leaves no partial importer registration.
+        applyImportExportCommandMetadata("registerImporter", commandPath, options);
         registrations.importers.push({
             layer: extension.layer,
             name: extension.name,
@@ -1129,7 +1395,7 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
             }),
         });
     };
-    const registerExporter = (name, exporter) => {
+    const registerExporter = (name, exporter, options) => {
         assertExtensionCapability(extension, "importers", "registerExporter");
         if (!allowRegistration("importers.exporter", "registerExporter", "importers")) {
             return;
@@ -1137,6 +1403,9 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
         const normalizedName = normalizeRegistrationName(assertNonEmptyString("registerExporter name", name));
         assertFunctionHandler("registerExporter exporter", exporter);
         const commandPath = toRegistrationCommandPath(normalizedName, "export");
+        // Validate and register optional command metadata before mutating the registry
+        // so an invalid options object leaves no partial exporter registration.
+        applyImportExportCommandMetadata("registerExporter", commandPath, options);
         registrations.exporters.push({
             layer: extension.layer,
             name: extension.name,
@@ -1308,7 +1577,13 @@ function collectCommandCollisionWarnings(commands) {
         .filter((command) => handlerCommands.has(command))
         .sort((left, right) => left.localeCompare(right));
     for (const command of overlapCommands) {
-        warnings.push(`extension_command_override_handler_overlap:${command}`);
+        const handlers = commands.handlers.filter((entry) => entry.command === command);
+        const overrides = commands.overrides.filter((entry) => entry.command === command);
+        for (const override of overrides) {
+            for (const handler of handlers) {
+                warnings.push(`extension_command_override_handler_overlap:${command}:${override.layer}:${override.name}:${handler.layer}:${handler.name}`);
+            }
+        }
     }
     return warnings;
 }
@@ -1453,4 +1728,4 @@ export async function activateExtensions(loadResult) {
     };
 }
 //# sourceMappingURL=loader.js.map
-//# debugId=4fba8687-0797-5479-afc8-12f1a2e5a954
+//# debugId=c1d2f70f-a61e-585b-bfee-5401b41545f8