@unbrained/pm-cli 2026.6.20 → 2026.6.22

package/dist/cli.js

@@ -5,14 +5,14 @@
  * Bootstraps the executable pm CLI entrypoint and startup optimizations.
  */
 
-!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]="50b88050-16c3-5d09-886d-d265e0c50a2c")}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]="b1ba95ef-36cf-582b-8e85-d085a047afd2")}catch(e){}}();
 import fs from "node:fs";
 import * as nodeModule from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 function enableNodeCompileCache() {
-    const enableCompileCache = nodeModule.enableCompileCache;
+    const { enableCompileCache } = nodeModule;
     if (typeof enableCompileCache !== "function" || process.env.PM_CLI_DISABLE_COMPILE_CACHE === "1") {
         return;
     }
@@ -82,4 +82,4 @@ if (!printFastVersionIfRequested()) {
     await runPmCli(process.argv.slice(2));
 }
 //# sourceMappingURL=cli.js.map
-//# debugId=50b88050-16c3-5d09-886d-d265e0c50a2c
+//# debugId=b1ba95ef-36cf-582b-8e85-d085a047afd2

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sources":["cli.ts"],"sourceRoot":"/","sourcesContent":["#!/usr/bin/env node\n/**\n * @module cli\n *\n * Bootstraps the executable pm CLI entrypoint and startup optimizations.\n */\nimport fs from \"node:fs\";\nimport * as nodeModule from \"node:module\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nfunction enableNodeCompileCache(): void {\n  const enableCompileCache = nodeModule.enableCompileCache as\n    | ((cacheDir?: string) => { status?: number; message?: string })\n    | undefined;\n  if (typeof enableCompileCache !== \"function\" || process.env.PM_CLI_DISABLE_COMPILE_CACHE === \"1\") {\n    return;\n  }\n  const userCacheKey =\n    typeof process.getuid === \"function\"\n      ? String(process.getuid())\n      : os.userInfo().username.replace(/[^a-zA-Z0-9._-]/g, \"_\");\n  const cacheDir =\n    process.env.PM_CLI_COMPILE_CACHE_DIR ?? path.join(os.tmpdir(), `pm-cli-node-compile-cache-${userCacheKey}`);\n  try {\n    enableCompileCache(cacheDir);\n  } catch {\n    // Compile caching is a startup optimization only; never block CLI execution.\n  }\n}\n\nfunction findPackageJson(startPath: string): string | undefined {\n  let current = path.dirname(path.resolve(startPath));\n  while (true) {\n    const candidate = path.join(current, \"package.json\");\n    if (fs.existsSync(candidate)) {\n      return candidate;\n    }\n    const parent = path.dirname(current);\n    if (parent === current) {\n      return undefined;\n    }\n    current = parent;\n  }\n}\n\nfunction printFastVersionIfRequested(): boolean {\n  const args = process.argv.slice(2);\n  const versionArgs = args.filter((arg) => arg !== \"--no-extensions\");\n  if (versionArgs.length !== 1 || (versionArgs[0] !== \"--version\" && versionArgs[0] !== \"-V\")) {\n    return false;\n  }\n  const version = readPackageVersionForPath(fileURLToPath(import.meta.url));\n  if (version === undefined) {\n    return false;\n  }\n  console.log(version);\n  return true;\n}\n\nfunction readPackageVersionForPath(startPath: string): string | undefined {\n  const packageJsonPath = findPackageJson(startPath);\n  if (!packageJsonPath) {\n    return undefined;\n  }\n  try {\n    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, \"utf8\")) as { version?: unknown };\n    if (typeof parsed.version !== \"string\") {\n      return undefined;\n    }\n    return parsed.version;\n  } catch {\n    return undefined;\n  }\n}\n\nexport const _testOnly = {\n  enableNodeCompileCache,\n  findPackageJson,\n  printFastVersionIfRequested,\n  readPackageVersionForPath,\n};\n\nif (!printFastVersionIfRequested()) {\n  enableNodeCompileCache();\n  const { runPmCli } = await import(\"./cli/main.js\");\n  await runPmCli(process.argv.slice(2));\n}\n"],"names":[],"mappings":"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","debugId":"50b88050-16c3-5d09-886d-d265e0c50a2c"}
+{"version":3,"file":"cli.js","sources":["cli.ts"],"sourceRoot":"/","sourcesContent":["#!/usr/bin/env node\n/**\n * @module cli\n *\n * Bootstraps the executable pm CLI entrypoint and startup optimizations.\n */\nimport fs from \"node:fs\";\nimport * as nodeModule from \"node:module\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\ntype NodeModuleWithCompileCache = typeof nodeModule & {\n  enableCompileCache?: (cacheDir?: string) => { status?: number; message?: string };\n};\n\nfunction enableNodeCompileCache(): void {\n  const { enableCompileCache } = nodeModule as NodeModuleWithCompileCache;\n  if (typeof enableCompileCache !== \"function\" || process.env.PM_CLI_DISABLE_COMPILE_CACHE === \"1\") {\n    return;\n  }\n  const userCacheKey =\n    typeof process.getuid === \"function\"\n      ? String(process.getuid())\n      : os.userInfo().username.replace(/[^a-zA-Z0-9._-]/g, \"_\");\n  const cacheDir =\n    process.env.PM_CLI_COMPILE_CACHE_DIR ?? path.join(os.tmpdir(), `pm-cli-node-compile-cache-${userCacheKey}`);\n  try {\n    enableCompileCache(cacheDir);\n  } catch {\n    // Compile caching is a startup optimization only; never block CLI execution.\n  }\n}\n\nfunction findPackageJson(startPath: string): string | undefined {\n  let current = path.dirname(path.resolve(startPath));\n  while (true) {\n    const candidate = path.join(current, \"package.json\");\n    if (fs.existsSync(candidate)) {\n      return candidate;\n    }\n    const parent = path.dirname(current);\n    if (parent === current) {\n      return undefined;\n    }\n    current = parent;\n  }\n}\n\nfunction printFastVersionIfRequested(): boolean {\n  const args = process.argv.slice(2);\n  const versionArgs = args.filter((arg) => arg !== \"--no-extensions\");\n  if (versionArgs.length !== 1 || (versionArgs[0] !== \"--version\" && versionArgs[0] !== \"-V\")) {\n    return false;\n  }\n  const version = readPackageVersionForPath(fileURLToPath(import.meta.url));\n  if (version === undefined) {\n    return false;\n  }\n  console.log(version);\n  return true;\n}\n\nfunction readPackageVersionForPath(startPath: string): string | undefined {\n  const packageJsonPath = findPackageJson(startPath);\n  if (!packageJsonPath) {\n    return undefined;\n  }\n  try {\n    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, \"utf8\")) as { version?: unknown };\n    if (typeof parsed.version !== \"string\") {\n      return undefined;\n    }\n    return parsed.version;\n  } catch {\n    return undefined;\n  }\n}\n\nexport const _testOnly = {\n  enableNodeCompileCache,\n  findPackageJson,\n  printFastVersionIfRequested,\n  readPackageVersionForPath,\n};\n\nif (!printFastVersionIfRequested()) {\n  enableNodeCompileCache();\n  const { runPmCli } = await import(\"./cli/main.js\");\n  await runPmCli(process.argv.slice(2));\n}\n"],"names":[],"mappings":"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","debugId":"b1ba95ef-36cf-582b-8e85-d085a047afd2"}

package/dist/core/diagnostics/remediation.js

@@ -24,7 +24,7 @@
  * intentionally excluded here (see pm-0hnu: "all non-extension checks").
  */
 
-!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]="18ec090a-cfc4-5acf-90b6-7e6fade40d8d")}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]="6700669e-bb33-5b85-a194-73e559d13abd")}catch(e){}}();
 export const REMEDIATION_REGISTRY = Object.freeze([
     // --- pm health: directories ---
     {
@@ -131,6 +131,17 @@ export const REMEDIATION_REGISTRY = Object.freeze([
         command: "pm history-repair <id>",
         summary: "A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain.",
     },
+    // --- pm health (integrity) + pm validate (format_version): item format version ---
+    {
+        code: "integrity_item_outdated_format_version",
+        command: "pm validate --verbose-diagnostics",
+        summary: "An item predates the current storage format version; a pm storage migration rewrites it. Use --verbose-diagnostics to list the affected items.",
+    },
+    {
+        code: "integrity_item_ahead_format_version",
+        command: "npm install -g @unbrained/pm-cli@latest",
+        summary: "An item was written by a newer pm format version than this runtime supports; upgrade pm to read and validate it safely.",
+    },
     // --- pm health: history_drift ---
     // `pm health` rewrites these commands to `pm history-repair --all` in the
     // per-check remediation_map when more than one stream is drifted.
@@ -335,6 +346,16 @@ export const REMEDIATION_REGISTRY = Object.freeze([
         command: 'pm update <id> --replace-tests --test "command=<corrected-command>" [--test ...]',
         summary: "Correct the stale pm-ID inside the item's linked test command (the check scans tests[].command, not the body). --replace-tests overwrites the entire tests list, so re-include the item's other linked tests in the same call.",
     },
+    {
+        code: "validate_format_version_outdated_items",
+        command: "pm validate --verbose-diagnostics",
+        summary: "One or more items predate the current storage format version; a pm storage migration rewrites them. Use --verbose-diagnostics to list the affected items.",
+    },
+    {
+        code: "validate_format_version_ahead_items",
+        command: "npm install -g @unbrained/pm-cli@latest",
+        summary: "One or more items were written by a newer pm format version than this runtime supports; upgrade pm to read and validate them safely.",
+    },
 ]);
 /**
  * Resolve the remediation entry for a warning token, or `undefined` when no
@@ -391,4 +412,4 @@ export function buildRemediationCommands(warnings) {
     return Object.values(buildRemediationMap(warnings));
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=18ec090a-cfc4-5acf-90b6-7e6fade40d8d
+//# debugId=6700669e-bb33-5b85-a194-73e559d13abd

package/dist/core/diagnostics/remediation.js.map

@@ -1 +1 @@
-{"version":3,"file":"remediation.js","sources":["core/diagnostics/remediation.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Shared machine-executable remediation registry.\n *\n * `pm health` and `pm validate` both emit stable, colon-delimited warning tokens\n * (for example `history_drift_missing_stream:pm-abcd` or\n * `validate_resolution_missing_fields:3`). Agents that gate on these commands\n * previously had to hardcode the mapping from a warning code to the `pm` command\n * that fixes it. This module is the single source of truth for that mapping so\n * `pm health --json` (per-check `remediation_map`) and `pm validate --fix-hints`\n * (per-check `fix_hints`) can both surface executable remediation without any\n * duplicated, drift-prone lookup tables.\n *\n * Semantics of {@link RemediationEntry.command}: the suggested next `pm` command\n * an operator/agent should run to resolve findings with that code. Per-item\n * findings use an `<id>` placeholder (callers that have the concrete id may\n * substitute it); findings whose only fix is a manual file edit point at the\n * most useful diagnostic/repair command and describe the manual step in\n * {@link RemediationEntry.summary}.\n */\n\n/** Maps a stable diagnostic warning code to the command and summary that resolve it. */\nexport interface RemediationEntry {\n  /**\n   * Stable warning-code prefix this entry resolves. A warning matches when it\n   * equals this code or begins with `<code>:`. Registry codes are mutually\n   * exclusive under that colon-boundary rule (no code is a `:`-delimited prefix\n   * of another — e.g. `settings:id_prefix_empty` is distinct from a bare\n   * `settings`, which is intentionally not registered), so `resolveRemediation`\n   * uses first-match with no ordering dependency.\n   */\n  readonly code: string;\n  /** Executable `pm` command (or imperative) that resolves the finding. May contain an `<id>` placeholder. */\n  readonly command: string;\n  /** One-line description of what the command does / which manual step it covers. */\n  readonly summary: string;\n}\n\n/**\n * Registry of every non-extension `pm health` / `pm validate` warning code and\n * its remediation. Extension findings keep their richer, contextual\n * `details.triage.remediation` produced by the extension health triage and are\n * intentionally excluded here (see pm-0hnu: \"all non-extension checks\").\n */\nexport const REMEDIATION_REGISTRY: readonly RemediationEntry[] = Object.freeze([\n  // --- pm health: directories ---\n  {\n    code: \"missing_directory\",\n    command: \"pm init\",\n    summary: \"Recreate missing tracker directories (pm init is idempotent and restores the scaffold).\",\n  },\n  // --- pm health: settings (read/parse) ---\n  {\n    code: \"settings_read_invalid_json\",\n    command: \"pm config list --json\",\n    summary:\n      \"settings.json is not valid JSON and pm fell back to defaults; fix the syntax error in the reported path, then re-run.\",\n  },\n  {\n    code: \"settings_read_invalid_schema\",\n    command: \"pm config list --json\",\n    summary:\n      \"settings.json failed schema validation and pm fell back to defaults; correct the reported key in the file, then re-run.\",\n  },\n  {\n    code: \"settings_read_merge_failed\",\n    command: \"pm config list --json\",\n    summary: \"Global/project settings could not be merged; reconcile the conflicting keys in the reported settings files.\",\n  },\n  // --- pm health: settings_values ---\n  {\n    code: \"settings:id_prefix_empty\",\n    command: \"pm config list --json\",\n    summary: 'id_prefix is empty; set a non-empty \"id_prefix\" in settings.json so generated item ids are well-formed.',\n  },\n  {\n    code: \"settings:locks_ttl_non_positive\",\n    command: \"pm config list --json\",\n    summary: 'locks.ttl_seconds must be positive; set a positive \"locks.ttl_seconds\" in settings.json.',\n  },\n  // --- pm health: telemetry (advisory) ---\n  {\n    code: \"telemetry_state_invalid_json\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Local telemetry state file is corrupt; pm recreates it on the next flush. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_invalid_rows\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry queue has unparseable rows; they are skipped on the next flush. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_pending\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Telemetry events are queued; they flush automatically on the next reachable command. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_high_retries\",\n    command: \"pm telemetry flush\",\n    summary:\n      \"Some queued telemetry events are near retry exhaustion; flush now and verify endpoint reachability before entries are dropped.\",\n  },\n  {\n    code: \"telemetry_endpoint_probe_failed\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry endpoint is unreachable; events stay queued until it recovers. Advisory only.\",\n  },\n  {\n    code: \"telemetry_endpoint_probe_http_status\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry endpoint returned a non-success status; events stay queued until it recovers. Advisory only.\",\n  },\n  {\n    code: \"telemetry_schema_version_behind\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Client schema is behind server; upgrade pm-cli to emit the latest event shape.\",\n  },\n  {\n    code: \"telemetry_otel_export_failing\",\n    command: \"pm health --check-telemetry\",\n    summary:\n      \"OTLP trace spans are queued but the traces endpoint export is failing; spans retry automatically on the next reachable command, or set PM_TELEMETRY_OTEL_DISABLED=1 to skip OTLP export. Advisory only.\",\n  },\n  // --- pm health: integrity ---\n  {\n    code: \"integrity_item_unreadable\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file could not be read; restore or repair the file at the reported path.\",\n  },\n  {\n    code: \"integrity_item_parse_failed\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file failed to parse; fix the malformed front matter at the reported path.\",\n  },\n  {\n    code: \"integrity_item_conflict_marker\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file contains Git conflict markers; resolve the <<<<<<< / >>>>>>> markers at the reported line.\",\n  },\n  {\n    code: \"integrity_history_unreadable\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream could not be read; re-anchor the affected item's history chain.\",\n  },\n  {\n    code: \"integrity_history_invalid_json\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream contains invalid JSON; re-anchor the affected item's history chain.\",\n  },\n  {\n    code: \"integrity_history_conflict_marker\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain.\",\n  },\n  // --- pm health: history_drift ---\n  // `pm health` rewrites these commands to `pm history-repair --all` in the\n  // per-check remediation_map when more than one stream is drifted.\n  {\n    code: \"history_drift_missing_stream\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item has no history stream; re-anchor the chain to rebuild it (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_unreadable_stream\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's history stream is unreadable; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_hash_mismatch\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's content hash no longer matches its history; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_chain_mismatch\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  // --- pm health: storage (history compaction policy) ---\n  {\n    code: \"history_stream_over_compact_threshold\",\n    command: \"pm history-compact <id>\",\n    summary: \"The history stream exceeds the configured compaction threshold; compact it (pm history-compact --all-streams sweeps every over-threshold stream in one pass).\",\n  },\n  // --- pm health: locks ---\n  {\n    code: \"locks_stale_count\",\n    command: \"pm gc --scope locks\",\n    summary:\n      \"Stale item-claim locks (embedded ttl elapsed) can block mutations; sweep them — gc retains active and unparseable locks.\",\n  },\n  {\n    code: \"locks_unreadable\",\n    command: \"pm gc --scope locks --dry-run\",\n    summary:\n      \"Some lock files could not be read; preview the sweep and inspect the unreadable files manually — gc never deletes what it cannot read.\",\n  },\n  // --- pm health: extensions ---\n  // Most extension findings keep their richer, contextual\n  // `details.triage.remediation` and are intentionally absent here. The\n  // partial-coverage code is the exception: it is not a per-extension triage\n  // result but a system-wide adoption gap (unmanaged installs the update-health\n  // scan had to skip), so it has a single deterministic fix and belongs in the\n  // shared registry like any other health finding (pm-bdvm).\n  {\n    code: \"extension_update_health_partial_coverage\",\n    command: \"pm extension --adopt-all --project\",\n    summary:\n      \"Update-health coverage is partial because unmanaged extensions were skipped; adopt the existing installs into managed metadata so the update scan covers them (use --global for global-scope extensions, or pm package --adopt-all when working with packages).\",\n  },\n  // --- pm health: vectorization ---\n  {\n    code: \"vectorization_stale_items_remaining\",\n    command: \"pm health --refresh-vectors\",\n    summary: \"Some items have stale embeddings; refresh vectors so semantic search results stay current.\",\n  },\n  {\n    code: \"vectorization_embedding_identity_changed\",\n    command: \"pm reindex --mode semantic\",\n    summary: \"Embedding provider/model changed since the last index; run a semantic reindex to rebuild vectors.\",\n  },\n  // --- pm validate: metadata ---\n  // Note: validate_metadata_missing_author has no entry on purpose. `pm update\n  // --author` sets the mutation/audit author (history), not the item's\n  // `metadata.author` front-matter field, and there is no CLI flag that writes\n  // that field — so emitting a command here would record an audit entry without\n  // clearing the finding. A missing item author must be restored at the source.\n  {\n    code: \"validate_metadata_missing_acceptance_criteria\",\n    command: 'pm update <id> --acceptance-criteria \"<criteria>\"',\n    summary: \"Backfill the missing acceptance criteria on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_estimate\",\n    command: 'pm update <id> --estimate \"<estimate>\"',\n    summary: \"Backfill the missing estimate on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_close_reason\",\n    command: 'pm update <id> --close-reason \"<reason>\"',\n    summary: \"Backfill the missing close reason on the reported closed item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_reviewer\",\n    command: 'pm update <id> --reviewer \"<name>\"',\n    summary: \"Backfill the missing reviewer on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_risk\",\n    command: 'pm update <id> --risk \"<level>\"',\n    summary: \"Backfill the missing risk on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_confidence\",\n    command: 'pm update <id> --confidence \"<level>\"',\n    summary: \"Backfill the missing confidence on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_sprint\",\n    command: 'pm update <id> --sprint \"<sprint>\"',\n    summary: \"Backfill the missing sprint on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_release\",\n    command: 'pm update <id> --release \"<release>\"',\n    summary: \"Backfill the missing release on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_custom_profile_missing_required_fields\",\n    command: 'pm config set metadata-required-fields --criterion \"<field>\"',\n    summary:\n      \"Config-driven finding: the custom metadata profile has no required fields configured and falls back to core, so configure the fields rather than mutating items.\",\n  },\n  {\n    code: \"validate_metadata_duplicate_issue_codes\",\n    command: 'pm update <id> --title \"<distinct title>\"',\n    summary:\n      \"Two or more items share one logical issue code (GH-235); give each a distinct title so the derived code is unique, or close the redundant item with pm close <id> --duplicate-of <canonical-id> (closed-as-duplicate items are excluded from the check).\",\n  },\n  // --- pm validate: resolution ---\n  {\n    code: \"validate_resolution_missing_fields\",\n    command: 'pm update <id> --resolution \"<how resolved>\"',\n    summary: \"Backfill resolution / expected_result / actual_result on the reported closed item(s).\",\n  },\n  // --- pm validate: lifecycle ---\n  {\n    code: \"validate_lifecycle_active_closure_like_metadata\",\n    command: \"pm update <id> --unset <closure-like-field>\",\n    summary:\n      \"Clear the closure-like field the validator flags on this active item — the detail row names it (resolution / actual-result / blocked-reason) — or close the item if it is actually done.\",\n  },\n  {\n    code: \"validate_lifecycle_active_terminal_parent\",\n    command: \"pm update <id> --parent <active-parent-id>\",\n    summary: \"Reopen the terminal parent or move the active child under a non-terminal parent.\",\n  },\n  {\n    code: \"validate_lifecycle_stale_blockers\",\n    command: \"pm update <id> --unset blocked-by --unset blocked-reason\",\n    summary:\n      \"Resolve the stale blocker the validator flags: clear blocked-by/blocked-reason when they linger on a non-blocked item or report a resolved blocker; if instead a blocked item is missing blocker context, add the context or move it out of a blocked status.\",\n  },\n  {\n    code: \"validate_lifecycle_dependency_cycles_error\",\n    command: \"pm update <id> --dep-remove <dep-id>\",\n    summary: \"Break the dependency cycle by removing one edge from the reported cycle.\",\n  },\n  {\n    code: \"validate_lifecycle_dependency_cycles\",\n    command: \"pm update <id> --dep-remove <dep-id>\",\n    summary: \"Break the dependency cycle by removing one edge from the reported cycle.\",\n  },\n  {\n    code: \"validate_hierarchy_parent_cycle_error\",\n    command: \"pm update <id> --parent <other-id>\",\n    summary:\n      \"Break the parent-hierarchy cycle by reparenting one item in the reported cycle to a non-cyclic parent (or clear it with pm update <id> --unset parent).\",\n  },\n  {\n    code: \"validate_hierarchy_parent_cycle\",\n    command: \"pm update <id> --parent <other-id>\",\n    summary:\n      \"Break the parent-hierarchy cycle by reparenting one item in the reported cycle to a non-cyclic parent (or clear it with pm update <id> --unset parent).\",\n  },\n  // --- pm validate: files ---\n  {\n    code: \"validate_files_missing_linked_paths\",\n    command: \"pm <files|docs> <id> --remove <path>\",\n    summary:\n      \"The check spans both item.files and item.docs under one code: restore the missing linked artifact, or unlink it with pm files (linked file) or pm docs (linked doc).\",\n  },\n  {\n    code: \"validate_files_orphaned_paths\",\n    command: \"pm <files|docs> <id> --add <path>\",\n    summary:\n      \"Link the orphaned artifact with pm files (file) or pm docs (doc), or remove it from the workspace.\",\n  },\n  {\n    code: \"validate_files_tracked_all_strict_forces_pm_internals\",\n    command: \"pm validate --check-files --include-pm-internals\",\n    summary: \"tracked-all-strict scan flagged pm internals; re-run with --include-pm-internals or a softer --scan-mode.\",\n  },\n  // --- pm validate: history_drift ---\n  {\n    code: \"validate_history_drift_missing_streams\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items missing a history stream.\",\n  },\n  {\n    code: \"validate_history_drift_unreadable_streams\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items with an unreadable history stream.\",\n  },\n  {\n    code: \"validate_history_drift_hash_mismatches\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items whose content hash drifted.\",\n  },\n  {\n    code: \"validate_history_drift_chain_mismatches\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items with a broken history chain.\",\n  },\n  // --- pm validate: command_references ---\n  {\n    code: \"validate_command_references_stale_pm_ids\",\n    command: 'pm update <id> --replace-tests --test \"command=<corrected-command>\" [--test ...]',\n    summary:\n      \"Correct the stale pm-ID inside the item's linked test command (the check scans tests[].command, not the body). --replace-tests overwrites the entire tests list, so re-include the item's other linked tests in the same call.\",\n  },\n]);\n\n/**\n * Resolve the remediation entry for a warning token, or `undefined` when no\n * entry is registered. A warning matches an entry when it equals the entry code\n * or begins with `<code>:` (the colon boundary keeps sibling codes such as\n * `validate_lifecycle_dependency_cycles` and\n * `validate_lifecycle_dependency_cycles_error` disjoint).\n *\n * First match is intentional and correct: registry codes are mutually exclusive\n * under the colon-boundary rule, so at most one entry can ever match a warning\n * and order is irrelevant. That invariant is enforced by a test (see\n * remediation-registry.spec.ts \"keeps every registry code mutually exclusive\"),\n * which is why this stays a simple linear scan rather than a longest-prefix\n * search — a longest-prefix tie-break is unreachable with disjoint codes.\n *\n * Accepts unknown input defensively (this is an exported helper SDK consumers\n * may call from untyped JS): a non-string `warning` resolves to `undefined`.\n */\nexport function resolveRemediation(warning: string): RemediationEntry | undefined {\n  if (typeof warning !== \"string\") {\n    return undefined;\n  }\n  const normalized = warning.trim();\n  for (const entry of REMEDIATION_REGISTRY) {\n    if (normalized === entry.code || normalized.startsWith(`${entry.code}:`)) {\n      return entry;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Build a compact `remediation_map` (code -> command) for a set of warning\n * tokens. First match wins per code; unknown codes are skipped. Used by\n * `pm health --json` per-check details and as the source of deduped executable\n * commands for `pm validate --fix-hints`.\n */\nexport function buildRemediationMap(warnings: Iterable<string>): Record<string, string> {\n  const map: Record<string, string> = {};\n  for (const warning of warnings) {\n    const entry = resolveRemediation(warning);\n    if (entry !== undefined && !Object.prototype.hasOwnProperty.call(map, entry.code)) {\n      map[entry.code] = entry.command;\n    }\n  }\n  return map;\n}\n\n/**\n * Build a deduped, ordered list of executable remediation commands for a set of\n * warning tokens (one command per distinct matched code). Used by\n * `pm validate --fix-hints` for checks that do not already emit per-row\n * remediation commands.\n */\nexport function buildRemediationCommands(warnings: Iterable<string>): string[] {\n  return Object.values(buildRemediationMap(warnings));\n}\n"],"names":[],"mappings":"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","debugId":"18ec090a-cfc4-5acf-90b6-7e6fade40d8d"}
+{"version":3,"file":"remediation.js","sources":["core/diagnostics/remediation.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Shared machine-executable remediation registry.\n *\n * `pm health` and `pm validate` both emit stable, colon-delimited warning tokens\n * (for example `history_drift_missing_stream:pm-abcd` or\n * `validate_resolution_missing_fields:3`). Agents that gate on these commands\n * previously had to hardcode the mapping from a warning code to the `pm` command\n * that fixes it. This module is the single source of truth for that mapping so\n * `pm health --json` (per-check `remediation_map`) and `pm validate --fix-hints`\n * (per-check `fix_hints`) can both surface executable remediation without any\n * duplicated, drift-prone lookup tables.\n *\n * Semantics of {@link RemediationEntry.command}: the suggested next `pm` command\n * an operator/agent should run to resolve findings with that code. Per-item\n * findings use an `<id>` placeholder (callers that have the concrete id may\n * substitute it); findings whose only fix is a manual file edit point at the\n * most useful diagnostic/repair command and describe the manual step in\n * {@link RemediationEntry.summary}.\n */\n\n/** Maps a stable diagnostic warning code to the command and summary that resolve it. */\nexport interface RemediationEntry {\n  /**\n   * Stable warning-code prefix this entry resolves. A warning matches when it\n   * equals this code or begins with `<code>:`. Registry codes are mutually\n   * exclusive under that colon-boundary rule (no code is a `:`-delimited prefix\n   * of another — e.g. `settings:id_prefix_empty` is distinct from a bare\n   * `settings`, which is intentionally not registered), so `resolveRemediation`\n   * uses first-match with no ordering dependency.\n   */\n  readonly code: string;\n  /** Executable `pm` command (or imperative) that resolves the finding. May contain an `<id>` placeholder. */\n  readonly command: string;\n  /** One-line description of what the command does / which manual step it covers. */\n  readonly summary: string;\n}\n\n/**\n * Registry of every non-extension `pm health` / `pm validate` warning code and\n * its remediation. Extension findings keep their richer, contextual\n * `details.triage.remediation` produced by the extension health triage and are\n * intentionally excluded here (see pm-0hnu: \"all non-extension checks\").\n */\nexport const REMEDIATION_REGISTRY: readonly RemediationEntry[] = Object.freeze([\n  // --- pm health: directories ---\n  {\n    code: \"missing_directory\",\n    command: \"pm init\",\n    summary: \"Recreate missing tracker directories (pm init is idempotent and restores the scaffold).\",\n  },\n  // --- pm health: settings (read/parse) ---\n  {\n    code: \"settings_read_invalid_json\",\n    command: \"pm config list --json\",\n    summary:\n      \"settings.json is not valid JSON and pm fell back to defaults; fix the syntax error in the reported path, then re-run.\",\n  },\n  {\n    code: \"settings_read_invalid_schema\",\n    command: \"pm config list --json\",\n    summary:\n      \"settings.json failed schema validation and pm fell back to defaults; correct the reported key in the file, then re-run.\",\n  },\n  {\n    code: \"settings_read_merge_failed\",\n    command: \"pm config list --json\",\n    summary: \"Global/project settings could not be merged; reconcile the conflicting keys in the reported settings files.\",\n  },\n  // --- pm health: settings_values ---\n  {\n    code: \"settings:id_prefix_empty\",\n    command: \"pm config list --json\",\n    summary: 'id_prefix is empty; set a non-empty \"id_prefix\" in settings.json so generated item ids are well-formed.',\n  },\n  {\n    code: \"settings:locks_ttl_non_positive\",\n    command: \"pm config list --json\",\n    summary: 'locks.ttl_seconds must be positive; set a positive \"locks.ttl_seconds\" in settings.json.',\n  },\n  // --- pm health: telemetry (advisory) ---\n  {\n    code: \"telemetry_state_invalid_json\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Local telemetry state file is corrupt; pm recreates it on the next flush. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_invalid_rows\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry queue has unparseable rows; they are skipped on the next flush. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_pending\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Telemetry events are queued; they flush automatically on the next reachable command. Advisory only.\",\n  },\n  {\n    code: \"telemetry_queue_high_retries\",\n    command: \"pm telemetry flush\",\n    summary:\n      \"Some queued telemetry events are near retry exhaustion; flush now and verify endpoint reachability before entries are dropped.\",\n  },\n  {\n    code: \"telemetry_endpoint_probe_failed\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry endpoint is unreachable; events stay queued until it recovers. Advisory only.\",\n  },\n  {\n    code: \"telemetry_endpoint_probe_http_status\",\n    command: \"pm health --check-telemetry\",\n    summary: \"The telemetry endpoint returned a non-success status; events stay queued until it recovers. Advisory only.\",\n  },\n  {\n    code: \"telemetry_schema_version_behind\",\n    command: \"pm health --check-telemetry\",\n    summary: \"Client schema is behind server; upgrade pm-cli to emit the latest event shape.\",\n  },\n  {\n    code: \"telemetry_otel_export_failing\",\n    command: \"pm health --check-telemetry\",\n    summary:\n      \"OTLP trace spans are queued but the traces endpoint export is failing; spans retry automatically on the next reachable command, or set PM_TELEMETRY_OTEL_DISABLED=1 to skip OTLP export. Advisory only.\",\n  },\n  // --- pm health: integrity ---\n  {\n    code: \"integrity_item_unreadable\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file could not be read; restore or repair the file at the reported path.\",\n  },\n  {\n    code: \"integrity_item_parse_failed\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file failed to parse; fix the malformed front matter at the reported path.\",\n  },\n  {\n    code: \"integrity_item_conflict_marker\",\n    command: \"pm validate --check-files --verbose-diagnostics\",\n    summary: \"An item file contains Git conflict markers; resolve the <<<<<<< / >>>>>>> markers at the reported line.\",\n  },\n  {\n    code: \"integrity_history_unreadable\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream could not be read; re-anchor the affected item's history chain.\",\n  },\n  {\n    code: \"integrity_history_invalid_json\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream contains invalid JSON; re-anchor the affected item's history chain.\",\n  },\n  {\n    code: \"integrity_history_conflict_marker\",\n    command: \"pm history-repair <id>\",\n    summary: \"A history stream contains Git conflict markers; resolve the markers, then re-anchor the chain.\",\n  },\n  // --- pm health (integrity) + pm validate (format_version): item format version ---\n  {\n    code: \"integrity_item_outdated_format_version\",\n    command: \"pm validate --verbose-diagnostics\",\n    summary: \"An item predates the current storage format version; a pm storage migration rewrites it. Use --verbose-diagnostics to list the affected items.\",\n  },\n  {\n    code: \"integrity_item_ahead_format_version\",\n    command: \"npm install -g @unbrained/pm-cli@latest\",\n    summary: \"An item was written by a newer pm format version than this runtime supports; upgrade pm to read and validate it safely.\",\n  },\n  // --- pm health: history_drift ---\n  // `pm health` rewrites these commands to `pm history-repair --all` in the\n  // per-check remediation_map when more than one stream is drifted.\n  {\n    code: \"history_drift_missing_stream\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item has no history stream; re-anchor the chain to rebuild it (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_unreadable_stream\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's history stream is unreadable; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_hash_mismatch\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's content hash no longer matches its history; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  {\n    code: \"history_drift_chain_mismatch\",\n    command: \"pm history-repair <id>\",\n    summary: \"The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass).\",\n  },\n  // --- pm health: storage (history compaction policy) ---\n  {\n    code: \"history_stream_over_compact_threshold\",\n    command: \"pm history-compact <id>\",\n    summary: \"The history stream exceeds the configured compaction threshold; compact it (pm history-compact --all-streams sweeps every over-threshold stream in one pass).\",\n  },\n  // --- pm health: locks ---\n  {\n    code: \"locks_stale_count\",\n    command: \"pm gc --scope locks\",\n    summary:\n      \"Stale item-claim locks (embedded ttl elapsed) can block mutations; sweep them — gc retains active and unparseable locks.\",\n  },\n  {\n    code: \"locks_unreadable\",\n    command: \"pm gc --scope locks --dry-run\",\n    summary:\n      \"Some lock files could not be read; preview the sweep and inspect the unreadable files manually — gc never deletes what it cannot read.\",\n  },\n  // --- pm health: extensions ---\n  // Most extension findings keep their richer, contextual\n  // `details.triage.remediation` and are intentionally absent here. The\n  // partial-coverage code is the exception: it is not a per-extension triage\n  // result but a system-wide adoption gap (unmanaged installs the update-health\n  // scan had to skip), so it has a single deterministic fix and belongs in the\n  // shared registry like any other health finding (pm-bdvm).\n  {\n    code: \"extension_update_health_partial_coverage\",\n    command: \"pm extension --adopt-all --project\",\n    summary:\n      \"Update-health coverage is partial because unmanaged extensions were skipped; adopt the existing installs into managed metadata so the update scan covers them (use --global for global-scope extensions, or pm package --adopt-all when working with packages).\",\n  },\n  // --- pm health: vectorization ---\n  {\n    code: \"vectorization_stale_items_remaining\",\n    command: \"pm health --refresh-vectors\",\n    summary: \"Some items have stale embeddings; refresh vectors so semantic search results stay current.\",\n  },\n  {\n    code: \"vectorization_embedding_identity_changed\",\n    command: \"pm reindex --mode semantic\",\n    summary: \"Embedding provider/model changed since the last index; run a semantic reindex to rebuild vectors.\",\n  },\n  // --- pm validate: metadata ---\n  // Note: validate_metadata_missing_author has no entry on purpose. `pm update\n  // --author` sets the mutation/audit author (history), not the item's\n  // `metadata.author` front-matter field, and there is no CLI flag that writes\n  // that field — so emitting a command here would record an audit entry without\n  // clearing the finding. A missing item author must be restored at the source.\n  {\n    code: \"validate_metadata_missing_acceptance_criteria\",\n    command: 'pm update <id> --acceptance-criteria \"<criteria>\"',\n    summary: \"Backfill the missing acceptance criteria on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_estimate\",\n    command: 'pm update <id> --estimate \"<estimate>\"',\n    summary: \"Backfill the missing estimate on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_close_reason\",\n    command: 'pm update <id> --close-reason \"<reason>\"',\n    summary: \"Backfill the missing close reason on the reported closed item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_reviewer\",\n    command: 'pm update <id> --reviewer \"<name>\"',\n    summary: \"Backfill the missing reviewer on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_risk\",\n    command: 'pm update <id> --risk \"<level>\"',\n    summary: \"Backfill the missing risk on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_confidence\",\n    command: 'pm update <id> --confidence \"<level>\"',\n    summary: \"Backfill the missing confidence on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_sprint\",\n    command: 'pm update <id> --sprint \"<sprint>\"',\n    summary: \"Backfill the missing sprint on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_missing_release\",\n    command: 'pm update <id> --release \"<release>\"',\n    summary: \"Backfill the missing release on the reported item(s).\",\n  },\n  {\n    code: \"validate_metadata_custom_profile_missing_required_fields\",\n    command: 'pm config set metadata-required-fields --criterion \"<field>\"',\n    summary:\n      \"Config-driven finding: the custom metadata profile has no required fields configured and falls back to core, so configure the fields rather than mutating items.\",\n  },\n  {\n    code: \"validate_metadata_duplicate_issue_codes\",\n    command: 'pm update <id> --title \"<distinct title>\"',\n    summary:\n      \"Two or more items share one logical issue code (GH-235); give each a distinct title so the derived code is unique, or close the redundant item with pm close <id> --duplicate-of <canonical-id> (closed-as-duplicate items are excluded from the check).\",\n  },\n  // --- pm validate: resolution ---\n  {\n    code: \"validate_resolution_missing_fields\",\n    command: 'pm update <id> --resolution \"<how resolved>\"',\n    summary: \"Backfill resolution / expected_result / actual_result on the reported closed item(s).\",\n  },\n  // --- pm validate: lifecycle ---\n  {\n    code: \"validate_lifecycle_active_closure_like_metadata\",\n    command: \"pm update <id> --unset <closure-like-field>\",\n    summary:\n      \"Clear the closure-like field the validator flags on this active item — the detail row names it (resolution / actual-result / blocked-reason) — or close the item if it is actually done.\",\n  },\n  {\n    code: \"validate_lifecycle_active_terminal_parent\",\n    command: \"pm update <id> --parent <active-parent-id>\",\n    summary: \"Reopen the terminal parent or move the active child under a non-terminal parent.\",\n  },\n  {\n    code: \"validate_lifecycle_stale_blockers\",\n    command: \"pm update <id> --unset blocked-by --unset blocked-reason\",\n    summary:\n      \"Resolve the stale blocker the validator flags: clear blocked-by/blocked-reason when they linger on a non-blocked item or report a resolved blocker; if instead a blocked item is missing blocker context, add the context or move it out of a blocked status.\",\n  },\n  {\n    code: \"validate_lifecycle_dependency_cycles_error\",\n    command: \"pm update <id> --dep-remove <dep-id>\",\n    summary: \"Break the dependency cycle by removing one edge from the reported cycle.\",\n  },\n  {\n    code: \"validate_lifecycle_dependency_cycles\",\n    command: \"pm update <id> --dep-remove <dep-id>\",\n    summary: \"Break the dependency cycle by removing one edge from the reported cycle.\",\n  },\n  {\n    code: \"validate_hierarchy_parent_cycle_error\",\n    command: \"pm update <id> --parent <other-id>\",\n    summary:\n      \"Break the parent-hierarchy cycle by reparenting one item in the reported cycle to a non-cyclic parent (or clear it with pm update <id> --unset parent).\",\n  },\n  {\n    code: \"validate_hierarchy_parent_cycle\",\n    command: \"pm update <id> --parent <other-id>\",\n    summary:\n      \"Break the parent-hierarchy cycle by reparenting one item in the reported cycle to a non-cyclic parent (or clear it with pm update <id> --unset parent).\",\n  },\n  // --- pm validate: files ---\n  {\n    code: \"validate_files_missing_linked_paths\",\n    command: \"pm <files|docs> <id> --remove <path>\",\n    summary:\n      \"The check spans both item.files and item.docs under one code: restore the missing linked artifact, or unlink it with pm files (linked file) or pm docs (linked doc).\",\n  },\n  {\n    code: \"validate_files_orphaned_paths\",\n    command: \"pm <files|docs> <id> --add <path>\",\n    summary:\n      \"Link the orphaned artifact with pm files (file) or pm docs (doc), or remove it from the workspace.\",\n  },\n  {\n    code: \"validate_files_tracked_all_strict_forces_pm_internals\",\n    command: \"pm validate --check-files --include-pm-internals\",\n    summary: \"tracked-all-strict scan flagged pm internals; re-run with --include-pm-internals or a softer --scan-mode.\",\n  },\n  // --- pm validate: history_drift ---\n  {\n    code: \"validate_history_drift_missing_streams\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items missing a history stream.\",\n  },\n  {\n    code: \"validate_history_drift_unreadable_streams\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items with an unreadable history stream.\",\n  },\n  {\n    code: \"validate_history_drift_hash_mismatches\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items whose content hash drifted.\",\n  },\n  {\n    code: \"validate_history_drift_chain_mismatches\",\n    command: \"pm history-repair <id>\",\n    summary: \"Re-anchor the history chains of the items with a broken history chain.\",\n  },\n  // --- pm validate: command_references ---\n  {\n    code: \"validate_command_references_stale_pm_ids\",\n    command: 'pm update <id> --replace-tests --test \"command=<corrected-command>\" [--test ...]',\n    summary:\n      \"Correct the stale pm-ID inside the item's linked test command (the check scans tests[].command, not the body). --replace-tests overwrites the entire tests list, so re-include the item's other linked tests in the same call.\",\n  },\n  {\n    code: \"validate_format_version_outdated_items\",\n    command: \"pm validate --verbose-diagnostics\",\n    summary: \"One or more items predate the current storage format version; a pm storage migration rewrites them. Use --verbose-diagnostics to list the affected items.\",\n  },\n  {\n    code: \"validate_format_version_ahead_items\",\n    command: \"npm install -g @unbrained/pm-cli@latest\",\n    summary: \"One or more items were written by a newer pm format version than this runtime supports; upgrade pm to read and validate them safely.\",\n  },\n]);\n\n/**\n * Resolve the remediation entry for a warning token, or `undefined` when no\n * entry is registered. A warning matches an entry when it equals the entry code\n * or begins with `<code>:` (the colon boundary keeps sibling codes such as\n * `validate_lifecycle_dependency_cycles` and\n * `validate_lifecycle_dependency_cycles_error` disjoint).\n *\n * First match is intentional and correct: registry codes are mutually exclusive\n * under the colon-boundary rule, so at most one entry can ever match a warning\n * and order is irrelevant. That invariant is enforced by a test (see\n * remediation-registry.spec.ts \"keeps every registry code mutually exclusive\"),\n * which is why this stays a simple linear scan rather than a longest-prefix\n * search — a longest-prefix tie-break is unreachable with disjoint codes.\n *\n * Accepts unknown input defensively (this is an exported helper SDK consumers\n * may call from untyped JS): a non-string `warning` resolves to `undefined`.\n */\nexport function resolveRemediation(warning: string): RemediationEntry | undefined {\n  if (typeof warning !== \"string\") {\n    return undefined;\n  }\n  const normalized = warning.trim();\n  for (const entry of REMEDIATION_REGISTRY) {\n    if (normalized === entry.code || normalized.startsWith(`${entry.code}:`)) {\n      return entry;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Build a compact `remediation_map` (code -> command) for a set of warning\n * tokens. First match wins per code; unknown codes are skipped. Used by\n * `pm health --json` per-check details and as the source of deduped executable\n * commands for `pm validate --fix-hints`.\n */\nexport function buildRemediationMap(warnings: Iterable<string>): Record<string, string> {\n  const map: Record<string, string> = {};\n  for (const warning of warnings) {\n    const entry = resolveRemediation(warning);\n    if (entry !== undefined && !Object.prototype.hasOwnProperty.call(map, entry.code)) {\n      map[entry.code] = entry.command;\n    }\n  }\n  return map;\n}\n\n/**\n * Build a deduped, ordered list of executable remediation commands for a set of\n * warning tokens (one command per distinct matched code). Used by\n * `pm validate --fix-hints` for checks that do not already emit per-row\n * remediation commands.\n */\nexport function buildRemediationCommands(warnings: Iterable<string>): string[] {\n  return Object.values(buildRemediationMap(warnings));\n}\n"],"names":[],"mappings":"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","debugId":"6700669e-bb33-5b85-a194-73e559d13abd"}

package/dist/core/extensions/capability-usage.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module core/extensions/capability-usage
+ *
+ * Reconciles the capabilities an extension manifest *declares* against the
+ * capabilities it actually *exercises* during activation.
+ *
+ * The loader already enforces the opposite direction — registering a surface
+ * whose capability is absent from `manifest.capabilities` throws an
+ * `extension_capability_missing` activation failure. This module closes the
+ * least-privilege loop by detecting capabilities a manifest declares but never
+ * registers against, so package authors can trim manifests to the minimum
+ * grant. Every declared-but-unused capability is an over-broad permission a
+ * reviewer would otherwise have to catch by hand.
+ */
+import type { ExtensionActivationResult, ExtensionCapability, ExtensionLayer } from "./extension-types.js";
+/**
+ * Canonical map from each known extension capability to the human-readable
+ * registration surfaces that exercise it.
+ *
+ * The `satisfies Record<ExtensionCapability, ...>` guard makes this exhaustive
+ * at compile time: adding a capability to `KNOWN_EXTENSION_CAPABILITIES`
+ * without giving it a registration surface here fails the build, which prevents
+ * a capability that has *no* surface from being perpetually flagged as unused.
+ */
+export declare const EXTENSION_CAPABILITY_REGISTRATION_SURFACES: {
+    readonly commands: readonly ["registerCommand", "command override", "command handler"];
+    readonly renderers: readonly ["registerRenderer"];
+    readonly hooks: readonly ["hooks.beforeCommand", "hooks.afterCommand", "hooks.onWrite", "hooks.onRead", "hooks.onIndex"];
+    readonly schema: readonly ["registerFlags", "registerItemFields", "registerItemTypes", "registerMigration"];
+    readonly importers: readonly ["registerImporter", "registerExporter"];
+    readonly search: readonly ["registerSearchProvider", "registerVectorStoreAdapter"];
+    readonly parser: readonly ["registerParser"];
+    readonly preflight: readonly ["registerPreflight"];
+    readonly services: readonly ["registerService"];
+};
+/**
+ * Per-extension reconciliation of declared versus exercised capabilities.
+ */
+export interface ExtensionCapabilityUsageReconciliation {
+    /** Layer the extension was loaded from (`global` or `project`). */
+    layer: ExtensionLayer;
+    /** Extension name as it appears in the manifest. */
+    name: string;
+    /** Known capabilities declared in the manifest, sorted and de-duplicated. */
+    declared: ExtensionCapability[];
+    /** Known capabilities the extension actually registered against, sorted. */
+    used: ExtensionCapability[];
+    /** Declared capabilities with no matching registration (least-privilege gap). */
+    unused: ExtensionCapability[];
+}
+/**
+ * Options for {@link collectUsedExtensionCapabilities}.
+ */
+export interface CollectUsedExtensionCapabilitiesOptions {
+    /**
+     * Restrict the result to a single extension by name. Names are matched
+     * case-insensitively after trimming. Omit to union across every extension in
+     * the activation result.
+     */
+    extensionName?: string;
+}
+/**
+ * Collect the known capabilities exercised across an activation result.
+ *
+ * Without {@link CollectUsedExtensionCapabilitiesOptions.extensionName} the
+ * result unions every extension in the activation; with it, only the matching
+ * extension's registrations contribute (across both layers).
+ */
+export declare function collectUsedExtensionCapabilities(activation: ExtensionActivationResult, options?: CollectUsedExtensionCapabilitiesOptions): ExtensionCapability[];
+/**
+ * Reconcile each loaded extension's declared capabilities against what it
+ * exercised during activation.
+ *
+ * Extensions with no known declared capabilities are skipped — there is nothing
+ * to reconcile. The returned entries preserve every reconcilable extension even
+ * when `unused` is empty so callers can report fully-minimal manifests too.
+ */
+export declare function reconcileExtensionCapabilityUsage(loaded: ReadonlyArray<{
+    layer: ExtensionLayer;
+    name: string;
+    capabilities?: readonly string[];
+}>, activation: ExtensionActivationResult): ExtensionCapabilityUsageReconciliation[];

package/dist/core/extensions/capability-usage.js

@@ -0,0 +1,133 @@
+
+!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]="b74f7cd3-95ed-5473-a724-d3afb634a68b")}catch(e){}}();
+import { normalizeKnownExtensionCapability } from "./extension-capability-aliases.js";
+/**
+ * Canonical map from each known extension capability to the human-readable
+ * registration surfaces that exercise it.
+ *
+ * The `satisfies Record<ExtensionCapability, ...>` guard makes this exhaustive
+ * at compile time: adding a capability to `KNOWN_EXTENSION_CAPABILITIES`
+ * without giving it a registration surface here fails the build, which prevents
+ * a capability that has *no* surface from being perpetually flagged as unused.
+ */
+export const EXTENSION_CAPABILITY_REGISTRATION_SURFACES = {
+    commands: ["registerCommand", "command override", "command handler"],
+    renderers: ["registerRenderer"],
+    hooks: ["hooks.beforeCommand", "hooks.afterCommand", "hooks.onWrite", "hooks.onRead", "hooks.onIndex"],
+    schema: ["registerFlags", "registerItemFields", "registerItemTypes", "registerMigration"],
+    importers: ["registerImporter", "registerExporter"],
+    search: ["registerSearchProvider", "registerVectorStoreAdapter"],
+    parser: ["registerParser"],
+    preflight: ["registerPreflight"],
+    services: ["registerService"],
+};
+// `layer` is a closed enum (`"global" | "project"`) that never contains a
+// colon, so the first colon always separates the layer from the (possibly
+// colon-bearing) name — making the key collision-proof without serialization.
+const USAGE_KEY_SEPARATOR = ":";
+function usageKey(layer, name) {
+    return `${layer}${USAGE_KEY_SEPARATOR}${normalizeExtensionName(name)}`;
+}
+function usageKeyName(key) {
+    return key.slice(key.indexOf(USAGE_KEY_SEPARATOR) + 1);
+}
+function normalizeExtensionName(name) {
+    return name.trim().toLowerCase();
+}
+function normalizeDeclaredCapabilities(capabilities) {
+    if (!Array.isArray(capabilities)) {
+        return [];
+    }
+    const known = new Set();
+    for (const capability of capabilities) {
+        // Unknown capabilities are reported by the separate unknown-capability
+        // diagnostic; reconciling them here would double-report a typo as "unused".
+        const normalized = normalizeKnownExtensionCapability(capability);
+        if (normalized !== null) {
+            known.add(normalized);
+        }
+    }
+    return [...known].sort((left, right) => left.localeCompare(right));
+}
+function attributeCapabilityUsage(activation) {
+    const usage = new Map();
+    const record = (entries, capability) => {
+        for (const entry of entries) {
+            const key = usageKey(entry.layer, entry.name);
+            let exercised = usage.get(key);
+            if (exercised === undefined) {
+                exercised = new Set();
+                usage.set(key, exercised);
+            }
+            exercised.add(capability);
+        }
+    };
+    const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;
+    record(registrations.commands, "commands");
+    record(commands.overrides, "commands");
+    record(commands.handlers, "commands");
+    record(registrations.flags, "schema");
+    record(registrations.item_fields, "schema");
+    record(registrations.item_types, "schema");
+    record(registrations.migrations, "schema");
+    record(registrations.importers, "importers");
+    record(registrations.exporters, "importers");
+    record(registrations.search_providers, "search");
+    record(registrations.vector_store_adapters, "search");
+    record(parsers.overrides, "parser");
+    record(preflight.overrides, "preflight");
+    record(services.overrides, "services");
+    record(renderers.overrides, "renderers");
+    record(hooks.beforeCommand, "hooks");
+    record(hooks.afterCommand, "hooks");
+    record(hooks.onWrite, "hooks");
+    record(hooks.onRead, "hooks");
+    record(hooks.onIndex, "hooks");
+    return usage;
+}
+/**
+ * Collect the known capabilities exercised across an activation result.
+ *
+ * Without {@link CollectUsedExtensionCapabilitiesOptions.extensionName} the
+ * result unions every extension in the activation; with it, only the matching
+ * extension's registrations contribute (across both layers).
+ */
+export function collectUsedExtensionCapabilities(activation, options = {}) {
+    const usage = attributeCapabilityUsage(activation);
+    const filter = options.extensionName !== undefined ? normalizeExtensionName(options.extensionName) : null;
+    const used = new Set();
+    for (const [key, capabilities] of usage) {
+        if (filter !== null && usageKeyName(key) !== filter) {
+            continue;
+        }
+        for (const capability of capabilities) {
+            used.add(capability);
+        }
+    }
+    return [...used].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Reconcile each loaded extension's declared capabilities against what it
+ * exercised during activation.
+ *
+ * Extensions with no known declared capabilities are skipped — there is nothing
+ * to reconcile. The returned entries preserve every reconcilable extension even
+ * when `unused` is empty so callers can report fully-minimal manifests too.
+ */
+export function reconcileExtensionCapabilityUsage(loaded, activation) {
+    const usage = attributeCapabilityUsage(activation);
+    const reconciliations = [];
+    for (const extension of loaded) {
+        const declared = normalizeDeclaredCapabilities(extension.capabilities);
+        if (declared.length === 0) {
+            continue;
+        }
+        const exercised = usage.get(usageKey(extension.layer, extension.name)) ?? new Set();
+        const used = [...exercised].sort((left, right) => left.localeCompare(right));
+        const unused = declared.filter((capability) => !exercised.has(capability));
+        reconciliations.push({ layer: extension.layer, name: extension.name, declared, used, unused });
+    }
+    return reconciliations;
+}
+//# sourceMappingURL=capability-usage.js.map
+//# debugId=b74f7cd3-95ed-5473-a724-d3afb634a68b

package/dist/core/extensions/capability-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-usage.js","sources":["core/extensions/capability-usage.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/capability-usage\n *\n * Reconciles the capabilities an extension manifest *declares* against the\n * capabilities it actually *exercises* during activation.\n *\n * The loader already enforces the opposite direction — registering a surface\n * whose capability is absent from `manifest.capabilities` throws an\n * `extension_capability_missing` activation failure. This module closes the\n * least-privilege loop by detecting capabilities a manifest declares but never\n * registers against, so package authors can trim manifests to the minimum\n * grant. Every declared-but-unused capability is an over-broad permission a\n * reviewer would otherwise have to catch by hand.\n */\nimport type { ExtensionActivationResult, ExtensionCapability, ExtensionLayer } from \"./extension-types.js\";\nimport { normalizeKnownExtensionCapability } from \"./extension-capability-aliases.js\";\n\n/**\n * Canonical map from each known extension capability to the human-readable\n * registration surfaces that exercise it.\n *\n * The `satisfies Record<ExtensionCapability, ...>` guard makes this exhaustive\n * at compile time: adding a capability to `KNOWN_EXTENSION_CAPABILITIES`\n * without giving it a registration surface here fails the build, which prevents\n * a capability that has *no* surface from being perpetually flagged as unused.\n */\nexport const EXTENSION_CAPABILITY_REGISTRATION_SURFACES = {\n  commands: [\"registerCommand\", \"command override\", \"command handler\"],\n  renderers: [\"registerRenderer\"],\n  hooks: [\"hooks.beforeCommand\", \"hooks.afterCommand\", \"hooks.onWrite\", \"hooks.onRead\", \"hooks.onIndex\"],\n  schema: [\"registerFlags\", \"registerItemFields\", \"registerItemTypes\", \"registerMigration\"],\n  importers: [\"registerImporter\", \"registerExporter\"],\n  search: [\"registerSearchProvider\", \"registerVectorStoreAdapter\"],\n  parser: [\"registerParser\"],\n  preflight: [\"registerPreflight\"],\n  services: [\"registerService\"],\n} as const satisfies Record<ExtensionCapability, readonly string[]>;\n\n/**\n * Per-extension reconciliation of declared versus exercised capabilities.\n */\nexport interface ExtensionCapabilityUsageReconciliation {\n  /** Layer the extension was loaded from (`global` or `project`). */\n  layer: ExtensionLayer;\n  /** Extension name as it appears in the manifest. */\n  name: string;\n  /** Known capabilities declared in the manifest, sorted and de-duplicated. */\n  declared: ExtensionCapability[];\n  /** Known capabilities the extension actually registered against, sorted. */\n  used: ExtensionCapability[];\n  /** Declared capabilities with no matching registration (least-privilege gap). */\n  unused: ExtensionCapability[];\n}\n\n/**\n * Options for {@link collectUsedExtensionCapabilities}.\n */\nexport interface CollectUsedExtensionCapabilitiesOptions {\n  /**\n   * Restrict the result to a single extension by name. Names are matched\n   * case-insensitively after trimming. Omit to union across every extension in\n   * the activation result.\n   */\n  extensionName?: string;\n}\n\n// `layer` is a closed enum (`\"global\" | \"project\"`) that never contains a\n// colon, so the first colon always separates the layer from the (possibly\n// colon-bearing) name — making the key collision-proof without serialization.\nconst USAGE_KEY_SEPARATOR = \":\";\n\nfunction usageKey(layer: ExtensionLayer, name: string): string {\n  return `${layer}${USAGE_KEY_SEPARATOR}${normalizeExtensionName(name)}`;\n}\n\nfunction usageKeyName(key: string): string {\n  return key.slice(key.indexOf(USAGE_KEY_SEPARATOR) + 1);\n}\n\nfunction normalizeExtensionName(name: string): string {\n  return name.trim().toLowerCase();\n}\n\nfunction normalizeDeclaredCapabilities(capabilities: readonly string[] | undefined): ExtensionCapability[] {\n  if (!Array.isArray(capabilities)) {\n    return [];\n  }\n  const known = new Set<ExtensionCapability>();\n  for (const capability of capabilities) {\n    // Unknown capabilities are reported by the separate unknown-capability\n    // diagnostic; reconciling them here would double-report a typo as \"unused\".\n    const normalized = normalizeKnownExtensionCapability(capability);\n    if (normalized !== null) {\n      known.add(normalized);\n    }\n  }\n  return [...known].sort((left, right) => left.localeCompare(right));\n}\n\nfunction attributeCapabilityUsage(activation: ExtensionActivationResult): Map<string, Set<ExtensionCapability>> {\n  const usage = new Map<string, Set<ExtensionCapability>>();\n  const record = (\n    entries: ReadonlyArray<{ layer: ExtensionLayer; name: string }>,\n    capability: ExtensionCapability,\n  ): void => {\n    for (const entry of entries) {\n      const key = usageKey(entry.layer, entry.name);\n      let exercised = usage.get(key);\n      if (exercised === undefined) {\n        exercised = new Set<ExtensionCapability>();\n        usage.set(key, exercised);\n      }\n      exercised.add(capability);\n    }\n  };\n  const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;\n  record(registrations.commands, \"commands\");\n  record(commands.overrides, \"commands\");\n  record(commands.handlers, \"commands\");\n  record(registrations.flags, \"schema\");\n  record(registrations.item_fields, \"schema\");\n  record(registrations.item_types, \"schema\");\n  record(registrations.migrations, \"schema\");\n  record(registrations.importers, \"importers\");\n  record(registrations.exporters, \"importers\");\n  record(registrations.search_providers, \"search\");\n  record(registrations.vector_store_adapters, \"search\");\n  record(parsers.overrides, \"parser\");\n  record(preflight.overrides, \"preflight\");\n  record(services.overrides, \"services\");\n  record(renderers.overrides, \"renderers\");\n  record(hooks.beforeCommand, \"hooks\");\n  record(hooks.afterCommand, \"hooks\");\n  record(hooks.onWrite, \"hooks\");\n  record(hooks.onRead, \"hooks\");\n  record(hooks.onIndex, \"hooks\");\n  return usage;\n}\n\n/**\n * Collect the known capabilities exercised across an activation result.\n *\n * Without {@link CollectUsedExtensionCapabilitiesOptions.extensionName} the\n * result unions every extension in the activation; with it, only the matching\n * extension's registrations contribute (across both layers).\n */\nexport function collectUsedExtensionCapabilities(\n  activation: ExtensionActivationResult,\n  options: CollectUsedExtensionCapabilitiesOptions = {},\n): ExtensionCapability[] {\n  const usage = attributeCapabilityUsage(activation);\n  const filter = options.extensionName !== undefined ? normalizeExtensionName(options.extensionName) : null;\n  const used = new Set<ExtensionCapability>();\n  for (const [key, capabilities] of usage) {\n    if (filter !== null && usageKeyName(key) !== filter) {\n      continue;\n    }\n    for (const capability of capabilities) {\n      used.add(capability);\n    }\n  }\n  return [...used].sort((left, right) => left.localeCompare(right));\n}\n\n/**\n * Reconcile each loaded extension's declared capabilities against what it\n * exercised during activation.\n *\n * Extensions with no known declared capabilities are skipped — there is nothing\n * to reconcile. The returned entries preserve every reconcilable extension even\n * when `unused` is empty so callers can report fully-minimal manifests too.\n */\nexport function reconcileExtensionCapabilityUsage(\n  loaded: ReadonlyArray<{ layer: ExtensionLayer; name: string; capabilities?: readonly string[] }>,\n  activation: ExtensionActivationResult,\n): ExtensionCapabilityUsageReconciliation[] {\n  const usage = attributeCapabilityUsage(activation);\n  const reconciliations: ExtensionCapabilityUsageReconciliation[] = [];\n  for (const extension of loaded) {\n    const declared = normalizeDeclaredCapabilities(extension.capabilities);\n    if (declared.length === 0) {\n      continue;\n    }\n    const exercised = usage.get(usageKey(extension.layer, extension.name)) ?? new Set<ExtensionCapability>();\n    const used = [...exercised].sort((left, right) => left.localeCompare(right));\n    const unused = declared.filter((capability) => !exercised.has(capability));\n    reconciliations.push({ layer: extension.layer, name: extension.name, declared, used, unused });\n  }\n  return reconciliations;\n}\n"],"names":[],"mappings":"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","debugId":"b74f7cd3-95ed-5473-a724-d3afb634a68b"}

package/dist/core/extensions/extension-capability-aliases.d.ts

@@ -12,6 +12,13 @@ export declare function normalizeNames(values: string[]): string[];
  * Implements check whether known extension capability for the public runtime surface of this module.
  */
 export declare function isKnownExtensionCapability(value: string): value is ExtensionCapability;
+/**
+ * Trim and lower-case a capability token, returning it only when it is a known
+ * canonical capability (otherwise `null`). Shared so capability normalization
+ * and known-capability filtering stay identical across the doctor and the SDK
+ * least-privilege helpers.
+ */
+export declare function normalizeKnownExtensionCapability(value: string): ExtensionCapability | null;
 /**
  * Implements collect unknown extension capabilities for the public runtime surface of this module.
  */

package/dist/core/extensions/extension-capability-aliases.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Extension Capability Aliases.
  */
 
-!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]="0be603c7-ab83-5880-a57f-8140caf82657")}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]="5723464e-1f10-5a39-96a9-787c0052a036")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, } from "./extension-types.js";
 import { levenshteinDistanceWithinLimit } from "../shared/levenshtein.js";
 /**
@@ -19,6 +19,16 @@ export function normalizeNames(values) {
 export function isKnownExtensionCapability(value) {
     return KNOWN_EXTENSION_CAPABILITIES.includes(value);
 }
+/**
+ * Trim and lower-case a capability token, returning it only when it is a known
+ * canonical capability (otherwise `null`). Shared so capability normalization
+ * and known-capability filtering stay identical across the doctor and the SDK
+ * least-privilege helpers.
+ */
+export function normalizeKnownExtensionCapability(value) {
+    const normalized = value.trim().toLowerCase();
+    return isKnownExtensionCapability(normalized) ? normalized : null;
+}
 /**
  * Implements collect unknown extension capabilities for the public runtime surface of this module.
  */
@@ -165,4 +175,4 @@ export function parseLegacyExtensionCapabilityAliasWarning(warning) {
     return parsed;
 }
 //# sourceMappingURL=extension-capability-aliases.js.map
-//# debugId=0be603c7-ab83-5880-a57f-8140caf82657
+//# debugId=5723464e-1f10-5a39-96a9-787c0052a036

package/dist/core/extensions/extension-capability-aliases.js.map

@@ -1 +1 @@
-{"version":3,"file":"extension-capability-aliases.js","sources":["core/extensions/extension-capability-aliases.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/extension-capability-aliases\n *\n * Implements extension runtime contracts and governance for Extension Capability Aliases.\n */\nimport {\n  KNOWN_EXTENSION_CAPABILITIES,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  type ExtensionCapability,\n  type ExtensionLayer,\n  type LegacyExtensionCapabilityAliasMapping,\n  type UnknownExtensionCapabilityWarningDetails,\n} from \"./extension-types.js\";\nimport { levenshteinDistanceWithinLimit } from \"../shared/levenshtein.js\";\n\n/**\n * Implements normalize names for the public runtime surface of this module.\n */\nexport function normalizeNames(values: string[]): string[] {\n  return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((a, b) =>\n    a.localeCompare(b),\n  );\n}\n\n/**\n * Implements check whether known extension capability for the public runtime surface of this module.\n */\nexport function isKnownExtensionCapability(value: string): value is ExtensionCapability {\n  return (KNOWN_EXTENSION_CAPABILITIES as readonly string[]).includes(value);\n}\n\n/**\n * Implements collect unknown extension capabilities for the public runtime surface of this module.\n */\nexport function collectUnknownExtensionCapabilities(capabilities: readonly string[]): string[] {\n  return capabilities.filter((capability) => !isKnownExtensionCapability(capability));\n}\n\n/**\n * Implements resolve legacy extension capability alias for the public runtime surface of this module.\n */\nexport function resolveLegacyExtensionCapabilityAlias(capability: string): ExtensionCapability | null {\n  const normalized = capability.trim().toLowerCase();\n  if (normalized.length === 0) {\n    return null;\n  }\n  return EXTENSION_CAPABILITY_LEGACY_ALIASES[normalized] ?? null;\n}\n\n/**\n * Implements normalize manifest capabilities for the public runtime surface of this module.\n */\nexport function normalizeManifestCapabilities(rawCapabilities: readonly string[]): {\n  capabilities: string[];\n  legacy_aliases: LegacyExtensionCapabilityAliasMapping[];\n} {\n  const normalizedCapabilities = normalizeNames([...rawCapabilities].map((value) => value.toLowerCase()));\n  const remappedCapabilities: string[] = [];\n  const legacyAliases: LegacyExtensionCapabilityAliasMapping[] = [];\n  for (const capability of normalizedCapabilities) {\n    const legacyAliasTarget = resolveLegacyExtensionCapabilityAlias(capability);\n    if (legacyAliasTarget) {\n      remappedCapabilities.push(legacyAliasTarget);\n      legacyAliases.push({\n        alias: capability,\n        target: legacyAliasTarget,\n      });\n      continue;\n    }\n    remappedCapabilities.push(capability);\n  }\n  const dedupedLegacyAliases = [...new Map(legacyAliases.map((entry) => [`${entry.alias}>${entry.target}`, entry])).values()].sort(\n    (left, right) => left.alias.localeCompare(right.alias),\n  );\n  return {\n    capabilities: normalizeNames(remappedCapabilities),\n    legacy_aliases: dedupedLegacyAliases,\n  };\n}\n\n/**\n * Implements suggest known extension capability for the public runtime surface of this module.\n */\nexport function suggestKnownExtensionCapability(capability: string): string | null {\n  const normalized = capability.trim().toLowerCase();\n  if (normalized.length === 0) {\n    return null;\n  }\n  const legacyAlias = resolveLegacyExtensionCapabilityAlias(normalized);\n  if (legacyAlias) {\n    return legacyAlias;\n  }\n  const maxDistance = Math.max(1, Math.floor(normalized.length * 0.34));\n  let bestMatch: string | null = null;\n  let bestDistance = Number.POSITIVE_INFINITY;\n  for (const candidate of KNOWN_EXTENSION_CAPABILITIES) {\n    const distance = levenshteinDistanceWithinLimit(normalized, candidate, maxDistance);\n    if (distance !== null && distance < bestDistance) {\n      bestDistance = distance;\n      bestMatch = candidate;\n    }\n  }\n  return bestMatch;\n}\n\n/**\n * Implements format unknown extension capability warning for the public runtime surface of this module.\n */\nexport function formatUnknownExtensionCapabilityWarning(layer: ExtensionLayer, name: string, capability: string): string {\n  const allowed = KNOWN_EXTENSION_CAPABILITIES.join(\",\");\n  const suggested = suggestKnownExtensionCapability(capability) ?? \"none\";\n  return `extension_capability_unknown:${layer}:${name}:${capability}:allowed=${allowed}:suggested=${suggested}`;\n}\n\n/**\n * Implements format legacy extension capability alias warning for the public runtime surface of this module.\n */\nexport function formatLegacyExtensionCapabilityAliasWarning(\n  layer: ExtensionLayer,\n  name: string,\n  aliases: readonly LegacyExtensionCapabilityAliasMapping[],\n): string {\n  const aliasesToken = aliases.map((entry) => `${entry.alias}>${entry.target}`).join(\",\");\n  return `extension_capability_legacy_alias:${layer}:${name}:aliases=${aliasesToken}`;\n}\n\n\n/**\n * Implements parse unknown extension capability warning for the public runtime surface of this module.\n */\nexport function parseUnknownExtensionCapabilityWarning(\n  warning: string,\n): UnknownExtensionCapabilityWarningDetails | null {\n  const match = /^extension_capability_unknown:(global|project):([^:]+):([^:]+):allowed=([^:]+):suggested=([^:]+)$/.exec(\n    warning.trim(),\n  );\n  if (!match) {\n    return null;\n  }\n  const [, layerRaw, name, capability, allowedRaw, suggestedRaw] = match;\n  const layer = layerRaw as ExtensionLayer;\n  const allowed_capabilities = allowedRaw\n    .split(\",\")\n    .map((value) => value.trim())\n    .filter((value) => value.length > 0);\n  const legacyAlias = resolveLegacyExtensionCapabilityAlias(capability);\n  const suggestedFromWarning = suggestedRaw === \"none\" ? undefined : suggestedRaw;\n  const suggested_capability = suggestedFromWarning ?? legacyAlias ?? undefined;\n  const suggestion_source = suggested_capability\n    ? legacyAlias === suggested_capability\n      ? \"legacy_alias\"\n      : \"nearest_match\"\n    : undefined;\n  return {\n    layer,\n    name,\n    capability,\n    allowed_capabilities,\n    capability_contract_version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n    suggested_capability,\n    suggestion_source,\n    legacy_alias_target: legacyAlias ?? undefined,\n  };\n}\n\n/**\n * Implements parse legacy extension capability alias warning for the public runtime surface of this module.\n */\nexport function parseLegacyExtensionCapabilityAliasWarning(warning: string): UnknownExtensionCapabilityWarningDetails[] {\n  const match = /^extension_capability_legacy_alias:(global|project):([^:]+):aliases=(.+)$/.exec(warning.trim());\n  if (!match) {\n    return [];\n  }\n  const [, layerRaw, name, aliasesRaw] = match;\n  const layer = layerRaw as ExtensionLayer;\n  const allowedCapabilities = [...KNOWN_EXTENSION_CAPABILITIES];\n  const parsed: UnknownExtensionCapabilityWarningDetails[] = [];\n  for (const token of aliasesRaw.split(\",\")) {\n    const [rawAlias, rawTarget] = token.split(\">\");\n    const alias = rawAlias?.trim();\n    const target = rawTarget?.trim().toLowerCase();\n    if (!alias || !target || !isKnownExtensionCapability(target)) {\n      continue;\n    }\n    parsed.push({\n      layer,\n      name,\n      capability: alias,\n      allowed_capabilities: allowedCapabilities,\n      capability_contract_version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n      suggested_capability: target,\n      suggestion_source: \"legacy_alias\",\n      legacy_alias_target: target,\n    });\n  }\n  return parsed;\n}\n"],"names":[],"mappings":"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","debugId":"0be603c7-ab83-5880-a57f-8140caf82657"}
+{"version":3,"file":"extension-capability-aliases.js","sources":["core/extensions/extension-capability-aliases.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/extension-capability-aliases\n *\n * Implements extension runtime contracts and governance for Extension Capability Aliases.\n */\nimport {\n  KNOWN_EXTENSION_CAPABILITIES,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  type ExtensionCapability,\n  type ExtensionLayer,\n  type LegacyExtensionCapabilityAliasMapping,\n  type UnknownExtensionCapabilityWarningDetails,\n} from \"./extension-types.js\";\nimport { levenshteinDistanceWithinLimit } from \"../shared/levenshtein.js\";\n\n/**\n * Implements normalize names for the public runtime surface of this module.\n */\nexport function normalizeNames(values: string[]): string[] {\n  return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((a, b) =>\n    a.localeCompare(b),\n  );\n}\n\n/**\n * Implements check whether known extension capability for the public runtime surface of this module.\n */\nexport function isKnownExtensionCapability(value: string): value is ExtensionCapability {\n  return (KNOWN_EXTENSION_CAPABILITIES as readonly string[]).includes(value);\n}\n\n/**\n * Trim and lower-case a capability token, returning it only when it is a known\n * canonical capability (otherwise `null`). Shared so capability normalization\n * and known-capability filtering stay identical across the doctor and the SDK\n * least-privilege helpers.\n */\nexport function normalizeKnownExtensionCapability(value: string): ExtensionCapability | null {\n  const normalized = value.trim().toLowerCase();\n  return isKnownExtensionCapability(normalized) ? normalized : null;\n}\n\n/**\n * Implements collect unknown extension capabilities for the public runtime surface of this module.\n */\nexport function collectUnknownExtensionCapabilities(capabilities: readonly string[]): string[] {\n  return capabilities.filter((capability) => !isKnownExtensionCapability(capability));\n}\n\n/**\n * Implements resolve legacy extension capability alias for the public runtime surface of this module.\n */\nexport function resolveLegacyExtensionCapabilityAlias(capability: string): ExtensionCapability | null {\n  const normalized = capability.trim().toLowerCase();\n  if (normalized.length === 0) {\n    return null;\n  }\n  return EXTENSION_CAPABILITY_LEGACY_ALIASES[normalized] ?? null;\n}\n\n/**\n * Implements normalize manifest capabilities for the public runtime surface of this module.\n */\nexport function normalizeManifestCapabilities(rawCapabilities: readonly string[]): {\n  capabilities: string[];\n  legacy_aliases: LegacyExtensionCapabilityAliasMapping[];\n} {\n  const normalizedCapabilities = normalizeNames([...rawCapabilities].map((value) => value.toLowerCase()));\n  const remappedCapabilities: string[] = [];\n  const legacyAliases: LegacyExtensionCapabilityAliasMapping[] = [];\n  for (const capability of normalizedCapabilities) {\n    const legacyAliasTarget = resolveLegacyExtensionCapabilityAlias(capability);\n    if (legacyAliasTarget) {\n      remappedCapabilities.push(legacyAliasTarget);\n      legacyAliases.push({\n        alias: capability,\n        target: legacyAliasTarget,\n      });\n      continue;\n    }\n    remappedCapabilities.push(capability);\n  }\n  const dedupedLegacyAliases = [...new Map(legacyAliases.map((entry) => [`${entry.alias}>${entry.target}`, entry])).values()].sort(\n    (left, right) => left.alias.localeCompare(right.alias),\n  );\n  return {\n    capabilities: normalizeNames(remappedCapabilities),\n    legacy_aliases: dedupedLegacyAliases,\n  };\n}\n\n/**\n * Implements suggest known extension capability for the public runtime surface of this module.\n */\nexport function suggestKnownExtensionCapability(capability: string): string | null {\n  const normalized = capability.trim().toLowerCase();\n  if (normalized.length === 0) {\n    return null;\n  }\n  const legacyAlias = resolveLegacyExtensionCapabilityAlias(normalized);\n  if (legacyAlias) {\n    return legacyAlias;\n  }\n  const maxDistance = Math.max(1, Math.floor(normalized.length * 0.34));\n  let bestMatch: string | null = null;\n  let bestDistance = Number.POSITIVE_INFINITY;\n  for (const candidate of KNOWN_EXTENSION_CAPABILITIES) {\n    const distance = levenshteinDistanceWithinLimit(normalized, candidate, maxDistance);\n    if (distance !== null && distance < bestDistance) {\n      bestDistance = distance;\n      bestMatch = candidate;\n    }\n  }\n  return bestMatch;\n}\n\n/**\n * Implements format unknown extension capability warning for the public runtime surface of this module.\n */\nexport function formatUnknownExtensionCapabilityWarning(layer: ExtensionLayer, name: string, capability: string): string {\n  const allowed = KNOWN_EXTENSION_CAPABILITIES.join(\",\");\n  const suggested = suggestKnownExtensionCapability(capability) ?? \"none\";\n  return `extension_capability_unknown:${layer}:${name}:${capability}:allowed=${allowed}:suggested=${suggested}`;\n}\n\n/**\n * Implements format legacy extension capability alias warning for the public runtime surface of this module.\n */\nexport function formatLegacyExtensionCapabilityAliasWarning(\n  layer: ExtensionLayer,\n  name: string,\n  aliases: readonly LegacyExtensionCapabilityAliasMapping[],\n): string {\n  const aliasesToken = aliases.map((entry) => `${entry.alias}>${entry.target}`).join(\",\");\n  return `extension_capability_legacy_alias:${layer}:${name}:aliases=${aliasesToken}`;\n}\n\n\n/**\n * Implements parse unknown extension capability warning for the public runtime surface of this module.\n */\nexport function parseUnknownExtensionCapabilityWarning(\n  warning: string,\n): UnknownExtensionCapabilityWarningDetails | null {\n  const match = /^extension_capability_unknown:(global|project):([^:]+):([^:]+):allowed=([^:]+):suggested=([^:]+)$/.exec(\n    warning.trim(),\n  );\n  if (!match) {\n    return null;\n  }\n  const [, layerRaw, name, capability, allowedRaw, suggestedRaw] = match;\n  const layer = layerRaw as ExtensionLayer;\n  const allowed_capabilities = allowedRaw\n    .split(\",\")\n    .map((value) => value.trim())\n    .filter((value) => value.length > 0);\n  const legacyAlias = resolveLegacyExtensionCapabilityAlias(capability);\n  const suggestedFromWarning = suggestedRaw === \"none\" ? undefined : suggestedRaw;\n  const suggested_capability = suggestedFromWarning ?? legacyAlias ?? undefined;\n  const suggestion_source = suggested_capability\n    ? legacyAlias === suggested_capability\n      ? \"legacy_alias\"\n      : \"nearest_match\"\n    : undefined;\n  return {\n    layer,\n    name,\n    capability,\n    allowed_capabilities,\n    capability_contract_version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n    suggested_capability,\n    suggestion_source,\n    legacy_alias_target: legacyAlias ?? undefined,\n  };\n}\n\n/**\n * Implements parse legacy extension capability alias warning for the public runtime surface of this module.\n */\nexport function parseLegacyExtensionCapabilityAliasWarning(warning: string): UnknownExtensionCapabilityWarningDetails[] {\n  const match = /^extension_capability_legacy_alias:(global|project):([^:]+):aliases=(.+)$/.exec(warning.trim());\n  if (!match) {\n    return [];\n  }\n  const [, layerRaw, name, aliasesRaw] = match;\n  const layer = layerRaw as ExtensionLayer;\n  const allowedCapabilities = [...KNOWN_EXTENSION_CAPABILITIES];\n  const parsed: UnknownExtensionCapabilityWarningDetails[] = [];\n  for (const token of aliasesRaw.split(\",\")) {\n    const [rawAlias, rawTarget] = token.split(\">\");\n    const alias = rawAlias?.trim();\n    const target = rawTarget?.trim().toLowerCase();\n    if (!alias || !target || !isKnownExtensionCapability(target)) {\n      continue;\n    }\n    parsed.push({\n      layer,\n      name,\n      capability: alias,\n      allowed_capabilities: allowedCapabilities,\n      capability_contract_version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n      suggested_capability: target,\n      suggestion_source: \"legacy_alias\",\n      legacy_alias_target: target,\n    });\n  }\n  return parsed;\n}\n"],"names":[],"mappings":"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","debugId":"5723464e-1f10-5a39-96a9-787c0052a036"}

package/dist/core/extensions/index.d.ts

@@ -113,3 +113,4 @@ export declare function runActiveServiceOverride(service: ExtensionServiceName,
  */
 export declare function runActiveServiceOverrideSync(service: ExtensionServiceName, payload: unknown): ServiceOverrideResult;
 export * from "./loader.js";
+export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabilities, reconcileExtensionCapabilityUsage, type CollectUsedExtensionCapabilitiesOptions, type ExtensionCapabilityUsageReconciliation, } from "./capability-usage.js";