@unbrained/pm-cli 2026.7.5 → 2026.7.6

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

@@ -0,0 +1,447 @@
+import {
+  collectBlockedByIds
+} from "./chunk-JJP45OEI.js";
+import {
+  buildItemNotFoundError,
+  listAllFrontMatterLight,
+  locateItem,
+  mutateItem,
+  readLocatedItem,
+  toItemRecord
+} from "./chunk-5VAA4YHR.js";
+import {
+  isTerminalStatus
+} from "./chunk-NMP5I3I5.js";
+import {
+  PmCliError,
+  readSettings
+} from "./chunk-SHQY2IDC.js";
+import {
+  EXIT_CODE,
+  getSettingsPath,
+  pathExists,
+  resolveItemTypeRegistry,
+  resolvePmRoot,
+  resolveRuntimeStatusRegistry
+} from "./chunk-LK6XLOGP.js";
+
+// dist/cli/commands/close.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] = "19dbc992-675b-554c-83bd-4aa14b766810");
+  } catch (e2) {
+  }
+})();
+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, global2) {
+  const pmRoot = resolvePmRoot(process.cwd(), global2.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-W3DSJQIO.js.map