@unbrained/pm-cli 2026.5.31 → 2026.6.5

package/dist/cli-bundle/chunks/{chunk-OGZEG5TT.js → chunk-OIQIXTNB.js}

@@ -1,12 +1,9 @@
-import {
-  resolvePmPackageRootFromModule
-} from "./chunk-EGUGFSNX.js";
 import {
   splitCommaList
 } from "./chunk-3HUE7XOF.js";
 import {
   nowIso
-} from "./chunk-PVNQLCIS.js";
+} from "./chunk-RANZIID5.js";
 import {
   EXIT_CODE,
   EXTENSION_CAPABILITY_CONTRACT,
@@ -22,9 +19,10 @@ import {
   readSettings,
   resolveExtensionRoots,
   resolveGlobalPmRoot,
+  resolvePmPackageRootFromModule,
   resolvePmRoot,
   writeSettings
-} from "./chunk-LSXGH6NE.js";
+} from "./chunk-SRVKTWPR.js";
 
 // dist/cli/commands/extension.js
 import { execFile as execFile2 } from "node:child_process";
@@ -1146,38 +1144,24 @@ import path6 from "node:path";
 !(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] = "6ba6d57e-c873-51ad-b55d-3f35c6f9ef55");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "a36c8ce6-d9bd-5c8b-bb3c-5615aa081b71");
   } catch (e2) {
   }
 })();
+var SCAFFOLD_MANIFEST_VERSION = 1;
+var SCAFFOLD_PM_MIN_VERSION = "2026.5.0";
 function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary) {
   const packageName = `pm-${extensionName}`;
   const manifest = `${JSON.stringify({
     name: extensionName,
     version: "0.1.0",
     entry: "./index.js",
-    capabilities: ["commands"]
+    capabilities: ["commands"],
+    manifest_version: SCAFFOLD_MANIFEST_VERSION,
+    pm_min_version: SCAFFOLD_PM_MIN_VERSION
   }, null, 2)}
 `;
-  const entrypoint = vocabulary === "package" ? [
-    'import { defineExtension } from "@unbrained/pm-cli/sdk";',
-    "",
-    "export default defineExtension({",
-    "  activate(api) {",
-    "    api.registerCommand({",
-    `      name: ${JSON.stringify(commandName)},`,
-    '      description: "Starter scaffold command. Replace with your own behavior.",',
-    "      run: async (context) => ({",
-    "        ok: true,",
-    `        source: ${JSON.stringify(extensionName)},`,
-    "        command: context.command,",
-    '        message: "Starter extension scaffold is active.",',
-    "      }),",
-    "    });",
-    "  },",
-    "});",
-    ""
-  ].join("\n") : [
+  const entrypoint = [
     '/** @param {import("@unbrained/pm-cli/sdk").ExtensionApi} api */',
     "export function activate(api) {",
     "  api.registerCommand({",
@@ -1209,7 +1193,7 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
       },
       pm: {
         aliases: [extensionName],
-        extensions: [`extensions/${extensionName}`],
+        extensions: ["."],
         docs: ["README.md"],
         examples: ["README.md"],
         catalog: {
@@ -1228,8 +1212,8 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
       "",
       "## Included Files",
       "- `package.json`: package metadata and `pm` resource manifest.",
-      `- \`extensions/${extensionName}/manifest.json\`: extension metadata and capabilities.`,
-      `- \`extensions/${extensionName}/index.js\`: starter command registration using the \`commands\` capability.`,
+      "- `manifest.json`: extension metadata and capabilities.",
+      "- `index.js`: starter command registration using the `commands` capability.",
       "",
       "## Quick Start",
       "```bash",
@@ -1238,16 +1222,23 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
       "pm package doctor --project --detail summary",
       "```",
       "",
+      "## Compatibility Bounds",
+      "`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:",
+      `- \`manifest_version\` (integer): manifest schema generation. Leave at \`${SCAFFOLD_MANIFEST_VERSION}\` unless you adopt a newer manifest schema.`,
+      `- \`pm_min_version\` (string): lowest pm CLI version that may load this package. Scaffolded as \`${SCAFFOLD_PM_MIN_VERSION}\`. The loader blocks the package on older CLIs.`,
+      "- `pm_max_version` (string, optional): highest pm CLI version that may load this package. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the package when the CLI exceeds this bound.",
+      "",
       "## Notes",
-      "- Keep package metadata in `package.json` and runtime behavior under `extensions/`.",
+      "- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.",
+      "- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.",
       "- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.",
       "- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.",
       ""
     ].join("\n");
     return {
       "package.json": packageJson,
-      [`extensions/${extensionName}/manifest.json`]: manifest,
-      [`extensions/${extensionName}/index.js`]: entrypoint,
+      "manifest.json": manifest,
+      "index.js": entrypoint,
       "README.md": packageReadme
     };
   }
@@ -1267,6 +1258,12 @@ function buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabula
     "pm extension --doctor --project --detail summary",
     "```",
     "",
+    "## Compatibility Bounds",
+    "`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:",
+    `- \`manifest_version\` (integer): manifest schema generation. Leave at \`${SCAFFOLD_MANIFEST_VERSION}\` unless you adopt a newer manifest schema.`,
+    `- \`pm_min_version\` (string): lowest pm CLI version that may load this extension. Scaffolded as \`${SCAFFOLD_PM_MIN_VERSION}\`. The loader blocks the extension on older CLIs.`,
+    "- `pm_max_version` (string, optional): highest pm CLI version that may load this extension. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the extension when the CLI exceeds this bound.",
+    "",
     "## Notes",
     "- This scaffold uses ESM exports so it works in package scopes with `type: module`.",
     "- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.",
@@ -1334,7 +1331,7 @@ async function scaffoldExtensionProject(target, vocabulary = "extension") {
 !(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] = "71448117-1b4c-5c35-8233-433f32151c95");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "2c378b79-515a-5ad7-a807-9ab870e2d33d");
   } catch (e2) {
   }
 })();
@@ -1446,6 +1443,61 @@ function summarizePolicyWarnings(warnings) {
 function lifecycleFlagCommand(options, action) {
   return options.vocabulary === "package" ? `pm package --${action}` : `pm extension --${action}`;
 }
+var REGISTRATION_COLLISION_WARNING_CODES = /* @__PURE__ */ new Set([
+  "extension_command_handler_collision",
+  "extension_command_override_collision",
+  "extension_command_override_handler_overlap",
+  "extension_parser_override_collision",
+  "extension_preflight_override_collision",
+  "extension_renderer_collision",
+  "extension_service_override_collision"
+]);
+function isRegistrationCollisionWarning(warning) {
+  return REGISTRATION_COLLISION_WARNING_CODES.has(warningCode(warning));
+}
+function isExtensionLayer(value) {
+  return value === "project" || value === "global";
+}
+function parseRegistrationCollisionWarning(warning) {
+  const parts = warning.split(":");
+  const code = parts[0];
+  if (!code || !REGISTRATION_COLLISION_WARNING_CODES.has(code)) {
+    return null;
+  }
+  const winnerLayer = parts.at(-4);
+  const winnerName = parts.at(-3)?.trim();
+  const displacedLayer = parts.at(-2);
+  const displacedName = parts.at(-1)?.trim();
+  if (!isExtensionLayer(winnerLayer) || !isExtensionLayer(displacedLayer) || !winnerName || !displacedName) {
+    return null;
+  }
+  return {
+    code,
+    winner: { layer: winnerLayer, name: winnerName },
+    displaced: { layer: displacedLayer, name: displacedName }
+  };
+}
+function collectRegistrationCollisionExtensionNames(warnings) {
+  const names = /* @__PURE__ */ new Set();
+  for (const warning of warnings) {
+    const parsed = parseRegistrationCollisionWarning(warning);
+    if (!parsed) {
+      continue;
+    }
+    names.add(parsed.winner.name);
+    names.add(parsed.displaced.name);
+  }
+  return [...names].sort((left, right) => left.localeCompare(right));
+}
+function buildRegistrationCollisionRemediation(warnings, commands) {
+  const registrationCollisionWarnings = warnings.filter(isRegistrationCollisionWarning);
+  if (registrationCollisionWarnings.length === 0) {
+    return null;
+  }
+  const collisionNames = collectRegistrationCollisionExtensionNames(registrationCollisionWarnings);
+  const collisionNameText = collisionNames.length > 0 ? ` Conflicting extensions: ${collisionNames.join(", ")}.` : "";
+  return `Extension registration collisions or handler/override overlaps detected.${collisionNameText} Single-winner surfaces can hide earlier package behavior. Deactivate one conflicting package with ${commands.deactivate}, or scope registration surfaces in extensions.policy.extension_overrides, then rerun ${commands.doctor}.`;
+}
 function classifyDoctorLoadFailureWarnings(loadFailures) {
   const warnings = [];
   for (const failure of loadFailures) {
@@ -1459,6 +1511,20 @@ function classifyDoctorLoadFailureWarnings(loadFailures) {
   }
   return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
 }
+function classifyDoctorActivationFailureWarnings(activationFailures = []) {
+  const failures = Array.isArray(activationFailures) ? activationFailures : [];
+  const warnings = [];
+  for (const failure of failures) {
+    if (!failure || typeof failure.name !== "string") {
+      continue;
+    }
+    const missingCapability = failure.trace?.missing_capability ?? failure.trace?.capability;
+    if (typeof missingCapability === "string" && missingCapability.trim().length > 0) {
+      warnings.push(`extension_capability_missing:${failure.name}:${missingCapability.trim().toLowerCase()}`);
+    }
+  }
+  return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+}
 function buildExtensionTriageSummary(scope, warnings, extensions, options = {}) {
   const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
   const managedTotal = extensions.filter((entry) => entry.managed).length;
@@ -1490,6 +1556,13 @@ function buildExtensionTriageSummary(scope, warnings, extensions, options = {})
   const scopeFlag = scope === "global" ? "--global" : "--project";
   const remediation = [];
   if (normalizedWarnings.length > 0) {
+    const registrationCollisionRemediation = buildRegistrationCollisionRemediation(normalizedWarnings, {
+      deactivate: `${lifecycleFlagCommand(options, "deactivate")} <name> ${scopeFlag}`,
+      doctor: `${lifecycleFlagCommand(options, "doctor")} ${scopeFlag} --detail deep --trace`
+    });
+    if (registrationCollisionRemediation) {
+      remediation.push(registrationCollisionRemediation);
+    }
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_manifest_"))) {
       remediation.push(`Run ${lifecycleFlagCommand(options, "explore")} ${scopeFlag} to inspect discovered manifests and directories.`);
     }
@@ -1499,15 +1572,24 @@ function buildExtensionTriageSummary(scope, warnings, extensions, options = {})
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_legacy_alias:"))) {
       remediation.push("Legacy extension capability aliases were auto-remapped to canonical capabilities. Update manifests to canonical names (migration/validation -> schema).");
     }
+    if (normalizedWarnings.some((warning) => warning.startsWith("extension_capability_missing:"))) {
+      remediation.push(`Extension activation failed because code registered a surface missing from manifest capabilities. Run ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag} --detail deep --trace and add the reported missing_capability to manifest.json before publishing.`);
+    }
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_command_definition_legacy_handler_alias:"))) {
       remediation.push("Extension command definitions using legacy handler were auto-remapped. Update command definitions to use run: (context) => ... for forward compatibility.");
     }
+    if (normalizedWarnings.some((warning) => warning.startsWith("extension_output_service_override_global:") || warning.startsWith("extension_output_renderer_override_global:"))) {
+      remediation.push("Global output service/renderer overrides are active. For output_format, return context.payload/null/undefined unless the extension owns the command. For renderers, return null for unrelated payloads so pm falls back to native rendering.");
+    }
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_load_failed_sdk_dependency_missing:"))) {
       remediation.push(`Detected extension load failures caused by missing SDK dependency resolution. Ensure extension package dependencies include "@unbrained/pm-cli" and reinstall dependencies before running ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
     }
     if (normalizedWarnings.some((warning) => warning.startsWith("extension_load_failed_module_mode_mismatch:"))) {
       remediation.push(`Detected extension module-mode mismatches. For ESM-based extension entries/imports, set package.json "type": "module" or use an explicit .mjs entry and rerun ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
     }
+    if (normalizedWarnings.some((warning) => warning.startsWith("extension_pm_min_version_") || warning.startsWith("extension_pm_max_version_"))) {
+      remediation.push(`Extension pm version-bound warnings detected. Align each package manifest's pm_min_version/pm_max_version with the installed pm CLI version (see the warning's required/allowed=...:current=... details), or upgrade/downgrade the pm CLI to satisfy the declared bounds, then rerun ${lifecycleFlagCommand(options, "doctor")} ${scopeFlag}.`);
+    }
     if (updateCheckFailedTotal > 0) {
       remediation.push(`Run ${lifecycleFlagCommand(options, "manage")} ${scopeFlag} after validating network and repository access.`);
     }
@@ -1652,7 +1734,7 @@ function buildDoctorConsistencySummary(scope, installedExtensions, loadedExtensi
 !(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] = "dc0411c0-3d3c-5495-9be5-d221c8a9498d");
+    n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "120f378d-34a8-5b2f-ab24-f056fb646d43");
   } catch (e2) {
   }
 })();
@@ -1661,6 +1743,7 @@ var EXTENSION_INSTALL_COPY_ATTEMPTS = 3;
 var EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;
 var EXTENSION_INSTALL_LOCK_DELAY_MS = 250;
 var EXTENSION_INSTALL_LOCK_STALE_MS = 12e4;
+var NATIVE_OUTPUT_MARKER = "__pm_native_output";
 function buildExtensionPolicyDetails(policy) {
   const overrides = (policy.extension_overrides ?? []).map((override) => ({
     name: override.name.trim(),
@@ -2186,6 +2269,19 @@ function requireTarget(target, action) {
   }
   return normalized;
 }
+function collectGlobalOutputOverrideDoctorWarnings(activationResult) {
+  const warnings = [];
+  for (const entry of activationResult.services.overrides) {
+    if (entry.service !== "output_format") {
+      continue;
+    }
+    warnings.push(`extension_output_service_override_global:${entry.service}:${entry.layer}:${entry.name}`);
+  }
+  for (const entry of activationResult.renderers.overrides) {
+    warnings.push(`extension_output_renderer_override_global:${entry.format}:${entry.layer}:${entry.name}`);
+  }
+  return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+}
 async function runExtension(target, options, global2) {
   const action = resolveAction(target, options);
   if ((options.strictExit === true || options.failOnWarn === true) && action !== "doctor") {
@@ -2223,24 +2319,34 @@ async function runExtension(target, options, global2) {
   const scope = resolveScope(options);
   const resolvedRoots = resolveExtensionRootsForScope(scope, global2);
   const warnings = [];
-  const withResult = (details) => ({
-    ok: true,
-    action,
-    scope,
-    roots: action === "catalog" && typeof options.fields === "string" && options.fields.trim().length > 0 ? {
-      project: "project",
-      global: "global",
-      selected: scope,
-      settings_root: "project"
-    } : {
-      project: resolvedRoots.roots.project,
-      global: resolvedRoots.roots.global,
-      selected: resolvedRoots.selected_root,
-      settings_root: resolvedRoots.settings_root
-    },
-    warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
-    details
-  });
+  const withResult = (details) => {
+    const result = {
+      ok: true,
+      action,
+      scope,
+      roots: action === "catalog" && typeof options.fields === "string" && options.fields.trim().length > 0 ? {
+        project: "project",
+        global: "global",
+        selected: scope,
+        settings_root: "project"
+      } : {
+        project: resolvedRoots.roots.project,
+        global: resolvedRoots.roots.global,
+        selected: resolvedRoots.selected_root,
+        settings_root: resolvedRoots.settings_root
+      },
+      warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
+      details
+    };
+    if (action === "doctor") {
+      Object.defineProperty(result, NATIVE_OUTPUT_MARKER, {
+        value: true,
+        enumerable: false,
+        configurable: false
+      });
+    }
+    return result;
+  };
   if (action === "init") {
     const githubOption = resolveGithubOption(options);
     if (githubOption !== void 0 || typeof options.ref === "string" && options.ref.trim().length > 0) {
@@ -2649,6 +2755,8 @@ async function runExtension(target, options, global2) {
     warnings.push(...loadResult.warnings);
     warnings.push(...classifyDoctorLoadFailureWarnings(loadResult.failed));
     warnings.push(...activationResult.warnings);
+    warnings.push(...classifyDoctorActivationFailureWarnings(activationResult.failed));
+    warnings.push(...collectGlobalOutputOverrideDoctorWarnings(activationResult));
     const runtimeInstalledExtensions = applyDoctorRuntimeActivationState(refreshedInstalled.extensions, loadResult, activationResult);
     const doctorConsistency = buildDoctorConsistencySummary(scope, runtimeInstalledExtensions, loadResult.loaded.map((entry) => ({ layer: entry.layer, name: entry.name })), loadResult.failed.map((entry) => ({ name: entry.name })), loadResult.disabled_by_flag);
     warnings.push(...doctorConsistency.warnings);
@@ -2801,6 +2909,8 @@ async function runExtension(target, options, global2) {
             error: entry.error,
             method: entry.trace?.method,
             command: entry.trace?.command,
+            capability: entry.trace?.capability,
+            missing_capability: entry.trace?.missing_capability,
             registration_index: entry.trace?.registration_index,
             expected_schema: entry.trace?.expected_schema,
             hint: entry.trace?.hint,
@@ -2923,7 +3033,8 @@ export {
   readManagedExtensionState,
   writeManagedExtensionState,
   parseExtensionInstallSource,
+  buildRegistrationCollisionRemediation,
   copyExtensionDirectoryForInstall,
   runExtension
 };
-//# sourceMappingURL=chunk-OGZEG5TT.js.map
+//# sourceMappingURL=chunk-OIQIXTNB.js.map