@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

package/dist/services/stage-pause.js

@@ -0,0 +1,175 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
+import { refreshRunWorkProjection } from "./work-registry.js";
+export function pauseStageForUser(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    if (work.status !== "running")
+        throw new AppError("invalid_work_state", "Only a running Work can pause", 1, { work_id: work.work_id, status: work.status });
+    const question = input.question;
+    if (!question.trim())
+        throw new AppError("validation", "stage pause requires a non-empty user question", 2);
+    const stage = requireStage(run, input.stage, "running");
+    const pauseId = nextPauseId(requireRunHome(run));
+    const pauseRoot = path.join(requireRunHome(run), "intake", "hitl", `${pauseId}-${safeStage(input.stage)}`);
+    const questionPath = path.join(pauseRoot, "question.md");
+    fs.mkdirSync(pauseRoot, { recursive: true });
+    fs.writeFileSync(questionPath, question);
+    const now = context.now();
+    context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
+    pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
+    refreshRunWorkProjection(context, project.id, run.id);
+    const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot });
+    const resumeTemplate = `${resume} <<'USER_ANSWER'\n<paste the complete user answer exactly>\nUSER_ANSWER`;
+    return {
+        ok: true,
+        outcome: "paused",
+        run_id: run.id,
+        work_id: work.work_id,
+        stage: stage.stage,
+        pause: { id: pauseId, reason: "waiting_for_user", question_path: questionPath, user_message: question },
+        next_action: "ask_user_then_resume_same_stage",
+        agent_instruction: "Send user_message to the user and stop this Turn. When the user answers, do not interpret or edit the answer first: make resume_command the first flow command, pass the complete raw answer on stdin, then follow the returned continuation prompt. Do not create a RUN, Work, attempt, or stage start.",
+        resume_command: resume,
+        resume_command_template: resumeTemplate
+    };
+}
+export function resumeStageAfterUser(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    if (work.status !== "paused")
+        throw new AppError("invalid_work_state", "stage resume requires its paused Work", 1, { work_id: work.work_id, status: work.status });
+    const stage = requireStage(run, input.stage, "paused");
+    if (!stage.pause || stage.pause.work_id !== work.work_id || stage.pause.answer_path)
+        throw new AppError("invalid_stage_state", "Stage has no unanswered pause for this Work", 1, { run_id: run.id, stage: stage.stage, work_id: work.work_id });
+    if (!input.answer.trim())
+        throw new AppError("validation", "stage resume requires a non-empty user answer", 2);
+    const hookEventId = input.hookEventId ?? findRecentMatchingHookEvent(context, {
+        projectId: project.id,
+        matchKey: stageResumeMatchKey(run.id, stage.stage, work.work_id, projectRoot),
+        errorCode: "trusted_stage_resume_required",
+        operation: "stage resume"
+    }).eventKey;
+    const identity = claimStageResumeHookEvent(context, {
+        projectId: project.id,
+        runId: run.id,
+        stage: stage.stage,
+        workId: work.work_id,
+        projectRoot,
+        eventKey: hookEventId
+    });
+    const answerPath = path.join(path.dirname(stage.pause.question_path), "answer.md");
+    fs.writeFileSync(answerPath, input.answer);
+    const now = context.now();
+    const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
+    if (!workSession)
+        throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
+    if (workSession.session_id !== identity.sessionId) {
+        context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
+        context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+    }
+    context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
+    resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
+    refreshRunWorkProjection(context, project.id, run.id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
+    const prompt = fs.readFileSync(workSession.prompt_path, "utf8");
+    const continuation = [
+        prompt.trimEnd(),
+        "",
+        "<hitl_resume>",
+        `- Pause: ${stage.pause.id}`,
+        `- Question source: ${stage.pause.question_path}`,
+        `- Answer source: ${answerPath}`,
+        "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
+        "",
+        "<user_question>",
+        fs.readFileSync(stage.pause.question_path, "utf8"),
+        "</user_question>",
+        "",
+        "<user_answer>",
+        input.answer,
+        "</user_answer>",
+        "</hitl_resume>",
+        ""
+    ].join("\n");
+    return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: stage.pause.id, question_path: stage.pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+}
+export function stagePauseCommand(context, input) {
+    return `${flowCommand(context)} stage pause ${input.runId} --stage ${input.stage} --work ${input.workId} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`;
+}
+/**
+ * The only shell form allowed for an agent-owned HITL pause.  Supplying a
+ * complete heredoc makes stdin explicit without asking an agent to invent a
+ * pipe, a temporary file or a second command.
+ */
+export function stagePauseCommandTemplate(command) {
+    return `${command} <<'USER_QUESTION'
+## Q-001 — <short decision title>
+
+Why this decision is required:
+- <one sentence>
+
+Options:
+- <option A>
+- <option B>
+
+Recommendation:
+- <one option and reason>
+
+Effect on scope or acceptance:
+- <one sentence>
+USER_QUESTION`;
+}
+function stageResumeCommand(context, input) {
+    return `${flowCommand(context)} stage resume ${input.runId} --stage ${input.stage} --work ${input.workId} --answer-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`;
+}
+export function flowCommand(context) {
+    const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));
+    return context.ddFlowHome === defaultHome ? "dd-flow" : `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
+}
+function requireRun(context, projectId, id) {
+    const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
+    if (rows.length !== 1)
+        throw new AppError(rows.length ? "ambiguous_alias" : "not_found", rows.length ? "RUN alias is ambiguous" : "RUN is not registered", 1, { run_id: id });
+    return rows[0];
+}
+function requireWork(context, projectId, runId, workId) {
+    const work = context.db.get("SELECT work_id, project_id, run_id, status FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [projectId, runId, workId]);
+    if (!work)
+        throw new AppError("not_found", "Work does not belong to this RUN", 1, { run_id: runId, work_id: workId });
+    return work;
+}
+function requireStage(run, stage, status) {
+    const index = JSON.parse(run.index_json);
+    const found = index.stage_runs?.find((item) => item.stage === stage);
+    if (!found || found.status !== status)
+        throw new AppError("invalid_stage_state", `Stage must be ${status}`, 1, { run_id: run.id, stage, status: found?.status ?? "missing" });
+    return found;
+}
+function requireRunHome(run) {
+    if (!run.run_home_path)
+        throw new AppError("runtime_missing", "RUN has no artifact home", 1, { run_id: run.id });
+    return run.run_home_path;
+}
+function nextPauseId(runHome) {
+    const root = path.join(runHome, "intake", "hitl");
+    const max = fs.existsSync(root) ? fs.readdirSync(root).reduce((value, name) => Math.max(value, Number(name.match(/^HITL-(\d+)/)?.[1] ?? 0)), 0) : 0;
+    return `HITL-${String(max + 1).padStart(3, "0")}`;
+}
+function safeStage(stage) {
+    const value = stage.trim().toLowerCase();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value))
+        throw new AppError("validation", "stage name is invalid", 2, { stage });
+    return value;
+}

package/dist/services/stage-report-renderer.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { writeJsonAtomic } from "../storage/paths.js";
+/** Deterministic JSON -> Markdown/HTML projection shared by every stage. */
+export function writeStageReport(root, report) {
+    const json = path.join(root, "stage-report.json");
+    const markdown = path.join(root, "stage-report.md");
+    const html = path.join(root, "stage-report.html");
+    const semantic = object(report.semantic);
+    const sourceArtifacts = object(report.artifacts);
+    const normalized = {
+        ...report,
+        schema_id: "dd-flow/stage-report@2",
+        summary: string(report.summary) || string(semantic.result) || "Stage completed.",
+        semantic: {
+            ...semantic,
+            result: string(semantic.result),
+            acceptance: array(semantic.acceptance),
+            changed_files: array(semantic.changed_files ?? semantic.run_changed_files),
+            checks: array(semantic.checks),
+            evidence: array(semantic.evidence),
+            next_action: string(semantic.next_action)
+        },
+        artifacts: {
+            json: string(sourceArtifacts.json) || "stage-report.json",
+            markdown: string(sourceArtifacts.markdown) || "stage-report.md",
+            html: string(sourceArtifacts.html) || "stage-report.html"
+        }
+    };
+    writeJsonAtomic(json, normalized);
+    const text = renderStageReportMarkdown(normalized);
+    fs.writeFileSync(markdown, text);
+    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
+    return { json, markdown, html };
+}
+export function renderStageReportMarkdown(report) {
+    const semantic = object(report.semantic);
+    const summary = string(semantic.result) || string(report.summary) || "Stage completed.";
+    const acceptance = strings(semantic.acceptance);
+    const checks = strings(semantic.checks);
+    const evidence = strings(semantic.evidence);
+    const next = string(semantic.next_action);
+    const sections = [
+        `# ${string(report.stage).toUpperCase() || "Stage"} report`,
+        "",
+        summary,
+        "",
+        `**Verdict:** ${string(report.verdict) || "unknown"}`,
+        ...(acceptance.length ? ["", "## Acceptance", "", ...acceptance.map((item) => `- ${item}`)] : []),
+        ...(checks.length ? ["", "## Checks", "", ...checks.map((item) => `- ${item}`)] : []),
+        ...(evidence.length ? ["", "## Evidence", "", ...evidence.map((item) => `- ${item}`)] : []),
+        ...(next ? ["", `**Next action:** ${next}`] : []),
+        ""
+    ];
+    return sections.join("\n");
+}
+function renderStageReportHtml(report, markdown) {
+    const title = `${string(report.stage).toUpperCase() || "Stage"} report`;
+    return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(title)}</title><style>body{font:16px/1.55 system-ui,sans-serif;max-width:880px;margin:3rem auto;padding:0 1.25rem;color:#202124}pre{white-space:pre-wrap;font:inherit}</style><main><pre>${escape(markdown)}</pre></main></html>\n`;
+}
+function object(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function string(value) { return typeof value === "string" ? value : ""; }
+function strings(value) { return Array.isArray(value) ? value.filter((item) => typeof item === "string") : []; }
+function array(value) { return Array.isArray(value) ? value : []; }
+function escape(value) { return value.replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]); }

package/dist/services/status.js

@@ -9,7 +9,7 @@ import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-sta
 import { findProjectByRoot } from "./projects.js";
 import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityReport } from "./compatibility-preflight.js";
-import { selectEngine } from "./engines.js";
+import { compatibilityContexts, selectEngine } from "./engines.js";
 export function getRuntimeStatus(context, input = {}) {
     const cwd = process.cwd();
     const projectRootResolution = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd });
@@ -26,9 +26,13 @@ export function getRuntimeStatus(context, input = {}) {
     const cli = getCliBuildInfo();
     const compatibilityManifest = resolvedCanonForProject ? readCompatibilityManifest(canon) : null;
     const cliCompatibility = cliCompatibilityVerdict(cli, compatibilityManifest);
-    const engineSelection = projectRoot ? selectEngine(context, { projectRoot }) : null;
+    const classification = classifyCliOperation(["status"], context.env);
+    const engineSelection = projectRoot
+        ? selectEngine(context, { projectRoot, env: context.env }, { allowCurrentInProcess: true }, classification)
+        : null;
     const flowContract = projectRoot ? projectFlowContractStatus(projectRoot) : null;
     const registry = input.checkRegistry ? checkNpmRegistry(context, cli.package_name) : undefined;
+    const contexts = projectRoot ? compatibilityContexts(context, { projectRoot, env: context.env, classification }) : null;
     return {
         ok: true,
         schema_id: "dd-flow/status-report@1",
@@ -54,7 +58,8 @@ export function getRuntimeStatus(context, input = {}) {
         engine: engineSelection
             ? {
                 selection: engineSelection,
-                compatibility: compatibilityReport(engineSelection, classifyCliOperation(["status"]))
+                compatibility: compatibilityReport(engineSelection, classification),
+                contexts
             }
             : null,
         canon: {