@unbrained/pm-cli 2026.7.13 → 2026.7.14

package/dist/sdk/dependencies.js

@@ -0,0 +1,327 @@
+/**
+ * @module sdk/dependencies
+ *
+ * Implements the pm deps command surface and its agent-facing runtime behavior.
+ */
+
+!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]="27ed78ad-a876-57b7-8604-51a45d22d0f4")}catch(e){}}();
+import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
+import { pathExists } from "../core/fs/fs-utils.js";
+import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+import { isTerminalStatus } from "../core/item/status.js";
+import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { listAllItemMetadataLight } from "../core/store/item-store.js";
+import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { readSettings } from "../core/store/settings.js";
+/** Supported values accepted by the deps format contract. */
+export const DEPS_FORMAT_VALUES = ["tree", "graph"];
+/** Supported values accepted by the deps collapse contract. */
+export const DEPS_COLLAPSE_VALUES = ["none", "repeated"];
+/**
+ * Classify missing hierarchy and dependency targets without mutating their holders.
+ *
+ * Consumers provide the workspace's terminal-status predicate so custom lifecycle
+ * schemas receive the same active-versus-historical behavior as the built-in
+ * closed/canceled statuses.
+ */
+export function collectDanglingDependencyReferences(items, isTerminal = (status) => status === "closed" || status === "canceled") {
+    const knownIds = new Set(items.map((item) => item.id.trim().toLowerCase()));
+    const rows = new Map();
+    const addReference = (item, target, kind, source) => {
+        const normalized = typeof target === "string" ? target.trim() : "";
+        if (!normalized ||
+            ["none", "null", "n/a", "na"].includes(normalized.toLowerCase()) ||
+            knownIds.has(normalized.toLowerCase())) {
+            return;
+        }
+        const row = {
+            holder_id: item.id,
+            target_id: normalized,
+            kind,
+            source,
+            holder_status: item.status,
+            legacy_terminal: isTerminal(item.status),
+            no_active_blocker_sentinel: normalized.toLowerCase() === "no-active-blocker",
+        };
+        rows.set(`${row.holder_id}::${row.target_id}::${row.kind}::${row.source}`, row);
+    };
+    for (const item of items) {
+        addReference(item, item.parent, "parent", "parent");
+        addReference(item, item.blocked_by, "blocked_by", "blocked_by");
+        for (const dependency of item.dependencies ?? []) {
+            // Public SDK callers may supply legacy or JSON-decoded payloads that do
+            // not yet satisfy the current structured dependency contract.
+            if (typeof dependency !== "object" || dependency === null) {
+                continue;
+            }
+            const legacyDependency = dependency;
+            addReference(item, legacyDependency.id, typeof legacyDependency.kind === "string"
+                ? legacyDependency.kind
+                : "related", "dependency");
+        }
+    }
+    const sorted = [...rows.values()].sort((left, right) => left.holder_id.localeCompare(right.holder_id) ||
+        left.target_id.localeCompare(right.target_id) ||
+        left.kind.localeCompare(right.kind) ||
+        left.source.localeCompare(right.source));
+    const legacyTerminal = sorted.filter((row) => row.legacy_terminal);
+    return {
+        active: sorted.filter((row) => !row.legacy_terminal),
+        legacy_terminal: legacyTerminal,
+        no_active_blocker_sentinels: sorted.filter((row) => row.no_active_blocker_sentinel),
+    };
+}
+function parseFormat(raw) {
+    const candidate = raw?.trim().toLowerCase() ?? "tree";
+    if (DEPS_FORMAT_VALUES.includes(candidate)) {
+        return candidate;
+    }
+    throw new PmCliError(`Invalid --format value "${raw}". Use "tree" or "graph".`, EXIT_CODE.USAGE);
+}
+function parseMaxDepth(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const normalized = typeof raw === "number" ? raw : Number(raw.trim());
+    if (!Number.isInteger(normalized) || normalized < 0) {
+        throw new PmCliError(`Invalid --max-depth value "${raw}". Use a non-negative integer.`, EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+function parseCollapse(raw) {
+    const candidate = raw?.trim().toLowerCase() ?? "none";
+    if (DEPS_COLLAPSE_VALUES.includes(candidate)) {
+        return candidate;
+    }
+    throw new PmCliError(`Invalid --collapse value "${raw}". Use "none" or "repeated".`, EXIT_CODE.USAGE);
+}
+function normalizeDependencies(dependencies) {
+    if (!dependencies || dependencies.length === 0) {
+        return [];
+    }
+    const sorted = dependencies.map(({ id, kind }) => ({
+        id: id.trim(),
+        kind: kind.trim().toLowerCase(),
+    })).sort((left, right) => {
+        const byKind = left.kind.localeCompare(right.kind);
+        if (byKind !== 0)
+            return byKind;
+        return left.id.localeCompare(right.id);
+    });
+    const deduped = new Map();
+    for (const dependency of sorted) {
+        const key = `${dependency.kind.toLowerCase()}::${dependency.id.toLowerCase()}`;
+        if (!deduped.has(key)) {
+            deduped.set(key, { id: dependency.id, kind: dependency.kind });
+        }
+    }
+    return [...deduped.values()];
+}
+function toIndexedItem(item) {
+    return {
+        id: item.id,
+        title: item.title,
+        type: item.type,
+        status: item.status,
+        dependencies: normalizeDependencies(item.dependencies),
+    };
+}
+function toTreeNode(id, index, lineage, maxDepth, collapse, expanded, depth = 0, via) {
+    const lookupId = id.trim().toLowerCase();
+    const item = index.get(lookupId);
+    const baseNode = {
+        id: item?.id ?? id,
+        title: item?.title,
+        type: item?.type,
+        status: item?.status,
+        via,
+        missing: !item,
+        cycle: lineage.has(lookupId),
+        dependencies: [],
+    };
+    if (!item || baseNode.cycle) {
+        return baseNode;
+    }
+    if (maxDepth !== undefined && depth >= maxDepth) {
+        if (item.dependencies.length > 0) {
+            baseNode.truncated = true;
+        }
+        return baseNode;
+    }
+    if (collapse === "repeated" && expanded.has(lookupId)) {
+        baseNode.collapsed = true;
+        return baseNode;
+    }
+    if (collapse === "repeated") {
+        expanded.add(lookupId);
+    }
+    const nextLineage = new Set(lineage);
+    nextLineage.add(lookupId);
+    baseNode.dependencies = item.dependencies.map((dependency) => toTreeNode(dependency.id, index, nextLineage, maxDepth, collapse, expanded, depth + 1, dependency.kind));
+    return baseNode;
+}
+function mergeGraphNode(existing, candidate) {
+    if (!existing) {
+        return candidate;
+    }
+    /* c8 ignore start -- defensive: mixed missing/non-missing duplicates only occur in malformed synthetic trees. */
+    if (existing.missing && !candidate.missing)
+        return candidate;
+    /* c8 ignore stop */
+    return {
+        ...existing,
+        title: existing.title ?? candidate.title,
+        type: existing.type ?? candidate.type,
+        status: existing.status ?? candidate.status,
+    };
+}
+function toGraph(root) {
+    const nodesById = new Map();
+    const edgesByKey = new Map();
+    const visit = (node) => {
+        nodesById.set(node.id, mergeGraphNode(nodesById.get(node.id), {
+            id: node.id,
+            title: node.title,
+            type: node.type,
+            status: node.status,
+            missing: node.missing,
+        }));
+        for (const child of node.dependencies) {
+            nodesById.set(child.id, mergeGraphNode(nodesById.get(child.id), {
+                id: child.id,
+                title: child.title,
+                type: child.type,
+                status: child.status,
+                missing: child.missing,
+            }));
+            /* c8 ignore start -- legacy malformed dependency payloads may omit kind/via. */
+            const relationKind = child.via ?? "related";
+            const edgeKey = `${node.id}::${child.id}::${relationKind}`;
+            if (!edgesByKey.has(edgeKey)) {
+                edgesByKey.set(edgeKey, {
+                    from: node.id,
+                    to: child.id,
+                    kind: relationKind,
+                });
+            }
+            /* c8 ignore stop */
+            if (!child.cycle) {
+                visit(child);
+            }
+        }
+    };
+    visit(root);
+    const nodes = [...nodesById.values()].sort((left, right) => left.id.localeCompare(right.id));
+    const edges = [...edgesByKey.values()].sort((left, right) => {
+        const byFrom = left.from.localeCompare(right.from);
+        if (byFrom !== 0)
+            return byFrom;
+        const byTo = left.to.localeCompare(right.to);
+        if (byTo !== 0)
+            return byTo;
+        return left.kind.localeCompare(right.kind);
+    });
+    const missingIds = nodes
+        .filter((node) => node.missing)
+        .map((node) => node.id);
+    return {
+        root_id: root.id,
+        nodes,
+        edges,
+        missing_ids: missingIds,
+    };
+}
+/** Count a dependency result without allocating its potentially exponential tree payload. */
+function countDependencyGraph(rootId, index, maxDepth) {
+    const nodeIds = new Set();
+    const edgeKeys = new Set();
+    const missingIds = new Set();
+    const expanded = new Set();
+    const pending = [{ id: rootId, depth: 0 }];
+    let pendingIndex = 0;
+    while (pendingIndex < pending.length) {
+        const current = pending[pendingIndex++];
+        const lookupId = current.id.trim().toLowerCase();
+        nodeIds.add(lookupId);
+        const item = index.get(lookupId);
+        if (!item) {
+            missingIds.add(lookupId);
+            continue;
+        }
+        if (maxDepth !== undefined && current.depth >= maxDepth) {
+            continue;
+        }
+        if (expanded.has(lookupId)) {
+            continue;
+        }
+        expanded.add(lookupId);
+        for (const dependency of item.dependencies) {
+            edgeKeys.add(`${lookupId}::${dependency.id.trim().toLowerCase()}::${dependency.kind}`);
+            pending.push({ id: dependency.id, depth: current.depth + 1 });
+        }
+    }
+    return {
+        node_count: nodeIds.size,
+        edge_count: edgeKeys.size,
+        missing_count: missingIds.size,
+    };
+}
+/** Implements run deps for the public runtime surface of this module. */
+export async function runDeps(id, 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 format = parseFormat(options.format);
+    const maxDepth = parseMaxDepth(options.maxDepth);
+    const collapse = parseCollapse(options.collapse);
+    const summaryOnly = options.summary === true;
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const items = await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const index = new Map(items.map((item) => [item.id.trim().toLowerCase(), toIndexedItem(item)]));
+    const dangling = collectDanglingDependencyReferences(items, (status) => isTerminalStatus(status, statusRegistry));
+    for (const reference of [...dangling.active, ...dangling.legacy_terminal]) {
+        const holder = index.get(reference.holder_id.trim().toLowerCase());
+        const referenceKind = reference.kind.trim().toLowerCase();
+        if (holder &&
+            !holder.dependencies.some((dependency) => dependency.id.trim().toLowerCase() === reference.target_id.trim().toLowerCase() &&
+                dependency.kind === referenceKind)) {
+            holder.dependencies.push({ id: reference.target_id, kind: referenceKind });
+        }
+    }
+    if (!index.has(id.trim().toLowerCase())) {
+        throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    if (summaryOnly) {
+        return {
+            id,
+            format,
+            ...countDependencyGraph(id, index, maxDepth),
+        };
+    }
+    const tree = toTreeNode(id, index, new Set(), maxDepth, collapse, new Set());
+    const graph = toGraph(tree);
+    const baseResult = {
+        id,
+        format,
+        node_count: graph.nodes.length,
+        edge_count: graph.edges.length,
+        missing_count: graph.missing_ids.length,
+    };
+    if (format === "tree") {
+        return {
+            ...baseResult,
+            tree,
+        };
+    }
+    return {
+        ...baseResult,
+        graph,
+    };
+}
+//# sourceMappingURL=dependencies.js.map
+//# debugId=27ed78ad-a876-57b7-8604-51a45d22d0f4

package/dist/sdk/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sources":["sdk/dependencies.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/dependencies\n *\n * Implements the pm deps command surface and its agent-facing runtime behavior.\n */\nimport { getActiveExtensionRegistrations } from \"../core/extensions/index.js\";\nimport { pathExists } from \"../core/fs/fs-utils.js\";\nimport { resolveItemTypeRegistry } from \"../core/item/type-registry.js\";\nimport { isTerminalStatus } from \"../core/item/status.js\";\nimport { resolveRuntimeStatusRegistry } from \"../core/schema/runtime-schema.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 { listAllItemMetadataLight } from \"../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../core/store/paths.js\";\nimport { readSettings } from \"../core/store/settings.js\";\nimport type {\n  Dependency,\n  ItemMetadata,\n  ItemStatus,\n  ItemType,\n} from \"../types/index.js\";\n\n/** Supported values accepted by the deps format contract. */\nexport const DEPS_FORMAT_VALUES = [\"tree\", \"graph\"] as const;\n/** Restricts deps format values accepted by command, SDK, and storage contracts. */\nexport type DepsFormat = (typeof DEPS_FORMAT_VALUES)[number];\n/** Supported values accepted by the deps collapse contract. */\nexport const DEPS_COLLAPSE_VALUES = [\"none\", \"repeated\"] as const;\n/** Restricts deps collapse mode values accepted by command, SDK, and storage contracts. */\nexport type DepsCollapseMode = (typeof DEPS_COLLAPSE_VALUES)[number];\n\n/** Documents the deps command options payload exchanged by command, SDK, and package integrations. */\nexport interface DepsCommandOptions {\n  /** Value that configures or reports format for this contract. */\n  format?: string;\n  /** Value that configures or reports max depth for this contract. */\n  maxDepth?: string | number;\n  /** Value that configures or reports collapse for this contract. */\n  collapse?: string;\n  /** Value that configures or reports summary for this contract. */\n  summary?: boolean;\n}\n\ninterface IndexedItem {\n  id: string;\n  title: string;\n  type: ItemType;\n  status: ItemStatus;\n  dependencies: IndexedDependency[];\n}\n\ninterface IndexedDependency {\n  id: string;\n  kind: string;\n}\n\n/** Minimal item shape inspected by dependency-reference governance. */\nexport interface DependencyReferenceHolder {\n  /** Stable item identifier. */\n  id: string;\n  /** Lifecycle status used to separate actionable work from historical debt. */\n  status: ItemStatus;\n  /** Optional hierarchy parent reference. */\n  parent?: string;\n  /** Optional legacy scalar blocker reference. */\n  blocked_by?: string;\n  /** Structured dependency edges. */\n  dependencies?: Dependency[];\n}\n\n/** Storage surface that contributed a normalized dependency reference. */\nexport type DependencyReferenceSource = \"parent\" | \"blocked_by\" | \"dependency\";\n\n/** One normalized dependency reference whose target is absent from the tracker. */\nexport interface DanglingDependencyReference {\n  /** Item that owns the reference. */\n  holder_id: string;\n  /** Missing referenced item id or legacy sentinel. */\n  target_id: string;\n  /** Relationship field or dependency kind. */\n  kind: string;\n  /** Storage surface that owns the reference and determines its remediation. */\n  source: DependencyReferenceSource;\n  /** Current lifecycle status of the holder. */\n  holder_status: ItemStatus;\n  /** Whether the holder is terminal and therefore historical, non-actionable debt. */\n  legacy_terminal: boolean;\n  /** Whether the target is the pre-structured-dependency `no-active-blocker` sentinel. */\n  no_active_blocker_sentinel: boolean;\n}\n\n/** Actionable and historical partitions returned by dependency-reference governance. */\nexport interface DanglingDependencyReferenceSummary {\n  /** Missing references held by active items; these may affect scheduling and should gate validation. */\n  active: DanglingDependencyReference[];\n  /** Missing references held only by terminal items; retained as informational history debt. */\n  legacy_terminal: DanglingDependencyReference[];\n  /** Legacy sentinel rows across active and terminal holders, called out separately from typo-like ids. */\n  no_active_blocker_sentinels: DanglingDependencyReference[];\n}\n\n/**\n * Classify missing hierarchy and dependency targets without mutating their holders.\n *\n * Consumers provide the workspace's terminal-status predicate so custom lifecycle\n * schemas receive the same active-versus-historical behavior as the built-in\n * closed/canceled statuses.\n */\nexport function collectDanglingDependencyReferences(\n  items: readonly DependencyReferenceHolder[],\n  isTerminal: (status: ItemStatus) => boolean = (status) =>\n    status === \"closed\" || status === \"canceled\",\n): DanglingDependencyReferenceSummary {\n  const knownIds = new Set(items.map((item) => item.id.trim().toLowerCase()));\n  const rows = new Map<string, DanglingDependencyReference>();\n  const addReference = (\n    item: DependencyReferenceHolder,\n    target: unknown,\n    kind: string,\n    source: DependencyReferenceSource,\n  ): void => {\n    const normalized = typeof target === \"string\" ? target.trim() : \"\";\n    if (\n      !normalized ||\n      [\"none\", \"null\", \"n/a\", \"na\"].includes(normalized.toLowerCase()) ||\n      knownIds.has(normalized.toLowerCase())\n    ) {\n      return;\n    }\n    const row: DanglingDependencyReference = {\n      holder_id: item.id,\n      target_id: normalized,\n      kind,\n      source,\n      holder_status: item.status,\n      legacy_terminal: isTerminal(item.status),\n      no_active_blocker_sentinel:\n        normalized.toLowerCase() === \"no-active-blocker\",\n    };\n    rows.set(\n      `${row.holder_id}::${row.target_id}::${row.kind}::${row.source}`,\n      row,\n    );\n  };\n  for (const item of items) {\n    addReference(item, item.parent, \"parent\", \"parent\");\n    addReference(item, item.blocked_by, \"blocked_by\", \"blocked_by\");\n    for (const dependency of item.dependencies ?? []) {\n      // Public SDK callers may supply legacy or JSON-decoded payloads that do\n      // not yet satisfy the current structured dependency contract.\n      if (typeof dependency !== \"object\" || dependency === null) {\n        continue;\n      }\n      const legacyDependency = dependency as Partial<Dependency>;\n      addReference(\n        item,\n        legacyDependency.id,\n        typeof legacyDependency.kind === \"string\"\n          ? legacyDependency.kind\n          : \"related\",\n        \"dependency\",\n      );\n    }\n  }\n  const sorted = [...rows.values()].sort(\n    (left, right) =>\n      left.holder_id.localeCompare(right.holder_id) ||\n      left.target_id.localeCompare(right.target_id) ||\n      left.kind.localeCompare(right.kind) ||\n      left.source.localeCompare(right.source),\n  );\n  const legacyTerminal = sorted.filter((row) => row.legacy_terminal);\n  return {\n    active: sorted.filter((row) => !row.legacy_terminal),\n    legacy_terminal: legacyTerminal,\n    no_active_blocker_sentinels: sorted.filter(\n      (row) => row.no_active_blocker_sentinel,\n    ),\n  };\n}\n\n/** Documents the deps tree node payload exchanged by command, SDK, and package integrations. */\nexport interface DepsTreeNode {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports title for this contract. */\n  title?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type?: ItemType;\n  /** Lifecycle state reported for status. */\n  status?: ItemStatus;\n  /** Value that configures or reports via for this contract. */\n  via?: string;\n  /** Value that configures or reports missing for this contract. */\n  missing: boolean;\n  /** Value that configures or reports cycle for this contract. */\n  cycle: boolean;\n  /** Value that configures or reports truncated for this contract. */\n  truncated?: boolean;\n  /** Value that configures or reports collapsed for this contract. */\n  collapsed?: boolean;\n  /** Value that configures or reports dependencies for this contract. */\n  dependencies: DepsTreeNode[];\n}\n\n/** Documents the deps graph node payload exchanged by command, SDK, and package integrations. */\nexport interface DepsGraphNode {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports title for this contract. */\n  title?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type?: ItemType;\n  /** Lifecycle state reported for status. */\n  status?: ItemStatus;\n  /** Value that configures or reports missing for this contract. */\n  missing: boolean;\n}\n\n/** Documents the deps graph edge payload exchanged by command, SDK, and package integrations. */\nexport interface DepsGraphEdge {\n  /** Value that configures or reports from for this contract. */\n  from: string;\n  /** Value that configures or reports to for this contract. */\n  to: string;\n  /** Value that configures or reports kind for this contract. */\n  kind: string;\n}\n\n/** Documents the deps graph result payload exchanged by command, SDK, and package integrations. */\nexport interface DepsGraphResult {\n  /** Value that configures or reports root id for this contract. */\n  root_id: string;\n  /** Value that configures or reports nodes for this contract. */\n  nodes: DepsGraphNode[];\n  /** Value that configures or reports edges for this contract. */\n  edges: DepsGraphEdge[];\n  /** Value that configures or reports missing ids for this contract. */\n  missing_ids: string[];\n}\n\n/** Documents the deps result payload exchanged by command, SDK, and package integrations. */\nexport interface DepsResult {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports format for this contract. */\n  format: DepsFormat;\n  /** Number of node entries represented by this result. */\n  node_count: number;\n  /** Number of edge entries represented by this result. */\n  edge_count: number;\n  /** Number of missing entries represented by this result. */\n  missing_count: number;\n  /** Value that configures or reports tree for this contract. */\n  tree?: DepsTreeNode;\n  /** Value that configures or reports graph for this contract. */\n  graph?: DepsGraphResult;\n}\n\nfunction parseFormat(raw: string | undefined): DepsFormat {\n  const candidate = raw?.trim().toLowerCase() ?? \"tree\";\n  if ((DEPS_FORMAT_VALUES as readonly string[]).includes(candidate)) {\n    return candidate as DepsFormat;\n  }\n  throw new PmCliError(\n    `Invalid --format value \"${raw}\". Use \"tree\" or \"graph\".`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nfunction parseMaxDepth(raw: string | number | undefined): number | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const normalized = typeof raw === \"number\" ? raw : Number(raw.trim());\n  if (!Number.isInteger(normalized) || normalized < 0) {\n    throw new PmCliError(\n      `Invalid --max-depth value \"${raw}\". Use a non-negative integer.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return normalized;\n}\n\nfunction parseCollapse(raw: string | undefined): DepsCollapseMode {\n  const candidate = raw?.trim().toLowerCase() ?? \"none\";\n  if ((DEPS_COLLAPSE_VALUES as readonly string[]).includes(candidate)) {\n    return candidate as DepsCollapseMode;\n  }\n  throw new PmCliError(\n    `Invalid --collapse value \"${raw}\". Use \"none\" or \"repeated\".`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nfunction normalizeDependencies(\n  dependencies: Dependency[] | undefined,\n): IndexedDependency[] {\n  if (!dependencies || dependencies.length === 0) {\n    return [];\n  }\n  const sorted = dependencies.map(({ id, kind }) => ({\n    id: id.trim(),\n    kind: kind.trim().toLowerCase(),\n  })).sort((left, right) => {\n    const byKind = left.kind.localeCompare(right.kind);\n    if (byKind !== 0) return byKind;\n    return left.id.localeCompare(right.id);\n  });\n  const deduped = new Map<string, IndexedDependency>();\n  for (const dependency of sorted) {\n    const key = `${dependency.kind.toLowerCase()}::${dependency.id.toLowerCase()}`;\n    if (!deduped.has(key)) {\n      deduped.set(key, { id: dependency.id, kind: dependency.kind });\n    }\n  }\n  return [...deduped.values()];\n}\n\nfunction toIndexedItem(item: ItemMetadata): IndexedItem {\n  return {\n    id: item.id,\n    title: item.title,\n    type: item.type,\n    status: item.status,\n    dependencies: normalizeDependencies(item.dependencies),\n  };\n}\n\nfunction toTreeNode(\n  id: string,\n  index: Map<string, IndexedItem>,\n  lineage: Set<string>,\n  maxDepth: number | undefined,\n  collapse: DepsCollapseMode,\n  expanded: Set<string>,\n  depth = 0,\n  via?: string,\n): DepsTreeNode {\n  const lookupId = id.trim().toLowerCase();\n  const item = index.get(lookupId);\n  const baseNode: DepsTreeNode = {\n    id: item?.id ?? id,\n    title: item?.title,\n    type: item?.type,\n    status: item?.status,\n    via,\n    missing: !item,\n    cycle: lineage.has(lookupId),\n    dependencies: [],\n  };\n  if (!item || baseNode.cycle) {\n    return baseNode;\n  }\n  if (maxDepth !== undefined && depth >= maxDepth) {\n    if (item.dependencies.length > 0) {\n      baseNode.truncated = true;\n    }\n    return baseNode;\n  }\n  if (collapse === \"repeated\" && expanded.has(lookupId)) {\n    baseNode.collapsed = true;\n    return baseNode;\n  }\n  if (collapse === \"repeated\") {\n    expanded.add(lookupId);\n  }\n  const nextLineage = new Set(lineage);\n  nextLineage.add(lookupId);\n  baseNode.dependencies = item.dependencies.map((dependency) =>\n    toTreeNode(\n      dependency.id,\n      index,\n      nextLineage,\n      maxDepth,\n      collapse,\n      expanded,\n      depth + 1,\n      dependency.kind,\n    ),\n  );\n  return baseNode;\n}\n\nfunction mergeGraphNode(\n  existing: DepsGraphNode | undefined,\n  candidate: DepsGraphNode,\n): DepsGraphNode {\n  if (!existing) {\n    return candidate;\n  }\n  /* c8 ignore start -- defensive: mixed missing/non-missing duplicates only occur in malformed synthetic trees. */\n  if (existing.missing && !candidate.missing) return candidate;\n  /* c8 ignore stop */\n  return {\n    ...existing,\n    title: existing.title ?? candidate.title,\n    type: existing.type ?? candidate.type,\n    status: existing.status ?? candidate.status,\n  };\n}\n\nfunction toGraph(root: DepsTreeNode): DepsGraphResult {\n  const nodesById = new Map<string, DepsGraphNode>();\n  const edgesByKey = new Map<string, DepsGraphEdge>();\n\n  const visit = (node: DepsTreeNode): void => {\n    nodesById.set(\n      node.id,\n      mergeGraphNode(nodesById.get(node.id), {\n        id: node.id,\n        title: node.title,\n        type: node.type,\n        status: node.status,\n        missing: node.missing,\n      }),\n    );\n    for (const child of node.dependencies) {\n      nodesById.set(\n        child.id,\n        mergeGraphNode(nodesById.get(child.id), {\n          id: child.id,\n          title: child.title,\n          type: child.type,\n          status: child.status,\n          missing: child.missing,\n        }),\n      );\n      /* c8 ignore start -- legacy malformed dependency payloads may omit kind/via. */\n      const relationKind = child.via ?? \"related\";\n      const edgeKey = `${node.id}::${child.id}::${relationKind}`;\n      if (!edgesByKey.has(edgeKey)) {\n        edgesByKey.set(edgeKey, {\n          from: node.id,\n          to: child.id,\n          kind: relationKind,\n        });\n      }\n      /* c8 ignore stop */\n      if (!child.cycle) {\n        visit(child);\n      }\n    }\n  };\n\n  visit(root);\n\n  const nodes = [...nodesById.values()].sort((left, right) =>\n    left.id.localeCompare(right.id),\n  );\n  const edges = [...edgesByKey.values()].sort((left, right) => {\n    const byFrom = left.from.localeCompare(right.from);\n    if (byFrom !== 0) return byFrom;\n    const byTo = left.to.localeCompare(right.to);\n    if (byTo !== 0) return byTo;\n    return left.kind.localeCompare(right.kind);\n  });\n  const missingIds = nodes\n    .filter((node) => node.missing)\n    .map((node) => node.id);\n  return {\n    root_id: root.id,\n    nodes,\n    edges,\n    missing_ids: missingIds,\n  };\n}\n\n/** Count a dependency result without allocating its potentially exponential tree payload. */\nfunction countDependencyGraph(\n  rootId: string,\n  index: Map<string, IndexedItem>,\n  maxDepth: number | undefined,\n): Pick<DepsResult, \"node_count\" | \"edge_count\" | \"missing_count\"> {\n  const nodeIds = new Set<string>();\n  const edgeKeys = new Set<string>();\n  const missingIds = new Set<string>();\n  const expanded = new Set<string>();\n  const pending = [{ id: rootId, depth: 0 }];\n  let pendingIndex = 0;\n  while (pendingIndex < pending.length) {\n    const current = pending[pendingIndex++]!;\n    const lookupId = current.id.trim().toLowerCase();\n    nodeIds.add(lookupId);\n    const item = index.get(lookupId);\n    if (!item) {\n      missingIds.add(lookupId);\n      continue;\n    }\n    if (maxDepth !== undefined && current.depth >= maxDepth) {\n      continue;\n    }\n    if (expanded.has(lookupId)) {\n      continue;\n    }\n    expanded.add(lookupId);\n    for (const dependency of item.dependencies) {\n      edgeKeys.add(\n        `${lookupId}::${dependency.id.trim().toLowerCase()}::${dependency.kind}`,\n      );\n      pending.push({ id: dependency.id, depth: current.depth + 1 });\n    }\n  }\n  return {\n    node_count: nodeIds.size,\n    edge_count: edgeKeys.size,\n    missing_count: missingIds.size,\n  };\n}\n\n/** Implements run deps for the public runtime surface of this module. */\nexport async function runDeps(\n  id: string,\n  options: DepsCommandOptions,\n  global: GlobalOptions,\n): Promise<DepsResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n  const format = parseFormat(options.format);\n  const maxDepth = parseMaxDepth(options.maxDepth);\n  const collapse = parseCollapse(options.collapse);\n  const summaryOnly = options.summary === true;\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(\n    settings,\n    getActiveExtensionRegistrations(),\n  );\n  const items = await listAllItemMetadataLight(\n    pmRoot,\n    settings.item_format,\n    typeRegistry.type_to_folder,\n    undefined,\n    settings.schema,\n  );\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const index = new Map(\n    items.map((item) => [item.id.trim().toLowerCase(), toIndexedItem(item)]),\n  );\n  const dangling = collectDanglingDependencyReferences(\n    items,\n    (status) => isTerminalStatus(status, statusRegistry),\n  );\n  for (const reference of [...dangling.active, ...dangling.legacy_terminal]) {\n    const holder = index.get(reference.holder_id.trim().toLowerCase());\n    const referenceKind = reference.kind.trim().toLowerCase();\n    if (\n      holder &&\n      !holder.dependencies.some(\n        (dependency) =>\n          dependency.id.trim().toLowerCase() === reference.target_id.trim().toLowerCase() &&\n          dependency.kind === referenceKind,\n      )\n    ) {\n      holder.dependencies.push({ id: reference.target_id, kind: referenceKind });\n    }\n  }\n  if (!index.has(id.trim().toLowerCase())) {\n    throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n  }\n\n  if (summaryOnly) {\n    return {\n      id,\n      format,\n      ...countDependencyGraph(id, index, maxDepth),\n    };\n  }\n\n  const tree = toTreeNode(\n    id,\n    index,\n    new Set<string>(),\n    maxDepth,\n    collapse,\n    new Set<string>(),\n  );\n  const graph = toGraph(tree);\n  const baseResult = {\n    id,\n    format,\n    node_count: graph.nodes.length,\n    edge_count: graph.edges.length,\n    missing_count: graph.missing_ids.length,\n  };\n  if (format === \"tree\") {\n    return {\n      ...baseResult,\n      tree,\n    };\n  }\n  return {\n    ...baseResult,\n    graph,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"27ed78ad-a876-57b7-8604-51a45d22d0f4"}

package/dist/sdk/docs.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module sdk/docs
+ *
+ * Implements the pm docs command surface and its agent-facing runtime behavior.
+ */
+import type { GlobalOptions } from "../core/shared/command-types.js";
+import type { LinkedDoc } from "../types/index.js";
+import { type LinkedPathValidation } from "./linked-artifacts.js";
+/** Documents the docs command options payload exchanged by command, SDK, and package integrations. */
+export interface DocsCommandOptions {
+    /** Value that configures or reports add for this contract. */
+    add?: string[];
+    /** Value that configures or reports add glob for this contract. */
+    addGlob?: string[];
+    /** Value that configures or reports remove for this contract. */
+    remove?: string[];
+    /** Value that configures or reports migrate for this contract. */
+    migrate?: string[];
+    /** GH-170 (pm-pfnx): standalone note applied to every --add/--add-glob link in this invocation. */
+    note?: string;
+    /** Value that configures or reports list for this contract. */
+    list?: boolean;
+    /** Value that configures or reports validate paths for this contract. */
+    validatePaths?: boolean;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Human-readable explanation suitable for logs and agent-facing output. */
+    message?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the docs result payload exchanged by command, SDK, and package integrations. */
+export interface DocsResult {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports docs for this contract. */
+    docs: LinkedDoc[];
+    /** Value that configures or reports changed for this contract. */
+    changed: boolean;
+    /** Value that configures or reports count for this contract. */
+    count: number;
+    /** Value that configures or reports migrations applied for this contract. */
+    migrations_applied?: number;
+    /** Value that configures or reports validation for this contract. */
+    validation?: LinkedPathValidation;
+}
+/** Implements run docs for the public runtime surface of this module. */
+export declare function runDocs(id: string, options: DocsCommandOptions, global: GlobalOptions): Promise<DocsResult>;

package/dist/sdk/docs.js

@@ -0,0 +1,15 @@
+
+!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]="5e3087d8-a9c9-5374-bc37-7af8db10df0b")}catch(e){}}();
+import { renameArtifactsResultKey, runLinkedArtifacts, } from "./linked-artifacts.js";
+/** Implements run docs for the public runtime surface of this module. */
+export async function runDocs(id, options, global) {
+    const result = await runLinkedArtifacts(id, options, global, {
+        metadataKey: "docs",
+        op: "docs_add",
+        bareNoun: "doc",
+        supportsAppendStable: false,
+    });
+    return renameArtifactsResultKey(result, "docs");
+}
+//# sourceMappingURL=docs.js.map
+//# debugId=5e3087d8-a9c9-5374-bc37-7af8db10df0b

package/dist/sdk/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sources":["sdk/docs.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/docs\n *\n * Implements the pm docs command surface and its agent-facing runtime behavior.\n */\nimport type { GlobalOptions } from \"../core/shared/command-types.js\";\nimport type { LinkedDoc } from \"../types/index.js\";\nimport {\n  renameArtifactsResultKey,\n  runLinkedArtifacts,\n  type LinkedArtifactResult,\n  type LinkedPathValidation,\n} from \"./linked-artifacts.js\";\n\n/** Documents the docs command options payload exchanged by command, SDK, and package integrations. */\nexport interface DocsCommandOptions {\n  /** Value that configures or reports add for this contract. */\n  add?: string[];\n  /** Value that configures or reports add glob for this contract. */\n  addGlob?: string[];\n  /** Value that configures or reports remove for this contract. */\n  remove?: string[];\n  /** Value that configures or reports migrate for this contract. */\n  migrate?: string[];\n  /** GH-170 (pm-pfnx): standalone note applied to every --add/--add-glob link in this invocation. */\n  note?: string;\n  /** Value that configures or reports list for this contract. */\n  list?: boolean;\n  /** Value that configures or reports validate paths for this contract. */\n  validatePaths?: boolean;\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Human-readable explanation suitable for logs and agent-facing output. */\n  message?: string;\n  /** Value that configures or reports force for this contract. */\n  force?: boolean;\n}\n\n/** Documents the docs result payload exchanged by command, SDK, and package integrations. */\nexport interface DocsResult {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports docs for this contract. */\n  docs: LinkedDoc[];\n  /** Value that configures or reports changed for this contract. */\n  changed: boolean;\n  /** Value that configures or reports count for this contract. */\n  count: number;\n  /** Value that configures or reports migrations applied for this contract. */\n  migrations_applied?: number;\n  /** Value that configures or reports validation for this contract. */\n  validation?: LinkedPathValidation;\n}\n\n/** Implements run docs for the public runtime surface of this module. */\nexport async function runDocs(\n  id: string,\n  options: DocsCommandOptions,\n  global: GlobalOptions,\n): Promise<DocsResult> {\n  const result: LinkedArtifactResult = await runLinkedArtifacts(\n    id,\n    options,\n    global,\n    {\n      metadataKey: \"docs\",\n      op: \"docs_add\",\n      bareNoun: \"doc\",\n      supportsAppendStable: false,\n    },\n  );\n  return renameArtifactsResultKey(result, \"docs\");\n}\n"],"names":[],"mappings":";;AAOA,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GAGnB,MAAM,uBAAuB,CAAC;AA0C/B,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,EAAU,EACV,OAA2B,EAC3B,MAAqB;IAErB,MAAM,MAAM,GAAyB,MAAM,kBAAkB,CAC3D,EAAE,EACF,OAAO,EACP,MAAM,EACN;QACE,WAAW,EAAE,MAAM;QACnB,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,KAAK;QACf,oBAAoB,EAAE,KAAK;KAC5B,CACF,CAAC;IACF,OAAO,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC","debugId":"5e3087d8-a9c9-5374-bc37-7af8db10df0b"}

package/dist/sdk/files.d.ts

@@ -0,0 +1,135 @@
+import type { GlobalOptions } from "../core/shared/command-types.js";
+import type { ItemDocument, LinkedFile, LinkScope } from "../types/index.js";
+import { type LinkedPathValidation } from "./linked-artifacts.js";
+/** Documents the files command options payload exchanged by command, SDK, and package integrations. */
+export interface FilesCommandOptions {
+    /** Value that configures or reports add for this contract. */
+    add?: string[];
+    /** Value that configures or reports add glob for this contract. */
+    addGlob?: string[];
+    /** Value that configures or reports remove for this contract. */
+    remove?: string[];
+    /** Value that configures or reports migrate for this contract. */
+    migrate?: string[];
+    /** GH-170 (pm-pfnx): standalone note applied to every --add/--add-glob link in this invocation. */
+    note?: string;
+    /** Value that configures or reports list for this contract. */
+    list?: boolean;
+    /** Value that configures or reports append stable for this contract. */
+    appendStable?: boolean;
+    /** Value that configures or reports validate paths for this contract. */
+    validatePaths?: boolean;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Human-readable explanation suitable for logs and agent-facing output. */
+    message?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the files discover options payload exchanged by command, SDK, and package integrations. */
+export interface FilesDiscoverOptions {
+    /** Value that configures or reports apply for this contract. */
+    apply?: boolean;
+    /** Value that configures or reports append stable for this contract. */
+    appendStable?: boolean;
+    /** Value that configures or reports note for this contract. */
+    note?: string;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Human-readable explanation suitable for logs and agent-facing output. */
+    message?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the files discovery candidate payload exchanged by command, SDK, and package integrations. */
+export interface FilesDiscoveryCandidate {
+    /** Filesystem path used for path resolution. */
+    path: string;
+    /** Value that configures or reports scope for this contract. */
+    scope: LinkScope;
+    /** Lifecycle state reported for status. */
+    status: "addable" | "already_linked";
+    /** Number of source entries represented by this result. */
+    source_count: number;
+    /** Value that configures or reports source fields for this contract. */
+    source_fields: string[];
+    /** Value that configures or reports original paths for this contract. */
+    original_paths: string[];
+}
+/** Documents the files result payload exchanged by command, SDK, and package integrations. */
+export interface FilesResult {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports files for this contract. */
+    files: LinkedFile[];
+    /** Value that configures or reports changed for this contract. */
+    changed: boolean;
+    /** Value that configures or reports count for this contract. */
+    count: number;
+    /** Value that configures or reports migrations applied for this contract. */
+    migrations_applied?: number;
+    /** Value that configures or reports validation for this contract. */
+    validation?: LinkedPathValidation;
+}
+/** Documents the files discover result payload exchanged by command, SDK, and package integrations. */
+export interface FilesDiscoverResult {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports files for this contract. */
+    files: LinkedFile[];
+    /** Value that configures or reports changed for this contract. */
+    changed: boolean;
+    /** Value that configures or reports apply for this contract. */
+    apply: boolean;
+    /** Value that configures or reports count for this contract. */
+    count: number;
+    /** Number of candidate entries represented by this result. */
+    candidate_count: number;
+    /** Number of addable entries represented by this result. */
+    addable_count: number;
+    /** Number of added entries represented by this result. */
+    added_count: number;
+    /** Number of skipped existing entries represented by this result. */
+    skipped_existing_count: number;
+    /** Value that configures or reports candidates for this contract. */
+    candidates: FilesDiscoveryCandidate[];
+    /** Value that configures or reports added for this contract. */
+    added: LinkedFile[];
+    /** Value that configures or reports skipped existing for this contract. */
+    skipped_existing: FilesDiscoveryCandidate[];
+}
+interface TextReference {
+    field: string;
+    value: string;
+}
+interface RawPathReference {
+    field: string;
+    value: string;
+}
+declare function normalizeCandidatePathForOutput(value: string): string;
+declare function realpathForContainment(inputPath: string): Promise<string>;
+declare function linkedFileResolvedKey(linkedFile: Pick<LinkedFile, "path" | "scope">, projectRoot: string): string;
+declare function collectTextReferences(value: unknown, fieldPath: string, references: TextReference[]): void;
+declare function collectItemTextReferences(document: ItemDocument): TextReference[];
+declare function cleanupPathToken(value: string): string;
+declare function extractRawPathReferences(references: TextReference[]): RawPathReference[];
+declare function resolveDiscoveredFile(rawPath: string, workspaceRoot: string, invocationRoot?: string): Promise<Pick<LinkedFile, "path" | "scope"> | undefined>;
+declare function discoverReferencedFiles(document: ItemDocument, workspaceRoot: string, invocationRoot?: string): Promise<FilesDiscoveryCandidate[]>;
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export declare const _testOnly: {
+    relativeReferenceScanMaxChars: number;
+    normalizeCandidatePathForOutput: typeof normalizeCandidatePathForOutput;
+    realpathForContainment: typeof realpathForContainment;
+    linkedFileResolvedKey: typeof linkedFileResolvedKey;
+    collectTextReferences: typeof collectTextReferences;
+    collectItemTextReferences: typeof collectItemTextReferences;
+    cleanupPathToken: typeof cleanupPathToken;
+    extractRawPathReferences: typeof extractRawPathReferences;
+    resolveDiscoveredFile: typeof resolveDiscoveredFile;
+    discoverReferencedFiles: typeof discoverReferencedFiles;
+};
+/** Implements run files for the public runtime surface of this module. */
+export declare function runFiles(id: string, options: FilesCommandOptions, global: GlobalOptions): Promise<FilesResult>;
+/** Implements run files discover for the public runtime surface of this module. */
+export declare function runFilesDiscover(id: string, options: FilesDiscoverOptions, global: GlobalOptions): Promise<FilesDiscoverResult>;
+export {};