@deksden-com/dd-flow-cli 0.1.0

package/dist/services/sessions.js

@@ -0,0 +1,365 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { continuationPolicies, flowKinds } from "../domain/contracts.js";
+import { AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { appendAudit } from "./audit.js";
+export function registerFlowSession(context, input) {
+    const payload = decodeFlowSessionPayload(input);
+    const project = requireProjectByRoot(context, resolveProjectRoot(payload.project_root));
+    const session = upsertFlowSession(context, project, payload, input.sessionId);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_session.registered",
+        payload: {
+            project_id: project.id,
+            session_id: session.session_id,
+            flow_kind: session.flow_kind,
+            run_id: session.run_id,
+            worker_id: session.worker_id,
+            continuation_policy: session.continuation_policy
+        },
+        ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
+    });
+    return { ok: true, session };
+}
+export function getFlowSessionStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return {
+        ok: true,
+        sessions: flowSessionsForProject(context, project.id, {
+            sessionId: input.sessionId,
+            workerId: input.workerId
+        })
+    };
+}
+export function stopFlowSession(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const session = requireFlowSession(context, project.id, input.sessionId);
+    markSessionStopped(context, project, session, input.reason);
+    return { ok: true, session: flowSessionById(context, project.id, input.sessionId) };
+}
+export function stopMergeWorker(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const sessions = flowSessionsForProject(context, project.id, { workerId: input.workerId }).filter((session) => session.flow_kind === "merge_worker" && ["active", "pending", "stopping"].includes(session.status));
+    let lock_release = { ok: true, released: false, reason: "no_active_session" };
+    for (const session of sessions) {
+        lock_release = markSessionStopped(context, project, session, input.reason) ?? lock_release;
+    }
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_session.merge_worker_stopped",
+        reason: input.reason,
+        payload: { project_id: project.id, worker_id: input.workerId, stopped_sessions: sessions.length, lock_release }
+    });
+    return { ok: true, stopped_sessions: sessions.length, lock_release };
+}
+export function stoppedMergeWorkerState(context, projectId, workerId) {
+    const latest = context.db.get(`SELECT status, stop_reason FROM flow_sessions
+     WHERE project_id = ? AND worker_id = ? AND flow_kind = 'merge_worker'
+     ORDER BY updated_at DESC, rowid DESC LIMIT 1`, [projectId, workerId]);
+    return {
+        stopped: latest?.status === "stopped",
+        reason: latest?.stop_reason ?? null
+    };
+}
+export function activeFlowSessionsForProject(context, projectId) {
+    return context.db.all(`SELECT * FROM flow_sessions
+     WHERE project_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')
+     ORDER BY updated_at DESC`, [projectId]);
+}
+export function flowSessionsForProject(context, projectId, filter = {}) {
+    if (filter.sessionId) {
+        return context.db.all("SELECT * FROM flow_sessions WHERE project_id = ? AND session_id = ? ORDER BY updated_at DESC", [projectId, filter.sessionId]);
+    }
+    if (filter.workerId) {
+        return context.db.all("SELECT * FROM flow_sessions WHERE project_id = ? AND worker_id = ? ORDER BY updated_at DESC", [projectId, filter.workerId]);
+    }
+    return context.db.all("SELECT * FROM flow_sessions WHERE project_id = ? ORDER BY updated_at DESC", [projectId]);
+}
+export function flowSessionById(context, projectId, sessionId) {
+    return context.db.get("SELECT * FROM flow_sessions WHERE project_id = ? AND session_id = ?", [
+        projectId,
+        sessionId
+    ]);
+}
+export function updateFlowSessionContinuation(context, projectId, sessionId, actionKey) {
+    const session = flowSessionById(context, projectId, sessionId);
+    if (!session) {
+        return 0;
+    }
+    const actionHash = hashString(actionKey);
+    const nextCount = session.last_action_hash === actionHash ? session.continuation_count + 1 : 1;
+    context.db.run(`UPDATE flow_sessions
+     SET continuation_count = ?, last_action_hash = ?, updated_at = ?
+     WHERE project_id = ? AND session_id = ?`, [nextCount, actionHash, context.now(), projectId, sessionId]);
+    return nextCount;
+}
+export function recordPendingFlowSessionBinding(context, project, input) {
+    const payload = flowSessionPayloadFromRegisterCommand(input.command);
+    if (!payload) {
+        return { recorded: false };
+    }
+    const payloadRoot = resolveProjectRoot(payload.project_root);
+    if (payloadRoot !== project.root) {
+        throw new AppError("project_mismatch", "Session register payload project_root does not match hook project", 1, {
+            expected: project.root,
+            actual: payloadRoot
+        });
+    }
+    const now = context.now();
+    context.db.run(`INSERT INTO pending_flow_session_bindings
+      (session_id, project_id, payload_json, cwd, transcript_path, turn_id, status, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, 'observed', ?, ?)
+     ON CONFLICT(session_id, project_id) DO UPDATE SET
+       payload_json = excluded.payload_json,
+       cwd = COALESCE(excluded.cwd, cwd),
+       transcript_path = COALESCE(excluded.transcript_path, transcript_path),
+       turn_id = excluded.turn_id,
+       status = 'observed',
+       updated_at = excluded.updated_at`, [
+        input.sessionId,
+        project.id,
+        JSON.stringify(sanitizeSessionPayload(payload)),
+        input.cwd ?? payload.cwd ?? null,
+        input.transcriptPath ?? payload.transcript_path ?? null,
+        input.turnId ?? null,
+        now,
+        now
+    ]);
+    return { recorded: true, payload };
+}
+export function confirmPendingFlowSessionBinding(context, project, input) {
+    const pending = context.db.get("SELECT * FROM pending_flow_session_bindings WHERE project_id = ? AND session_id = ? AND status = 'observed'", [project.id, input.sessionId]);
+    if (!pending) {
+        return undefined;
+    }
+    const payload = normalizeFlowSessionPayload(JSON.parse(pending.payload_json));
+    const session = upsertFlowSession(context, project, {
+        ...payload,
+        cwd: pending.cwd ?? payload.cwd ?? null,
+        transcript_path: pending.transcript_path ?? payload.transcript_path ?? null
+    }, input.sessionId);
+    context.db.run(`UPDATE pending_flow_session_bindings SET status = 'confirmed', updated_at = ?
+     WHERE project_id = ? AND session_id = ?`, [context.now(), project.id, input.sessionId]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_session.bound",
+        payload: { project_id: project.id, session_id: input.sessionId, flow_kind: session.flow_kind },
+        ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
+    });
+    return session;
+}
+export function flowSessionPayloadFromRegisterCommand(command) {
+    if (!/\bdd-flow\s+session\s+register\b/.test(command)) {
+        return undefined;
+    }
+    const payloadBase64 = optionFromCommand(command, "payload-base64");
+    const payloadJson = optionFromCommand(command, "payload-json");
+    const payloadFile = optionFromCommand(command, "payload-file");
+    if (!payloadBase64 && !payloadJson && !payloadFile) {
+        return undefined;
+    }
+    return decodeFlowSessionPayload({ payloadBase64, payloadJson, payloadFile });
+}
+function decodeFlowSessionPayload(input) {
+    if (input.payloadFile) {
+        return normalizeFlowSessionPayload(parseJsonObject(fs.readFileSync(input.payloadFile, "utf8"), "session payload"));
+    }
+    if (input.payloadBase64) {
+        if (/\$[A-Za-z_{(]/.test(input.payloadBase64)) {
+            throw new AppError("validation", "session register --payload-base64 must be a literal base64 value because Codex PreToolUse hooks run before shell variable expansion; use --payload-file from prompts", 2);
+        }
+        return normalizeFlowSessionPayload(parseJsonObject(Buffer.from(input.payloadBase64, "base64").toString("utf8"), "session payload"));
+    }
+    if (input.payloadJson) {
+        return normalizeFlowSessionPayload(parseJsonObject(input.payloadJson, "session payload"));
+    }
+    throw new AppError("validation", "session register requires --payload-file, --payload-base64, or --payload-json", 2);
+}
+function normalizeFlowSessionPayload(payload) {
+    const projectRoot = requiredStringField(payload, "project_root");
+    const flowKind = requiredStringField(payload, "flow_kind");
+    const continuationPolicy = requiredStringField(payload, "continuation_policy");
+    if (!flowKinds.includes(flowKind)) {
+        throw new AppError("validation", "flow_kind is not supported", 2, { flow_kind: flowKind, allowed: flowKinds });
+    }
+    if (!continuationPolicies.includes(continuationPolicy)) {
+        throw new AppError("validation", "continuation_policy is not supported", 2, {
+            continuation_policy: continuationPolicy,
+            allowed: continuationPolicies
+        });
+    }
+    const metadata = payload.metadata && typeof payload.metadata === "object" && !Array.isArray(payload.metadata) ? payload.metadata : {};
+    const sessionId = stringField(payload, "session_id", false);
+    return {
+        ...(sessionId ? { session_id: sessionId } : {}),
+        project_root: projectRoot,
+        flow_kind: flowKind,
+        run_id: stringField(payload, "run_id", false) ?? null,
+        protocol_id: stringField(payload, "protocol_id", false) ?? null,
+        worker_id: stringField(payload, "worker_id", false) ?? null,
+        workspace_path: stringField(payload, "workspace_path", false) ?? null,
+        continuation_policy: continuationPolicy,
+        current_stage: stringField(payload, "current_stage", false) ?? null,
+        next_action: redactString(stringField(payload, "next_action", false) ?? null),
+        transcript_path: stringField(payload, "transcript_path", false) ?? null,
+        cwd: stringField(payload, "cwd", false) ?? null,
+        metadata: sanitizeValue(metadata)
+    };
+}
+function upsertFlowSession(context, project, payload, forcedSessionId) {
+    const now = context.now();
+    const sessionId = forcedSessionId ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    const workspacePath = payload.workspace_path ?? payload.cwd ?? project.root;
+    context.db.run(`INSERT INTO flow_sessions
+      (session_id, project_id, project_root, flow_kind, status, run_id, protocol_id, worker_id, workspace_path,
+       continuation_policy, current_stage, next_action, last_action_hash, continuation_count, stop_reason,
+       transcript_path, cwd, metadata_json, created_at, updated_at, stopped_at)
+     VALUES (?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, NULL, 0, NULL, ?, ?, ?, ?, ?, NULL)
+     ON CONFLICT(session_id, project_id) DO UPDATE SET
+       project_root = excluded.project_root,
+       flow_kind = excluded.flow_kind,
+       status = 'active',
+       run_id = excluded.run_id,
+       protocol_id = excluded.protocol_id,
+       worker_id = excluded.worker_id,
+       workspace_path = excluded.workspace_path,
+       continuation_policy = excluded.continuation_policy,
+       current_stage = excluded.current_stage,
+       next_action = excluded.next_action,
+       transcript_path = COALESCE(excluded.transcript_path, transcript_path),
+       cwd = COALESCE(excluded.cwd, cwd),
+       metadata_json = excluded.metadata_json,
+       updated_at = excluded.updated_at,
+       stop_reason = NULL,
+       stopped_at = NULL`, [
+        sessionId,
+        project.id,
+        project.root,
+        payload.flow_kind,
+        payload.run_id ?? null,
+        payload.protocol_id,
+        payload.worker_id,
+        workspacePath,
+        payload.continuation_policy,
+        payload.current_stage ?? null,
+        redactString(payload.next_action ?? null),
+        payload.transcript_path ?? null,
+        payload.cwd ?? null,
+        JSON.stringify(payload.metadata ?? {}),
+        now,
+        now
+    ]);
+    return requireFlowSession(context, project.id, sessionId);
+}
+function requireFlowSession(context, projectId, sessionId) {
+    const session = flowSessionById(context, projectId, sessionId);
+    if (!session) {
+        throw new AppError("not_found", `Flow session is not registered: ${sessionId}`, 1);
+    }
+    return session;
+}
+function markSessionStopped(context, project, session, reason) {
+    const now = context.now();
+    context.db.run(`UPDATE flow_sessions
+     SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+     WHERE project_id = ? AND session_id = ?`, [reason, now, now, project.id, session.session_id]);
+    let lockRelease = undefined;
+    if ((session.flow_kind === "merge_worker" || session.flow_kind === "merge_job") && session.worker_id) {
+        lockRelease = releaseMergeLockIfOwned(context, project.root, session.worker_id, reason);
+    }
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_session.stopped",
+        reason,
+        payload: { project_id: project.id, session_id: session.session_id, flow_kind: session.flow_kind },
+        ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
+    });
+    return lockRelease;
+}
+function releaseMergeLockIfOwned(context, projectRoot, workerId, reason) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
+    const lock = context.db.get(`SELECT id, worker_id FROM lane_locks
+     WHERE project_id = ? AND lane = 'merge' AND status = 'active'
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [project.id]);
+    if (!lock) {
+        return { ok: true, released: false, reason: "lane_lock_not_active" };
+    }
+    if (lock.worker_id !== workerId) {
+        return { ok: true, released: false, reason: "lane_lock_owned_by_other_worker", worker_id: lock.worker_id };
+    }
+    const now = context.now();
+    context.db.run(`UPDATE lane_locks SET status = 'released', released_at = ?, reason = ?, updated_at = ? WHERE id = ?`, [now, reason, now, lock.id]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "lane_lock.released",
+        reason,
+        payload: { project_id: project.id, lane: "merge", worker_id: workerId, lock_id: lock.id }
+    });
+    return { ok: true, released: true, lock_id: lock.id };
+}
+function optionFromCommand(command, key) {
+    const pattern = new RegExp(`--${key}(?:\\s+|=)(?:"([^"]*)"|'([^']*)'|([^\\s]+))`);
+    const match = command.match(pattern);
+    return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+function sanitizeSessionPayload(payload) {
+    return {
+        ...payload,
+        next_action: redactString(payload.next_action ?? null),
+        metadata: sanitizeValue(payload.metadata ?? {})
+    };
+}
+function sanitizeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sanitizeValue);
+    }
+    if (value && typeof value === "object") {
+        const next = {};
+        for (const [key, child] of Object.entries(value)) {
+            next[key] = secretKey(key) ? "<redacted>" : sanitizeValue(child);
+        }
+        return next;
+    }
+    return typeof value === "string" ? redactString(value) : value;
+}
+function secretKey(key) {
+    return /(token|secret|password|api[_-]?key|authorization|auth)/i.test(key);
+}
+function redactString(value) {
+    if (value === null) {
+        return null;
+    }
+    return value
+        .replace(/(token|secret|password|api[_-]?key)=\S+/gi, "$1=<redacted>")
+        .replace(/Bearer\s+[A-Za-z0-9._-]+/g, "Bearer <redacted>");
+}
+function stringField(payload, key, required) {
+    const value = payload[key];
+    if (typeof value === "string" && value.length > 0) {
+        return value;
+    }
+    if (required) {
+        throw new AppError("validation", `session payload requires ${key}`, 2);
+    }
+    return undefined;
+}
+function requiredStringField(payload, key) {
+    const value = stringField(payload, key, true);
+    if (!value) {
+        throw new AppError("validation", `session payload requires ${key}`, 2);
+    }
+    return value;
+}
+function hashString(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+function requireProjectByRoot(context, root) {
+    const project = context.db.get("SELECT id, root FROM projects WHERE root = ?", [root]);
+    if (!project) {
+        throw new AppError("not_found", `Project is not registered: ${root}`, 1);
+    }
+    return project;
+}

package/dist/services/worktrees.js

@@ -0,0 +1,204 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { flowContractForState } from "../domain/flow-contract.js";
+import { requireStage } from "../domain/validation.js";
+import { AppError } from "../shared/errors.js";
+import { projectCheckoutRoot } from "../storage/paths.js";
+import { appendAudit } from "./audit.js";
+import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+const worktrunkBinEnv = "DD_FLOW_WORKTRUNK_BIN";
+export function planWorktree(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const suggestedPath = path.join(projectCheckoutRoot(context.ddFlowHome, protocol.project_id), "worktrees", protocol.id, path.basename(protocol.project_root));
+    return {
+        ok: true,
+        protocol_id: protocol.id,
+        project_id: protocol.project_id,
+        route_git: state.route.git,
+        suggested: {
+            integration_branch: state.workspace.integration_branch ?? "main",
+            worktree_path: suggestedPath,
+            bootstrap_status: "pending",
+            owner: "dd-flow",
+            purpose: "feature"
+        },
+        worktrunk: detectWorktrunk(context)
+    };
+}
+export function createWorktreeRecord(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const existing = activeWorktreeRecord(context, protocol.id);
+    if (existing) {
+        throw new AppError("worktree_already_exists", "Protocol already has an active worktree record", 1, {
+            protocol_id: protocol.id,
+            worktree_path: existing.worktree_path
+        });
+    }
+    const worktrunk = requireWorktrunk(context);
+    const worktreePath = path.resolve(input.path);
+    if (isTrackedProjectPath(protocol.project_root, worktreePath)) {
+        throw new AppError("worktree_active", "Worktree path is inside tracked project files", 1, { path: worktreePath });
+    }
+    const command = [worktrunk.bin, "worktree", "create", "--branch", input.branch, "--base", input.base, "--path", worktreePath];
+    const result = runExternal(command);
+    if (result.exit_code !== 0) {
+        throw new AppError("tool_unavailable", "Worktrunk command failed", 1, { command: sanitizeCommand(command), result });
+    }
+    const now = context.now();
+    const state = readProtocolRuntimeState(context, protocol).state;
+    context.db.run(`INSERT INTO worktree_records
+      (protocol_id, project_id, integration_branch, feature_branch, base_ref, worktree_path,
+       worktrunk_metadata_json, bootstrap_status, status, last_command_result_json, created_at, updated_at, closed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 'active', ?, ?, ?, NULL)`, [
+        protocol.id,
+        protocol.project_id,
+        typeof state.workspace.integration_branch === "string" ? state.workspace.integration_branch : null,
+        input.branch,
+        input.base,
+        worktreePath,
+        JSON.stringify({ bin: worktrunk.bin }),
+        JSON.stringify(result),
+        now,
+        now
+    ]);
+    persistProtocolState(context, protocol, {
+        ...state,
+        workspace: {
+            ...state.workspace,
+            feature_branch: input.branch,
+            worktree_path: worktreePath,
+            base_commit: input.base,
+            worktrunk: { bin: worktrunk.bin },
+            bootstrap: { status: "pending" }
+        },
+        updated_at: now
+    });
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "worktree.created",
+        payload: { protocol_id: protocol.id, feature_branch: input.branch, base: input.base, path: worktreePath }
+    });
+    return { ok: true, worktree: activeWorktreeRecord(context, protocol.id) };
+}
+export function getWorktreeStatus(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    return { ok: true, protocol_id: protocol.id, worktree: worktreeRecord(context, protocol.id), worktrunk: detectWorktrunk(context) };
+}
+export function bootstrapWorktree(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const record = activeWorktreeRecord(context, protocol.id);
+    if (!record) {
+        throw new AppError("not_found", `Worktree record is not active for protocol: ${protocol.id}`, 1);
+    }
+    const now = context.now();
+    const result = {
+        exit_code: 0,
+        stdout: "No project bootstrap command configured.",
+        stderr: ""
+    };
+    context.db.run(`UPDATE worktree_records
+     SET bootstrap_status = 'succeeded', last_command_result_json = ?, updated_at = ?
+     WHERE protocol_id = ?`, [JSON.stringify(result), now, protocol.id]);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    persistProtocolState(context, protocol, {
+        ...state,
+        workspace: {
+            ...state.workspace,
+            bootstrap: { status: "succeeded", commands: [], blockers: [] }
+        },
+        updated_at: now
+    });
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "worktree.bootstrap_succeeded",
+        payload: { protocol_id: protocol.id, worktree_path: record.worktree_path }
+    });
+    return { ok: true, worktree: worktreeRecord(context, protocol.id) };
+}
+export function closeWorktree(context, input) {
+    if (!["keep", "remove"].includes(input.mode)) {
+        throw new AppError("validation", "--mode must be keep or remove", 2);
+    }
+    const protocol = requireProtocol(context, input.protocolId);
+    const record = activeWorktreeRecord(context, protocol.id);
+    if (!record) {
+        throw new AppError("not_found", `Worktree record is not active for protocol: ${protocol.id}`, 1);
+    }
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const stage = requireStage(state.stage, flowContractForState(state));
+    if (input.mode === "remove" && !["integration", "closed"].includes(stage)) {
+        throw new AppError("worktree_active", "Refusing to remove worktree before protocol is merged or closed", 1, {
+            stage: state.stage
+        });
+    }
+    const now = context.now();
+    const nextStatus = input.mode === "keep" ? "kept" : fs.existsSync(record.worktree_path) ? "kept" : "removed";
+    context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ? WHERE protocol_id = ?`, [nextStatus, now, now, protocol.id]);
+    appendAudit(context, {
+        protocolId: protocol.id,
+        projectId: protocol.project_id,
+        eventType: "worktree.closed",
+        payload: { protocol_id: protocol.id, mode: input.mode, status: nextStatus }
+    });
+    return {
+        ok: true,
+        worktree: worktreeRecord(context, protocol.id),
+        outcome: {
+            status: nextStatus,
+            reason: nextStatus === "removed" ? "path_absent" : input.mode === "remove" ? "physical_checkout_kept" : "keep_requested"
+        }
+    };
+}
+export function worktreeRecordsForProject(context, projectId) {
+    return context.db.all(`SELECT * FROM worktree_records WHERE project_id = ? ORDER BY updated_at DESC`, [projectId]);
+}
+export function worktreeRecord(context, protocolId) {
+    return context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocolId]);
+}
+function activeWorktreeRecord(context, protocolId) {
+    return context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ? AND status = 'active'", [protocolId]);
+}
+function detectWorktrunk(context) {
+    const configured = context.env[worktrunkBinEnv];
+    if (configured && fs.existsSync(configured)) {
+        return { available: true, bin: configured };
+    }
+    const probe = spawnSync("worktrunk", ["--version"], { encoding: "utf8" });
+    return probe.error ? { available: false, bin: null } : { available: true, bin: "worktrunk" };
+}
+function requireWorktrunk(context) {
+    const detected = detectWorktrunk(context);
+    if (!detected.available || !detected.bin) {
+        throw new AppError("tool_unavailable", "Worktrunk executable is unavailable", 1, {
+            tool: "worktrunk",
+            next_action: `Set ${worktrunkBinEnv} to a Worktrunk-compatible executable for local proof.`
+        });
+    }
+    return { bin: detected.bin };
+}
+function runExternal(command) {
+    const [bin, ...args] = command;
+    if (!bin) {
+        return { exit_code: null, stdout: "", stderr: "Missing executable." };
+    }
+    const result = spawnSync(bin, args, { encoding: "utf8" });
+    return {
+        exit_code: typeof result.status === "number" ? result.status : null,
+        stdout: sanitizeOutput(result.stdout),
+        stderr: sanitizeOutput(result.stderr || result.error?.message || "")
+    };
+}
+function sanitizeCommand(command) {
+    return command.map((part) => (part.includes("=") ? part.replace(/=.*/, "=<redacted>") : part));
+}
+function sanitizeOutput(value) {
+    return value.replace(/(token|secret|password)=\S+/gi, "$1=<redacted>");
+}
+function isTrackedProjectPath(projectRoot, candidate) {
+    const relative = path.relative(projectRoot, candidate);
+    return Boolean(relative && !relative.startsWith("..") && !path.isAbsolute(relative) && !relative.startsWith(".tasks"));
+}

package/dist/shared/errors.js

@@ -0,0 +1,14 @@
+export class AppError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = 1, details = {}) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function isAppError(error) {
+    return error instanceof AppError;
+}

package/dist/shared/json.js

@@ -0,0 +1,17 @@
+import { AppError } from "./errors.js";
+export function writeJson(stream, value) {
+    stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function parseJsonObject(text, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new AppError("validation", `Invalid JSON in ${label}: ${String(error)}`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AppError("validation", `${label} must be a JSON object`, 2);
+    }
+    return parsed;
+}