@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

package/dist/services/protocols.js

@@ -1,31 +1,38 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { parse as parseYaml } from "yaml";
 import { canTransition } from "../domain/contracts.js";
 import { defaultFlowContract, flowContractForState, loadProjectFlowContract } from "../domain/flow-contract.js";
 import { requireStage } from "../domain/validation.js";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
-import { ensureReadableFile } from "../storage/database.js";
-import { ensureDir, planJsonPath, resolveProjectRoot, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
+import { prepareJsonFile } from "../cli/input-preparation.js";
+import { ensureDir, planJsonPath, resolveProjectRoot, resolveProtocolPlanPath, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit, getAuditEvents } from "./audit.js";
+import { withProjectionLock } from "../storage/projection-lock.js";
 import { requireProjectByRoot } from "./projects.js";
-import { ensureRuntimeProtocolFiles, readStateFile, writeState } from "../protocol/local-files.js";
+import { prepareRuntimeProtocolFiles, publishRuntimeProtocolMetadata, readStateFile, writeState } from "../protocol/local-files.js";
 import { planSummary, planWithProgress, readCanonicalPlan } from "./plan-runtime.js";
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
 import { buildProtocolFlowGuidance } from "./flow-guidance.js";
 import { lifecycleIsTerminalFailure, lifecycleIsTerminalSuccess, normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 import { getProtocolBranchContext } from "./branch-context.js";
-export function registerProtocol(context, input) {
+export function prepareProtocolRegistration(context, input) {
+    if (typeof input.handshakeId !== "string" || !input.handshakeId.trim() || /[/\\\0]/.test(input.handshakeId) || [".", ".."].includes(input.handshakeId))
+        throw new AppError("validation", "Protocol handshake must be a non-empty identifier, not a path", 2);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
-    const now = context.now();
     const workspacePath = input.workspacePath ? resolveProjectRoot(input.workspacePath) : undefined;
     const idRoot = workspacePath ?? projectRoot;
     const protocolId = inferProtocolId(idRoot, input.handshakeId);
     const runtimeDir = runtimeProtocolDir(context.ddFlowHome, project.id, protocolId);
-    const state = ensureRuntimeProtocolFiles({
+    return { projectRoot, project, workspacePath, protocolId, runtimeDir };
+}
+export function registerProtocol(context, input) {
+    const { projectRoot, project, workspacePath, protocolId, runtimeDir } = prepareProtocolRegistration(context, input);
+    const now = context.now();
+    const initialized = prepareRuntimeProtocolFiles({
         runtimeDir,
         protocolId,
         projectRoot,
@@ -33,25 +40,27 @@ export function registerProtocol(context, input) {
         workspacePath,
         now
     });
-    const existing = findProtocol(context, protocolId, project.id);
-    const params = [
-        protocolId,
-        input.handshakeId,
-        project.id,
-        projectRoot,
-        state.status,
-        state.stage,
-        state.next_action,
-        JSON.stringify(state.route),
-        JSON.stringify(state.workspace),
-        JSON.stringify(state.blockers),
-        JSON.stringify(state.active_def),
-        runtimeStateJsonPath(context.ddFlowHome, project.id, protocolId),
-        planJsonPath(workspacePath ?? projectRoot, protocolId),
-        existing?.created_at ?? now,
-        now
-    ];
-    context.db.run(`INSERT INTO protocols
+    return context.db.writeTransaction(() => {
+        const existing = findProtocol(context, protocolId, project.id);
+        const state = existing ? latestProtocolProjection(context, project.id, protocolId) ?? initialized : initialized;
+        const params = [
+            protocolId,
+            input.handshakeId,
+            project.id,
+            projectRoot,
+            state.status,
+            state.stage,
+            state.next_action,
+            JSON.stringify(state.route),
+            JSON.stringify(state.workspace),
+            JSON.stringify(state.blockers),
+            JSON.stringify(state.active_def),
+            runtimeStateJsonPath(context.ddFlowHome, project.id, protocolId),
+            planJsonPath(workspacePath ?? projectRoot, protocolId),
+            existing?.created_at ?? now,
+            now
+        ];
+        context.db.run(`INSERT INTO protocols
       (id, handshake_id, project_id, project_root, status, stage, next_action,
        route_json, workspace_json, blockers_json, active_def_json, state_path, plan_path,
        created_at, updated_at)
@@ -70,19 +79,23 @@ export function registerProtocol(context, input) {
        state_path = excluded.state_path,
        plan_path = excluded.plan_path,
        updated_at = excluded.updated_at`, params);
-    appendAudit(context, {
-        protocolId,
-        projectId: project.id,
-        eventType: existing ? "protocol.registration_refreshed" : "protocol.registered",
-        payload: {
-            protocol_id: protocolId,
-            handshake_id: input.handshakeId,
-            project_root: projectRoot,
-            workspace_path: workspacePath ?? null,
-            runtime_dir: runtimeDir
-        }
-    });
-    return { ok: true, protocol: protocolStatusPayload(requireProtocol(context, protocolId, project.id)), state };
+        appendAudit(context, { protocolId, projectId: project.id, eventType: "protocol.state_projection", payload: { state } });
+        context.db.afterCommit(() => publishProtocolProjection(context, project.id, protocolId));
+        context.db.afterCommit(() => publishRuntimeProtocolMetadata({ runtimeDir, protocolId, handshakeId: input.handshakeId, projectRoot }));
+        appendAudit(context, {
+            protocolId,
+            projectId: project.id,
+            eventType: existing ? "protocol.registration_refreshed" : "protocol.registered",
+            payload: {
+                protocol_id: protocolId,
+                handshake_id: input.handshakeId,
+                project_root: projectRoot,
+                workspace_path: workspacePath ?? null,
+                runtime_dir: runtimeDir
+            }
+        });
+        return { ok: true, protocol: protocolStatusPayload(requireProtocol(context, protocolId, project.id)), state };
+    }, "protocol.register");
 }
 export function getProtocolStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -243,7 +256,22 @@ export function implementProtocol(context, input) {
         }
     };
 }
-export function transitionProtocol(context, input) {
+export function prepareProtocolTransition(context, input) {
+    const { value } = prepareJsonFile(input.jsonFile, "Protocol transition payload");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "Protocol transition payload must be an object", 2);
+    const payload = value;
+    for (const [key, field] of Object.entries(payload)) {
+        const valid = key === "next_action" ? typeof field === "string"
+            : ["route", "workspace"].includes(key) ? Boolean(field && typeof field === "object" && !Array.isArray(field))
+                : ["blockers", "active_def"].includes(key) && Array.isArray(field);
+        if (!valid)
+            throw new AppError("validation", `Unsupported field or invalid value in protocol transition: ${key}`, 2, { file: input.jsonFile, parameter: key });
+    }
+    protocolTransitionState(context, input);
+    return payload;
+}
+function protocolTransitionState(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const state = readProtocolRuntimeState(context, protocol).state;
@@ -256,8 +284,10 @@ export function transitionProtocol(context, input) {
     if (input.force && (!input.reason || input.reason.trim().length === 0)) {
         throw new AppError("validation", "Forced transitions require --reason", 2);
     }
-    ensureReadableFile(input.jsonFile);
-    const payload = parseJsonObject(fs.readFileSync(input.jsonFile, "utf8"), input.jsonFile);
+    return { project, protocol, state, flowContract, from, to };
+}
+export function transitionProtocol(context, input, payload = prepareProtocolTransition(context, input)) {
+    const { project, protocol, state, flowContract, from, to } = protocolTransitionState(context, input);
     const nextState = {
         ...state,
         stage: to,
@@ -416,8 +446,7 @@ export function syncProtocolFromRun(context, input) {
         next_action: nextActionForSyncedTarget(targetStage),
         updated_at: now
     };
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    context.db.writeTransaction(() => {
         persistProtocolState(context, protocol, nextState);
         if (targetStage === "ready_for_merge") {
             context.db.run(`INSERT INTO merge_queue
@@ -449,12 +478,7 @@ export function syncProtocolFromRun(context, input) {
                 stage_chain: stageChain(index)
             }
         });
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    }, "protocols.syncFromRun");
     return {
         ok: true,
         protocol_id: protocol.id,
@@ -486,8 +510,7 @@ export function cancelProtocol(context, input) {
     const now = context.now();
     const worktree = context.db.get("SELECT worktree_path, status FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
     const worktreeRemoval = input.worktree === "remove" ? removeProtocolWorktreeBeforeCancel(protocol, state, worktree, input.force) : undefined;
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    return context.db.writeTransaction(() => {
         const nextState = {
             ...state,
             stage: "cancelled",
@@ -548,7 +571,6 @@ export function cancelProtocol(context, input) {
                 worktree_outcome: worktreeOutcome
             }
         });
-        context.db.exec("COMMIT");
         return {
             ok: true,
             protocol_id: protocol.id,
@@ -560,11 +582,7 @@ export function cancelProtocol(context, input) {
             worktree_outcome: worktreeOutcome,
             worktree: context.db.get("SELECT * FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]) ?? null
         };
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    }, "protocols.cancel");
 }
 export function requireProtocol(context, protocolId, projectId) {
     const matches = projectId
@@ -579,7 +597,10 @@ export function requireProtocol(context, protocolId, projectId) {
             candidates: matches.map((protocol) => ({ project_id: protocol.project_id, project_root: protocol.project_root }))
         });
     }
-    return matches[0];
+    return resolvedProtocolRecord(matches[0]);
+}
+function resolvedProtocolRecord(protocol) {
+    return { ...protocol, plan_path: resolveProtocolPlanPath(protocol.project_root, protocol.id, protocol.plan_path) };
 }
 function cancelQueueForProtocol(context, protocol, reason, force) {
     const job = context.db.get("SELECT id, status, claimed_by_session_id FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
@@ -647,7 +668,9 @@ function removeProtocolWorktreeBeforeCancel(protocol, state, record, force) {
     }
     const existsBefore = fs.existsSync(worktreePath);
     if (existsBefore && !force) {
-        const dirty = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
+        const dirty = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
+        if (dirty.error || dirty.status !== 0)
+            throw new AppError("workspace_status_failed", "Cannot establish worktree status before removal", 1, { path: worktreePath, cause: dirty.error?.message ?? dirty.stderr });
         if (dirty.status === 0 && dirty.stdout.trim().length > 0) {
             throw new AppError("worktree_dirty", "Refusing to remove dirty worktree without --force --reason", 1, {
                 path: worktreePath
@@ -733,9 +756,42 @@ function releaseRelatedMergeLocks(context, protocol, reason) {
     return { ok: true, released: released.length, locks: released };
 }
 export function readProtocolRuntimeState(context, protocol) {
+    const expected = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    if (protocol.state_path !== expected)
+        throw new AppError("protocol_state_migration_required", "Protocol runtime path requires explicit cleanup scan/apply before use", 1, { protocol_id: protocol.id, path: protocol.state_path, expected_path: expected });
+    const accepted = latestProtocolProjection(context, protocol.project_id, protocol.id);
+    if (accepted)
+        return { state: accepted, diagnostics: [] };
+    return resolveProtocolRuntimeState(context, { ...protocol }, false);
+}
+/** Explicit cleanup migration; productive readers accept only the current path. */
+export function repairProtocolRuntimeState(context, protocol) {
+    // Readers project the canonical plan path without migrating storage. Repair
+    // must start from the stored locations, not that already-normalized view.
+    const stored = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [protocol.project_id, protocol.id]);
+    if (stored)
+        Object.assign(protocol, stored);
+    return resolveProtocolRuntimeState(context, protocol, true);
+}
+/** Read-only repair preparation; caller CASes paths, then persists this state. */
+export function prepareProtocolRuntimeRepair(context, protocol) {
+    const stored = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [protocol.project_id, protocol.id]);
+    if (!stored)
+        throw new AppError("not_found", "Protocol is not registered", 1, { protocol_id: protocol.id });
+    const state = latestProtocolProjection(context, stored.project_id, stored.id) ?? resolveProtocolRuntimeState(context, { ...stored }, false).state;
+    return {
+        state,
+        statePath: runtimeStateJsonPath(context.ddFlowHome, stored.project_id, stored.id),
+        planPath: planJsonPath(stored.project_root, stored.id),
+        previousStatePath: stored.state_path
+    };
+}
+function resolveProtocolRuntimeState(context, protocol, repair) {
     const diagnostics = [];
-    normalizeProtocolPlanPath(context, protocol, diagnostics);
+    normalizeProtocolPlanPath(context, protocol, diagnostics, repair);
     try {
+        if (protocol.state_path !== runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id))
+            throw new AppError("protocol_state_migration_required", "Retired state files are not runtime authority", 1);
         return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
     }
     catch {
@@ -750,7 +806,8 @@ export function readProtocolRuntimeState(context, protocol) {
                 recommended_action: "legacy protocol state_path was moved to stable runtime storage"
             });
             const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
-            context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
+            if (repair && context.db.writable)
+                context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
             protocol.state_path = stableStatePath;
             protocol.plan_path = stablePlanPath;
             return { state: readStateFile(stableStatePath, protocol.id), diagnostics };
@@ -783,7 +840,7 @@ export function readProtocolRuntimeState(context, protocol) {
         flow_contract: flowContract,
         updated_at: protocol.updated_at
     };
-    if (!context.db.writable) {
+    if (!repair || !context.db.writable) {
         return { state, diagnostics };
     }
     const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
@@ -802,9 +859,9 @@ export function readProtocolRuntimeState(context, protocol) {
     });
     return { state, diagnostics };
 }
-function normalizeProtocolPlanPath(context, protocol, diagnostics) {
-    const canonicalPlanPath = planJsonPath(protocol.project_root, protocol.id);
-    if (protocol.plan_path === canonicalPlanPath || !fs.existsSync(canonicalPlanPath))
+function normalizeProtocolPlanPath(context, protocol, diagnostics, repair) {
+    const canonicalPlanPath = resolveProtocolPlanPath(protocol.project_root, protocol.id, protocol.plan_path);
+    if (protocol.plan_path === canonicalPlanPath)
         return;
     diagnostics.push({
         code: "protocol_plan_relocated",
@@ -814,7 +871,7 @@ function normalizeProtocolPlanPath(context, protocol, diagnostics) {
         source: "project_canonical_plan",
         recommended_action: "use the project canonical plan as the sole semantic plan source"
     });
-    if (context.db.writable) {
+    if (repair && context.db.writable) {
         context.db.run("UPDATE protocols SET plan_path = ?, updated_at = ? WHERE project_id = ? AND id = ?", [canonicalPlanPath, context.now(), protocol.project_id, protocol.id]);
     }
     protocol.plan_path = canonicalPlanPath;
@@ -847,38 +904,57 @@ export function protocolRunDiagnostics(context, protocol, state) {
     return { latest_run: latestWithStages, diagnostics };
 }
 export function persistProtocolState(context, protocol, state) {
-    ensureDir(path.dirname(protocol.state_path));
-    writeState(protocol.state_path, state);
-    context.db.run(`UPDATE protocols SET
+    context.db.writeTransaction(() => {
+        context.db.run(`UPDATE protocols SET
        status = ?, stage = ?, next_action = ?, route_json = ?, workspace_json = ?,
        blockers_json = ?, active_def_json = ?, updated_at = ?
      WHERE project_id = ? AND id = ?`, [
-        state.status,
-        state.stage,
-        state.next_action,
-        JSON.stringify(state.route),
-        JSON.stringify(state.workspace),
-        JSON.stringify(state.blockers),
-        JSON.stringify(state.active_def),
-        state.updated_at,
-        protocol.project_id,
-        protocol.id
-    ]);
-    if (state.status === "closed" || state.stage === "closed") {
-        const now = context.now();
-        context.db.run(`UPDATE sessions
+            state.status,
+            state.stage,
+            state.next_action,
+            JSON.stringify(state.route),
+            JSON.stringify(state.workspace),
+            JSON.stringify(state.blockers),
+            JSON.stringify(state.active_def),
+            state.updated_at,
+            protocol.project_id,
+            protocol.id
+        ]);
+        appendAudit(context, { protocolId: protocol.id, projectId: protocol.project_id, eventType: "protocol.state_projection", payload: { state } });
+        if (state.status === "closed" || state.stage === "closed") {
+            const now = context.now();
+            context.db.run(`UPDATE sessions
        SET status = 'stopped', stop_reason = 'protocol closed', updated_at = ?, stopped_at = ?
        WHERE project_id = ?
          AND protocol_id = ?
          AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [now, now, protocol.project_id, protocol.id]);
-    }
+        }
+        context.db.afterCommit(() => publishProtocolProjection(context, protocol.project_id, protocol.id));
+    }, "protocols.persistProtocolState");
+}
+function latestProtocolProjection(context, projectId, protocolId) {
+    const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id = ? AND protocol_id = ? AND event_type = 'protocol.state_projection' ORDER BY id DESC LIMIT 1", [projectId, protocolId]);
+    return row ? JSON.parse(row.payload_json).state : null;
+}
+export function publishProtocolProjection(context, projectId, protocolId) {
+    const protocol = requireProtocol(context, protocolId, projectId);
+    ensureDir(path.dirname(protocol.state_path));
+    withProjectionLock(`${protocol.state_path}.publish-lock`, () => {
+        const accepted = latestProtocolProjection(context, projectId, protocolId);
+        if (!accepted)
+            throw new AppError("runtime_state_missing", "Protocol has no accepted SQL state", 1, { protocol_id: protocolId });
+        const temporary = `${protocol.state_path}.tmp-${process.pid}-${crypto.randomUUID()}`;
+        fs.writeFileSync(temporary, `${JSON.stringify(accepted, null, 2)}\n`);
+        fs.renameSync(temporary, protocol.state_path);
+    });
 }
 function findProtocol(context, protocolId, projectId) {
     if (projectId) {
-        return context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+        const protocol = context.db.get("SELECT * FROM protocols WHERE project_id = ? AND id = ?", [projectId, protocolId]);
+        return protocol ? resolvedProtocolRecord(protocol) : undefined;
     }
     const matches = context.db.all("SELECT * FROM protocols WHERE id = ? ORDER BY project_id", [protocolId]);
-    return matches.length === 1 ? matches[0] : undefined;
+    return matches.length === 1 ? resolvedProtocolRecord(matches[0]) : undefined;
 }
 function protocolDocumentsForProject(projectRoot) {
     const protocolRoot = path.join(projectRoot, ".memory-bank", "protocol");