@unbrained/pm-cli 2026.6.23 → 2026.6.30

package/dist/cli/commands/next.js

@@ -0,0 +1,304 @@
+/**
+ * @module cli/commands/next
+ *
+ * Implements the `pm next` command: the distilled "what should I work on now?"
+ * query. It loads the active corpus, computes dependency-aware actionability
+ * (ready vs blocked leaf work), and returns a single ranked recommendation with a
+ * deterministic rationale plus the ranked ready/blocked queues — so an agent gets
+ * the next action and the reason for it in one token-efficient read instead of
+ * re-deriving readiness from a full `pm context` snapshot every turn.
+ */
+
+!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]="38a305c9-7ad5-5b16-9eaf-c0f210ef70e3")}catch(e){}}();
+import { collectBlockedByIds, computeActionabilityReport, } from "../../core/item/actionability.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 { nowIso } from "../../core/shared/time.js";
+import { normalizeStatusInput, normalizeStatusForRegistry } from "../../core/item/status.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { parseIntegerLimit } from "../shared-parsers.js";
+import { buildChildrenByParent, collectSubtreeIds, compareCriticalItems, toContextFocusItem, } from "./context.js";
+import { runList } from "./list.js";
+export const NEXT_OUTPUT_VALUES = ["markdown", "toon", "json"];
+const DEFAULT_NEXT_LIMIT = 5;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function parseNextOutputFormat(raw) {
+    if (!raw)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (!NEXT_OUTPUT_VALUES.includes(normalized)) {
+        throw new PmCliError("Next format must be one of markdown|toon|json", EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+/**
+ * Resolves the effective `pm next` output format from the command `--format` flag
+ * and the global `--json` switch, rejecting the contradictory `--json --format
+ * markdown|toon` combination. Defaults to `toon`.
+ */
+export function resolveNextOutputFormat(options, global) {
+    const commandFormat = parseNextOutputFormat(options.format);
+    if (global.json && commandFormat && commandFormat !== "json") {
+        throw new PmCliError("Cannot combine --json with --format markdown|toon", EXIT_CODE.USAGE);
+    }
+    if (global.json) {
+        return "json";
+    }
+    return commandFormat ?? "toon";
+}
+// Per-section row cap. A non-positive or absent value falls back to the default;
+// invalid (non-integer) values throw via parseIntegerLimit.
+function parseNextLimit(raw, flag, fallback) {
+    const parsed = parseIntegerLimit(raw, flag);
+    if (parsed === undefined || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+// Projects an actionable entry onto its output row. Ready entries carry no
+// blockers; blocked entries surface their unresolved blockers for the agent.
+function toNextActionableItem(entry, statusRegistry, childrenByParent) {
+    return {
+        ...toContextFocusItem(entry.item, statusRegistry, childrenByParent),
+        open_blocker_count: entry.open_blockers.length,
+        blockers: entry.open_blockers.map((blocker) => ({ id: blocker.id, title: blocker.title, status: blocker.status })),
+        unblocks: entry.unblocks,
+    };
+}
+// Builds the human+agent readable rationale for the recommended item, ordering
+// clauses from most to least decisive (status, priority, deadline, blocker
+// clearance, parent advancement, downstream unblocks).
+function buildRecommendationReasons(entry, statusRegistry, now, completedContainer) {
+    const item = entry.item;
+    const reasons = [];
+    const inProgressStatus = normalizeStatusInput("in_progress", statusRegistry);
+    reasons.push(normalizeStatusForRegistry(item.status, statusRegistry) === inProgressStatus
+        ? "in progress — resume to finish"
+        : "open and ready to start");
+    if (completedContainer) {
+        reasons.push("completed container — governance closeout");
+    }
+    reasons.push(`priority p${item.priority}${item.priority === 0 ? " (highest)" : ""}`);
+    if (typeof item.deadline === "string" && item.deadline.trim().length > 0) {
+        reasons.push(describeDeadline(item.deadline, now));
+    }
+    reasons.push(collectBlockedByIds(item).length > 0 ? "all blockers resolved" : "no blockers");
+    if (typeof item.parent === "string" && item.parent.trim().length > 0) {
+        reasons.push(`advances ${item.parent.trim()}`);
+    }
+    if (entry.unblocks.length > 0) {
+        reasons.push(`unblocks ${entry.unblocks.length} item(s): ${entry.unblocks.join(", ")}`);
+    }
+    return reasons;
+}
+// Renders a deadline as a date token plus a relative tag (overdue/today/in Nd).
+// The relative delta is computed on UTC calendar dates (both sides normalized to
+// midnight) so a deadline due today never reads as "overdue 1d" just because the
+// wall-clock time of `now` has passed midnight. Unparseable deadlines degrade to
+// the raw token (defensive — stored deadlines are always valid ISO).
+function describeDeadline(deadline, now) {
+    const deadlineMs = Date.parse(deadline);
+    /* c8 ignore start -- defensive: a stored deadline that fails Date.parse still surfaces its raw token */
+    if (!Number.isFinite(deadlineMs)) {
+        return `deadline ${deadline.trim()}`;
+    }
+    /* c8 ignore stop */
+    const dateToken = new Date(deadlineMs).toISOString().slice(0, 10);
+    const nowToken = new Date(Date.parse(now)).toISOString().slice(0, 10);
+    const days = Math.round((Date.parse(dateToken) - Date.parse(nowToken)) / MS_PER_DAY);
+    if (days < 0)
+        return `deadline ${dateToken} (overdue ${-days}d)`;
+    if (days === 0)
+        return `deadline ${dateToken} (due today)`;
+    return `deadline ${dateToken} (in ${days}d)`;
+}
+function inProgressReadyCount(ready, statusRegistry) {
+    const inProgressStatus = normalizeStatusInput("in_progress", statusRegistry);
+    return ready.filter((item) => normalizeStatusForRegistry(item.status, statusRegistry) === inProgressStatus).length;
+}
+// Returns true when an otherwise-ready item still has terminal descendants. Such
+// rows are useful governance closeout context, but concrete leaf work should rank
+// ahead of them in the default agent loop.
+function hasCompletedDescendants(item, childrenByParent) {
+    return (childrenByParent.get(item.id.trim().toLowerCase()) ?? []).length > 0;
+}
+// Strips projection/pagination flags so the corpus reads stay full: limits are
+// per-section display caps applied after classification, never corpus filters.
+function nextListOptions(options, extra) {
+    return {
+        type: options.type,
+        tag: options.tag,
+        priority: options.priority,
+        assignee: options.assignee,
+        assigneeFilter: options.assigneeFilter,
+        sprint: options.sprint,
+        release: options.release,
+        noTruncate: true,
+        ...extra,
+    };
+}
+/**
+ * Implements `pm next`: computes the ranked ready/blocked actionable queues and a
+ * single recommended next item with rationale for the public runtime surface.
+ */
+export async function runNext(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const settings = await readSettings(pmRoot);
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const now = nowIso();
+    const limit = parseNextLimit(options.limit, "--limit", DEFAULT_NEXT_LIMIT);
+    const blockedLimit = parseNextLimit(options.blockedLimit, "--blocked-limit", limit);
+    const readyOnly = options.readyOnly === true;
+    const parentScope = typeof options.parent === "string" ? options.parent.trim() : "";
+    // Active (non-terminal) candidates honor the caller's filters; the corpus is the
+    // FULL, UNFILTERED set (every status, every item) so blocker and descendant
+    // resolution still sees items outside the caller's filters or --parent subtree —
+    // otherwise a real blocker assigned to someone else (or a parent of a different
+    // type) would be missing and the blocked item misread as ready.
+    const candidatesList = await runList(undefined, nextListOptions(options, { excludeTerminal: true }), global);
+    const corpusList = await runList(undefined, { excludeTerminal: false, noTruncate: true }, global);
+    let candidates = candidatesList.items;
+    const corpus = corpusList.items;
+    if (parentScope.length > 0) {
+        const subtree = collectSubtreeIds(corpus, parentScope);
+        if (!subtree.found) {
+            throw new PmCliError(`Next --parent item not found: ${parentScope}`, EXIT_CODE.NOT_FOUND);
+        }
+        candidates = candidates.filter((item) => subtree.ids.has(item.id.trim().toLowerCase()));
+    }
+    const report = computeActionabilityReport(candidates, corpus, statusRegistry);
+    const childrenByParent = buildChildrenByParent(corpus);
+    const rankedReady = [...report.ready].sort((left, right) => {
+        const leftCompletedContainer = hasCompletedDescendants(left.item, childrenByParent);
+        const rightCompletedContainer = hasCompletedDescendants(right.item, childrenByParent);
+        if (leftCompletedContainer !== rightCompletedContainer) {
+            return Number(leftCompletedContainer) - Number(rightCompletedContainer);
+        }
+        return compareCriticalItems(left.item, right.item, statusRegistry);
+    });
+    const rankedBlocked = [...report.blocked].sort((left, right) => compareCriticalItems(left.item, right.item, statusRegistry));
+    const concreteReady = rankedReady.filter((entry) => !hasCompletedDescendants(entry.item, childrenByParent));
+    const projectedReady = concreteReady.length > 0 ? concreteReady : rankedReady;
+    const readyRows = projectedReady.map((entry) => toNextActionableItem(entry, statusRegistry, childrenByParent));
+    const blockedRows = rankedBlocked.map((entry) => toNextActionableItem(entry, statusRegistry, childrenByParent));
+    const recommended = projectedReady.length > 0
+        ? {
+            ...readyRows[0],
+            reasons: buildRecommendationReasons(projectedReady[0], statusRegistry, now, concreteReady.length === 0),
+        }
+        : null;
+    const result = {
+        output_default: "toon",
+        now,
+        recommended,
+        ready: readyRows.slice(0, limit),
+        blocked: readyOnly ? [] : blockedRows.slice(0, blockedLimit),
+        summary: {
+            recommended: recommended !== null,
+            ready: readyRows.length,
+            blocked: blockedRows.length,
+            in_progress: inProgressReadyCount(readyRows, statusRegistry),
+            candidates: report.active_count,
+            containers: report.container_count,
+        },
+        filters: {
+            type: options.type ?? null,
+            tag: options.tag ?? null,
+            priority: options.priority ?? null,
+            assignee: options.assignee ?? null,
+            assignee_filter: options.assigneeFilter ?? null,
+            sprint: options.sprint ?? null,
+            release: options.release ?? null,
+            parent: parentScope.length > 0 ? parentScope : null,
+            limit,
+            blocked_limit: blockedLimit,
+            ready_only: readyOnly,
+        },
+    };
+    const warnings = [...new Set([...(candidatesList.warnings ?? []), ...(corpusList.warnings ?? [])])].sort((a, b) => a.localeCompare(b));
+    if (warnings.length > 0)
+        result.warnings = warnings;
+    if (recommended === null) {
+        result.suggestions =
+            blockedRows.length > 0
+                ? [
+                    `${blockedRows.length} item(s) are blocked; unblock the top one by closing ${blockedRows[0].blockers
+                        .map((blocker) => blocker.id)
+                        .join(", ")}`,
+                    "pm next --ready-only after a blocker closes to re-check ready work",
+                    'pm create --type Task --title "..." to add new ready work',
+                ]
+                : [
+                    'pm create --type Task --title "..." to add a new work item',
+                    "pm list --status in_progress to review work already underway",
+                    "pm context --depth deep for the full project snapshot",
+                ];
+    }
+    return result;
+}
+/**
+ * Renders a {@link NextResult} as compact agent-readable markdown: the
+ * recommendation with its rationale, the ranked ready queue, and (unless
+ * `--ready-only`) the blocked queue annotated with each item's open blockers.
+ */
+export function renderNextMarkdown(result) {
+    const lines = ["# pm next", ""];
+    lines.push(`- now: ${result.now}`);
+    lines.push(`- ready: ${result.summary.ready} (in_progress: ${result.summary.in_progress}), blocked: ${result.summary.blocked}, candidates: ${result.summary.candidates}`);
+    if (result.filters.parent) {
+        lines.push(`- scope: subtree of ${result.filters.parent}`);
+    }
+    lines.push("");
+    lines.push("## Recommended");
+    if (result.recommended) {
+        lines.push(`- ${formatNextLine(result.recommended)}`);
+        lines.push(`  why: ${result.recommended.reasons.join("; ")}`);
+    }
+    else {
+        lines.push("No ready work.");
+    }
+    lines.push("");
+    lines.push("## Ready");
+    if (result.ready.length === 0) {
+        lines.push("No ready items.");
+    }
+    else {
+        for (const item of result.ready) {
+            lines.push(`- ${formatNextLine(item)}`);
+        }
+    }
+    lines.push("");
+    if (!result.filters.ready_only) {
+        lines.push("## Blocked");
+        if (result.blocked.length === 0) {
+            lines.push("No blocked items.");
+        }
+        else {
+            for (const item of result.blocked) {
+                const by = item.blockers
+                    .map((blocker) => `${blocker.id}(${blocker.status ?? "?"})`)
+                    .join(", ");
+                lines.push(`- ${formatNextLine(item)} blocked_by:${by}`);
+            }
+        }
+        lines.push("");
+    }
+    if (result.suggestions && result.suggestions.length > 0) {
+        lines.push("## Suggestions");
+        for (const suggestion of result.suggestions) {
+            lines.push(`- ${suggestion}`);
+        }
+    }
+    return lines.join("\n").trimEnd();
+}
+// Formats a single actionable row: id, priority, status, type, deadline, parent,
+// downstream-unblock count, and title. Mirrors the context focus-line shape.
+function formatNextLine(item) {
+    const deadlineToken = item.deadline ?? "-";
+    const parentToken = item.parent ? ` parent:${item.parent}` : "";
+    const unblocksToken = item.unblocks.length > 0 ? ` unblocks:${item.unblocks.length}` : "";
+    return `${item.id} p${item.priority} ${item.status} ${item.type} deadline:${deadlineToken}${parentToken}${unblocksToken} ${item.title}`;
+}
+//# sourceMappingURL=next.js.map
+//# debugId=38a305c9-7ad5-5b16-9eaf-c0f210ef70e3

package/dist/cli/commands/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sources":["cli/commands/next.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/next\n *\n * Implements the `pm next` command: the distilled \"what should I work on now?\"\n * query. It loads the active corpus, computes dependency-aware actionability\n * (ready vs blocked leaf work), and returns a single ranked recommendation with a\n * deterministic rationale plus the ranked ready/blocked queues — so an agent gets\n * the next action and the reason for it in one token-efficient read instead of\n * re-deriving readiness from a full `pm context` snapshot every turn.\n */\nimport {\n  collectBlockedByIds,\n  computeActionabilityReport,\n  type ActionableEntry,\n} from \"../../core/item/actionability.js\";\nimport { resolveRuntimeStatusRegistry, type RuntimeStatusRegistry } 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 { nowIso } from \"../../core/shared/time.js\";\nimport { normalizeStatusInput, normalizeStatusForRegistry } from \"../../core/item/status.js\";\nimport { resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport type { ItemFrontMatter, ItemStatus } from \"../../types/index.js\";\nimport { parseIntegerLimit } from \"../shared-parsers.js\";\nimport {\n  buildChildrenByParent,\n  collectSubtreeIds,\n  compareCriticalItems,\n  toContextFocusItem,\n  type ContextFocusItem,\n} from \"./context.js\";\nimport { runList, type ListOptions } from \"./list.js\";\n\nexport const NEXT_OUTPUT_VALUES = [\"markdown\", \"toon\", \"json\"] as const;\n/**\n * Restricts `pm next` output format values accepted by command, SDK, and storage contracts.\n */\nexport type NextOutputFormat = (typeof NEXT_OUTPUT_VALUES)[number];\n\nconst DEFAULT_NEXT_LIMIT = 5;\nconst MS_PER_DAY = 24 * 60 * 60 * 1000;\n\n/**\n * Documents the `pm next` options payload exchanged by command, SDK, and package integrations.\n */\nexport interface NextOptions {\n  type?: string;\n  tag?: string;\n  priority?: string;\n  assignee?: string;\n  assigneeFilter?: string;\n  sprint?: string;\n  release?: string;\n  parent?: string;\n  limit?: string;\n  blockedLimit?: string;\n  readyOnly?: boolean;\n  format?: string;\n  [key: string]: unknown;\n}\n\n/** A blocker reference projected onto the `pm next` output. */\nexport interface NextBlockerRef {\n  id: string;\n  title: string | null;\n  status: ItemStatus | null;\n}\n\n/**\n * A classified actionable item on the `pm next` output: a {@link ContextFocusItem}\n * focus row augmented with its open-blocker references and the downstream items it\n * would unblock.\n */\nexport interface NextActionableItem extends ContextFocusItem {\n  open_blocker_count: number;\n  blockers: NextBlockerRef[];\n  unblocks: string[];\n}\n\n/** The single recommended next item: an actionable row plus its rationale. */\nexport interface NextRecommendation extends NextActionableItem {\n  reasons: string[];\n}\n\ninterface NextSummary {\n  recommended: boolean;\n  ready: number;\n  blocked: number;\n  in_progress: number;\n  candidates: number;\n  containers: number;\n}\n\n/**\n * Documents the `pm next` result payload exchanged by command, SDK, and package integrations.\n */\nexport interface NextResult {\n  output_default: \"toon\";\n  now: string;\n  recommended: NextRecommendation | null;\n  ready: NextActionableItem[];\n  blocked: NextActionableItem[];\n  summary: NextSummary;\n  filters: {\n    type: string | null;\n    tag: string | null;\n    priority: string | null;\n    assignee: string | null;\n    assignee_filter: string | null;\n    sprint: string | null;\n    release: string | null;\n    parent: string | null;\n    limit: number;\n    blocked_limit: number;\n    ready_only: boolean;\n  };\n  suggestions?: string[];\n  warnings?: string[];\n}\n\nfunction parseNextOutputFormat(raw: string | undefined): NextOutputFormat | undefined {\n  if (!raw) return undefined;\n  const normalized = raw.trim().toLowerCase();\n  if (!NEXT_OUTPUT_VALUES.includes(normalized as NextOutputFormat)) {\n    throw new PmCliError(\"Next format must be one of markdown|toon|json\", EXIT_CODE.USAGE);\n  }\n  return normalized as NextOutputFormat;\n}\n\n/**\n * Resolves the effective `pm next` output format from the command `--format` flag\n * and the global `--json` switch, rejecting the contradictory `--json --format\n * markdown|toon` combination. Defaults to `toon`.\n */\nexport function resolveNextOutputFormat(options: NextOptions, global: GlobalOptions): NextOutputFormat {\n  const commandFormat = parseNextOutputFormat(options.format);\n  if (global.json && commandFormat && commandFormat !== \"json\") {\n    throw new PmCliError(\"Cannot combine --json with --format markdown|toon\", EXIT_CODE.USAGE);\n  }\n  if (global.json) {\n    return \"json\";\n  }\n  return commandFormat ?? \"toon\";\n}\n\n// Per-section row cap. A non-positive or absent value falls back to the default;\n// invalid (non-integer) values throw via parseIntegerLimit.\nfunction parseNextLimit(raw: string | undefined, flag: string, fallback: number): number {\n  const parsed = parseIntegerLimit(raw, flag);\n  if (parsed === undefined || parsed <= 0) return fallback;\n  return parsed;\n}\n\n// Projects an actionable entry onto its output row. Ready entries carry no\n// blockers; blocked entries surface their unresolved blockers for the agent.\nfunction toNextActionableItem(\n  entry: ActionableEntry,\n  statusRegistry: RuntimeStatusRegistry,\n  childrenByParent: Map<string, ItemFrontMatter[]>,\n): NextActionableItem {\n  return {\n    ...toContextFocusItem(entry.item, statusRegistry, childrenByParent),\n    open_blocker_count: entry.open_blockers.length,\n    blockers: entry.open_blockers.map((blocker) => ({ id: blocker.id, title: blocker.title, status: blocker.status })),\n    unblocks: entry.unblocks,\n  };\n}\n\n// Builds the human+agent readable rationale for the recommended item, ordering\n// clauses from most to least decisive (status, priority, deadline, blocker\n// clearance, parent advancement, downstream unblocks).\nfunction buildRecommendationReasons(\n  entry: ActionableEntry,\n  statusRegistry: RuntimeStatusRegistry,\n  now: string,\n  completedContainer: boolean,\n): string[] {\n  const item = entry.item;\n  const reasons: string[] = [];\n  const inProgressStatus = normalizeStatusInput(\"in_progress\", statusRegistry);\n  reasons.push(\n    normalizeStatusForRegistry(item.status, statusRegistry) === inProgressStatus\n      ? \"in progress — resume to finish\"\n      : \"open and ready to start\",\n  );\n  if (completedContainer) {\n    reasons.push(\"completed container — governance closeout\");\n  }\n  reasons.push(`priority p${item.priority}${item.priority === 0 ? \" (highest)\" : \"\"}`);\n  if (typeof item.deadline === \"string\" && item.deadline.trim().length > 0) {\n    reasons.push(describeDeadline(item.deadline, now));\n  }\n  reasons.push(collectBlockedByIds(item).length > 0 ? \"all blockers resolved\" : \"no blockers\");\n  if (typeof item.parent === \"string\" && item.parent.trim().length > 0) {\n    reasons.push(`advances ${item.parent.trim()}`);\n  }\n  if (entry.unblocks.length > 0) {\n    reasons.push(`unblocks ${entry.unblocks.length} item(s): ${entry.unblocks.join(\", \")}`);\n  }\n  return reasons;\n}\n\n// Renders a deadline as a date token plus a relative tag (overdue/today/in Nd).\n// The relative delta is computed on UTC calendar dates (both sides normalized to\n// midnight) so a deadline due today never reads as \"overdue 1d\" just because the\n// wall-clock time of `now` has passed midnight. Unparseable deadlines degrade to\n// the raw token (defensive — stored deadlines are always valid ISO).\nfunction describeDeadline(deadline: string, now: string): string {\n  const deadlineMs = Date.parse(deadline);\n  /* c8 ignore start -- defensive: a stored deadline that fails Date.parse still surfaces its raw token */\n  if (!Number.isFinite(deadlineMs)) {\n    return `deadline ${deadline.trim()}`;\n  }\n  /* c8 ignore stop */\n  const dateToken = new Date(deadlineMs).toISOString().slice(0, 10);\n  const nowToken = new Date(Date.parse(now)).toISOString().slice(0, 10);\n  const days = Math.round((Date.parse(dateToken) - Date.parse(nowToken)) / MS_PER_DAY);\n  if (days < 0) return `deadline ${dateToken} (overdue ${-days}d)`;\n  if (days === 0) return `deadline ${dateToken} (due today)`;\n  return `deadline ${dateToken} (in ${days}d)`;\n}\n\nfunction inProgressReadyCount(ready: NextActionableItem[], statusRegistry: RuntimeStatusRegistry): number {\n  const inProgressStatus = normalizeStatusInput(\"in_progress\", statusRegistry);\n  return ready.filter((item) => normalizeStatusForRegistry(item.status, statusRegistry) === inProgressStatus).length;\n}\n\n// Returns true when an otherwise-ready item still has terminal descendants. Such\n// rows are useful governance closeout context, but concrete leaf work should rank\n// ahead of them in the default agent loop.\nfunction hasCompletedDescendants(item: ItemFrontMatter, childrenByParent: Map<string, ItemFrontMatter[]>): boolean {\n  return (childrenByParent.get(item.id.trim().toLowerCase()) ?? []).length > 0;\n}\n\n// Strips projection/pagination flags so the corpus reads stay full: limits are\n// per-section display caps applied after classification, never corpus filters.\nfunction nextListOptions(options: NextOptions, extra: Partial<ListOptions>): ListOptions {\n  return {\n    type: options.type,\n    tag: options.tag,\n    priority: options.priority,\n    assignee: options.assignee,\n    assigneeFilter: options.assigneeFilter,\n    sprint: options.sprint,\n    release: options.release,\n    noTruncate: true,\n    ...extra,\n  };\n}\n\n/**\n * Implements `pm next`: computes the ranked ready/blocked actionable queues and a\n * single recommended next item with rationale for the public runtime surface.\n */\nexport async function runNext(options: NextOptions, global: GlobalOptions): Promise<NextResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  const settings = await readSettings(pmRoot);\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const now = nowIso();\n  const limit = parseNextLimit(options.limit, \"--limit\", DEFAULT_NEXT_LIMIT);\n  const blockedLimit = parseNextLimit(options.blockedLimit, \"--blocked-limit\", limit);\n  const readyOnly = options.readyOnly === true;\n  const parentScope = typeof options.parent === \"string\" ? options.parent.trim() : \"\";\n\n  // Active (non-terminal) candidates honor the caller's filters; the corpus is the\n  // FULL, UNFILTERED set (every status, every item) so blocker and descendant\n  // resolution still sees items outside the caller's filters or --parent subtree —\n  // otherwise a real blocker assigned to someone else (or a parent of a different\n  // type) would be missing and the blocked item misread as ready.\n  const candidatesList = await runList(undefined, nextListOptions(options, { excludeTerminal: true }), global);\n  const corpusList = await runList(undefined, { excludeTerminal: false, noTruncate: true }, global);\n  let candidates = candidatesList.items as ItemFrontMatter[];\n  const corpus = corpusList.items as ItemFrontMatter[];\n\n  if (parentScope.length > 0) {\n    const subtree = collectSubtreeIds(corpus, parentScope);\n    if (!subtree.found) {\n      throw new PmCliError(`Next --parent item not found: ${parentScope}`, EXIT_CODE.NOT_FOUND);\n    }\n    candidates = candidates.filter((item) => subtree.ids.has(item.id.trim().toLowerCase()));\n  }\n\n  const report = computeActionabilityReport(candidates, corpus, statusRegistry);\n  const childrenByParent = buildChildrenByParent(corpus);\n  const rankedReady = [...report.ready].sort((left, right) => {\n    const leftCompletedContainer = hasCompletedDescendants(left.item, childrenByParent);\n    const rightCompletedContainer = hasCompletedDescendants(right.item, childrenByParent);\n    if (leftCompletedContainer !== rightCompletedContainer) {\n      return Number(leftCompletedContainer) - Number(rightCompletedContainer);\n    }\n    return compareCriticalItems(left.item, right.item, statusRegistry);\n  });\n  const rankedBlocked = [...report.blocked].sort((left, right) =>\n    compareCriticalItems(left.item, right.item, statusRegistry),\n  );\n  const concreteReady = rankedReady.filter((entry) => !hasCompletedDescendants(entry.item, childrenByParent));\n  const projectedReady = concreteReady.length > 0 ? concreteReady : rankedReady;\n\n  const readyRows = projectedReady.map((entry) => toNextActionableItem(entry, statusRegistry, childrenByParent));\n  const blockedRows = rankedBlocked.map((entry) => toNextActionableItem(entry, statusRegistry, childrenByParent));\n\n  const recommended: NextRecommendation | null =\n    projectedReady.length > 0\n      ? {\n          ...readyRows[0],\n          reasons: buildRecommendationReasons(\n            projectedReady[0],\n            statusRegistry,\n            now,\n            concreteReady.length === 0,\n          ),\n        }\n      : null;\n\n  const result: NextResult = {\n    output_default: \"toon\",\n    now,\n    recommended,\n    ready: readyRows.slice(0, limit),\n    blocked: readyOnly ? [] : blockedRows.slice(0, blockedLimit),\n    summary: {\n      recommended: recommended !== null,\n      ready: readyRows.length,\n      blocked: blockedRows.length,\n      in_progress: inProgressReadyCount(readyRows, statusRegistry),\n      candidates: report.active_count,\n      containers: report.container_count,\n    },\n    filters: {\n      type: options.type ?? null,\n      tag: options.tag ?? null,\n      priority: options.priority ?? null,\n      assignee: options.assignee ?? null,\n      assignee_filter: options.assigneeFilter ?? null,\n      sprint: options.sprint ?? null,\n      release: options.release ?? null,\n      parent: parentScope.length > 0 ? parentScope : null,\n      limit,\n      blocked_limit: blockedLimit,\n      ready_only: readyOnly,\n    },\n  };\n\n  const warnings = [...new Set([...(candidatesList.warnings ?? []), ...(corpusList.warnings ?? [])])].sort((a, b) =>\n    a.localeCompare(b),\n  );\n  if (warnings.length > 0) result.warnings = warnings;\n\n  if (recommended === null) {\n    result.suggestions =\n      blockedRows.length > 0\n        ? [\n            `${blockedRows.length} item(s) are blocked; unblock the top one by closing ${blockedRows[0].blockers\n              .map((blocker) => blocker.id)\n              .join(\", \")}`,\n            \"pm next --ready-only after a blocker closes to re-check ready work\",\n            'pm create --type Task --title \"...\" to add new ready work',\n          ]\n        : [\n            'pm create --type Task --title \"...\" to add a new work item',\n            \"pm list --status in_progress to review work already underway\",\n            \"pm context --depth deep for the full project snapshot\",\n          ];\n  }\n\n  return result;\n}\n\n/**\n * Renders a {@link NextResult} as compact agent-readable markdown: the\n * recommendation with its rationale, the ranked ready queue, and (unless\n * `--ready-only`) the blocked queue annotated with each item's open blockers.\n */\nexport function renderNextMarkdown(result: NextResult): string {\n  const lines: string[] = [\"# pm next\", \"\"];\n  lines.push(`- now: ${result.now}`);\n  lines.push(\n    `- ready: ${result.summary.ready} (in_progress: ${result.summary.in_progress}), blocked: ${result.summary.blocked}, candidates: ${result.summary.candidates}`,\n  );\n  if (result.filters.parent) {\n    lines.push(`- scope: subtree of ${result.filters.parent}`);\n  }\n  lines.push(\"\");\n\n  lines.push(\"## Recommended\");\n  if (result.recommended) {\n    lines.push(`- ${formatNextLine(result.recommended)}`);\n    lines.push(`  why: ${result.recommended.reasons.join(\"; \")}`);\n  } else {\n    lines.push(\"No ready work.\");\n  }\n  lines.push(\"\");\n\n  lines.push(\"## Ready\");\n  if (result.ready.length === 0) {\n    lines.push(\"No ready items.\");\n  } else {\n    for (const item of result.ready) {\n      lines.push(`- ${formatNextLine(item)}`);\n    }\n  }\n  lines.push(\"\");\n\n  if (!result.filters.ready_only) {\n    lines.push(\"## Blocked\");\n    if (result.blocked.length === 0) {\n      lines.push(\"No blocked items.\");\n    } else {\n      for (const item of result.blocked) {\n        const by = item.blockers\n          .map((blocker) => `${blocker.id}(${blocker.status ?? \"?\"})`)\n          .join(\", \");\n        lines.push(`- ${formatNextLine(item)} blocked_by:${by}`);\n      }\n    }\n    lines.push(\"\");\n  }\n\n  if (result.suggestions && result.suggestions.length > 0) {\n    lines.push(\"## Suggestions\");\n    for (const suggestion of result.suggestions) {\n      lines.push(`- ${suggestion}`);\n    }\n  }\n\n  return lines.join(\"\\n\").trimEnd();\n}\n\n// Formats a single actionable row: id, priority, status, type, deadline, parent,\n// downstream-unblock count, and title. Mirrors the context focus-line shape.\nfunction formatNextLine(item: NextActionableItem): string {\n  const deadlineToken = item.deadline ?? \"-\";\n  const parentToken = item.parent ? ` parent:${item.parent}` : \"\";\n  const unblocksToken = item.unblocks.length > 0 ? ` unblocks:${item.unblocks.length}` : \"\";\n  return `${item.id} p${item.priority} ${item.status} ${item.type} deadline:${deadlineToken}${parentToken}${unblocksToken} ${item.title}`;\n}\n"],"names":[],"mappings":"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","debugId":"38a305c9-7ad5-5b16-9eaf-c0f210ef70e3"}

package/dist/cli/commands/profile.d.ts

@@ -0,0 +1,208 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type ProfileSourceKind } from "../../core/profile/profile-presets.js";
+import { type ProjectProfileComposition } from "../../core/profile/profile-describe.js";
+import { type ProjectProfileLintFinding } from "../../core/profile/profile-lint.js";
+/** Ordered `pm profile` subcommands. */
+export declare const PROFILE_SUBCOMMANDS: readonly ["list", "show", "apply", "lint"];
+/**
+ * Restricts profile subcommand values accepted by command, SDK, and storage contracts.
+ */
+export type ProfileSubcommand = (typeof PROFILE_SUBCOMMANDS)[number];
+/**
+ * Per-dimension counts summarizing how much a profile stages. Aliases the shared
+ * {@link ProjectProfileComposition} so the CLI result shape and the core describe
+ * primitive never drift.
+ */
+export type ProfileComposition = ProjectProfileComposition;
+/** A single profile entry in the `pm profile list` payload. */
+export interface ProfileListEntry {
+    /** Profile name. */
+    name: string;
+    /** Display title. */
+    title: string;
+    /** One-line archetype summary. */
+    summary: string;
+    /** Whether the profile is core-baked or contributed by an active extension. */
+    source: ProfileSourceKind;
+    /** Owning package/extension name for an extension profile; omitted for builtins. */
+    package?: string;
+    /** Per-dimension counts. */
+    composition: ProfileComposition;
+}
+/** Result of `pm profile list`. */
+export interface ProfileListResult {
+    /** Discriminant for the profile result union. */
+    action: "list";
+    /** Built-in profiles in canonical order followed by active extension profiles. */
+    profiles: ProfileListEntry[];
+    /** Non-fatal merge warnings (built-in shadowing attempts, duplicate names). */
+    warnings: string[];
+    /** ISO timestamp the result was produced. */
+    generated_at: string;
+}
+/** Result of `pm profile show <name>`. */
+export interface ProfileShowResult {
+    /** Discriminant for the profile result union. */
+    action: "show";
+    /** Profile name. */
+    name: string;
+    /** Display title. */
+    title: string;
+    /** One-line archetype summary. */
+    summary: string;
+    /** Whether the profile is core-baked or contributed by an active extension. */
+    source: ProfileSourceKind;
+    /** Owning package/extension name for an extension profile; omitted for builtins. */
+    package?: string;
+    /** Per-dimension counts. */
+    composition: ProfileComposition;
+    /** Item type names the profile registers. */
+    types: string[];
+    /** Custom status ids. */
+    statuses: string[];
+    /** Custom field keys. */
+    fields: string[];
+    /** Item types governed by a staged workflow. */
+    workflows: string[];
+    /** Config knobs as `key=value` pairs. */
+    config: string[];
+    /** Template names the profile stages. */
+    templates: string[];
+    /** Recommended package specs with rationale. */
+    packages: Array<{
+        spec: string;
+        reason: string;
+    }>;
+    /** Non-fatal merge warnings (built-in shadowing attempts, duplicate names). */
+    warnings: string[];
+    /** ISO timestamp the result was produced. */
+    generated_at: string;
+}
+/** Per-dimension change summary in an apply result. */
+export interface ProfileApplyDimension {
+    /** Entry keys that were newly created. */
+    added: string[];
+    /** Entry keys whose stored value was overwritten. */
+    updated: string[];
+    /** Entry keys already current (no write). */
+    unchanged: string[];
+}
+/** Result of `pm profile apply <name>`. */
+export interface ProfileApplyResult {
+    /** Discriminant for the profile result union. */
+    action: "apply";
+    /** Applied profile name. */
+    name: string;
+    /** Display title. */
+    title: string;
+    /** True when changes were persisted; false for `--dry-run` or a no-op. */
+    applied: boolean;
+    /** True when `--dry-run` previewed without writing. */
+    dry_run: boolean;
+    /** True when at least one dimension stages an add/update. */
+    changed: boolean;
+    /** Item-type change summary. */
+    types: ProfileApplyDimension;
+    /** Status change summary. */
+    statuses: ProfileApplyDimension;
+    /** Field change summary. */
+    fields: ProfileApplyDimension;
+    /** Workflow change summary. */
+    workflows: ProfileApplyDimension;
+    /** Config-knob change summary. */
+    config: ProfileApplyDimension;
+    /** Template change summary. */
+    templates: ProfileApplyDimension;
+    /** Advisory package recommendations with install status. */
+    packages: Array<{
+        spec: string;
+        reason: string;
+        status: "installed" | "recommended";
+    }>;
+    /** Deduped on-write hook + advisory warnings. */
+    warnings: string[];
+    /** ISO timestamp the result was produced. */
+    generated_at: string;
+}
+/** Result of `pm profile lint [name]`. */
+export interface ProfileLintResult {
+    /** Discriminant for the profile result union. */
+    action: "lint";
+    /** Linted profile name. */
+    name: string;
+    /** Display title. */
+    title: string;
+    /** Whether the profile is core-baked or contributed by an active extension. */
+    source: ProfileSourceKind;
+    /** Owning package/extension name for an extension profile; omitted for builtins. */
+    package?: string;
+    /** True when the profile produced no error-severity findings. */
+    ok: boolean;
+    /** Count of error-severity findings. */
+    error_count: number;
+    /** Count of warning-severity findings. */
+    warning_count: number;
+    /** Every graded consistency finding in dimension order. */
+    findings: ProjectProfileLintFinding[];
+    /** Non-fatal catalog merge warnings (built-in shadowing attempts, duplicate names). */
+    warnings: string[];
+    /** ISO timestamp the result was produced. */
+    generated_at: string;
+}
+/** Discriminated union of every `pm profile` result shape. */
+export type ProfileResult = ProfileListResult | ProfileShowResult | ProfileApplyResult | ProfileLintResult;
+/**
+ * Lists every available profile — the built-in archetypes followed by profiles
+ * contributed by active extensions — with per-dimension composition counts and
+ * the source each came from. Surfaces any non-fatal merge collisions as warnings.
+ */
+export declare function runProfileList(): ProfileListResult;
+/**
+ * Shows the full composition of a single profile, resolved across built-in and
+ * extension-contributed archetypes. Throws a USAGE error for a missing or unknown
+ * profile name.
+ */
+export declare function runProfileShow(name: string | undefined): ProfileShowResult;
+/**
+ * Lints a single profile, resolved across built-in and extension-contributed
+ * archetypes, returning every graded consistency finding plus any catalog merge
+ * warnings. Throws a USAGE error for a missing or unknown profile name. This is
+ * the read-only author-time validation surface; it never writes to the tracker.
+ */
+export declare function runProfileLint(name: string | undefined): ProfileLintResult;
+/** Options accepted by {@link runProfileApply}. */
+export interface ProfileApplyCommandOptions {
+    /** Preview the diff without writing any files. */
+    dryRun?: boolean;
+    /** Mutation author override. */
+    author?: string;
+    /** Force ownership/lock override. */
+    force?: boolean;
+}
+/**
+ * Applies a profile to the initialized tracker, or previews the idempotent diff
+ * when `dryRun` is set. Schema files are written under their respective locks;
+ * config and workflows are persisted to settings; templates are staged via the
+ * shared template writer. Re-applying an already-applied profile performs zero
+ * writes. Throws a USAGE error for an unknown profile or an invalid config knob,
+ * and a NOT_FOUND error when the tracker is not initialized.
+ */
+export declare function runProfileApply(name: string | undefined, options: ProfileApplyCommandOptions, global: GlobalOptions): Promise<ProfileApplyResult>;
+/**
+ * Renders the `pm profile list` result as human-readable text.
+ */
+export declare function formatProfileListHuman(result: ProfileListResult): string;
+/**
+ * Renders the `pm profile show` result as human-readable text.
+ */
+export declare function formatProfileShowHuman(result: ProfileShowResult): string;
+/**
+ * Renders the `pm profile lint` result as human-readable text: a one-line verdict
+ * followed by each finding prefixed with its severity, code, and dimension.
+ */
+export declare function formatProfileLintHuman(result: ProfileLintResult): string;
+/**
+ * Renders the `pm profile apply` result as human-readable text, including the
+ * staged diff and any package recommendations.
+ */
+export declare function formatProfileApplyHuman(result: ProfileApplyResult): string;