@unbrained/pm-cli 2026.7.5 → 2026.7.7

package/dist/cli-bundle/chunks/chunk-JINYH2DB.js

@@ -1,371 +0,0 @@
-// dist/core/diagnostics/remediation.js
-!(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 (e2) {
-  }
-})();
-var REMEDIATION_REGISTRY = Object.freeze([
-  // --- pm health: directories ---
-  {
-    code: "missing_directory",
-    command: "pm init",
-    summary: "Recreate missing tracker directories (pm init is idempotent and restores the scaffold)."
-  },
-  // --- pm health: settings (read/parse) ---
-  {
-    code: "settings_read_invalid_json",
-    command: "pm config list --json",
-    summary: "settings.json is not valid JSON and pm fell back to defaults; fix the syntax error in the reported path, then re-run."
-  },
-  {
-    code: "settings_read_invalid_schema",
-    command: "pm config list --json",
-    summary: "settings.json failed schema validation and pm fell back to defaults; correct the reported key in the file, then re-run."
-  },
-  {
-    code: "settings_read_merge_failed",
-    command: "pm config list --json",
-    summary: "Global/project settings could not be merged; reconcile the conflicting keys in the reported settings files."
-  },
-  // --- pm health: settings_values ---
-  {
-    code: "settings:id_prefix_empty",
-    command: "pm config list --json",
-    summary: 'id_prefix is empty; set a non-empty "id_prefix" in settings.json so generated item ids are well-formed.'
-  },
-  {
-    code: "settings:locks_ttl_non_positive",
-    command: "pm config list --json",
-    summary: 'locks.ttl_seconds must be positive; set a positive "locks.ttl_seconds" in settings.json.'
-  },
-  // --- pm health: telemetry (advisory) ---
-  {
-    code: "telemetry_state_invalid_json",
-    command: "pm health --check-telemetry",
-    summary: "Local telemetry state file is corrupt; pm recreates it on the next flush. Advisory only."
-  },
-  {
-    code: "telemetry_queue_invalid_rows",
-    command: "pm health --check-telemetry",
-    summary: "The telemetry queue has unparseable rows; they are skipped on the next flush. Advisory only."
-  },
-  {
-    code: "telemetry_queue_pending",
-    command: "pm health --check-telemetry",
-    summary: "Telemetry events are queued; they flush automatically on the next reachable command. Advisory only."
-  },
-  {
-    code: "telemetry_queue_high_retries",
-    command: "pm telemetry flush",
-    summary: "Some queued telemetry events are near retry exhaustion; flush now and verify endpoint reachability before entries are dropped."
-  },
-  {
-    code: "telemetry_endpoint_probe_failed",
-    command: "pm health --check-telemetry",
-    summary: "The telemetry endpoint is unreachable; events stay queued until it recovers. Advisory only."
-  },
-  {
-    code: "telemetry_endpoint_probe_http_status",
-    command: "pm health --check-telemetry",
-    summary: "The telemetry endpoint returned a non-success status; events stay queued until it recovers. Advisory only."
-  },
-  {
-    code: "telemetry_schema_version_behind",
-    command: "pm health --check-telemetry",
-    summary: "Client schema is behind server; upgrade pm-cli to emit the latest event shape."
-  },
-  {
-    code: "telemetry_otel_export_failing",
-    command: "pm health --check-telemetry",
-    summary: "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."
-  },
-  // --- pm health: integrity ---
-  {
-    code: "integrity_item_unreadable",
-    command: "pm validate --check-files --verbose-diagnostics",
-    summary: "An item file could not be read; restore or repair the file at the reported path."
-  },
-  {
-    code: "integrity_item_parse_failed",
-    command: "pm validate --check-files --verbose-diagnostics",
-    summary: "An item file failed to parse; fix the malformed front matter at the reported path."
-  },
-  {
-    code: "integrity_item_conflict_marker",
-    command: "pm validate --check-files --verbose-diagnostics",
-    summary: "An item file contains Git conflict markers; resolve the <<<<<<< / >>>>>>> markers at the reported line."
-  },
-  {
-    code: "integrity_history_unreadable",
-    command: "pm history-repair <id>",
-    summary: "A history stream could not be read; re-anchor the affected item's history chain."
-  },
-  {
-    code: "integrity_history_invalid_json",
-    command: "pm history-repair <id>",
-    summary: "A history stream contains invalid JSON; re-anchor the affected item's history chain."
-  },
-  {
-    code: "integrity_history_conflict_marker",
-    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.
-  {
-    code: "history_drift_missing_stream",
-    command: "pm history-repair <id>",
-    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)."
-  },
-  {
-    code: "history_drift_unreadable_stream",
-    command: "pm history-repair <id>",
-    summary: "The item's history stream is unreadable; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass)."
-  },
-  {
-    code: "history_drift_hash_mismatch",
-    command: "pm history-repair <id>",
-    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)."
-  },
-  {
-    code: "history_drift_chain_mismatch",
-    command: "pm history-repair <id>",
-    summary: "The item's history chain is broken; re-anchor the chain (pm history-repair --all repairs every drifted stream in one pass)."
-  },
-  // --- pm health: storage (history compaction policy) ---
-  {
-    code: "history_stream_over_compact_threshold",
-    command: "pm history-compact <id>",
-    summary: "The history stream exceeds the configured compaction threshold; compact it (pm history-compact --all-streams sweeps every over-threshold stream in one pass)."
-  },
-  // --- pm health: locks ---
-  {
-    code: "locks_stale_count",
-    command: "pm gc --scope locks",
-    summary: "Stale item-claim locks (embedded ttl elapsed) can block mutations; sweep them \u2014 gc retains active and unparseable locks."
-  },
-  {
-    code: "locks_unreadable",
-    command: "pm gc --scope locks --dry-run",
-    summary: "Some lock files could not be read; preview the sweep and inspect the unreadable files manually \u2014 gc never deletes what it cannot read."
-  },
-  // --- pm health: extensions ---
-  // Most extension findings keep their richer, contextual
-  // `details.triage.remediation` and are intentionally absent here. The
-  // partial-coverage code is the exception: it is not a per-extension triage
-  // result but a system-wide adoption gap (unmanaged installs the update-health
-  // scan had to skip), so it has a single deterministic fix and belongs in the
-  // shared registry like any other health finding (pm-bdvm).
-  {
-    code: "extension_update_health_partial_coverage",
-    command: "pm extension --adopt-all --project",
-    summary: "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)."
-  },
-  // --- pm health: vectorization ---
-  {
-    code: "vectorization_stale_items_remaining",
-    command: "pm health --refresh-vectors",
-    summary: "Some items have stale embeddings; refresh vectors so semantic search results stay current."
-  },
-  {
-    code: "vectorization_embedding_identity_changed",
-    command: "pm reindex --mode semantic",
-    summary: "Embedding provider/model changed since the last index; run a semantic reindex to rebuild vectors."
-  },
-  // --- pm validate: metadata ---
-  // Note: validate_metadata_missing_author has no entry on purpose. `pm update
-  // --author` sets the mutation/audit author (history), not the item's
-  // `metadata.author` front-matter field, and there is no CLI flag that writes
-  // that field — so emitting a command here would record an audit entry without
-  // clearing the finding. A missing item author must be restored at the source.
-  {
-    code: "validate_metadata_missing_acceptance_criteria",
-    command: 'pm update <id> --acceptance-criteria "<criteria>"',
-    summary: "Backfill the missing acceptance criteria on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_missing_estimate",
-    command: 'pm update <id> --estimate "<estimate>"',
-    summary: "Backfill the missing estimate on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_missing_close_reason",
-    command: 'pm update <id> --close-reason "<reason>"',
-    summary: "Backfill the missing close reason on the reported closed item(s)."
-  },
-  {
-    code: "validate_metadata_missing_reviewer",
-    command: 'pm update <id> --reviewer "<name>"',
-    summary: "Backfill the missing reviewer on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_missing_risk",
-    command: 'pm update <id> --risk "<level>"',
-    summary: "Backfill the missing risk on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_missing_confidence",
-    command: 'pm update <id> --confidence "<level>"',
-    summary: "Backfill the missing confidence on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_missing_sprint",
-    command: 'pm update <id> --sprint "<sprint>"',
-    summary: "Backfill the missing sprint on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_missing_release",
-    command: 'pm update <id> --release "<release>"',
-    summary: "Backfill the missing release on the reported item(s)."
-  },
-  {
-    code: "validate_metadata_custom_profile_missing_required_fields",
-    command: 'pm config set metadata-required-fields --criterion "<field>"',
-    summary: "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."
-  },
-  {
-    code: "validate_metadata_duplicate_issue_codes",
-    command: 'pm update <id> --title "<distinct title>"',
-    summary: "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)."
-  },
-  // --- pm validate: resolution ---
-  {
-    code: "validate_resolution_missing_fields",
-    command: 'pm update <id> --resolution "<how resolved>"',
-    summary: "Backfill resolution / expected_result / actual_result on the reported closed item(s)."
-  },
-  // --- pm validate: lifecycle ---
-  {
-    code: "validate_lifecycle_active_closure_like_metadata",
-    command: "pm update <id> --unset <closure-like-field>",
-    summary: "Clear the closure-like field the validator flags on this active item \u2014 the detail row names it (resolution / actual-result / blocked-reason) \u2014 or close the item if it is actually done."
-  },
-  {
-    code: "validate_lifecycle_active_terminal_parent",
-    command: "pm update <id> --parent <active-parent-id>",
-    summary: "Reopen the terminal parent or move the active child under a non-terminal parent."
-  },
-  {
-    code: "validate_lifecycle_stale_blockers",
-    command: "pm update <id> --unset blocked-by --unset blocked-reason",
-    summary: "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."
-  },
-  {
-    code: "validate_lifecycle_dependency_cycles_error",
-    command: "pm update <id> --dep-remove <dep-id>",
-    summary: "Break the dependency cycle by removing one edge from the reported cycle."
-  },
-  {
-    code: "validate_lifecycle_dependency_cycles",
-    command: "pm update <id> --dep-remove <dep-id>",
-    summary: "Break the dependency cycle by removing one edge from the reported cycle."
-  },
-  {
-    code: "validate_hierarchy_parent_cycle_error",
-    command: "pm update <id> --parent <other-id>",
-    summary: "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)."
-  },
-  {
-    code: "validate_hierarchy_parent_cycle",
-    command: "pm update <id> --parent <other-id>",
-    summary: "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)."
-  },
-  // --- pm validate: files ---
-  {
-    code: "validate_files_missing_linked_paths",
-    command: "pm <files|docs> <id> --remove <path>",
-    summary: "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)."
-  },
-  {
-    code: "validate_files_orphaned_paths",
-    command: "pm <files|docs> <id> --add <path>",
-    summary: "Link the orphaned artifact with pm files (file) or pm docs (doc), or remove it from the workspace."
-  },
-  {
-    code: "validate_files_tracked_all_strict_forces_pm_internals",
-    command: "pm validate --check-files --include-pm-internals",
-    summary: "tracked-all-strict scan flagged pm internals; re-run with --include-pm-internals or a softer --scan-mode."
-  },
-  // --- pm validate: history_drift ---
-  {
-    code: "validate_history_drift_missing_streams",
-    command: "pm history-repair <id>",
-    summary: "Re-anchor the history chains of the items missing a history stream."
-  },
-  {
-    code: "validate_history_drift_unreadable_streams",
-    command: "pm history-repair <id>",
-    summary: "Re-anchor the history chains of the items with an unreadable history stream."
-  },
-  {
-    code: "validate_history_drift_hash_mismatches",
-    command: "pm history-repair <id>",
-    summary: "Re-anchor the history chains of the items whose content hash drifted."
-  },
-  {
-    code: "validate_history_drift_chain_mismatches",
-    command: "pm history-repair <id>",
-    summary: "Re-anchor the history chains of the items with a broken history chain."
-  },
-  // --- pm validate: command_references ---
-  {
-    code: "validate_command_references_stale_pm_ids",
-    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."
-  }
-]);
-function resolveRemediation(warning) {
-  if (typeof warning !== "string") {
-    return void 0;
-  }
-  const normalized = warning.trim();
-  for (const entry of REMEDIATION_REGISTRY) {
-    if (normalized === entry.code || normalized.startsWith(`${entry.code}:`)) {
-      return entry;
-    }
-  }
-  return void 0;
-}
-function buildRemediationMap(warnings) {
-  const map = {};
-  for (const warning of warnings) {
-    const entry = resolveRemediation(warning);
-    if (entry !== void 0 && !Object.prototype.hasOwnProperty.call(map, entry.code)) {
-      map[entry.code] = entry.command;
-    }
-  }
-  return map;
-}
-function buildRemediationCommands(warnings) {
-  return Object.values(buildRemediationMap(warnings));
-}
-
-export {
-  buildRemediationMap,
-  buildRemediationCommands
-};
-//# sourceMappingURL=chunk-JINYH2DB.js.map

package/dist/cli-bundle/chunks/chunk-JINYH2DB.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../../../core/diagnostics/remediation.ts"],
-  "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"],
-  "mappings": "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",
-  "names": []
-}

package/dist/cli-bundle/chunks/chunk-JLA7EVYV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../../../cli/commands/annotation-command.ts"],"sourcesContent":["/**\n * @module cli/commands/annotation-command\n *\n * Implements the pm annotation command command surface and its agent-facing runtime behavior.\n */\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { parseCsvKv } from \"../../core/item/parse.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { resolveAuthor } from \"../../core/shared/author.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\n\ninterface AnnotationEntry {\n  created_at: string;\n  author: string;\n  text: string;\n  edited_at?: string;\n}\n\ninterface AnnotationCommandOptions {\n  limit?: string;\n  author?: string;\n  message?: string;\n  force?: boolean;\n  includeMeta?: boolean;\n}\n\ninterface AnnotationInput {\n  mode: \"list\" | \"add\" | \"stdin\" | \"file\" | \"edit\" | \"delete\";\n  value?: string;\n  emptyFlag?: string;\n  index?: number;\n}\n\ninterface OwnershipConflictGuidance {\n  required: string;\n  examples: string[];\n  nextSteps: string[];\n}\n\ninterface AnnotationCommandConfig<TKey extends string> {\n  input: AnnotationInput;\n  collectionKey: TKey;\n  op: Parameters<typeof mutateItem>[0][\"op\"];\n  editOp?: Parameters<typeof mutateItem>[0][\"op\"];\n  deleteOp?: Parameters<typeof mutateItem>[0][\"op\"];\n  parseText: (raw: string) => string;\n  allowAuditBypass: boolean;\n  conflictGuidance: OwnershipConflictGuidance;\n}\n\ntype AnnotationCommandResult<TKey extends string, TEntry extends AnnotationEntry> = {\n  id: string;\n  count: number;\n} & Record<TKey, TEntry[]> & {\n    total_count?: number;\n    returned_count?: number;\n    has_more?: boolean;\n    limit?: number;\n  };\n\n/**\n * Implements limit annotation entries for the public runtime surface of this module.\n */\nexport function limitAnnotationEntries<TEntry>(values: TEntry[], limit: number | undefined): TEntry[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\n/**\n * Implements read annotation entries for the public runtime surface of this module.\n */\nexport function readAnnotationEntries<TEntry>(source: Record<string, unknown>, collectionKey: string): TEntry[] {\n  const value = source[collectionKey];\n  return Array.isArray(value) ? (value as TEntry[]) : [];\n}\n\n/**\n * Implements parse annotation text input for the public runtime surface of this module.\n */\nexport function parseAnnotationTextInput(raw: string, options: { stripPlainTextPrefix?: boolean } = {}): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const textPrefixMatch = /^(?:[-*+]\\s*)?text\\s*[:=]/i.exec(trimmed);\n  if (options.stripPlainTextPrefix === true && textPrefixMatch && !trimmed.startsWith(\"```\")) {\n    const text = trimmed.slice(textPrefixMatch[0].length).trim();\n    return text || trimmed;\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\n/**\n * Implements wrap ownership conflict for the public runtime surface of this module.\n */\nexport function wrapOwnershipConflict(error: unknown, guidance: OwnershipConflictGuidance): never {\n  if (\n    error instanceof PmCliError &&\n    error.exitCode === EXIT_CODE.CONFLICT &&\n    error.message.includes(\"is assigned to\") &&\n    error.message.includes(\"Use --force to override\")\n  ) {\n    throw new PmCliError(error.message, error.exitCode, {\n      code: \"ownership_conflict\",\n      required: guidance.required,\n      examples: guidance.examples,\n      nextSteps: guidance.nextSteps,\n    });\n  }\n  throw error;\n}\n\n/**\n * Implements run annotation command for the public runtime surface of this module.\n */\nexport async function runAnnotationCommand<TKey extends string, TEntry extends AnnotationEntry>(\n  id: string,\n  options: AnnotationCommandOptions,\n  global: GlobalOptions,\n  config: AnnotationCommandConfig<TKey>,\n): Promise<AnnotationCommandResult<TKey, TEntry>> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n\n  if (config.input.mode === \"list\") {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const allEntries = readAnnotationEntries<TEntry>(loaded.document.metadata, config.collectionKey);\n    return renderAnnotationResult(located.id, config.collectionKey, allEntries, limit, options.includeMeta === true);\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n\n  if (config.input.mode === \"delete\") {\n    const op = config.deleteOp ?? config.op;\n    let result: Awaited<ReturnType<typeof mutateItem>>;\n    try {\n      result = await mutateItem({\n        pmRoot,\n        settings,\n        id,\n        op,\n        author,\n        message: options.message,\n        force: options.force,\n        bypassAssigneeConflict: config.allowAuditBypass,\n        mutate(document) {\n          const entries = readAnnotationEntries<TEntry>(document.metadata, config.collectionKey);\n          const arrayIndex = resolveAnnotationIndex(config.input.index, entries.length, config.collectionKey);\n          entries.splice(arrayIndex, 1);\n          document.metadata[config.collectionKey] = entries as never;\n          return { changedFields: [config.collectionKey] };\n        },\n      });\n    } catch (error: unknown) {\n      wrapOwnershipConflict(error, config.conflictGuidance);\n    }\n    const allEntries = readAnnotationEntries<TEntry>(result.item, config.collectionKey);\n    return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true);\n  }\n\n  const text = config.parseText(config.input.value ?? \"\");\n  if (!text.trim()) {\n    throw new PmCliError(`${config.input.emptyFlag ?? \"--add\"} text cannot be empty`, EXIT_CODE.USAGE);\n  }\n\n  if (config.input.mode === \"edit\") {\n    const op = config.editOp ?? config.op;\n    let result: Awaited<ReturnType<typeof mutateItem>>;\n    try {\n      result = await mutateItem({\n        pmRoot,\n        settings,\n        id,\n        op,\n        author,\n        message: options.message,\n        force: options.force,\n        bypassAssigneeConflict: config.allowAuditBypass,\n        mutate(document) {\n          const entries = readAnnotationEntries<TEntry>(document.metadata, config.collectionKey);\n          const arrayIndex = resolveAnnotationIndex(config.input.index, entries.length, config.collectionKey);\n          const existing = entries[arrayIndex];\n          entries[arrayIndex] = {\n            ...existing,\n            text,\n            edited_at: nowIso(),\n          } as TEntry;\n          document.metadata[config.collectionKey] = entries as never;\n          return { changedFields: [config.collectionKey] };\n        },\n      });\n    } catch (error: unknown) {\n      wrapOwnershipConflict(error, config.conflictGuidance);\n    }\n    const allEntries = readAnnotationEntries<TEntry>(result.item, config.collectionKey);\n    return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: config.op,\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: config.allowAuditBypass,\n      mutate(document) {\n        const entries = readAnnotationEntries<TEntry>(document.metadata, config.collectionKey);\n        entries.push({\n          created_at: nowIso(),\n          author,\n          text,\n        } as TEntry);\n        document.metadata[config.collectionKey] = entries as never;\n        return { changedFields: [config.collectionKey] };\n      },\n    });\n  } catch (error: unknown) {\n    wrapOwnershipConflict(error, config.conflictGuidance);\n  }\n\n  const allEntries = readAnnotationEntries<TEntry>(result.item, config.collectionKey);\n  return renderAnnotationResult(result.item.id, config.collectionKey, allEntries, limit, options.includeMeta === true);\n}\n\n/**\n * Implements resolve annotation index for the public runtime surface of this module.\n */\nexport function resolveAnnotationIndex(\n  oneBasedIndex: number | undefined,\n  count: number,\n  collectionKey: string,\n): number {\n  if (oneBasedIndex === undefined || !Number.isInteger(oneBasedIndex) || oneBasedIndex < 1 || oneBasedIndex > count) {\n    const singular = collectionKey.replace(/s$/, \"\");\n    const label = `${singular.charAt(0).toUpperCase()}${singular.slice(1)}`;\n    const noun = count === 1 ? `1 ${singular}` : `${count} ${collectionKey}`;\n    throw new PmCliError(\n      `${label} index ${oneBasedIndex ?? \"(missing)\"} out of range (item has ${noun})`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return oneBasedIndex - 1;\n}\n\nfunction renderAnnotationResult<TKey extends string, TEntry extends AnnotationEntry>(\n  id: string,\n  collectionKey: TKey,\n  allEntries: TEntry[],\n  limit: number | undefined,\n  includeMeta: boolean,\n): AnnotationCommandResult<TKey, TEntry> {\n  const entries = limitAnnotationEntries(allEntries, limit);\n  return {\n    id,\n    [collectionKey]: entries,\n    count: entries.length,\n    ...(includeMeta\n      ? {\n          total_count: allEntries.length,\n          returned_count: entries.length,\n          has_more: entries.length < allEntries.length,\n          ...(limit !== undefined ? { limit } : {}),\n        }\n      : {}),\n  } as AnnotationCommandResult<TKey, TEntry>;\n}\n"],"names":["allEntries","result"],"mappings":"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","debugId":"1775008a-959d-5fa2-a867-2a4d24c3a190"}

package/dist/cli-bundle/chunks/chunk-K32L7HZO.js

@@ -1,76 +0,0 @@
-
-!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]="19198c42-e182-5131-a1e0-d6421ac4309c")}catch(e){}}();
-import {
-  normalizeExtensionNameForMatch
-} from "./chunk-FUM6UMY4.js";
-import {
-  describeExtensionActivation,
-  renderExtensionSurfaceMarkdown
-} from "./chunk-AAEQMOC6.js";
-
-// dist/cli/commands/extension/describe.js
-function layerNameKey(layer, name) {
-  return `${layer}:${normalizeExtensionNameForMatch(name)}`;
-}
-function buildExtensionDescribeResult(target, loadResult, activationResult) {
-  const activationFailedKeys = new Set(activationResult.failed.map((entry) => layerNameKey(entry.layer, entry.name)));
-  const candidates = [
-    ...loadResult.loaded.map((entry) => ({
-      name: entry.name,
-      layer: entry.layer,
-      version: entry.version,
-      activation_status: activationFailedKeys.has(layerNameKey(entry.layer, entry.name)) ? "failed" : "ok",
-      surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name })
-    })),
-    ...loadResult.failed.map((entry) => ({
-      name: entry.name,
-      layer: entry.layer,
-      version: "unknown",
-      activation_status: "not_loaded",
-      surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name })
-    }))
-  ].sort((left, right) => left.name.localeCompare(right.name) || left.layer.localeCompare(right.layer));
-  const normalizedTarget = typeof target === "string" ? normalizeExtensionNameForMatch(target) : null;
-  const matchedNames = normalizedTarget === null ? null : new Set(loadResult.loaded.filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizedTarget || typeof entry.source_package === "string" && normalizeExtensionNameForMatch(entry.source_package) === normalizedTarget).map((entry) => normalizeExtensionNameForMatch(entry.name)).concat(normalizedTarget));
-  const extensions = matchedNames === null ? candidates : candidates.filter((entry) => matchedNames.has(normalizeExtensionNameForMatch(entry.name)));
-  const unionOptions = matchedNames === null ? {} : { extensionNames: [...matchedNames] };
-  return {
-    target: typeof target === "string" ? target.trim() : null,
-    total: extensions.length,
-    extensions,
-    union: describeExtensionActivation(activationResult, unionOptions)
-  };
-}
-var ACTIVATION_STATUS_LABELS = {
-  ok: "loaded",
-  failed: "activation failed",
-  not_loaded: "not loaded"
-};
-function renderExtensionDescribeMarkdown(result, noun) {
-  const titleNoun = `${noun[0].toUpperCase()}${noun.slice(1)}`;
-  const lines = [`# ${titleNoun} surface reference`, ""];
-  lines.push(result.target === null ? `Scope: all loaded ${noun}s` : `Scope: \`${result.target}\``);
-  lines.push(`Described: ${result.total} ${noun}${result.total === 1 ? "" : "s"}`, "");
-  if (result.extensions.length === 0) {
-    lines.push(`_No ${noun}s are loaded._`, "");
-    return `${lines.join("\n").trimEnd()}
-`;
-  }
-  for (const entry of result.extensions) {
-    const title = `${entry.name} (${entry.layer} v${entry.version}, ${ACTIVATION_STATUS_LABELS[entry.activation_status]})`;
-    lines.push(renderExtensionSurfaceMarkdown(entry.surfaces, { title, headingLevel: 2 }));
-  }
-  if (result.extensions.length > 1) {
-    lines.push(renderExtensionSurfaceMarkdown(result.union, { title: `Union across all described ${noun}s`, headingLevel: 2 }));
-  }
-  return `${lines.join("\n").trimEnd()}
-`;
-}
-
-export {
-  buildExtensionDescribeResult,
-  renderExtensionDescribeMarkdown
-};
-//# sourceMappingURL=chunk-K32L7HZO.js.map
-
-//# debugId=19198c42-e182-5131-a1e0-d6421ac4309c

package/dist/cli-bundle/chunks/chunk-K32L7HZO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../../../cli/commands/extension/describe.ts"],"sourcesContent":["/**\n * @module cli/commands/extension/describe\n *\n * Builds the `pm extension describe` / `pm package describe` payload: a flat,\n * by-name map of every surface each loaded extension registered.\n *\n * The SDK already ships {@link describeExtensionActivation} -- the `describe`\n * (enumerate-all) verb that complements the `assert*` (verify-one) and `run*`\n * (invoke-one) testing helpers -- but until now it was reachable only from a test\n * that hand-built an {@link ExtensionActivationResult}. This module is the thin\n * orchestration that lets an agent at the CLI (or over MCP) ask \"what does this\n * installed extension add to my context?\" in one call, instead of stitching\n * together `doctor` (errors), `manage` (update metadata), and a manifest read.\n *\n * It is intentionally pure: the caller performs the load+activate cycle (exactly\n * as `explore`/`doctor` already do) and hands the results here, so the same\n * builder is trivially unit-testable against synthetic activations.\n */\nimport { describeExtensionActivation, type ExtensionActivationSummary } from \"../../../core/extensions/activation-summary.js\";\nimport { renderExtensionSurfaceMarkdown } from \"../../../core/extensions/activation-summary-markdown.js\";\nimport type { ExtensionActivationResult, ExtensionLayer, ExtensionLoadResult } from \"../../../core/extensions/loader.js\";\nimport { normalizeExtensionNameForMatch } from \"./shared.js\";\n\n/**\n * Runtime state of a described extension. `ok` loaded and activated cleanly,\n * `failed` loaded but threw during `activate`, and `not_loaded` failed to import\n * at all -- the latter two register nothing, so their `surfaces` are empty and\n * the status explains why (rather than implying the extension contributes\n * nothing).\n */\nexport type ExtensionDescribeActivationStatus = \"ok\" | \"failed\" | \"not_loaded\";\n\n/**\n * One extension's contribution to the workspace: its identity plus the\n * {@link ExtensionActivationSummary} of every surface it registered.\n *\n * `surfaces` is matched by extension *name* (mirroring\n * {@link describeExtensionActivation}'s name filter), so when the same name is\n * loaded in both the project and global layers each entry reflects that name's\n * combined surfaces -- the `layer`/`version` fields still distinguish the\n * physical entries.\n */\nexport interface ExtensionSurfaceDescription {\n  name: string;\n  layer: ExtensionLayer;\n  version: string;\n  activation_status: ExtensionDescribeActivationStatus;\n  surfaces: ExtensionActivationSummary;\n}\n\n/**\n * Result of {@link buildExtensionDescribeResult}: the per-extension surface maps\n * plus a deduplicated `union` across the described set. `target` echoes the\n * requested name filter (or `null` for the whole workspace) and `total` counts\n * the described entries so callers need not re-measure `extensions`.\n */\nexport interface ExtensionDescribeResult {\n  target: string | null;\n  total: number;\n  extensions: ExtensionSurfaceDescription[];\n  union: ExtensionActivationSummary;\n}\n\n/**\n * Compose a collision-free identity key for an extension from its layer and\n * normalized name. The two parts are joined with a colon; the layer prefix is\n * always a colon-free enum value, so distinct (layer, name) pairs never collide\n * even when a name itself contains a colon.\n */\nfunction layerNameKey(layer: ExtensionLayer, name: string): string {\n  return `${layer}:${normalizeExtensionNameForMatch(name)}`;\n}\n\n/**\n * Summarize, by name, every registration surface the loaded extensions exercised.\n *\n * Walks `loadResult.loaded` (annotating each with `failed` when its layer+name is\n * in `activationResult.failed`) and `loadResult.failed` (as `not_loaded`), sorts\n * the entries by name then layer for deterministic output, and attaches each\n * extension's {@link describeExtensionActivation} summary. When `target` is\n * provided only the case-insensitively matching extensions are described and the\n * `union` is scoped to that resolved name set; otherwise every loaded extension contributes.\n * A target may name either the extension itself or its source npm package\n * (`source_package`), so agents can reuse the `package_name` values surfaced by\n * `pm extension list` / install discovery without a second lookup. An unmatched\n * `target` yields an empty `extensions` array -- the caller decides whether that\n * is a not-found error.\n */\nexport function buildExtensionDescribeResult(\n  target: string | undefined,\n  loadResult: ExtensionLoadResult,\n  activationResult: ExtensionActivationResult,\n): ExtensionDescribeResult {\n  const activationFailedKeys = new Set(activationResult.failed.map((entry) => layerNameKey(entry.layer, entry.name)));\n  const candidates: ExtensionSurfaceDescription[] = [\n    ...loadResult.loaded.map((entry) => ({\n      name: entry.name,\n      layer: entry.layer,\n      version: entry.version,\n      activation_status: activationFailedKeys.has(layerNameKey(entry.layer, entry.name))\n        ? (\"failed\" as const)\n        : (\"ok\" as const),\n      surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name }),\n    })),\n    ...loadResult.failed.map((entry) => ({\n      name: entry.name,\n      layer: entry.layer,\n      version: \"unknown\",\n      activation_status: \"not_loaded\" as const,\n      surfaces: describeExtensionActivation(activationResult, { extensionName: entry.name }),\n    })),\n  ].sort((left, right) => left.name.localeCompare(right.name) || left.layer.localeCompare(right.layer));\n\n  const normalizedTarget = typeof target === \"string\" ? normalizeExtensionNameForMatch(target) : null;\n  const matchedNames =\n    normalizedTarget === null\n      ? null\n      : new Set(\n          loadResult.loaded\n            .filter(\n              (entry) =>\n                normalizeExtensionNameForMatch(entry.name) === normalizedTarget ||\n                (typeof entry.source_package === \"string\" &&\n                  normalizeExtensionNameForMatch(entry.source_package) === normalizedTarget),\n            )\n            .map((entry) => normalizeExtensionNameForMatch(entry.name))\n            .concat(normalizedTarget),\n        );\n  const extensions =\n    matchedNames === null ? candidates : candidates.filter((entry) => matchedNames.has(normalizeExtensionNameForMatch(entry.name)));\n  const unionOptions =\n    matchedNames === null\n      ? {}\n      : { extensionNames: [...matchedNames] };\n\n  return {\n    target: typeof target === \"string\" ? target.trim() : null,\n    total: extensions.length,\n    extensions,\n    union: describeExtensionActivation(activationResult, unionOptions),\n  };\n}\n\n/**\n * Human-readable label for each {@link ExtensionDescribeActivationStatus}, used\n * in the Markdown per-extension heading so a reader sees *why* an entry has no\n * surfaces (activation failed / never loaded) rather than assuming it\n * contributes nothing.\n */\nconst ACTIVATION_STATUS_LABELS: Record<ExtensionDescribeActivationStatus, string> = {\n  ok: \"loaded\",\n  failed: \"activation failed\",\n  not_loaded: \"not loaded\",\n};\n\n/**\n * Render an {@link ExtensionDescribeResult} as a Markdown reference document: a\n * top-level title and scope line, one section per described extension (titled\n * with its identity and activation status), and — only when more than one\n * extension was described — a final union section spanning them all. Each\n * extension and the union are rendered with the shared\n * {@link renderExtensionSurfaceMarkdown} primitive at heading level 2, so the\n * document nests cleanly under the level-1 title.\n *\n * `noun` is the lifecycle vocabulary (`\"extension\"` or `\"package\"`) so the prose\n * matches the command the agent invoked. When no extensions match (an unmatched\n * target is already a not-found error upstream, so this is the \"nothing loaded\"\n * case) the document is the title plus a single explanatory note.\n */\nexport function renderExtensionDescribeMarkdown(result: ExtensionDescribeResult, noun: string): string {\n  const titleNoun = `${noun[0]!.toUpperCase()}${noun.slice(1)}`;\n  const lines = [`# ${titleNoun} surface reference`, \"\"];\n  lines.push(result.target === null ? `Scope: all loaded ${noun}s` : `Scope: \\`${result.target}\\``);\n  lines.push(`Described: ${result.total} ${noun}${result.total === 1 ? \"\" : \"s\"}`, \"\");\n\n  if (result.extensions.length === 0) {\n    lines.push(`_No ${noun}s are loaded._`, \"\");\n    return `${lines.join(\"\\n\").trimEnd()}\\n`;\n  }\n\n  for (const entry of result.extensions) {\n    const title = `${entry.name} (${entry.layer} v${entry.version}, ${ACTIVATION_STATUS_LABELS[entry.activation_status]})`;\n    // renderExtensionSurfaceMarkdown already ends with a newline; the join adds a\n    // single blank line between sections, so no extra \"\" separator is pushed.\n    lines.push(renderExtensionSurfaceMarkdown(entry.surfaces, { title, headingLevel: 2 }));\n  }\n\n  if (result.extensions.length > 1) {\n    lines.push(renderExtensionSurfaceMarkdown(result.union, { title: `Union across all described ${noun}s`, headingLevel: 2 }));\n  }\n\n  return `${lines.join(\"\\n\").trimEnd()}\\n`;\n}\n"],"names":[],"mappings":"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","debugId":"19198c42-e182-5131-a1e0-d6421ac4309c"}