@deksden-com/dd-flow-cli 0.1.0

package/dist/schemas/memorybank-permissions-preflight.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/memorybank-permissions-preflight@1",
+  "title": "Memory Bank permissions preflight",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_id",
+    "ok",
+    "exit_code",
+    "flow",
+    "mode",
+    "platform",
+    "targets",
+    "checks",
+    "summary",
+    "remediation"
+  ],
+  "properties": {
+    "schema_id": {
+      "const": "dd-flow/memorybank-permissions-preflight@1"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 1]
+    },
+    "flow": {
+      "type": "string",
+      "enum": ["mb-init", "mb-upgrade", "mb-audit", "mb-fix", "mb-upgrade-review", "custom"]
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["read", "write", "repair", "report_only"]
+    },
+    "platform": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["os", "family", "cwd", "user", "group"],
+      "properties": {
+        "os": { "type": "string" },
+        "family": { "type": "string", "enum": ["posix", "windows"] },
+        "cwd": { "type": "string" },
+        "user": { "type": "string" },
+        "group": { "type": "string" }
+      }
+    },
+    "targets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["project_root", "memory_bank", "tasks"],
+      "properties": {
+        "project_root": { "type": "string" },
+        "memory_bank": { "type": "string" },
+        "tasks": { "type": "string" }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/check" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["errors", "warnings", "can_continue"],
+      "properties": {
+        "errors": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 },
+        "can_continue": { "type": "boolean" }
+      }
+    },
+    "remediation": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/remediation" }
+    }
+  },
+  "$defs": {
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "severity", "path", "operation", "status", "reason", "side_effect"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "severity": { "type": "string", "enum": ["info", "warning", "error"] },
+        "path": { "type": "string" },
+        "operation": {
+          "type": "string",
+          "enum": [
+            "read_existing_file",
+            "write_existing_file",
+            "create_file",
+            "create_directory",
+            "delete_probe",
+            "stat_metadata",
+            "detect_acl",
+            "detect_flags"
+          ]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["passed", "failed", "warning", "skipped", "unknown"]
+        },
+        "reason": {
+          "type": "string",
+          "enum": [
+            "ok",
+            "not_found",
+            "not_writable",
+            "not_readable",
+            "owner_mismatch",
+            "acl_denied",
+            "read_only_attribute",
+            "immutable_flag",
+            "unsupported_platform",
+            "probe_failed",
+            "unknown"
+          ]
+        },
+        "fs_error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["message"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" }
+          }
+        },
+        "owner": { "type": "string" },
+        "group": { "type": "string" },
+        "mode": { "type": "string" },
+        "side_effect": {
+          "type": "string",
+          "enum": ["none", "temporary_probe_created_and_removed", "temporary_probe_cleanup_failed"]
+        }
+      }
+    },
+    "remediation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["platform", "title", "commands", "requires_user_confirmation"],
+      "properties": {
+        "platform": { "type": "string" },
+        "title": { "type": "string" },
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "requires_user_confirmation": { "type": "boolean" }
+      }
+    }
+  }
+}

package/dist/schemas/merge-stage-report.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/merge-stage-report@1",
+  "title": "Merge stage report data",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_id",
+    "run",
+    "stage",
+    "project",
+    "subject",
+    "overall",
+    "breadcrumbs",
+    "merge_job",
+    "git",
+    "checks",
+    "cleanup",
+    "defs"
+  ],
+  "properties": {
+    "schema_id": { "const": "dd-flow/merge-stage-report@1" },
+    "run": { "$ref": "#/definitions/run" },
+    "stage": { "$ref": "#/definitions/stage" },
+    "project": { "$ref": "#/definitions/namedEntity" },
+    "subject": { "$ref": "#/definitions/namedEntity" },
+    "overall": { "$ref": "#/definitions/overall" },
+    "breadcrumbs": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/breadcrumb" }
+    },
+    "merge_job": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["status", "claimed_by", "queue_result"],
+      "properties": {
+        "status": { "type": "string", "minLength": 1 },
+        "claimed_by": { "type": "string" },
+        "queue_result": { "type": "string", "minLength": 1 }
+      }
+    },
+    "git": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["source_branch", "target_branch", "result_commit"],
+      "properties": {
+        "source_branch": { "type": "string", "minLength": 1 },
+        "target_branch": { "type": "string", "minLength": 1 },
+        "result_commit": { "type": "string" }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/check" }
+    },
+    "cleanup": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/check" }
+    },
+    "defs": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/deferral" }
+    }
+  },
+  "definitions": {
+    "run": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["run_id", "run_index"],
+      "properties": {
+        "run_id": { "type": "string", "pattern": "^RUN-[0-9]{3}-[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "run_index": { "type": "string", "minLength": 1 }
+      }
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name", "dir", "status"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "dir": { "type": "string", "pattern": "^[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "status": { "type": "string", "minLength": 1 }
+      }
+    },
+    "namedEntity": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 }
+      }
+    },
+    "overall": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["verdict", "summary", "next_action"],
+      "properties": {
+        "verdict": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "next_action": { "type": "string", "minLength": 1 }
+      }
+    },
+    "breadcrumb": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "href", "status"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "href": { "type": "string" },
+        "status": { "type": "string", "minLength": 1 }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name", "status"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string" }
+      }
+    },
+    "deferral": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "status", "summary"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/dist/services/audit.js

@@ -0,0 +1,19 @@
+export function appendAudit(context, input) {
+    context.db.run(`INSERT INTO audit_events
+      (protocol_id, project_id, event_type, forced, reason, payload_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+        input.protocolId ?? null,
+        input.projectId ?? null,
+        input.eventType,
+        input.forced ? 1 : 0,
+        input.reason ?? null,
+        JSON.stringify(input.payload),
+        context.now()
+    ]);
+}
+export function getAuditEvents(context, protocolId) {
+    return context.db.all(`SELECT id, protocol_id, project_id, event_type, forced, reason, payload_json, created_at
+     FROM audit_events
+     WHERE protocol_id = ?
+     ORDER BY id ASC`, [protocolId]);
+}

package/dist/services/cleanup.js

@@ -0,0 +1,310 @@
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+import { ensureReadableFile } from "../storage/database.js";
+import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { appendAudit } from "./audit.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+const actionKinds = new Set([
+    "repair_protocol_state",
+    "cancel_queue_job",
+    "close_flow_session",
+    "expire_lane_lock",
+    "close_worktree_record"
+]);
+export function cleanupScan(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const actions = [];
+    const findings = [];
+    const protocols = context.db.all("SELECT id, status, stage, state_path FROM protocols WHERE project_id = ? ORDER BY id ASC", [project.id]);
+    for (const protocol of protocols) {
+        const terminal = ["closed", "cancelled"].includes(protocol.status) || ["closed", "cancelled"].includes(protocol.stage);
+        if (!fs.existsSync(protocol.state_path)) {
+            pushFinding(findings, actions, "missing_protocol_runtime_state", "warning", {
+                protocol_id: protocol.id,
+                path: protocol.state_path,
+                action: { kind: "repair_protocol_state", project_id: project.id, protocol_id: protocol.id }
+            });
+        }
+        if (terminal) {
+            const queue = context.db.get("SELECT status FROM merge_queue WHERE protocol_id = ? AND status IN ('ready', 'requeued', 'claimed')", [protocol.id]);
+            if (queue) {
+                pushFinding(findings, actions, "active_queue_for_terminal_protocol", "warning", {
+                    protocol_id: protocol.id,
+                    queue_status: queue.status,
+                    action: { kind: "cancel_queue_job", project_id: project.id, protocol_id: protocol.id }
+                });
+            }
+        }
+    }
+    const orphanQueueJobs = context.db.all(`SELECT mq.protocol_id, mq.status FROM merge_queue mq
+     LEFT JOIN protocols p ON p.id = mq.protocol_id
+     WHERE mq.project_id = ?
+       AND mq.status IN ('ready', 'requeued')
+       AND p.id IS NULL
+     ORDER BY mq.created_at ASC, mq.id ASC`, [project.id]);
+    for (const job of orphanQueueJobs) {
+        pushFinding(findings, actions, "orphan_ready_merge_job", "warning", {
+            protocol_id: job.protocol_id,
+            queue_status: job.status,
+            action: { kind: "cancel_queue_job", project_id: project.id, protocol_id: job.protocol_id }
+        });
+    }
+    const staleSessions = context.db.all(`SELECT session_id, protocol_id, workspace_path FROM flow_sessions
+     WHERE project_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')
+     ORDER BY updated_at ASC, session_id ASC`, [project.id]);
+    for (const session of staleSessions) {
+        const protocol = session.protocol_id
+            ? context.db.get("SELECT status, stage FROM protocols WHERE id = ?", [session.protocol_id])
+            : undefined;
+        const missingWorkspace = !fs.existsSync(session.workspace_path);
+        const terminalProtocol = Boolean(protocol && (["closed", "cancelled"].includes(protocol.status) || ["closed", "cancelled"].includes(protocol.stage)));
+        if (missingWorkspace || terminalProtocol) {
+            pushFinding(findings, actions, "stale_flow_session", "warning", {
+                session_id: session.session_id,
+                protocol_id: session.protocol_id,
+                missing_workspace: missingWorkspace,
+                terminal_protocol: terminalProtocol,
+                action: { kind: "close_flow_session", project_id: project.id, session_id: session.session_id }
+            });
+        }
+    }
+    const now = context.now();
+    const expiredLocks = context.db.all(`SELECT id, lane, worker_id, expires_at FROM lane_locks
+     WHERE project_id = ? AND status = 'active' AND expires_at <= ?
+     ORDER BY id ASC`, [project.id, now]);
+    for (const lock of expiredLocks) {
+        pushFinding(findings, actions, "expired_active_lane_lock", "warning", {
+            lock_id: lock.id,
+            lane: lock.lane,
+            worker_id: lock.worker_id,
+            expires_at: lock.expires_at,
+            action: { kind: "expire_lane_lock", project_id: project.id, lock_id: lock.id }
+        });
+    }
+    const staleWorktrees = context.db.all(`SELECT wr.protocol_id, wr.worktree_path FROM worktree_records wr
+     JOIN protocols p ON p.id = wr.protocol_id
+     WHERE wr.project_id = ?
+       AND wr.status = 'active'
+       AND (p.status IN ('closed', 'cancelled') OR p.stage IN ('closed', 'cancelled') OR wr.worktree_path = '')
+     ORDER BY wr.protocol_id ASC`, [project.id]);
+    for (const worktree of staleWorktrees) {
+        pushFinding(findings, actions, "stale_worktree_record", "info", {
+            protocol_id: worktree.protocol_id,
+            worktree_path: worktree.worktree_path,
+            action: {
+                kind: "close_worktree_record",
+                project_id: project.id,
+                protocol_id: worktree.protocol_id,
+                worktree_path: worktree.worktree_path
+            }
+        });
+    }
+    return {
+        ok: true,
+        project_root: project.root,
+        project_id: project.id,
+        findings,
+        actions,
+        plan: { project_root: project.root, project_id: project.id, actions }
+    };
+}
+export function cleanupApply(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const reason = input.reason.trim();
+    if (!reason) {
+        throw new AppError("validation", "cleanup apply requires --reason", 2);
+    }
+    ensureReadableFile(input.planFile);
+    const plan = validateCleanupPlan(parseJsonObject(fs.readFileSync(input.planFile, "utf8"), input.planFile), project);
+    validateNoDestructiveSurprises(context, plan, input.force);
+    const now = context.now();
+    const results = [];
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        for (const action of plan.actions) {
+            results.push(applyAction(context, action, reason, input.force, now));
+        }
+        const changed = results.filter((result) => result.changed).length;
+        if (changed > 0) {
+            appendAudit(context, {
+                projectId: project.id,
+                eventType: "cleanup.applied",
+                reason,
+                forced: input.force,
+                payload: { project_id: project.id, action_count: plan.actions.length, changed, results }
+            });
+        }
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return {
+        ok: true,
+        project_root: project.root,
+        requested: plan.actions.length,
+        applied: results.filter((result) => result.changed).length,
+        changed: results.filter((result) => result.changed).length,
+        skipped: results.filter((result) => !result.changed).length,
+        results
+    };
+}
+function pushFinding(findings, actions, code, severity, details) {
+    findings.push({ code, severity, ...details });
+    actions.push(details.action);
+}
+function validateCleanupPlan(value, project) {
+    if (value.project_root !== project.root || value.project_id !== project.id) {
+        throw new AppError("project_mismatch", "cleanup plan does not match --project-root", 1, {
+            expected_root: project.root,
+            actual_root: value.project_root,
+            expected_project_id: project.id,
+            actual_project_id: value.project_id
+        });
+    }
+    if (!Array.isArray(value.actions)) {
+        throw new AppError("validation", "cleanup plan requires actions array", 2);
+    }
+    const actions = value.actions.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new AppError("validation", "cleanup action must be an object", 2);
+        }
+        const action = entry;
+        if (!actionKinds.has(action.kind)) {
+            throw new AppError("validation", "cleanup action kind is not supported", 2, { kind: action.kind });
+        }
+        if (action.project_id !== project.id) {
+            throw new AppError("project_mismatch", "cleanup action project_id does not match project", 1, {
+                expected_project_id: project.id,
+                actual_project_id: action.project_id
+            });
+        }
+        return action;
+    });
+    return { project_root: project.root, project_id: project.id, actions };
+}
+function validateNoDestructiveSurprises(context, plan, force) {
+    const destructive = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && dirtyGit(action.worktree_path));
+    if (destructive && !force) {
+        throw new AppError("worktree_dirty", "cleanup apply refuses dirty worktree actions without --force --reason", 1, {
+            path: destructive.worktree_path
+        });
+    }
+    const unsafeWorktree = plan.actions.find((action) => action.kind === "close_worktree_record" && action.worktree_path && !safeCleanupWorktreePath(context, action.project_id, action.worktree_path));
+    if (unsafeWorktree) {
+        throw new AppError("worktree_cleanup_unsafe", "cleanup apply refuses unsafe worktree path", 1, {
+            path: unsafeWorktree.worktree_path
+        });
+    }
+    const guardedQueue = plan.actions.find((action) => {
+        if (action.kind !== "cancel_queue_job" || !action.protocol_id) {
+            return false;
+        }
+        const job = context.db.get("SELECT status FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id]);
+        return Boolean(job && ["claimed", "merged", "failed"].includes(job.status));
+    });
+    if (guardedQueue && !force) {
+        throw new AppError("cleanup_force_required", "cleanup apply refuses claimed or terminal queue cancellation without --force --reason", 1, {
+            protocol_id: guardedQueue.protocol_id
+        });
+    }
+}
+function applyAction(context, action, reason, force, now) {
+    if (action.kind === "repair_protocol_state" && action.protocol_id) {
+        const protocol = requireProtocol(context, action.protocol_id);
+        const beforePath = protocol.state_path;
+        const existed = fs.existsSync(beforePath);
+        readProtocolRuntimeState(context, protocol);
+        return {
+            kind: action.kind,
+            changed: !existed || beforePath !== protocol.state_path,
+            ...(!existed || beforePath !== protocol.state_path ? {} : { skipped: true, reason: "state_exists" }),
+            protocol_id: action.protocol_id
+        };
+    }
+    if (action.kind === "cancel_queue_job" && action.protocol_id) {
+        const job = context.db.get("SELECT status FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id]);
+        if (!job) {
+            return { kind: action.kind, changed: false, skipped: true, reason: "no_queue_job", protocol_id: action.protocol_id };
+        }
+        const statuses = force ? "('ready', 'requeued', 'claimed', 'merged', 'failed')" : "('ready', 'requeued', 'claimed')";
+        const result = context.db.run(`UPDATE merge_queue SET status = 'cancelled', last_reason = ?, updated_at = ?
+       WHERE protocol_id = ? AND project_id = ? AND status IN ${statuses}`, [reason, now, action.protocol_id, action.project_id]);
+        if (result.changes !== 1) {
+            return { kind: action.kind, changed: false, skipped: true, reason: `already_${job.status}`, protocol_id: action.protocol_id };
+        }
+        appendAudit(context, {
+            projectId: action.project_id,
+            protocolId: action.protocol_id,
+            eventType: "merge_queue.cancelled",
+            reason,
+            forced: force,
+            payload: { protocol_id: action.protocol_id, from: job.status, source: "cleanup.apply" }
+        });
+        return { kind: action.kind, changed: true, protocol_id: action.protocol_id };
+    }
+    if (action.kind === "close_flow_session" && action.session_id) {
+        const result = context.db.run(`UPDATE flow_sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+       WHERE project_id = ? AND session_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, action.project_id, action.session_id]);
+        if (result.changes !== 1) {
+            return { kind: action.kind, changed: false, skipped: true, reason: "already_stopped", session_id: action.session_id };
+        }
+        appendAudit(context, {
+            projectId: action.project_id,
+            eventType: "flow_session.stopped",
+            reason,
+            forced: force,
+            payload: { session_id: action.session_id, source: "cleanup.apply" }
+        });
+        return { kind: action.kind, changed: true, session_id: action.session_id };
+    }
+    if (action.kind === "expire_lane_lock" && typeof action.lock_id === "number") {
+        const result = context.db.run("UPDATE lane_locks SET status = 'expired', reason = ?, updated_at = ? WHERE project_id = ? AND id = ? AND status = 'active'", [reason, now, action.project_id, action.lock_id]);
+        return {
+            kind: action.kind,
+            changed: result.changes === 1,
+            ...(result.changes === 1 ? {} : { skipped: true, reason: "already_inactive" }),
+            lock_id: action.lock_id
+        };
+    }
+    if (action.kind === "close_worktree_record" && action.protocol_id) {
+        const worktreePath = action.worktree_path ?? context.db.get("SELECT worktree_path FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id])?.worktree_path;
+        const status = worktreePath && fs.existsSync(worktreePath) ? "kept" : "removed";
+        const result = context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ?
+       WHERE project_id = ? AND protocol_id = ? AND status = 'active'`, [status, now, now, action.project_id, action.protocol_id]);
+        return {
+            kind: action.kind,
+            changed: result.changes === 1,
+            ...(result.changes === 1 ? { reason: status } : { skipped: true, reason: "already_closed" }),
+            protocol_id: action.protocol_id
+        };
+    }
+    return { kind: action.kind, changed: false, skipped: true, reason: "invalid_action" };
+}
+function dirtyGit(worktreePath) {
+    if (!fs.existsSync(worktreePath)) {
+        return false;
+    }
+    const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { encoding: "utf8" });
+    return result.status === 0 && result.stdout.trim().length > 0;
+}
+function safeCleanupWorktreePath(context, projectId, worktreePath) {
+    if (!fs.existsSync(worktreePath)) {
+        return true;
+    }
+    const real = fs.realpathSync(worktreePath);
+    if (real === process.cwd()) {
+        return false;
+    }
+    const checkoutRoot = projectCheckoutRoot(context.ddFlowHome, projectId);
+    if (!fs.existsSync(checkoutRoot)) {
+        return true;
+    }
+    const root = fs.realpathSync(checkoutRoot);
+    return real === root || real.startsWith(`${root}${path.sep}`);
+}