@deksden-com/dd-flow-cli 0.2.0 → 0.3.1

package/dist/services/flow-guidance.js

@@ -0,0 +1,221 @@
+import path from "node:path";
+import { defaultFlowContract, flowContractForState } from "../domain/flow-contract.js";
+import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
+export function buildProtocolFlowGuidance(input) {
+    const contract = flowContractForState(input.state);
+    const lifecycle = normalizeProtocolLifecycle({ state: input.state, queueStatus: input.queueStatus ?? null, flowContract: contract });
+    const stageChain = latestRunStageChain(input.latestRun);
+    return buildFlowGuidance({
+        currentStage: input.state.stage,
+        lifecycle,
+        contract,
+        stageChain,
+        runId: stringValue(input.latestRun?.id),
+        queueStatus: input.queueStatus ?? null
+    });
+}
+export function buildRunFlowGuidance(input) {
+    const contract = input.contract ?? defaultFlowContract;
+    const chain = input.stageRuns.map((stage) => `${String(stage.stage ?? "unknown")}:${String(stage.status ?? "unknown")}`);
+    const currentStage = input.protocolStage ?? inferStageFromRun(input.stageRuns);
+    return buildFlowGuidance({
+        currentStage,
+        lifecycle: normalizeProtocolLifecycle({ rawStage: currentStage, rawStatus: "running", flowContract: contract }),
+        contract,
+        stageChain: chain,
+        runId: input.runId ?? null,
+        runDir: input.runDir ?? null,
+        stageRuns: input.stageRuns
+    });
+}
+export function buildStaticFlowGuidance(input) {
+    const contract = input.contract ?? defaultFlowContract;
+    return buildFlowGuidance({
+        currentStage: input.stage,
+        lifecycle: normalizeProtocolLifecycle({ rawStage: input.stage, rawStatus: input.status ?? "running", queueStatus: input.queueStatus ?? null, flowContract: contract }),
+        contract,
+        stageChain: [],
+        runId: null,
+        queueStatus: input.queueStatus ?? null
+    });
+}
+function buildFlowGuidance(input) {
+    const planDone = hasDoneStage(input.stageChain, "plan");
+    const codeDone = hasDoneStage(input.stageChain, "code") || hasDoneStage(input.stageChain, "implementation") || hasDoneStage(input.stageChain, "readiness");
+    const evidence = evidencePaths(input.runId, input.runDir ?? null, input.stageRuns);
+    if (input.currentStage === "closed" || input.currentStage === "cancelled") {
+        return guidance(input, {
+            action: "none",
+            prompt: "none",
+            evidence: [],
+            guards: [{ id: "flow_terminal", status: "not_applicable", summary: `Protocol is ${input.currentStage}.` }],
+            missing: []
+        });
+    }
+    if (input.currentStage === "ready_for_merge" || input.currentStage === "queued_for_merge") {
+        return guidance(input, {
+            action: input.currentStage === "queued_for_merge" ? "wait for or run merge worker" : "run merge flow",
+            prompt: ".memory-bank/dd-flow/merge.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [
+                {
+                    id: "merge_requires_ready_for_merge",
+                    status: "pass",
+                    summary: input.queueStatus ? `Protocol is ${input.currentStage}; queue status is ${input.queueStatus}.` : `Protocol is ${input.currentStage}.`
+                }
+            ],
+            missing: []
+        });
+    }
+    if (input.currentStage === "integration") {
+        return guidance(input, {
+            action: "finish merge job",
+            prompt: ".memory-bank/dd-flow/merge/job.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [{ id: "merge_requires_ready_for_merge", status: "pass", summary: "Merge job is in integration stage." }],
+            missing: []
+        });
+    }
+    if (input.currentStage === "readiness") {
+        return guidance(input, {
+            action: "complete readiness and mark ready for merge",
+            prompt: ".memory-bank/dd-flow/code/readiness.md",
+            evidence: evidence.code.length > 0 ? evidence.code : defaultEvidence(input.runId, input.runDir ?? null, "03-code"),
+            guards: [{ id: "merge_requires_ready_for_merge", status: codeDone ? "unknown" : "fail", summary: codeDone ? "Code evidence exists; readiness must still be completed." : "Code evidence is missing." }],
+            missing: codeDone ? ["ready_for_merge transition"] : ["code stage report", "ready_for_merge transition"]
+        });
+    }
+    if (input.currentStage === "implementation" || input.currentStage === "hardening") {
+        return guidance(input, {
+            action: "continue code flow",
+            prompt: input.currentStage === "hardening" ? ".memory-bank/dd-flow/finish.md" : ".memory-bank/dd-flow/code.md",
+            evidence: evidence.plan.length > 0 ? evidence.plan : defaultEvidence(input.runId, input.runDir ?? null, "02-plan"),
+            guards: [{
+                    id: "code_flow_requires_plan_ready",
+                    status: planDone ? "pass" : "unknown",
+                    summary: planDone ? "Plan stage evidence exists." : "Plan evidence was not found in the linked run."
+                }],
+            missing: planDone ? [] : ["plan stage report", "ready_for_code verdict"]
+        });
+    }
+    if (input.currentStage === "plan") {
+        return guidance(input, {
+            action: planDone ? "run code flow" : "complete plan flow",
+            prompt: planDone ? ".memory-bank/dd-flow/code.md" : ".memory-bank/dd-flow/plan.md",
+            evidence: evidence.plan.length > 0 ? evidence.plan : defaultEvidence(input.runId, input.runDir ?? null, "02-plan"),
+            guards: [{
+                    id: "code_flow_requires_plan_ready",
+                    status: planDone ? "pass" : "fail",
+                    summary: planDone ? "Plan stage report exists in linked run evidence." : "Plan stage evidence is not complete."
+                }],
+            missing: planDone ? [] : ["plan stage report", "ready_for_code verdict"]
+        });
+    }
+    if (input.currentStage === "specify" || input.currentStage === "priming" || input.currentStage === "prime" || input.currentStage === "registered") {
+        const action = input.currentStage === "registered" ? "run protocol/specify flow" : "run plan flow after specification is complete";
+        return guidance(input, {
+            action,
+            prompt: input.currentStage === "registered" ? ".memory-bank/dd-flow/protocol.md" : ".memory-bank/dd-flow/plan.md",
+            evidence: [],
+            guards: [{
+                    id: "plan_requires_protocol_and_specification",
+                    status: input.currentStage === "registered" ? "unknown" : "pass",
+                    summary: input.currentStage === "registered" ? "Protocol is registered; specification evidence must be checked by the prompt." : "Protocol has progressed past registration."
+                }],
+            missing: input.currentStage === "registered" ? ["specification evidence"] : []
+        });
+    }
+    if (input.currentStage === "blocked") {
+        return guidance(input, {
+            action: "resolve blocker and continue named safe flow",
+            prompt: "depends_on_blocker",
+            evidence: [],
+            guards: [{ id: "flow_blocked", status: "fail", summary: "Protocol is blocked." }],
+            missing: ["blocker resolution"]
+        });
+    }
+    if (input.currentStage === "waiting_for_user") {
+        return guidance(input, {
+            action: "collect user answer",
+            prompt: "active_protocol_context",
+            evidence: [],
+            guards: [{ id: "flow_waiting_for_user", status: "unknown", summary: "Protocol is waiting for user input." }],
+            missing: ["user answer"]
+        });
+    }
+    return guidance(input, {
+        action: `continue ${input.currentStage}`,
+        prompt: "active_flow_prompt",
+        evidence: [],
+        guards: [{ id: "flow_guidance_unknown_stage_policy", status: "unknown", summary: `No specific guidance rule for stage ${input.currentStage}.` }],
+        missing: []
+    });
+}
+function guidance(input, value) {
+    return {
+        current_stage: input.currentStage,
+        ...(input.lifecycle ? { lifecycle: input.lifecycle } : {}),
+        allowed_next_stages: input.contract.transitions[input.currentStage] ?? [],
+        recommended_next_action: value.action,
+        recommended_prompt: value.prompt,
+        required_predecessor_evidence: value.evidence,
+        guards: value.guards,
+        blocked_if_missing: value.missing
+    };
+}
+function latestRunStageChain(run) {
+    return Array.isArray(run?.stage_chain) ? run.stage_chain.filter((item) => typeof item === "string") : [];
+}
+function hasDoneStage(chain, stage) {
+    return chain.includes(`${stage}:done`);
+}
+function inferStageFromRun(stageRuns) {
+    const done = new Set(stageRuns.filter((stage) => stage.status === "done").map((stage) => stage.stage));
+    if (done.has("merge"))
+        return "closed";
+    if (done.has("code") || done.has("implementation") || done.has("readiness"))
+        return "ready_for_merge";
+    if (done.has("plan"))
+        return "plan";
+    return "registered";
+}
+function evidencePaths(runId, runDir, stageRuns) {
+    const result = { plan: [], code: [] };
+    if (!stageRuns)
+        return result;
+    for (const stage of stageRuns) {
+        const bucket = stage.stage === "plan" ? result.plan : ["code", "implementation", "readiness"].includes(String(stage.stage)) ? result.code : null;
+        if (!bucket)
+            continue;
+        const dir = stage.dir ? path.posix.join(runDir ?? legacyRunDir(runId), stage.dir) : stage.dir;
+        for (const field of [stage.data, stage.stage_report, stage.report]) {
+            if (field)
+                bucket.push(toEvidencePath(runId, runDir, stage.dir, field, dir));
+        }
+    }
+    return result;
+}
+function toEvidencePath(runId, runDir, stageDir, field, prefixedStageDir) {
+    if (!runId)
+        return field;
+    if (field.startsWith(".tasks/dd-flow-runs/"))
+        return field;
+    if (field.startsWith("runs/"))
+        return field;
+    if (stageDir && field.startsWith(`${stageDir}/`)) {
+        return path.posix.join(runDir ?? legacyRunDir(runId), field);
+    }
+    return prefixedStageDir ? path.posix.join(prefixedStageDir, field) : field;
+}
+function defaultEvidence(runId, runDir, dir) {
+    if (!runId)
+        return [`<RUN>/${dir}/stage-report.json`, `<RUN>/${dir}/stage-report.html`];
+    const base = path.posix.join(runDir ?? legacyRunDir(runId), dir);
+    return [path.posix.join(base, "stage-report.json"), path.posix.join(base, "stage-report.html")];
+}
+function legacyRunDir(runId) {
+    return runId ? path.posix.join(".tasks/dd-flow-runs", runId) : "<RUN>";
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/services/hooks.js

@@ -801,7 +801,7 @@ function mergeQueueMutation(command) {
     return match?.[1] ?? null;
 }
 function mergeLaneLockMutation(command) {
-    return /\bdd-flow\s+lane\s+lock\s+(acquire|heartbeat|release|wait)\b/.test(command) && /(?:--lane(?:\s+|=)(?:"merge"|'merge'|merge)\b)/.test(command);
+    return /\bdd-flow\s+lane\s+lock\s+(acquire|heartbeat|release|wait|wait-acquire)\b/.test(command) && /(?:--lane(?:\s+|=)(?:"merge"|'merge'|merge)\b)/.test(command);
 }
 function selfWorktreeRemovalTarget(command, cwd) {
     if (!/\bgit\s+worktree\s+remove\b/.test(command)) {

package/dist/services/ids.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatFullId, parseFullEntityId } from "../domain/entity-ids.js";
+import { AppError } from "../shared/errors.js";
+import { projectRunHome, resolveProjectRoot } from "../storage/paths.js";
+const kindConfig = {
+    protocol: { type: "PRT", table: "protocols", fileRoot: ".memory-bank/protocol" },
+    run: { type: "RUN", table: "flow_runs", fileRoot: ".tasks/dd-flow-runs" }
+};
+export function previewNextEntityId(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const kind = parseEntityKind(input.type);
+    const slug = normalizeSlug(input.slug);
+    const config = kindConfig[kind];
+    const used = new Set();
+    for (const id of databaseIds(context, config.table, config.type)) {
+        addSequence(used, id, config.type);
+    }
+    for (const id of filesystemIds(projectRoot, config.fileRoot, config.type)) {
+        addSequence(used, id, config.type);
+    }
+    if (kind === "run") {
+        for (const id of homeRunIds(context, projectRoot)) {
+            addSequence(used, id, config.type);
+        }
+        for (const id of filesystemIds(projectRoot, ".tasks", config.type)) {
+            addSequence(used, id, config.type);
+        }
+    }
+    for (let sequence = 1; sequence <= 999; sequence += 1) {
+        if (used.has(sequence))
+            continue;
+        const id = formatFullId(config.type, sequence, slug);
+        const parsed = parseFullEntityId(id);
+        return {
+            ok: true,
+            project_root: projectRoot,
+            entity: {
+                kind,
+                type: config.type,
+                id,
+                short_id: parsed.shortId,
+                slug,
+                sequence,
+                reserved: false
+            }
+        };
+    }
+    throw new AppError("validation", `${config.type} id sequence exhausted`, 2);
+}
+function homeRunIds(context, projectRoot) {
+    const project = context.db.get("SELECT id FROM projects WHERE root = ? AND status = 'active'", [projectRoot]);
+    if (!project) {
+        return [];
+    }
+    const root = projectRunHome(context.ddFlowHome, project.id, "__placeholder__").replace(/__placeholder__$/, "");
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [];
+    }
+    return fs.readdirSync(root).filter((entry) => entry.startsWith("RUN-"));
+}
+function parseEntityKind(value) {
+    const normalized = value.toLowerCase();
+    if (normalized === "protocol" || normalized === "prt")
+        return "protocol";
+    if (normalized === "run")
+        return "run";
+    throw new AppError("validation", "--type must be protocol or run", 2, { type: value });
+}
+function databaseIds(context, table, type) {
+    return context.db.all(`SELECT id FROM ${table} WHERE id LIKE ?`, [`${type}-%`]).map((row) => row.id);
+}
+function filesystemIds(projectRoot, relativeRoot, type) {
+    const root = path.join(projectRoot, relativeRoot);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return [];
+    }
+    return fs
+        .readdirSync(root)
+        .filter((entry) => entry.startsWith(`${type}-`))
+        .map((entry) => entry.replace(/\.md$/, ""));
+}
+function addSequence(used, id, type) {
+    try {
+        const parsed = parseFullEntityId(id);
+        if (parsed.type !== type)
+            return;
+        used.add(Number(parsed.shortId.slice(type.length + 1)));
+    }
+    catch {
+        return;
+    }
+}
+function normalizeSlug(value) {
+    const slug = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    if (!slug) {
+        throw new AppError("validation", "--slug must contain at least one ASCII letter or digit", 2);
+    }
+    return slug;
+}