@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/dist/cli/commands/plan.js

@@ -0,0 +1,975 @@
+
+!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]="588c239a-66d0-5d60-b675-5a5a4e79d70b")}catch(e){}}();
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { resolveItemTypeRegistry, resolveTypeName } from "../../core/item/type-registry.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { nowIso } from "../../core/shared/time.js";
+import { locateItem, mutateItem, readLocatedItem } from "../../core/store/item-store.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
+import { runCreate } from "./create.js";
+export const PLAN_SUBCOMMANDS = [
+    "create",
+    "show",
+    "add-step",
+    "update-step",
+    "complete-step",
+    "block-step",
+    "reorder-step",
+    "remove-step",
+    "link",
+    "unlink",
+    "decision",
+    "discovery",
+    "validation",
+    "resume",
+    "approve",
+    "materialize",
+];
+export const PLAN_SHOW_DEPTH_VALUES = ["brief", "standard", "deep"];
+const STEP_ID_PREFIX = "plan-step-";
+const DEFAULT_PLAN_MODE = "draft";
+function resolveAuthor(candidate, fallback) {
+    const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;
+    const trimmed = resolved.trim();
+    return trimmed.length > 0 ? trimmed : "unknown";
+}
+function toArray(value) {
+    if (Array.isArray(value))
+        return value.flatMap((entry) => entry.split(",")).map((entry) => entry.trim()).filter(Boolean);
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+    }
+    return [];
+}
+function toSpecArray(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => entry.trim()).filter(Boolean);
+    if (typeof value === "string" && value.trim().length > 0)
+        return [value.trim()];
+    return [];
+}
+function asPlanMode(value, fallback = DEFAULT_PLAN_MODE) {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    const found = PLAN_MODE_VALUES.find((entry) => entry === normalized);
+    if (!found) {
+        throw new PmCliError(`Invalid plan mode "${value}". Allowed: ${PLAN_MODE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    return found;
+}
+function asStepStatus(value, fallback = "pending") {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    const found = PLAN_STEP_STATUS_VALUES.find((entry) => entry === normalized);
+    if (!found) {
+        throw new PmCliError(`Invalid step status "${value}". Allowed: ${PLAN_STEP_STATUS_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    return found;
+}
+function asLinkKind(value, fallback = "related") {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    const found = PLAN_STEP_LINK_KIND_VALUES.find((entry) => entry === normalized);
+    if (!found) {
+        throw new PmCliError(`Invalid step link kind "${value}". Allowed: ${PLAN_STEP_LINK_KIND_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    return found;
+}
+function asHarness(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0)
+        return undefined;
+    const found = PLAN_HARNESS_VALUES.find((entry) => entry === normalized);
+    if (!found) {
+        throw new PmCliError(`Invalid plan harness "${value}". Allowed: ${PLAN_HARNESS_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    return found;
+}
+function asDepth(value) {
+    if (value === undefined)
+        return "brief";
+    const normalized = value.trim().toLowerCase();
+    const found = PLAN_SHOW_DEPTH_VALUES.find((entry) => entry === normalized);
+    if (!found) {
+        throw new PmCliError(`Invalid --depth "${value}". Allowed: ${PLAN_SHOW_DEPTH_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    return found;
+}
+function parsePlanFields(raw) {
+    if (raw === undefined) {
+        return null;
+    }
+    const fields = raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (fields.length === 0) {
+        throw new PmCliError("Plan --fields requires a comma-separated list of plan field names", EXIT_CODE.USAGE);
+    }
+    return fields;
+}
+function projectPlanForFields(plan, fields) {
+    const source = plan;
+    const projected = {};
+    for (const field of fields) {
+        const normalized = field.startsWith("plan.") ? field.slice("plan.".length) : field;
+        if (normalized.length === 0) {
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(source, normalized)) {
+            projected[normalized] = source[normalized];
+        }
+    }
+    return projected;
+}
+function parsePairList(raw, label) {
+    const out = {};
+    for (const entry of raw.split(",")) {
+        const trimmed = entry.trim();
+        if (trimmed.length === 0)
+            continue;
+        const equalsIndex = trimmed.indexOf("=");
+        if (equalsIndex <= 0) {
+            throw new PmCliError(`Invalid ${label} entry "${trimmed}"; expected key=value`, EXIT_CODE.USAGE);
+        }
+        out[trimmed.slice(0, equalsIndex).trim().toLowerCase()] = trimmed.slice(equalsIndex + 1).trim();
+    }
+    return out;
+}
+function parseStepFile(spec) {
+    const fields = parsePairList(spec, "--file");
+    if (!fields.path) {
+        throw new PmCliError("--file requires path=<value>", EXIT_CODE.USAGE);
+    }
+    const file = { path: fields.path };
+    if (fields.scope === "global" || fields.scope === "project")
+        file.scope = fields.scope;
+    if (fields.note)
+        file.note = fields.note;
+    return file;
+}
+function parseStepTest(spec) {
+    const fields = parsePairList(spec, "--test");
+    if (!fields.command && !fields.path) {
+        throw new PmCliError("--test requires at least command=<value> or path=<value>", EXIT_CODE.USAGE);
+    }
+    const test = {};
+    if (fields.command)
+        test.command = fields.command;
+    if (fields.path)
+        test.path = fields.path;
+    if (fields.note)
+        test.note = fields.note;
+    return test;
+}
+function parseStepDoc(spec) {
+    const fields = parsePairList(spec, "--doc");
+    if (!fields.path) {
+        throw new PmCliError("--doc requires path=<value>", EXIT_CODE.USAGE);
+    }
+    const doc = { path: fields.path };
+    if (fields.scope === "global" || fields.scope === "project")
+        doc.scope = fields.scope;
+    if (fields.note)
+        doc.note = fields.note;
+    return doc;
+}
+function summarizeSteps(steps) {
+    const summary = {
+        total: steps.length,
+        pending: 0,
+        in_progress: 0,
+        blocked: 0,
+        completed: 0,
+        skipped: 0,
+        superseded: 0,
+    };
+    for (const step of steps) {
+        summary[step.status] += 1;
+    }
+    return summary;
+}
+function newStepId(existing) {
+    const used = new Set(existing.map((step) => step.id));
+    for (let cursor = existing.length + 1; cursor < existing.length + 1024; cursor += 1) {
+        const candidate = `${STEP_ID_PREFIX}${String(cursor).padStart(3, "0")}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+    /* c8 ignore next -- step id allocation only fails if 1024 consecutive ids are taken. */
+    throw new PmCliError("Could not allocate step id (limit reached)", EXIT_CODE.GENERIC_FAILURE);
+}
+function resolveStepRef(steps, ref) {
+    const trimmed = ref.trim();
+    if (trimmed.length === 0) {
+        throw new PmCliError("Step reference cannot be empty", EXIT_CODE.USAGE);
+    }
+    const direct = steps.find((step) => step.id === trimmed);
+    if (direct)
+        return direct;
+    if (/^\d+$/.test(trimmed)) {
+        const order = Number.parseInt(trimmed, 10);
+        const byOrder = steps.find((step) => step.order === order);
+        if (byOrder)
+            return byOrder;
+    }
+    throw new PmCliError(`Step "${ref}" not found in plan`, EXIT_CODE.NOT_FOUND);
+}
+function findCurrentStep(steps) {
+    return steps.find((step) => step.status === "in_progress")
+        ?? steps.find((step) => step.status === "pending");
+}
+function blockedSteps(steps) {
+    return steps
+        .filter((step) => step.status === "blocked")
+        .map((step) => ({ id: step.id, order: step.order, title: step.title, blocked_reason: step.blocked_reason }));
+}
+function projectPlan(item, depth = "brief") {
+    const steps = (item.plan_steps ?? []).slice().sort((left, right) => left.order - right.order);
+    const summary = summarizeSteps(steps);
+    const current = findCurrentStep(steps);
+    const projection = {
+        id: item.id,
+        title: item.title,
+        status: item.status,
+        mode: (item.plan_mode ?? DEFAULT_PLAN_MODE),
+        scope: item.plan_scope,
+        harness: item.plan_harness,
+        parent: item.parent,
+        resume_context: item.plan_resume_context,
+        steps_summary: summary,
+        current_step: current
+            ? { id: current.id, order: current.order, title: current.title, status: current.status }
+            : undefined,
+        blocked_steps: blockedSteps(steps),
+        linked_items: (item.dependencies ?? []).map((dep) => ({ id: dep.id, kind: dep.kind })),
+    };
+    if (depth === "standard" || depth === "deep") {
+        projection.steps = steps;
+    }
+    if (depth === "deep") {
+        projection.decisions = item.plan_decisions ?? [];
+        projection.discoveries = item.plan_discoveries ?? [];
+        projection.validation = item.plan_validation ?? [];
+    }
+    return projection;
+}
+function nextActionsFor(planId, plan) {
+    const tips = [];
+    if (plan.steps_summary.total === 0) {
+        tips.push(`pm plan add-step ${planId} --step-title "First step"`);
+    }
+    if (plan.current_step) {
+        tips.push(`pm plan update-step ${planId} ${plan.current_step.id} --step-status in_progress`, `pm plan complete-step ${planId} ${plan.current_step.id} --step-evidence "..."`);
+    }
+    if (plan.steps_summary.blocked > 0) {
+        tips.push(`pm plan show ${planId} --depth standard`);
+    }
+    if (plan.mode === "draft" || plan.mode === "research") {
+        tips.push(`pm plan approve ${planId} --message "ready to execute"`);
+    }
+    if (plan.steps_summary.completed === plan.steps_summary.total && plan.steps_summary.total > 0) {
+        tips.push(`pm close ${planId} "plan complete"`);
+    }
+    return tips;
+}
+function ensurePlanItem(item) {
+    const normalizedType = (item.type ?? "").trim().toLowerCase();
+    if (normalizedType !== "plan") {
+        throw new PmCliError(`Item ${item.id} is type ${item.type}; pm plan commands require type=Plan. Use pm plan create or pm create --type Plan first.`, EXIT_CODE.USAGE);
+    }
+}
+async function loadContext(global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    return { pmRoot, settings };
+}
+async function readPlanItem(ctx, id) {
+    const typeRegistry = resolveItemTypeRegistry(ctx.settings, getActiveExtensionRegistrations());
+    const located = await locateItem(ctx.pmRoot, id, ctx.settings.id_prefix, ctx.settings.item_format, typeRegistry.type_to_folder);
+    if (!located) {
+        throw new PmCliError(`Plan ${id} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    const loaded = await readLocatedItem(located, { schema: ctx.settings.schema });
+    ensurePlanItem(loaded.document.metadata);
+    return { document: loaded.document, itemId: located.id };
+}
+async function planCreate(options, global, ctx) {
+    const title = options.title?.trim();
+    if (!title) {
+        throw new PmCliError("pm plan create requires --title", EXIT_CODE.USAGE, {
+            code: "missing_required_option",
+            examples: ['pm plan create --title "Refactor lock retry" --scope pm-a1b2'],
+        });
+    }
+    const mode = asPlanMode(options.mode, DEFAULT_PLAN_MODE);
+    const harness = asHarness(options.harness);
+    const fromSearch = options.fromSearch?.trim();
+    const related = toArray(options.related);
+    const blocks = toArray(options.blocks);
+    const blockedBy = toArray(options.blockedBy);
+    const deps = [];
+    if (options.parent) {
+        deps.push(`id=${options.parent.trim()},kind=parent`);
+    }
+    for (const ref of related)
+        deps.push(`id=${ref},kind=related`);
+    for (const ref of blocks)
+        deps.push(`id=${ref},kind=blocks`);
+    for (const ref of blockedBy)
+        deps.push(`id=${ref},kind=blocked_by`);
+    const description = options.description?.trim() ?? options.scope?.trim() ?? title;
+    const createOptions = {
+        title,
+        description,
+        type: "Plan",
+        body: options.body,
+        tags: options.tags,
+        priority: options.priority,
+        parent: options.parent,
+        dep: deps.length > 0 ? deps : undefined,
+        author: options.author,
+        message: options.message ?? (fromSearch ? `plan create (search: ${fromSearch})` : `plan create`),
+    };
+    const createResult = await runCreate(createOptions, global);
+    // The create command stores type_options. To use real metadata keys, run a follow-up mutate.
+    const seedResult = await mutateItem({
+        pmRoot: ctx.pmRoot,
+        settings: ctx.settings,
+        id: createResult.item.id,
+        op: "plan_create_metadata",
+        author: resolveAuthor(options.author, ctx.settings.author_default),
+        message: "seed plan metadata",
+        mutate(doc) {
+            const changed = [];
+            doc.metadata.plan_mode = mode;
+            changed.push("plan_mode");
+            if (harness) {
+                doc.metadata.plan_harness = harness;
+                changed.push("plan_harness");
+            }
+            if (options.scope?.trim()) {
+                doc.metadata.plan_scope = options.scope.trim();
+                changed.push("plan_scope");
+            }
+            if (options.resumeContext?.trim()) {
+                doc.metadata.plan_resume_context = options.resumeContext.trim();
+                changed.push("plan_resume_context");
+            }
+            doc.metadata.plan_steps = doc.metadata.plan_steps ?? [];
+            return { changedFields: changed };
+        },
+    });
+    let finalMetadata = seedResult.item;
+    if (options.claim) {
+        const claimed = await mutateItem({
+            pmRoot: ctx.pmRoot,
+            settings: ctx.settings,
+            id: createResult.item.id,
+            op: "claim",
+            author: resolveAuthor(options.author, ctx.settings.author_default),
+            message: "plan claim by author",
+            mutate(doc) {
+                doc.metadata.assignee = resolveAuthor(options.author, ctx.settings.author_default);
+                return { changedFields: ["assignee"] };
+            },
+        });
+        finalMetadata = claimed.item;
+    }
+    const plan = projectPlan(finalMetadata, "brief");
+    return {
+        action: "create",
+        plan,
+        next_actions: nextActionsFor(createResult.item.id, plan),
+        warnings: [...createResult.warnings],
+        generated_at: nowIso(),
+    };
+}
+async function planShow(id, options, ctx) {
+    const depth = asDepth(options.depth);
+    const fields = parsePlanFields(options.fields);
+    const { document, itemId } = await readPlanItem(ctx, id);
+    const fullPlan = projectPlan(document.metadata, depth);
+    const plan = fields === null ? fullPlan : projectPlanForFields(fullPlan, fields);
+    return {
+        action: "show",
+        plan,
+        next_actions: nextActionsFor(itemId, fullPlan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function mutatePlanSteps(args) {
+    const author = resolveAuthor(args.options.author, args.ctx.settings.author_default);
+    let resultStep;
+    const result = await mutateItem({
+        pmRoot: args.ctx.pmRoot,
+        settings: args.ctx.settings,
+        id: args.id,
+        op: args.op,
+        author,
+        message: args.options.message ?? args.message,
+        force: args.options.force,
+        mutate(doc) {
+            ensurePlanItem(doc.metadata);
+            const steps = (doc.metadata.plan_steps ?? []).slice();
+            const before = JSON.stringify(steps);
+            const outcome = args.mutator(steps, doc);
+            resultStep = outcome.resultStep;
+            const sorted = steps
+                .slice()
+                .sort((left, right) => left.order - right.order)
+                .map((step, index) => ({ ...step, order: index + 1 }));
+            doc.metadata.plan_steps = sorted;
+            const after = JSON.stringify(sorted);
+            const changedFields = before === after ? [] : ["plan_steps"];
+            if (changedFields.length === 0 && outcome.changedSteps.length === 0) {
+                return { changedFields: [] };
+            }
+            return { changedFields: changedFields.length > 0 ? changedFields : ["plan_steps"] };
+        },
+    });
+    return {
+        document: { metadata: result.item, body: result.body },
+        resultStep,
+        itemId: result.item.id,
+    };
+}
+async function planAddStep(id, options, ctx) {
+    const title = options.stepTitle?.trim();
+    if (!title) {
+        throw new PmCliError("pm plan add-step requires --step-title", EXIT_CODE.USAGE);
+    }
+    const status = asStepStatus(options.stepStatus, "pending");
+    const allowMultipleActive = options.allowMultipleActive === true;
+    const linkedItems = buildLinkInputs(options, "depends_on");
+    const files = toSpecArray(options.file).map(parseStepFile);
+    const tests = toSpecArray(options.test).map(parseStepTest);
+    const docs = toSpecArray(options.doc).map(parseStepDoc);
+    const { document, resultStep, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_add_step",
+        message: `plan add-step "${title}"`,
+        mutator(steps) {
+            const order = steps.length + 1;
+            if (status === "in_progress" && !allowMultipleActive) {
+                for (const step of steps) {
+                    if (step.status === "in_progress") {
+                        throw new PmCliError(`Plan already has step ${step.id} in_progress. Pass --allow-multiple-active or update that step first.`, EXIT_CODE.CONFLICT);
+                    }
+                }
+            }
+            const now = nowIso();
+            const step = {
+                id: newStepId(steps),
+                order,
+                title,
+                body: options.stepBody?.trim() || undefined,
+                status,
+                owner: options.stepOwner?.trim() || undefined,
+                evidence: options.stepEvidence?.trim() || undefined,
+                blocked_reason: status === "blocked" ? options.stepBlockedReason?.trim() || "" : undefined,
+                linked_items: linkedItems.length > 0 ? linkedItems : undefined,
+                files: files.length > 0 ? files : undefined,
+                tests: tests.length > 0 ? tests : undefined,
+                docs: docs.length > 0 ? docs : undefined,
+                created_at: now,
+                updated_at: now,
+                completed_at: status === "completed" ? now : undefined,
+            };
+            steps.push(step);
+            return { changedSteps: [step.id], resultStep: step };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: "add-step",
+        plan,
+        step: resultStep,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+function buildLinkInputs(options, fallbackKind) {
+    const dependsOn = toArray(options.dependsOn).map((id) => ({ id, kind: fallbackKind }));
+    const related = toArray(options.related).map((id) => ({ id, kind: "related" }));
+    const blocks = toArray(options.blocks).map((id) => ({ id, kind: "blocks" }));
+    const blockedBy = toArray(options.blockedBy).map((id) => ({ id, kind: "blocked_by" }));
+    const explicit = toArray(options.link);
+    const explicitKind = asLinkKind(options.linkKind, fallbackKind);
+    const note = options.linkNote?.trim();
+    const explicitLinks = explicit.map((id) => {
+        const link = { id, kind: explicitKind };
+        if (note)
+            link.note = note;
+        return link;
+    });
+    return [...dependsOn, ...related, ...blocks, ...blockedBy, ...explicitLinks];
+}
+async function planUpdateStep(id, options, ctx, args) {
+    const { document, resultStep, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: args.op,
+        message: options.message ?? `${args.op} ${args.stepRef}`,
+        mutator(steps, doc) {
+            const step = resolveStepRef(steps, args.stepRef);
+            const now = nowIso();
+            const desiredStatus = args.finalStatus ?? asStepStatus(options.stepStatus, step.status);
+            if (desiredStatus === "in_progress" && step.status !== "in_progress" && !options.allowMultipleActive && !args.allowMultipleActive) {
+                for (const other of steps) {
+                    if (other.id !== step.id && other.status === "in_progress") {
+                        throw new PmCliError(`Plan already has step ${other.id} in_progress. Pass --allow-multiple-active or update that step first.`, EXIT_CODE.CONFLICT);
+                    }
+                }
+            }
+            if (desiredStatus === "blocked" && !options.stepBlockedReason?.trim() && !step.blocked_reason) {
+                throw new PmCliError("Blocking a step requires --step-blocked-reason or an already-recorded blocked_reason.", EXIT_CODE.USAGE);
+            }
+            if (options.stepTitle?.trim())
+                step.title = options.stepTitle.trim();
+            if (options.stepBody !== undefined)
+                step.body = options.stepBody.trim() || undefined;
+            if (options.stepOwner !== undefined)
+                step.owner = options.stepOwner.trim() || undefined;
+            if (options.stepEvidence !== undefined)
+                step.evidence = options.stepEvidence.trim() || undefined;
+            if (options.stepBlockedReason !== undefined)
+                step.blocked_reason = options.stepBlockedReason.trim() || undefined;
+            if (options.stepReplacement !== undefined)
+                step.superseded_by = options.stepReplacement.trim() || undefined;
+            step.status = desiredStatus;
+            step.updated_at = now;
+            if (desiredStatus === "completed" && !step.completed_at) {
+                step.completed_at = now;
+            }
+            else if (desiredStatus !== "completed") {
+                step.completed_at = undefined;
+            }
+            doc.metadata.updated_at = now;
+            return { changedSteps: [step.id], resultStep: step };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: args.op === "plan_complete_step" ? "complete-step" : args.op === "plan_block_step" ? "block-step" : "update-step",
+        plan,
+        step: resultStep,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planReorderStep(id, options, ctx, stepRef, newOrder) {
+    const { document, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_reorder_step",
+        message: options.message ?? `plan reorder-step ${stepRef} -> ${newOrder}`,
+        mutator(steps) {
+            const step = resolveStepRef(steps, stepRef);
+            const filtered = steps.filter((entry) => entry.id !== step.id);
+            const clamped = Math.max(1, Math.min(newOrder, filtered.length + 1));
+            filtered.splice(clamped - 1, 0, step);
+            filtered.forEach((entry, index) => {
+                entry.order = index + 1;
+                entry.updated_at = nowIso();
+            });
+            steps.length = 0;
+            steps.push(...filtered);
+            return { changedSteps: [step.id], resultStep: step };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: "reorder-step",
+        plan,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planRemoveStep(id, options, ctx, stepRef) {
+    const { document, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_remove_step",
+        message: options.message ?? `plan remove-step ${stepRef}`,
+        mutator(steps) {
+            const step = resolveStepRef(steps, stepRef);
+            const remaining = steps.filter((entry) => entry.id !== step.id);
+            remaining.forEach((entry, index) => {
+                entry.order = index + 1;
+            });
+            steps.length = 0;
+            steps.push(...remaining);
+            return { changedSteps: [step.id] };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: "remove-step",
+        plan,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planLink(id, options, ctx, stepRef) {
+    const newLinks = buildLinkInputs(options, asLinkKind(options.linkKind, "related"));
+    if (newLinks.length === 0) {
+        throw new PmCliError("pm plan link requires at least one --link/--related/--blocks/--blocked-by/--depends-on id", EXIT_CODE.USAGE);
+    }
+    const promoteToItemDep = options.promoteToItemDep === true;
+    const { document, itemId, resultStep } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_link_step",
+        message: options.message ?? `plan link ${stepRef}`,
+        mutator(steps, doc) {
+            const step = resolveStepRef(steps, stepRef);
+            const existing = step.linked_items ?? [];
+            const dedupKey = (link) => `${link.kind}:${link.id}`;
+            const seen = new Set(existing.map(dedupKey));
+            for (const link of newLinks) {
+                const key = dedupKey(link);
+                if (seen.has(key))
+                    continue;
+                existing.push(link);
+                seen.add(key);
+            }
+            step.linked_items = existing;
+            step.updated_at = nowIso();
+            if (promoteToItemDep) {
+                const deps = doc.metadata.dependencies ?? [];
+                const depKey = (dep) => `${dep.kind}:${dep.id}`;
+                const seenDeps = new Set(deps.map(depKey));
+                for (const link of newLinks) {
+                    const candidate = {
+                        id: link.id,
+                        kind: link.kind,
+                        created_at: nowIso(),
+                        author: resolveAuthor(options.author, ctx.settings.author_default),
+                    };
+                    if (seenDeps.has(depKey(candidate)))
+                        continue;
+                    deps.push(candidate);
+                    seenDeps.add(depKey(candidate));
+                }
+                doc.metadata.dependencies = deps;
+            }
+            return { changedSteps: [step.id], resultStep: step };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: "link",
+        plan,
+        step: resultStep,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planUnlink(id, options, ctx, stepRef) {
+    const removeIds = toArray(options.link);
+    if (removeIds.length === 0) {
+        throw new PmCliError("pm plan unlink requires --link <id> to remove", EXIT_CODE.USAGE);
+    }
+    const { document, itemId, resultStep } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_unlink_step",
+        message: options.message ?? `plan unlink ${stepRef}`,
+        mutator(steps) {
+            const step = resolveStepRef(steps, stepRef);
+            const filtered = (step.linked_items ?? []).filter((link) => !removeIds.includes(link.id));
+            step.linked_items = filtered.length > 0 ? filtered : undefined;
+            step.updated_at = nowIso();
+            return { changedSteps: [step.id], resultStep: step };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: "unlink",
+        plan,
+        step: resultStep,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planAppendLog(id, options, ctx, kind) {
+    if (kind === "decision" && !options.decisionText?.trim()) {
+        throw new PmCliError("pm plan decision requires --decision-text", EXIT_CODE.USAGE);
+    }
+    if (kind === "discovery" && !options.discoveryText?.trim()) {
+        throw new PmCliError("pm plan discovery requires --discovery-text", EXIT_CODE.USAGE);
+    }
+    if (kind === "validation" && !options.validationText?.trim()) {
+        throw new PmCliError("pm plan validation requires --validation-text", EXIT_CODE.USAGE);
+    }
+    const author = resolveAuthor(options.author, ctx.settings.author_default);
+    const { document, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: `plan_append_${kind}`,
+        message: options.message ?? `plan ${kind} append`,
+        mutator(_steps, doc) {
+            const now = nowIso();
+            if (kind === "decision") {
+                const list = doc.metadata.plan_decisions ?? [];
+                list.push({
+                    ts: now,
+                    author,
+                    decision: options.decisionText.trim(),
+                    rationale: options.decisionRationale?.trim() || undefined,
+                    evidence: options.decisionEvidence?.trim() || undefined,
+                });
+                doc.metadata.plan_decisions = list;
+                return { changedSteps: [] };
+            }
+            if (kind === "discovery") {
+                const list = doc.metadata.plan_discoveries ?? [];
+                list.push({ ts: now, author, text: options.discoveryText.trim() });
+                doc.metadata.plan_discoveries = list;
+                return { changedSteps: [] };
+            }
+            const list = doc.metadata.plan_validation ?? [];
+            list.push({
+                text: options.validationText.trim(),
+                command: options.validationCommand?.trim() || undefined,
+                expected: options.validationExpected?.trim() || undefined,
+            });
+            doc.metadata.plan_validation = list;
+            return { changedSteps: [] };
+        },
+    });
+    const plan = projectPlan(document.metadata, "deep");
+    return {
+        action: kind,
+        plan,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planResume(id, options, ctx) {
+    const text = options.resumeContext?.trim();
+    if (!text) {
+        throw new PmCliError("pm plan resume requires --resume-context <text>", EXIT_CODE.USAGE);
+    }
+    const { document, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_resume",
+        message: options.message ?? "plan resume context update",
+        mutator(_steps, doc) {
+            doc.metadata.plan_resume_context = text;
+            return { changedSteps: [] };
+        },
+    });
+    const plan = projectPlan(document.metadata, "brief");
+    return {
+        action: "resume",
+        plan,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planApprove(id, options, ctx) {
+    const mode = asPlanMode(options.mode ?? "approved", "approved");
+    const { document, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_approve",
+        message: options.message ?? `plan approve mode=${mode}`,
+        mutator(_steps, doc) {
+            doc.metadata.plan_mode = mode;
+            return { changedSteps: [] };
+        },
+    });
+    const plan = projectPlan(document.metadata, "brief");
+    return {
+        action: "approve",
+        plan,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+async function planMaterialize(id, options, ctx) {
+    const stepRefs = toArray(options.steps);
+    if (stepRefs.length === 0) {
+        throw new PmCliError("pm plan materialize requires --steps <ids|orders>", EXIT_CODE.USAGE);
+    }
+    const targetType = options.materializeType?.trim() || "Task";
+    const typeRegistry = resolveItemTypeRegistry(ctx.settings, getActiveExtensionRegistrations());
+    const resolvedTypeName = resolveTypeName(targetType, typeRegistry);
+    if (!resolvedTypeName) {
+        throw new PmCliError(`Invalid --materialize-type "${targetType}"`, EXIT_CODE.USAGE);
+    }
+    const parent = options.materializeParent?.trim() || id;
+    const tags = options.materializeTags;
+    const planRead = await readPlanItem(ctx, id);
+    const steps = (planRead.document.metadata.plan_steps ?? []).slice();
+    const targets = stepRefs.map((ref) => resolveStepRef(steps, ref));
+    if (targets.length === 0) {
+        throw new PmCliError("No matching plan steps found for --steps", EXIT_CODE.NOT_FOUND);
+    }
+    const materialized = [];
+    for (const step of targets) {
+        const deps = [
+            `id=${parent},kind=parent`,
+            `id=${planRead.itemId},kind=discovered_from`,
+        ];
+        for (const link of step.linked_items ?? []) {
+            const realKind = link.kind === "blocked_by" || link.kind === "blocks" || link.kind === "related" || link.kind === "discovered_from"
+                ? link.kind
+                : "related";
+            deps.push(`id=${link.id},kind=${realKind}`);
+        }
+        const created = await runCreate({
+            title: step.title,
+            description: step.body?.trim() || step.title,
+            type: resolvedTypeName,
+            parent,
+            tags,
+            author: options.author,
+            message: options.message ?? `materialized from plan ${planRead.itemId} step ${step.id}`,
+            dep: deps,
+        }, ctx.settings ? { ...{}, path: ctx.pmRoot } : {});
+        materialized.push({ id: created.item.id, type: resolvedTypeName, from_step: step.id });
+    }
+    const { document, itemId } = await mutatePlanSteps({
+        id,
+        options,
+        ctx,
+        op: "plan_materialize",
+        message: options.message ?? `plan materialize ${stepRefs.join(",")}`,
+        mutator(currentSteps, doc) {
+            for (const target of targets) {
+                const matched = materialized.find((entry) => entry.from_step === target.id);
+                if (!matched)
+                    continue;
+                const step = currentSteps.find((entry) => entry.id === target.id);
+                if (!step)
+                    continue;
+                const links = step.linked_items ?? [];
+                links.push({ id: matched.id, kind: "implements", note: `materialized as ${matched.type}` });
+                step.linked_items = links;
+                step.updated_at = nowIso();
+            }
+            const deps = doc.metadata.dependencies ?? [];
+            for (const m of materialized) {
+                deps.push({ id: m.id, kind: "child", created_at: nowIso(), author: resolveAuthor(options.author, ctx.settings.author_default) });
+            }
+            doc.metadata.dependencies = deps;
+            return { changedSteps: targets.map((entry) => entry.id) };
+        },
+    });
+    const plan = projectPlan(document.metadata, "standard");
+    return {
+        action: "materialize",
+        plan,
+        materialized,
+        next_actions: nextActionsFor(itemId, plan),
+        warnings: [],
+        generated_at: nowIso(),
+    };
+}
+export async function runPlan(input) {
+    const ctx = await loadContext(input.global);
+    switch (input.subcommand) {
+        case "create":
+            return planCreate(input.options, input.global, ctx);
+        case "show":
+            if (!input.id)
+                throw new PmCliError("pm plan show requires a plan id", EXIT_CODE.USAGE);
+            return planShow(input.id, input.options, ctx);
+        case "add-step":
+            if (!input.id)
+                throw new PmCliError("pm plan add-step requires a plan id", EXIT_CODE.USAGE);
+            return planAddStep(input.id, input.options, ctx);
+        case "update-step":
+            if (!input.id || !input.stepRef)
+                throw new PmCliError("pm plan update-step requires <plan-id> <step>", EXIT_CODE.USAGE);
+            return planUpdateStep(input.id, input.options, ctx, { stepRef: input.stepRef, op: "plan_update_step" });
+        case "complete-step":
+            if (!input.id || !input.stepRef)
+                throw new PmCliError("pm plan complete-step requires <plan-id> <step>", EXIT_CODE.USAGE);
+            return planUpdateStep(input.id, input.options, ctx, { stepRef: input.stepRef, finalStatus: "completed", op: "plan_complete_step" });
+        case "block-step":
+            if (!input.id || !input.stepRef)
+                throw new PmCliError("pm plan block-step requires <plan-id> <step>", EXIT_CODE.USAGE);
+            return planUpdateStep(input.id, input.options, ctx, { stepRef: input.stepRef, finalStatus: "blocked", op: "plan_block_step" });
+        case "reorder-step":
+            if (!input.id || !input.stepRef || input.reorderTo === undefined)
+                throw new PmCliError("pm plan reorder-step requires <plan-id> <step> <new-order>", EXIT_CODE.USAGE);
+            return planReorderStep(input.id, input.options, ctx, input.stepRef, input.reorderTo);
+        case "remove-step":
+            if (!input.id || !input.stepRef)
+                throw new PmCliError("pm plan remove-step requires <plan-id> <step>", EXIT_CODE.USAGE);
+            return planRemoveStep(input.id, input.options, ctx, input.stepRef);
+        case "link":
+            if (!input.id || !input.stepRef)
+                throw new PmCliError("pm plan link requires <plan-id> <step>", EXIT_CODE.USAGE);
+            return planLink(input.id, input.options, ctx, input.stepRef);
+        case "unlink":
+            if (!input.id || !input.stepRef)
+                throw new PmCliError("pm plan unlink requires <plan-id> <step>", EXIT_CODE.USAGE);
+            return planUnlink(input.id, input.options, ctx, input.stepRef);
+        case "decision":
+            if (!input.id)
+                throw new PmCliError("pm plan decision requires a plan id", EXIT_CODE.USAGE);
+            return planAppendLog(input.id, input.options, ctx, "decision");
+        case "discovery":
+            if (!input.id)
+                throw new PmCliError("pm plan discovery requires a plan id", EXIT_CODE.USAGE);
+            return planAppendLog(input.id, input.options, ctx, "discovery");
+        case "validation":
+            if (!input.id)
+                throw new PmCliError("pm plan validation requires a plan id", EXIT_CODE.USAGE);
+            return planAppendLog(input.id, input.options, ctx, "validation");
+        case "resume":
+            if (!input.id)
+                throw new PmCliError("pm plan resume requires a plan id", EXIT_CODE.USAGE);
+            return planResume(input.id, input.options, ctx);
+        case "approve":
+            if (!input.id)
+                throw new PmCliError("pm plan approve requires a plan id", EXIT_CODE.USAGE);
+            return planApprove(input.id, input.options, ctx);
+        case "materialize":
+            if (!input.id)
+                throw new PmCliError("pm plan materialize requires a plan id", EXIT_CODE.USAGE);
+            return planMaterialize(input.id, input.options, ctx);
+        default:
+            throw new PmCliError(`Unknown pm plan subcommand "${input.subcommand}"`, EXIT_CODE.USAGE);
+    }
+}
+//# sourceMappingURL=plan.js.map
+//# debugId=588c239a-66d0-5d60-b675-5a5a4e79d70b