@unbrained/pm-cli 2026.7.5 → 2026.7.6

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

@@ -1,444 +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]="0c02a002-ef0a-50f4-9165-676c2dcfcb8a")}catch(e){}}();
-import {
-  collectBlockedByIds
-} from "./chunk-N6DNM2FA.js";
-import {
-  buildItemNotFoundError,
-  listAllFrontMatterLight,
-  locateItem,
-  mutateItem,
-  readLocatedItem,
-  toItemRecord
-} from "./chunk-57C2RLW5.js";
-import {
-  isTerminalStatus
-} from "./chunk-HK72NWAD.js";
-import {
-  PmCliError,
-  readSettings
-} from "./chunk-US3T3W5J.js";
-import {
-  EXIT_CODE,
-  getSettingsPath,
-  pathExists,
-  resolveItemTypeRegistry,
-  resolvePmRoot,
-  resolveRuntimeStatusRegistry
-} from "./chunk-YD5FML7K.js";
-
-// dist/cli/commands/close.js
-function toAuthor(candidate, defaultAuthor) {
-  const resolved = candidate ?? process.env.PM_AUTHOR ?? defaultAuthor;
-  const trimmed = resolved.trim();
-  return trimmed || "unknown";
-}
-function normalizeCloseReason(reasonText, required) {
-  const reason = (reasonText ?? "").trim();
-  if (reason.length > 0) {
-    return reason;
-  }
-  if (required) {
-    throw new PmCliError("Close reason text is required because governance.require_close_reason is enabled", EXIT_CODE.USAGE, {
-      code: "close_reason_required",
-      required: "Provide a one-line closing summary as the positional text, --reason, or --message.",
-      why: "governance.require_close_reason is enabled, so every close must record why the item is done.",
-      examples: [
-        'pm close <id> "Done: <what changed and why>"',
-        'pm close <id> --reason "<closing summary>"',
-        'pm close <id> -m "<closing summary>"',
-        "pm close <id> --duplicate-of <canonical-id>"
-      ],
-      nextSteps: [
-        "Re-run the close with a closing summary.",
-        'When closing as a duplicate, --duplicate-of <id> auto-fills the close reason as "Duplicate of <id>".',
-        "To stop requiring reasons, run: pm config set governance-require-close-reason --policy disabled"
-      ]
-    });
-  }
-  return void 0;
-}
-function resolveEffectiveCloseReasonText(input) {
-  if ((input.closeReasonText ?? "").trim().length > 0) {
-    return input.closeReasonText;
-  }
-  if (input.duplicateOf !== void 0) {
-    return `Duplicate of ${input.duplicateOf}`;
-  }
-  const trimmedResolution = typeof input.resolution === "string" ? input.resolution.trim() : "";
-  if (trimmedResolution.length > 0) {
-    return trimmedResolution;
-  }
-  const trimmedMessage = typeof input.message === "string" ? input.message.trim() : "";
-  if (input.requireCloseReason && trimmedMessage.length > 0) {
-    return trimmedMessage;
-  }
-  return input.closeReasonText;
-}
-var CLOSE_VALIDATION_FIELDS = [
-  { key: "resolution", label: "resolution" },
-  { key: "expected_result", label: "expected_result" },
-  { key: "actual_result", label: "actual_result" }
-];
-function parseValidateCloseMode(raw) {
-  if (raw === void 0) {
-    return void 0;
-  }
-  const normalized = raw.trim().toLowerCase();
-  if (normalized.length === 0 || normalized === "warn") {
-    return "warn";
-  }
-  if (normalized === "off" || normalized === "none" || normalized === "disabled") {
-    return "off";
-  }
-  if (normalized === "strict") {
-    return "strict";
-  }
-  throw new PmCliError(`Invalid --validate-close mode "${raw}" (expected "off", "warn", or "strict")`, EXIT_CODE.USAGE);
-}
-function findMissingCloseValidationFields(frontMatter) {
-  const missing = [];
-  for (const field of CLOSE_VALIDATION_FIELDS) {
-    const rawValue = frontMatter[field.key];
-    if (typeof rawValue !== "string" || rawValue.trim().length === 0) {
-      missing.push(field.label);
-    }
-  }
-  return missing;
-}
-async function duplicateChainReferencesClosingItem(loadItemById, initialDuplicateOf, closingId) {
-  const visited = /* @__PURE__ */ new Set();
-  let current = initialDuplicateOf;
-  while (typeof current === "string" && current.trim().length > 0) {
-    const currentId = current.trim();
-    if (currentId === closingId) {
-      return true;
-    }
-    if (visited.has(currentId)) {
-      return false;
-    }
-    visited.add(currentId);
-    current = (await loadItemById(currentId))?.duplicate_of;
-  }
-  return false;
-}
-function shouldApplyDuplicateFallback(value) {
-  return typeof value !== "string" || value.trim().length === 0;
-}
-async function assertDuplicateTargetExists(pmRoot, settings, duplicateOf, closingId) {
-  const rawTarget = duplicateOf?.trim();
-  if (!rawTarget) {
-    return void 0;
-  }
-  if (rawTarget === closingId) {
-    throw new PmCliError("An item cannot be closed as a duplicate of itself.", EXIT_CODE.USAGE, {
-      code: "duplicate_target_self",
-      why: "--duplicate-of must identify the canonical item that should remain open or already represent the work."
-    });
-  }
-  const typeRegistry = resolveItemTypeRegistry(settings);
-  const itemCache = /* @__PURE__ */ new Map();
-  const loadItemById = async (id) => {
-    if (itemCache.has(id)) {
-      return itemCache.get(id) ?? null;
-    }
-    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-    if (!located) {
-      itemCache.set(id, null);
-      return null;
-    }
-    const { document } = await readLocatedItem(located, { schema: settings.schema });
-    itemCache.set(id, document.metadata);
-    return document.metadata;
-  };
-  const target = await loadItemById(rawTarget);
-  if (!target) {
-    throw new PmCliError(`Duplicate target "${rawTarget}" was not found. Create or locate the canonical item first.`, EXIT_CODE.USAGE, {
-      code: "duplicate_target_missing",
-      why: "Duplicate closure should point at a real canonical pm item so future dedupe and changelog tooling can trace the relationship.",
-      examples: [`pm close ${closingId} "Duplicate of ${rawTarget}" --duplicate-of ${rawTarget}`],
-      nextSteps: ["Run pm search/list to find the canonical item, then retry with --duplicate-of <id>."]
-    });
-  }
-  if (await duplicateChainReferencesClosingItem(loadItemById, target.duplicate_of, closingId)) {
-    throw new PmCliError(`Circular duplicate reference detected. Target "${rawTarget}" points back to "${closingId}".`, EXIT_CODE.USAGE, {
-      code: "duplicate_target_circular",
-      why: "Circular duplicate relationships create loops for dedupe and status propagation tooling.",
-      nextSteps: ["Choose the existing canonical item, or clear the target duplicate_of metadata before closing this item as a duplicate."]
-    });
-  }
-  if (typeof target.duplicate_of === "string" && target.duplicate_of.trim().length > 0) {
-    throw new PmCliError(`Duplicate target "${rawTarget}" is already marked as a duplicate of "${target.duplicate_of.trim()}".`, EXIT_CODE.USAGE, {
-      code: "duplicate_target_is_duplicate",
-      why: "Duplicate closure should point directly at the canonical item, not another duplicate.",
-      examples: [`pm close ${closingId} "Duplicate of ${target.duplicate_of.trim()}" --duplicate-of ${target.duplicate_of.trim()}`],
-      nextSteps: ["Use the canonical item referenced by duplicate_of as the --duplicate-of target."]
-    });
-  }
-  return target.id;
-}
-async function findActiveChildIds(pmRoot, settings, parentId, statusRegistry) {
-  const typeRegistry = resolveItemTypeRegistry(settings);
-  const items = await listAllFrontMatterLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, void 0, settings.schema);
-  return items.filter((item) => item.parent === parentId && !isTerminalStatus(item.status, statusRegistry)).map((item) => item.id).sort((left, right) => left.localeCompare(right));
-}
-async function findAutoUnblockCandidates(pmRoot, settings, closedId, statusRegistry) {
-  const typeRegistry = resolveItemTypeRegistry(settings);
-  const items = await listAllFrontMatterLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, void 0, settings.schema);
-  const itemsById = new Map(items.map((item) => [item.id, item]));
-  const blockedStatuses = statusRegistry.blocked_statuses;
-  return items.filter((item) => blockedStatuses.has(item.status)).map((item) => ({ item, blockerIds: collectBlockedByIds(item) })).filter(({ blockerIds }) => blockerIds.includes(closedId)).filter(({ blockerIds }) => blockerIds.every((blockerId) => {
-    const blocker = itemsById.get(blockerId);
-    return blocker !== void 0 && isTerminalStatus(blocker.status, statusRegistry);
-  })).map(({ item, blockerIds }) => ({ id: item.id, blocker_ids: blockerIds })).sort((left, right) => left.id.localeCompare(right.id));
-}
-async function autoUnblockResolvedDependents(pmRoot, settings, closedId, author, statusRegistry) {
-  const candidates = await findAutoUnblockCandidates(pmRoot, settings, closedId, statusRegistry);
-  const warnings = [];
-  for (const candidate of candidates) {
-    try {
-      const unblocked = await mutateItem({
-        pmRoot,
-        settings,
-        id: candidate.id,
-        op: "update",
-        author,
-        message: `Auto-unblocked after blocker ${closedId} closed`,
-        mutate(document) {
-          const dependencies = document.metadata.dependencies ?? [];
-          const remainingDependencies = dependencies.filter((dependency) => {
-            const dependencyId = dependency.id.trim();
-            return dependency.kind !== "blocked_by" || !candidate.blocker_ids.includes(dependencyId);
-          });
-          document.metadata.status = statusRegistry.open_status;
-          delete document.metadata.blocked_by;
-          delete document.metadata.blocked_reason;
-          document.metadata.unblock_note = `Auto-unblocked after blocker ${closedId} closed; all blockers resolved (${candidate.blocker_ids.join(", ")}).`;
-          if (remainingDependencies.length > 0) {
-            document.metadata.dependencies = remainingDependencies;
-          } else {
-            delete document.metadata.dependencies;
-          }
-          const changedFields = ["status", "blocked_by", "blocked_reason", "unblock_note"];
-          if (remainingDependencies.length !== dependencies.length) {
-            changedFields.push("dependencies");
-          }
-          return {
-            changedFields
-          };
-        }
-      });
-      warnings.push(`auto_unblocked:${unblocked.item.id}:resolved_blockers=${candidate.blocker_ids.join(",")}`);
-    } catch (error) {
-      const reason = error instanceof Error ? error.message.replace(/\s+/g, " ").trim() : "unknown";
-      warnings.push(`auto_unblock_failed:${candidate.id}:${reason}`);
-    }
-  }
-  return warnings;
-}
-function applyInlineCloseFields(metadata, options) {
-  const changedFields = [];
-  const inlineCloseFields = [
-    { option: options.resolution, key: "resolution" },
-    { option: options.expectedResult, key: "expected_result" },
-    { option: options.actualResult, key: "actual_result" }
-  ];
-  for (const { option, key } of inlineCloseFields) {
-    if (typeof option !== "string") {
-      continue;
-    }
-    const trimmed = option.trim();
-    if (trimmed.length === 0) {
-      continue;
-    }
-    metadata[key] = trimmed;
-    changedFields.push(key);
-  }
-  return changedFields;
-}
-function applyDuplicateCloseMetadata(metadata, duplicateOf) {
-  if (duplicateOf === void 0) {
-    return [];
-  }
-  metadata.duplicate_of = duplicateOf;
-  const duplicateFallbackFields = [];
-  const fallbackValues = [
-    { key: "resolution", value: `Duplicate of ${duplicateOf}` },
-    { key: "expected_result", value: `Canonical item ${duplicateOf} tracks the work.` },
-    { key: "actual_result", value: `Closed as duplicate of ${duplicateOf}.` }
-  ];
-  for (const { key, value } of fallbackValues) {
-    if (shouldApplyDuplicateFallback(metadata[key])) {
-      metadata[key] = value;
-      duplicateFallbackFields.push(key);
-    }
-  }
-  return duplicateFallbackFields;
-}
-function collectCloseValidationWarnings(metadata, validateCloseMode, activeChildIds) {
-  const warnings = [];
-  if (validateCloseMode !== "off") {
-    const missingFields = findMissingCloseValidationFields(metadata);
-    if (missingFields.length > 0) {
-      if (validateCloseMode === "strict") {
-        throw new PmCliError(`Cannot close item ${metadata.id}: missing ${missingFields.join(", ")}. Populate fields or use --validate-close warn.`, EXIT_CODE.USAGE);
-      }
-      warnings.push(`close_validation_missing_fields:${metadata.id}:${missingFields.join(",")}`);
-    }
-    if (activeChildIds.length > 0) {
-      if (validateCloseMode === "strict") {
-        throw new PmCliError(`Cannot close item ${metadata.id}: active child items remain open (${activeChildIds.join(", ")}). Close, cancel, or re-parent them first, or use --validate-close warn.`, EXIT_CODE.USAGE);
-      }
-      warnings.push(`close_validation_active_children:${metadata.id}:${activeChildIds.join(",")}`);
-    }
-    return warnings;
-  }
-  if (activeChildIds.length > 0) {
-    warnings.push(`closed_with_active_children:${metadata.id}:${activeChildIds.join(",")}`);
-  }
-  return warnings;
-}
-function applyCloseReason(metadata, closeReason) {
-  if (closeReason !== void 0) {
-    metadata.close_reason = closeReason;
-    return ["close_reason"];
-  }
-  if (metadata.close_reason !== void 0) {
-    delete metadata.close_reason;
-    return ["close_reason"];
-  }
-  return [];
-}
-function clearCloseAssignee(metadata) {
-  if (metadata.assignee === void 0) {
-    return [];
-  }
-  delete metadata.assignee;
-  return ["assignee"];
-}
-function clearClosedBlockerSignals(metadata) {
-  const previousBlockedBy = typeof metadata.blocked_by === "string" ? metadata.blocked_by.trim() : "";
-  const existingDeps = metadata.dependencies ?? [];
-  const blockedByEdge = existingDeps.find((dep) => dep.kind === "blocked_by");
-  const hadBlockedReason = metadata.blocked_reason !== void 0;
-  if (previousBlockedBy.length === 0 && blockedByEdge === void 0 && !hadBlockedReason) {
-    return { changedFields: [], warnings: [] };
-  }
-  const changedFields = [];
-  if (previousBlockedBy.length > 0) {
-    delete metadata.blocked_by;
-    changedFields.push("blocked_by");
-  }
-  if (hadBlockedReason) {
-    delete metadata.blocked_reason;
-    changedFields.push("blocked_reason");
-  }
-  if (blockedByEdge !== void 0) {
-    const remainingDeps = existingDeps.filter((dep) => dep.kind !== "blocked_by");
-    if (remainingDeps.length > 0) {
-      metadata.dependencies = remainingDeps;
-    } else {
-      delete metadata.dependencies;
-    }
-    changedFields.push("dependencies");
-  }
-  const reportedBlocker = previousBlockedBy || blockedByEdge?.id;
-  return {
-    changedFields,
-    warnings: reportedBlocker ? [`closed_cleared_blocked_by:${metadata.id}:${reportedBlocker}`] : []
-  };
-}
-function mutateCloseMetadata(metadata, context) {
-  if (isTerminalStatus(metadata.status, context.statusRegistry) && !context.force) {
-    throw new PmCliError(`Item ${metadata.id} is already terminal; use --force to close again.`, EXIT_CODE.CONFLICT);
-  }
-  const inlineChangedFields = applyInlineCloseFields(metadata, context.options);
-  const duplicateFallbackFields = applyDuplicateCloseMetadata(metadata, context.duplicateOf);
-  const mutationWarnings = collectCloseValidationWarnings(metadata, context.validateCloseMode, context.activeChildIds);
-  metadata.status = context.statusRegistry.close_status;
-  const changedFields = [
-    "status",
-    ...applyCloseReason(metadata, context.closeReason),
-    ...inlineChangedFields
-  ];
-  if (context.duplicateOf !== void 0) {
-    changedFields.push("duplicate_of");
-    for (const key of duplicateFallbackFields) {
-      if (!changedFields.includes(key)) {
-        changedFields.push(key);
-      }
-    }
-  }
-  changedFields.push(...clearCloseAssignee(metadata));
-  const blockerCleanup = clearClosedBlockerSignals(metadata);
-  changedFields.push(...blockerCleanup.changedFields);
-  mutationWarnings.push(...blockerCleanup.warnings);
-  return {
-    changedFields,
-    ...mutationWarnings.length > 0 ? { warnings: mutationWarnings } : {}
-  };
-}
-var _testOnlyCloseCommand = {
-  blockedByIds: collectBlockedByIds
-};
-async function runClose(id, closeReasonText, options, global) {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  if (!await pathExists(getSettingsPath(pmRoot))) {
-    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-  }
-  const settings = await readSettings(pmRoot);
-  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
-  const author = toAuthor(options.author, settings.author_default);
-  const typeToFolder = resolveItemTypeRegistry(settings).type_to_folder;
-  const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeToFolder);
-  if (!located) {
-    throw await buildItemNotFoundError(pmRoot, id, settings.id_prefix, typeToFolder);
-  }
-  const duplicateOf = await assertDuplicateTargetExists(pmRoot, settings, options.duplicateOf, id);
-  const effectiveCloseReasonText = resolveEffectiveCloseReasonText({
-    closeReasonText,
-    duplicateOf,
-    resolution: options.resolution,
-    message: options.message,
-    requireCloseReason: settings.governance.require_close_reason
-  });
-  const closeReason = normalizeCloseReason(effectiveCloseReasonText, settings.governance.require_close_reason);
-  const validateCloseMode = parseValidateCloseMode(options.validateClose) ?? settings.governance.close_validation_default;
-  const activeChildIds = await findActiveChildIds(pmRoot, settings, id, statusRegistry);
-  const result = await mutateItem({
-    pmRoot,
-    settings,
-    id,
-    op: "close",
-    author,
-    message: options.message,
-    force: options.force,
-    mutate(document) {
-      return mutateCloseMetadata(document.metadata, {
-        statusRegistry,
-        force: options.force,
-        options,
-        duplicateOf,
-        validateCloseMode,
-        activeChildIds,
-        closeReason
-      });
-    }
-  });
-  return {
-    item: toItemRecord(result.item),
-    changed_fields: result.changedFields,
-    warnings: [
-      ...result.warnings,
-      ...await autoUnblockResolvedDependents(pmRoot, settings, located.id, author, statusRegistry)
-    ]
-  };
-}
-
-export {
-  _testOnlyCloseCommand,
-  runClose
-};
-//# sourceMappingURL=chunk-K3AGVXSF.js.map
-
-//# debugId=0c02a002-ef0a-50f4-9165-676c2dcfcb8a

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

@@ -1,79 +0,0 @@
-import {
-  normalizeExtensionNameForMatch
-} from "./chunk-R3ZBLGTC.js";
-import {
-  describeExtensionActivation,
-  renderExtensionSurfaceMarkdown
-} from "./chunk-C3PMDWGX.js";
-
-// dist/cli/commands/extension/describe.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] = "a0c1f4a6-427b-5cd4-bf6e-9bf77f83bf3f");
-  } catch (e2) {
-  }
-})();
-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-KDZ6K25I.js.map

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

@@ -1,7 +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"],
-  "mappings": ";;;;;;;;;;;;;;;;AAqEA,SAAS,aAAa,OAAuB,MAAY;AACvD,SAAO,GAAG,KAAK,IAAI,+BAA+B,IAAI,CAAC;AACzD;AAiBM,SAAU,6BACd,QACA,YACA,kBAA2C;AAE3C,QAAM,uBAAuB,IAAI,IAAI,iBAAiB,OAAO,IAAI,CAAC,UAAU,aAAa,MAAM,OAAO,MAAM,IAAI,CAAC,CAAC;AAClH,QAAM,aAA4C;IAChD,GAAG,WAAW,OAAO,IAAI,CAAC,WAAW;MACnC,MAAM,MAAM;MACZ,OAAO,MAAM;MACb,SAAS,MAAM;MACf,mBAAmB,qBAAqB,IAAI,aAAa,MAAM,OAAO,MAAM,IAAI,CAAC,IAC5E,WACA;MACL,UAAU,4BAA4B,kBAAkB,EAAE,eAAe,MAAM,KAAI,CAAE;MACrF;IACF,GAAG,WAAW,OAAO,IAAI,CAAC,WAAW;MACnC,MAAM,MAAM;MACZ,OAAO,MAAM;MACb,SAAS;MACT,mBAAmB;MACnB,UAAU,4BAA4B,kBAAkB,EAAE,eAAe,MAAM,KAAI,CAAE;MACrF;IACF,KAAK,CAAC,MAAM,UAAU,KAAK,KAAK,cAAc,MAAM,IAAI,KAAK,KAAK,MAAM,cAAc,MAAM,KAAK,CAAC;AAEpG,QAAM,mBAAmB,OAAO,WAAW,WAAW,+BAA+B,MAAM,IAAI;AAC/F,QAAM,eACJ,qBAAqB,OACjB,OACA,IAAI,IACF,WAAW,OACR,OACC,CAAC,UACC,+BAA+B,MAAM,IAAI,MAAM,oBAC9C,OAAO,MAAM,mBAAmB,YAC/B,+BAA+B,MAAM,cAAc,MAAM,gBAAiB,EAE/E,IAAI,CAAC,UAAU,+BAA+B,MAAM,IAAI,CAAC,EACzD,OAAO,gBAAgB,CAAC;AAEnC,QAAM,aACJ,iBAAiB,OAAO,aAAa,WAAW,OAAO,CAAC,UAAU,aAAa,IAAI,+BAA+B,MAAM,IAAI,CAAC,CAAC;AAChI,QAAM,eACJ,iBAAiB,OACb,CAAA,IACA,EAAE,gBAAgB,CAAC,GAAG,YAAY,EAAC;AAEzC,SAAO;IACL,QAAQ,OAAO,WAAW,WAAW,OAAO,KAAI,IAAK;IACrD,OAAO,WAAW;IAClB;IACA,OAAO,4BAA4B,kBAAkB,YAAY;;AAErE;AAQA,IAAM,2BAA8E;EAClF,IAAI;EACJ,QAAQ;EACR,YAAY;;AAiBR,SAAU,gCAAgC,QAAiC,MAAY;AAC3F,QAAM,YAAY,GAAG,KAAK,CAAC,EAAG,YAAW,CAAE,GAAG,KAAK,MAAM,CAAC,CAAC;AAC3D,QAAM,QAAQ,CAAC,KAAK,SAAS,sBAAsB,EAAE;AACrD,QAAM,KAAK,OAAO,WAAW,OAAO,qBAAqB,IAAI,MAAM,YAAY,OAAO,MAAM,IAAI;AAChG,QAAM,KAAK,cAAc,OAAO,KAAK,IAAI,IAAI,GAAG,OAAO,UAAU,IAAI,KAAK,GAAG,IAAI,EAAE;AAEnF,MAAI,OAAO,WAAW,WAAW,GAAG;AAClC,UAAM,KAAK,OAAO,IAAI,kBAAkB,EAAE;AAC1C,WAAO,GAAG,MAAM,KAAK,IAAI,EAAE,QAAO,CAAE;;EACtC;AAEA,aAAW,SAAS,OAAO,YAAY;AACrC,UAAM,QAAQ,GAAG,MAAM,IAAI,KAAK,MAAM,KAAK,KAAK,MAAM,OAAO,KAAK,yBAAyB,MAAM,iBAAiB,CAAC;AAGnH,UAAM,KAAK,+BAA+B,MAAM,UAAU,EAAE,OAAO,cAAc,EAAC,CAAE,CAAC;EACvF;AAEA,MAAI,OAAO,WAAW,SAAS,GAAG;AAChC,UAAM,KAAK,+BAA+B,OAAO,OAAO,EAAE,OAAO,8BAA8B,IAAI,KAAK,cAAc,EAAC,CAAE,CAAC;EAC5H;AAEA,SAAO,GAAG,MAAM,KAAK,IAAI,EAAE,QAAO,CAAE;;AACtC;",
-  "names": []
-}