@deksden-com/dd-flow-cli 0.1.0

package/dist/services/merge-queue.js

@@ -0,0 +1,333 @@
+import { loadProjectFlowContract } from "../domain/flow-contract.js";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { requireProjectByRoot } from "./projects.js";
+import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { acquireLaneLock, ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, requireLaneLockOwner } from "./lanes.js";
+import { stoppedMergeWorkerState } from "./sessions.js";
+const mergeLockTtlSeconds = 300;
+export function getMergeQueueStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return {
+        ok: true,
+        queue: queueForProject(context, project.id)
+    };
+}
+export function claimNextMergeJob(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    requireLaneLockOwner(context, {
+        projectRoot: project.root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath: input.workspacePath
+    });
+    const now = context.now();
+    let claimedProtocolId = null;
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const job = context.db.get(`SELECT * FROM merge_queue
+       WHERE project_id = ? AND status IN ('ready', 'requeued')
+       ORDER BY created_at ASC, id ASC
+       LIMIT 1`, [project.id]);
+        if (!job) {
+            context.db.exec("COMMIT");
+            return { ok: true, job: null };
+        }
+        const update = context.db.run(`UPDATE merge_queue
+       SET status = 'claimed', claimed_by_session_id = ?, claimed_at = ?, updated_at = ?
+       WHERE id = ? AND status IN ('ready', 'requeued')`, [input.workerId, now, now, job.id]);
+        if (update.changes !== 1) {
+            context.db.exec("COMMIT");
+            return { ok: true, job: null };
+        }
+        appendAudit(context, {
+            protocolId: job.protocol_id,
+            projectId: project.id,
+            eventType: "merge_queue.claimed",
+            payload: { protocol_id: job.protocol_id, worker_id: input.workerId }
+        });
+        claimedProtocolId = job.protocol_id;
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return { ok: true, job: claimedProtocolId ? queueJobByProtocol(context, claimedProtocolId) : null };
+}
+export async function waitNextMergeJob(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const timeoutSeconds = input.timeoutSeconds ?? 0;
+    const pollIntervalSeconds = input.pollIntervalSeconds ?? 10;
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) {
+        throw new AppError("validation", "--timeout must be zero or a positive number", 2);
+    }
+    if (!Number.isFinite(pollIntervalSeconds) || pollIntervalSeconds <= 0) {
+        throw new AppError("validation", "--poll-interval must be a positive number", 2);
+    }
+    if (input.acquireLock && pollIntervalSeconds >= mergeLockTtlSeconds) {
+        throw new AppError("validation", "--poll-interval must be lower than the merge lock TTL when --acquire-lock true", 2, {
+            lock_ttl_seconds: mergeLockTtlSeconds
+        });
+    }
+    const initialStopState = stoppedMergeWorkerState(context, project.id, input.workerId);
+    if (initialStopState.stopped) {
+        return { ok: true, job: null, waited: false, timed_out: false, stopped: true, reason: initialStopState.reason };
+    }
+    let releaseLockOnTimeout = false;
+    if (input.acquireLock) {
+        ensureLaneWorkspace(context, { projectRoot: project.root, lane: "merge", workspacePath: input.workspacePath });
+        const lockResult = acquireLaneLock(context, {
+            projectRoot: project.root,
+            lane: "merge",
+            workerId: input.workerId,
+            workspacePath: input.workspacePath,
+            ttlSeconds: mergeLockTtlSeconds,
+            reason: "merge queue wait-next"
+        });
+        releaseLockOnTimeout = !lockResult.reused;
+    }
+    else {
+        requireLaneLockOwner(context, {
+            projectRoot: project.root,
+            lane: "merge",
+            workerId: input.workerId,
+            workspacePath: input.workspacePath
+        });
+    }
+    const start = Date.now();
+    while (true) {
+        const stopState = stoppedMergeWorkerState(context, project.id, input.workerId);
+        if (stopState.stopped) {
+            if (input.acquireLock) {
+                releaseLaneLockIfOwned(context, {
+                    projectRoot: project.root,
+                    lane: "merge",
+                    workerId: input.workerId,
+                    workspacePath: input.workspacePath,
+                    reason: stopState.reason ?? "merge worker stopped"
+                });
+            }
+            appendAudit(context, {
+                projectId: project.id,
+                eventType: "merge_queue.wait_stopped",
+                ...(stopState.reason ? { reason: stopState.reason } : {}),
+                payload: { project_id: project.id, worker_id: input.workerId }
+            });
+            return { ok: true, job: null, waited: true, timed_out: false, stopped: true, reason: stopState.reason };
+        }
+        if (input.acquireLock) {
+            heartbeatLaneLock(context, {
+                projectRoot: project.root,
+                lane: "merge",
+                workerId: input.workerId,
+                workspacePath: input.workspacePath,
+                ttlSeconds: mergeLockTtlSeconds
+            });
+        }
+        const claimed = claimNextMergeJob(context, {
+            projectRoot: project.root,
+            workerId: input.workerId,
+            workspacePath: input.workspacePath
+        });
+        if (claimed.job) {
+            return { ...claimed, waited: true, timed_out: false };
+        }
+        if (timeoutSeconds > 0 && Date.now() - start >= timeoutSeconds * 1000) {
+            appendAudit(context, {
+                projectId: project.id,
+                eventType: "merge_queue.wait_timeout",
+                payload: { project_id: project.id, worker_id: input.workerId, timeout_seconds: timeoutSeconds }
+            });
+            if (input.acquireLock && releaseLockOnTimeout) {
+                releaseLaneLock(context, {
+                    projectRoot: project.root,
+                    lane: "merge",
+                    workerId: input.workerId,
+                    workspacePath: input.workspacePath,
+                    reason: "merge queue wait-next timeout"
+                });
+            }
+            return { ok: true, job: null, waited: true, timed_out: true };
+        }
+        await delay(pollIntervalSeconds * 1000);
+    }
+}
+export function completeMergeJob(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const job = requireClaimedJob(context, input.protocolId, input.workerId);
+    requireLaneLockOwner(context, {
+        projectRoot: protocol.project_root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath: input.workspacePath
+    });
+    const now = context.now();
+    context.db.run(`UPDATE merge_queue
+     SET status = 'merged', last_reason = ?, completed_at = ?, updated_at = ?
+     WHERE id = ?`, [input.summary, now, now, job.id]);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const flowContract = loadProjectFlowContract(protocol.project_root);
+    const targetStage = flowContract.merge_queue.complete.target_stage;
+    const targetStatus = flowContract.stages[targetStage]?.terminal ? targetStage : "running";
+    persistProtocolState(context, protocol, {
+        ...state,
+        stage: targetStage,
+        status: targetStatus,
+        next_action: flowContract.merge_queue.complete.next_action,
+        updated_at: now
+    });
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "merge_queue.completed",
+        payload: { protocol_id: protocol.id, worker_id: input.workerId, summary: input.summary, flow_contract_id: flowContract.id }
+    });
+    return { ok: true, job: queueJobByProtocol(context, protocol.id), next_stage: targetStage };
+}
+export function noteMergeJob(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const job = queueJobByProtocol(context, protocol.id);
+    if (!job) {
+        throw new AppError("not_found", "Merge queue job is not found", 1, { protocol_id: protocol.id });
+    }
+    if (job.status !== "merged") {
+        throw new AppError("merge_job_not_merged", "Merge queue note requires a merged job", 1, {
+            protocol_id: protocol.id,
+            status: job.status
+        });
+    }
+    if (job.claimed_by_session_id !== input.workerId) {
+        throw new AppError("merge_job_claimed_by_other_session", "Merge job is owned by another worker", 1, {
+            protocol_id: protocol.id,
+            claimed_by_session_id: job.claimed_by_session_id
+        });
+    }
+    const now = context.now();
+    context.db.run(`UPDATE merge_queue
+     SET last_reason = ?, updated_at = ?
+     WHERE id = ?`, [input.summary, now, job.id]);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "merge_queue.note",
+        payload: { protocol_id: protocol.id, worker_id: input.workerId, summary: input.summary }
+    });
+    return { ok: true, job: queueJobByProtocol(context, protocol.id) };
+}
+export function failMergeJob(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const job = requireClaimedJob(context, input.protocolId, input.workerId);
+    requireLaneLockOwner(context, {
+        projectRoot: protocol.project_root,
+        lane: "merge",
+        workerId: input.workerId,
+        workspacePath: input.workspacePath
+    });
+    const now = context.now();
+    const status = input.requeue ? "requeued" : "failed";
+    context.db.run(`UPDATE merge_queue
+     SET status = ?, attempts_count = attempts_count + 1, last_reason = ?, updated_at = ?
+     WHERE id = ?`, [status, input.reason, now, job.id]);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "merge_queue.failed",
+        reason: input.reason,
+        payload: { protocol_id: protocol.id, worker_id: input.workerId, requeue: input.requeue }
+    });
+    return { ok: true, job: queueJobByProtocol(context, protocol.id) };
+}
+export function cancelMergeQueueJob(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const reason = input.reason.trim();
+    if (!reason) {
+        throw new AppError("validation", "merge-queue cancel requires --reason", 2);
+    }
+    const now = context.now();
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        const job = queueJobByProtocol(context, protocol.id);
+        if (!job) {
+            throw new AppError("not_found", "Merge queue job is not found", 1, { protocol_id: protocol.id });
+        }
+        if (job.status === "cancelled") {
+            context.db.exec("COMMIT");
+            return { ok: true, job, cancelled: false, reason: "already_cancelled" };
+        }
+        if (job.status === "claimed" && !input.force) {
+            if (!input.workerId) {
+                throw new AppError("merge_job_claimed", "Claimed jobs require --worker-id or --force", 1, { protocol_id: protocol.id });
+            }
+            if (job.claimed_by_session_id !== input.workerId) {
+                throw new AppError("merge_job_claimed_by_other_session", "Merge job is claimed by another worker", 1, {
+                    protocol_id: protocol.id,
+                    claimed_by_session_id: job.claimed_by_session_id
+                });
+            }
+            requireLaneLockOwner(context, {
+                projectRoot: protocol.project_root,
+                lane: "merge",
+                workerId: input.workerId,
+                workspacePath: input.workspacePath
+            });
+        }
+        if (["merged", "failed"].includes(job.status) && !input.force) {
+            throw new AppError("merge_job_terminal", `Merge job is ${job.status}; cancellation requires --force --reason`, 1, {
+                protocol_id: protocol.id,
+                status: job.status
+            });
+        }
+        context.db.run(`UPDATE merge_queue
+       SET status = 'cancelled', last_reason = ?, updated_at = ?
+       WHERE id = ?`, [reason, now, job.id]);
+        appendAudit(context, {
+            protocolId: protocol.id,
+            projectId: protocol.project_id,
+            eventType: "merge_queue.cancelled",
+            reason,
+            forced: input.force,
+            payload: { protocol_id: protocol.id, from: job.status, worker_id: input.workerId ?? null }
+        });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return { ok: true, job: queueJobByProtocol(context, protocol.id), cancelled: true };
+}
+export function queueForProject(context, projectId) {
+    return context.db.all(`SELECT * FROM merge_queue WHERE project_id = ? ORDER BY created_at ASC, id ASC`, [projectId]);
+}
+function queueJobByProtocol(context, protocolId) {
+    return context.db.get("SELECT * FROM merge_queue WHERE protocol_id = ?", [protocolId]);
+}
+function requireClaimedJob(context, protocolId, sessionId) {
+    const job = queueJobByProtocol(context, protocolId);
+    if (!job || job.status !== "claimed") {
+        throw new AppError("merge_job_not_claimed", "Merge job is not claimed", 1, { protocol_id: protocolId });
+    }
+    if (job.claimed_by_session_id !== sessionId) {
+        throw new AppError("merge_job_claimed_by_other_session", "Merge job is claimed by another session", 1, {
+            protocol_id: protocolId,
+            claimed_by_session_id: job.claimed_by_session_id
+        });
+    }
+    return job;
+}
+function releaseLaneLockIfOwned(context, input) {
+    try {
+        releaseLaneLock(context, input);
+    }
+    catch (error) {
+        if (error instanceof AppError && ["lane_lock_not_active", "lane_lock_owned_by_other_worker"].includes(error.code)) {
+            return;
+        }
+        throw error;
+    }
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/services/plans.js

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import { schemaVersion } from "../domain/contracts.js";
+import { validatePlan } from "../domain/validation.js";
+import { AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+import { ensureReadableFile } from "../storage/database.js";
+import { appendAudit } from "./audit.js";
+import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { writePlanFile } from "../protocol/local-files.js";
+export function setProtocolPlan(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    ensureReadableFile(input.file);
+    const plan = validatePlan(parseJsonObject(fs.readFileSync(input.file, "utf8"), input.file), protocol.id);
+    writePlanFile(protocol.plan_path, plan);
+    context.db.run(`INSERT INTO plans (protocol_id, plan_json, updated_at)
+     VALUES (?, ?, ?)
+     ON CONFLICT(protocol_id) DO UPDATE SET plan_json = excluded.plan_json, updated_at = excluded.updated_at`, [protocol.id, JSON.stringify(plan), context.now()]);
+    updateStatePlanSummary(context, protocol, plan);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "plan.set",
+        payload: { protocol_id: protocol.id, plan_id: plan.plan_id, total: plan.items.length }
+    });
+    return { ok: true, protocol_id: protocol.id, plan: summarizePlan(plan) };
+}
+export function getPlanStatus(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const plan = requireStoredPlan(context, protocol.id);
+    return {
+        ok: true,
+        protocol_id: protocol.id,
+        plan: summarizePlan(plan),
+        blocked_items: plan.items
+            .filter((item) => item.status === "blocked")
+            .map((item) => ({
+            id: item.id,
+            title: item.title,
+            reason: item.block_reason ?? "",
+            user_required: item.user_required ?? false
+        })),
+        items: plan.items
+    };
+}
+export function startPlanItem(context, input) {
+    return updatePlanItem(context, input.protocolId, input.itemId, (item, plan) => {
+        assertDependenciesClosed(plan, item);
+        return {
+            ...item,
+            status: "in_progress",
+            summary: item.summary || "Started."
+        };
+    });
+}
+export function completePlanItem(context, input) {
+    return updatePlanItem(context, input.protocolId, input.itemId, (item, plan) => {
+        assertDependenciesClosed(plan, item);
+        return {
+            ...item,
+            status: "done",
+            summary: input.summary,
+            evidence: [...new Set([...item.evidence, ...input.evidence])]
+        };
+    });
+}
+export function blockPlanItem(context, input) {
+    return updatePlanItem(context, input.protocolId, input.itemId, (item) => ({
+        ...item,
+        status: "blocked",
+        summary: input.reason,
+        block_reason: input.reason,
+        user_required: input.userRequired
+    }));
+}
+export function skipPlanItem(context, input) {
+    return updatePlanItem(context, input.protocolId, input.itemId, (item) => ({
+        ...item,
+        status: "skipped",
+        summary: input.reason
+    }));
+}
+function updatePlanItem(context, protocolId, itemId, transform) {
+    const protocol = requireProtocol(context, protocolId);
+    const plan = requireStoredPlan(context, protocol.id);
+    const item = plan.items.find((candidate) => candidate.id === itemId);
+    if (!item) {
+        throw new AppError("not_found", `Plan item is not found: ${itemId}`, 1);
+    }
+    const nextPlan = {
+        ...plan,
+        items: plan.items.map((candidate) => (candidate.id === itemId ? transform(candidate, plan) : candidate))
+    };
+    const validated = validatePlan(nextPlan, protocol.id);
+    writePlanFile(protocol.plan_path, validated);
+    context.db.run("UPDATE plans SET plan_json = ?, updated_at = ? WHERE protocol_id = ?", [
+        JSON.stringify(validated),
+        context.now(),
+        protocol.id
+    ]);
+    updateStatePlanSummary(context, protocol, validated);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "plan.item.updated",
+        payload: {
+            protocol_id: protocol.id,
+            item_id: itemId,
+            from: item.status,
+            to: validated.items.find((candidate) => candidate.id === itemId)?.status
+        }
+    });
+    return { ok: true, protocol_id: protocol.id, item: validated.items.find((candidate) => candidate.id === itemId) };
+}
+function requireStoredPlan(context, protocolId) {
+    const row = context.db.get("SELECT plan_json FROM plans WHERE protocol_id = ?", [protocolId]);
+    if (!row) {
+        throw new AppError("not_found", `Plan is not attached to protocol: ${protocolId}`, 1);
+    }
+    return validatePlan(parseJsonObject(row.plan_json, `stored plan for ${protocolId}`), protocolId);
+}
+function assertDependenciesClosed(plan, item) {
+    const openDependencies = item.depends_on
+        .map((dependencyId) => plan.items.find((candidate) => candidate.id === dependencyId))
+        .filter((dependency) => Boolean(dependency))
+        .filter((dependency) => !["done", "skipped"].includes(dependency.status));
+    if (openDependencies.length > 0) {
+        throw new AppError("plan_dependency_open", `Plan item ${item.id} has open dependencies`, 1, {
+            item_id: item.id,
+            dependencies: openDependencies.map((dependency) => ({ id: dependency.id, status: dependency.status }))
+        });
+    }
+}
+function updateStatePlanSummary(context, protocol, plan) {
+    const state = readProtocolRuntimeState(context, protocol).state;
+    persistProtocolState(context, protocol, {
+        ...state,
+        schema_version: state.schema_version || schemaVersion,
+        plan: summarizePlan(plan),
+        updated_at: context.now()
+    });
+}
+function summarizePlan(plan) {
+    return {
+        plan_id: plan.plan_id,
+        total: plan.items.length,
+        done: plan.items.filter((item) => item.status === "done").length,
+        blocked: plan.items.filter((item) => item.status === "blocked").length
+    };
+}