@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.91

package/dist/services/workspace-bootstrap.js

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { codeExecutionEnvironment, reconcileWorkspaceOwnership, runCheck, workspaceOperationId } from "./code-checks.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedOwnerIsAlive, managedProcessStatus, processTreeIsAlive, registerManagedProcess } from "./managed-processes.js";
+/** CODE and MERGE prepare their own checkout through the same managed executor.
+ * Bootstrap is a project operation, not an alias classified by the engine as a test. */
+export async function runWorkspaceBootstrap(context, input) {
+    reconcileWorkspaceOwnership(context, input.workspaceRoot);
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
+    const operationId = workspaceOperationId(input.workspaceRoot);
+    const identity = crypto.createHash("sha256").update(JSON.stringify([input.projectId, input.runId, generation, path.resolve(input.workspaceRoot), input.command])).digest("hex");
+    const pending = managedProcessStatus(context).find(item => item.operation_id === operationId && ["starting", "running", "stopping"].includes(item.state));
+    if (pending) {
+        if (pending.kind !== "workspace-bootstrap")
+            throw new AppError("bootstrap_in_progress", "A check currently owns this workspace; wait for it before bootstrapping", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
+        if (processTreeIsAlive(pending) || (pending.state === "starting" && managedOwnerIsAlive(pending) !== false)) {
+            throw new AppError("bootstrap_in_progress", "Workspace preparation is still running; inspect its logs and wait for the existing process, do not launch another copy", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
+        }
+        let pendingIdentity = null;
+        try {
+            const metadata = JSON.parse(pending.metadata_json);
+            pendingIdentity = typeof metadata.bootstrap_identity === "string" ? metadata.bootstrap_identity : null;
+        }
+        catch { /* Legacy records have no usable identity. */ }
+        if (pendingIdentity !== identity) {
+            finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: "failed", reason: "bootstrap_identity_superseded" });
+        }
+        else {
+            const completionPath = path.join(path.dirname(pending.stdout_path), "completion.json");
+            let completion = null;
+            try {
+                completion = JSON.parse(fs.readFileSync(completionPath, "utf8"));
+            }
+            catch { /* Interrupted shell has no terminal marker. */ }
+            const exitCode = typeof completion?.exit_code === "number" ? completion.exit_code : null;
+            const error = exitCode === null ? "bootstrap ended without a completion marker; inspect retained logs before retrying" : null;
+            finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: exitCode === 0 ? "stopped" : "failed", reason: error ?? "bootstrap_completion_reconciled" });
+            assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+            return result(pending.id, pending.stdout_path, pending.stderr_path, completionPath, exitCode, error);
+        }
+    }
+    const directory = path.join(input.runHome, input.artifactDir, `bootstrap-${crypto.randomUUID()}`);
+    fs.mkdirSync(directory, { recursive: true });
+    const stdoutPath = path.join(directory, "stdout.log"), stderrPath = path.join(directory, "stderr.log"), completionPath = path.join(directory, "completion.json");
+    const managed = registerManagedProcess(context, { kind: "workspace-bootstrap", ownerId: `${operationId}:${identity}`, ownerPid: process.pid, operationId, uniqueActiveOperation: true, projectId: input.projectId, runId: input.runId, stdoutPath, stderrPath, metadata: { command: input.command, workspace_root: input.workspaceRoot, bootstrap_identity: identity } });
+    const stdout = fs.openSync(stdoutPath, "a"), stderr = fs.openSync(stderrPath, "a");
+    try {
+        try {
+            input.progress?.(`workspace bootstrap preparing: ${input.command}; logs: ${directory}`);
+            assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+        }
+        catch (error) {
+            finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: "failed", reason: "dispatch_fenced_before_spawn" });
+            throw error;
+        }
+        const completed = await runCheck(input.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_CHECK_COMPLETION_FILE: completionPath }, stdout, stderr, elapsed => input.progress?.(`workspace bootstrap still running (${elapsed}s); logs: ${directory}; next report in 15s`), pid => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
+        const current = managedProcessStatus(context).find(item => item.id === managed.id);
+        if (processTreeIsAlive(current))
+            throw new AppError("bootstrap_tree_not_settled", "Bootstrap shell exited but still owns live processes; resources were retained for inspection", 2, { process_id: managed.id, stdout_path: stdoutPath, stderr_path: stderrPath });
+        assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+        finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: completed.exitCode === 0 && !completed.error ? "stopped" : "failed", reason: completed.error });
+        return result(managed.id, stdoutPath, stderrPath, completionPath, completed.exitCode, completed.error);
+    }
+    finally {
+        fs.closeSync(stdout);
+        fs.closeSync(stderr);
+    }
+}
+function result(id, stdout, stderr, completion, exitCode, error) {
+    // Full logs remain on disk; keep the returned prompt bounded.
+    const excerpt = (file) => fs.existsSync(file) ? fs.readFileSync(file, "utf8").slice(-64_000) : "";
+    return { exit_code: exitCode, stdout: excerpt(stdout), stderr: excerpt(stderr), error, process_id: id, stdout_path: stdout, stderr_path: stderr, completion_path: completion };
+}

package/dist/services/worktrees.js

@@ -4,7 +4,7 @@ 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, resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -28,7 +28,7 @@ export function planWorktree(context, input) {
         worktrunk: inspectManagedWorktrunk(context)
     };
 }
-export function createWorktreeRecord(context, input) {
+export function prepareWorktreeCreate(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const existing = activeWorktreeRecord(context, protocol.project_id, protocol.id);
     if (existing) {
@@ -37,17 +37,56 @@ export function createWorktreeRecord(context, input) {
             worktree_path: existing.worktree_path
         });
     }
-    const created = createManagedWorktree(context, { projectRoot: protocol.project_root, branch: input.branch, base: input.base, path: input.path });
-    recordManagedWorktree(context, { protocolId: protocol.id, projectRoot: protocol.project_root, branch: input.branch, base: input.base, created });
+    return prepareManagedWorktree({ ...input, projectRoot: protocol.project_root });
+}
+export function createWorktreeRecord(context, input, prepared = prepareWorktreeCreate(context, input)) {
+    const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
+    if (activeWorktreeRecord(context, protocol.project_id, protocol.id))
+        throw new AppError("worktree_already_exists", "Protocol already has an active worktree record", 1);
+    const created = createManagedWorktree(context, prepared, prepared);
+    recordManagedWorktree(context, { protocolId: protocol.id, projectRoot: protocol.project_root, branch: prepared.branch, base: prepared.base, created });
     return { ok: true, worktree: activeWorktreeRecord(context, protocol.project_id, protocol.id) };
 }
-/** Creates the checkout before a PRT exists. PROTOCOLIZE materializes the PRT only inside this checkout. */
-export function createManagedWorktree(context, input) {
+export function prepareManagedWorktree(input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
+    const invalid = (message) => { throw new AppError("validation", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true }); };
+    for (const key of ["branch", "base", "path"])
+        if (typeof input[key] !== "string" || !input[key].trim() || input[key].includes("\0"))
+            invalid(`--${key} must be a non-empty value without NUL`);
+    const git = (args) => {
+        const result = spawnSync("git", ["-C", projectRoot, ...args], { encoding: "utf8", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+        if (result.error)
+            throw result.error;
+        return result;
+    };
+    const branch = git(["check-ref-format", "--branch", input.branch]);
+    if (input.branch.startsWith("-") || branch.status !== 0 || branch.stdout.trim() !== input.branch)
+        invalid("--branch must be a literal valid Git branch name");
+    const base = git(["rev-parse", "--verify", "--end-of-options", `${input.base}^{commit}`]);
+    if (base.status !== 0)
+        invalid("--base must resolve to an existing Git commit");
+    if (git(["show-ref", "--verify", "--quiet", `refs/heads/${input.branch}`]).status === 0)
+        invalid("--branch already exists; choose a new feature branch");
+    const destination = canonicalPath(input.path, false);
+    if (isTrackedProjectPath(canonicalPath(projectRoot), destination))
+        invalid("--path must be outside the project checkout");
+    if (fs.existsSync(destination) && (!fs.statSync(destination).isDirectory() || fs.readdirSync(destination).length))
+        invalid("--path must be an absent or empty directory");
+    let parent = path.dirname(destination);
+    while (!fs.existsSync(parent) && path.dirname(parent) !== parent)
+        parent = path.dirname(parent);
+    if (!fs.statSync(parent).isDirectory())
+        invalid("--path has a parent that is not a directory");
+    fs.accessSync(parent, fs.constants.W_OK | fs.constants.X_OK);
+    return { projectRoot, branch: input.branch, base: base.stdout.trim(), path: destination };
+}
+/** Creates the checkout before a PRT exists. PROTOCOLIZE materializes the PRT only inside this checkout. */
+export function createManagedWorktree(context, input, prepared = prepareManagedWorktree(input)) {
+    const { projectRoot } = prepared;
     const worktrunk = ensureManagedWorktrunk(context);
     // Worktrunk owns creation; the CLI supplies its project-scoped service path
     // as a one-shot config override rather than relying on a developer's user config.
-    const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(path.resolve(input.path))}`, "switch", "--create", input.branch, "--base", input.base, "--no-cd", "--format=json", "-y"];
+    const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(prepared.path)}`, "switch", "--create", prepared.branch, "--base", prepared.base, "--no-cd", "--format=json", "-y"];
     const result = runExternal(command);
     if (result.exit_code !== 0)
         throw new AppError("worktrunk_command_unavailable", "Worktrunk switch failed", 1, { command: sanitizeCommand(command), result });
@@ -76,14 +115,29 @@ export function recordManagedWorktree(context, input) {
     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: input.created.worktreePath } });
 }
 /** Bootstrap a just-created RUN workspace before a durable PRT exists. */
-export function bootstrapManagedWorktree(context, input) {
-    const projectRoot = resolveProjectRoot(input.projectRoot);
-    const worktreePath = path.resolve(input.worktreePath);
+export function prepareManagedWorktreeBootstrapSources(root) {
+    const projectRoot = resolveProjectRoot(root);
     const includeFile = path.join(projectRoot, ".worktreeinclude");
     const configFile = path.join(projectRoot, ".config", "wt.toml");
     if (!fs.existsSync(includeFile) || !fs.existsSync(configFile)) {
         throw new AppError("bootstrap_unavailable", "Project-owned Worktrunk bootstrap files are required", 1, { include_file: includeFile, config_file: configFile });
     }
+    for (const file of [includeFile, configFile]) {
+        if (!fs.statSync(file).isFile())
+            throw new AppError("bootstrap_unavailable", "Project-owned bootstrap inputs must be regular files", 1, { file });
+        fs.accessSync(file, fs.constants.R_OK);
+    }
+    return projectRoot;
+}
+export function prepareManagedWorktreeBootstrap(input) {
+    const projectRoot = prepareManagedWorktreeBootstrapSources(input.projectRoot);
+    const worktreePath = path.resolve(input.worktreePath);
+    if (!fs.statSync(worktreePath).isDirectory())
+        throw new AppError("bootstrap_unavailable", "Bootstrap worktree must be a directory", 1, { worktree_path: worktreePath });
+    return { projectRoot, worktreePath };
+}
+export function bootstrapManagedWorktree(context, input, prepared = prepareManagedWorktreeBootstrap(input)) {
+    const { worktreePath } = prepared;
     const worktrunk = ensureManagedWorktrunk(context);
     const commands = [
         [worktrunk.bin, "-C", worktreePath, "step", "copy-ignored", "--require-include"],
@@ -103,38 +157,30 @@ export function getWorktreeStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     return { ok: true, protocol_id: protocol.id, worktree: worktreeRecord(context, protocol.project_id, protocol.id), worktrunk: inspectManagedWorktrunk(context) };
 }
-export function bootstrapWorktree(context, input) {
+export function prepareWorktreeBootstrap(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const record = activeWorktreeRecord(context, protocol.project_id, protocol.id);
     if (!record) {
         throw new AppError("not_found", `Worktree record is not active for protocol: ${protocol.id}`, 1);
     }
-    const includeFile = path.join(protocol.project_root, ".worktreeinclude");
-    const configFile = path.join(protocol.project_root, ".config", "wt.toml");
-    if (!fs.existsSync(includeFile) || !fs.existsSync(configFile)) {
-        throw new AppError("bootstrap_unavailable", "Project-owned Worktrunk bootstrap files are required", 1, {
-            include_file: includeFile,
-            config_file: configFile,
-            next_action: "Add .worktreeinclude and .config/wt.toml before bootstrapping the workspace."
-        });
+    return { protocol, record, managed: prepareManagedWorktreeBootstrap({ projectRoot: protocol.project_root, worktreePath: record.worktree_path }) };
+}
+export function bootstrapWorktree(context, input, prepared = prepareWorktreeBootstrap(context, input)) {
+    const { protocol, record } = prepared;
+    const active = activeWorktreeRecord(context, protocol.project_id, protocol.id);
+    if (!active || active.worktree_path !== record.worktree_path)
+        throw new AppError("worktree_active", "Worktree changed after bootstrap preparation", 1);
+    let result;
+    try {
+        result = bootstrapManagedWorktree(context, prepared.managed, prepared.managed);
     }
-    const worktrunk = ensureManagedWorktrunk(context);
-    const commands = [
-        [worktrunk.bin, "-C", record.worktree_path, "step", "copy-ignored", "--require-include"],
-        [worktrunk.bin, "-C", record.worktree_path, "hook", "pre-start", "--yes"]
-    ];
-    const results = [];
-    for (const command of commands) {
-        const result = runExternal(command);
-        results.push({ command: sanitizeCommand(command), ...result });
-        if (result.exit_code !== 0) {
-            const failed = { command: sanitizeCommand(command), result, results };
-            markBootstrapFailed(context, protocol, record, failed);
-            throw new AppError("bootstrap_failed", "Project-owned Worktrunk bootstrap failed", 1, failed);
-        }
+    catch (error) {
+        if (error instanceof AppError && error.code === "bootstrap_failed")
+            markBootstrapFailed(context, protocol, record, error.details);
+        throw error;
     }
     const now = context.now();
-    const result = { commands: results, status: "succeeded" };
+    const results = result.commands;
     context.db.run(`UPDATE worktree_records
      SET bootstrap_status = 'succeeded', last_command_result_json = ?, updated_at = ?
      WHERE project_id = ? AND protocol_id = ?`, [JSON.stringify(result), now, protocol.project_id, protocol.id]);
@@ -155,7 +201,7 @@ export function bootstrapWorktree(context, input) {
     });
     return { ok: true, worktree: worktreeRecord(context, protocol.project_id, protocol.id) };
 }
-export function closeWorktree(context, input) {
+export function prepareWorktreeClose(context, input) {
     if (!["keep", "remove"].includes(input.mode)) {
         throw new AppError("validation", "--mode must be keep or remove", 2);
     }
@@ -171,6 +217,10 @@ export function closeWorktree(context, input) {
             stage: state.stage
         });
     }
+    return { protocol, record };
+}
+export function closeWorktree(context, input) {
+    const { protocol, record } = prepareWorktreeClose(context, input);
     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 project_id = ? AND protocol_id = ?`, [nextStatus, now, now, protocol.project_id, protocol.id]);

package/dist/shared/entity-references.js

@@ -0,0 +1,8 @@
+/** Stable model-facing reference for persisted project, RUN and Work IDs. */
+export function shortEntityReference(id) {
+    return /^(?:PRJ|RUN|WRK)-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id;
+}
+/** Accepted spellings of one already-resolved entity. Wrong full slugs stay distinct. */
+export function entityReferenceVariants(id) {
+    return [...new Set([id, shortEntityReference(id)])];
+}

package/dist/shared/errors.js

@@ -9,6 +9,18 @@ export class AppError extends Error {
         this.details = details;
     }
 }
+/** Error fields must cross JSON boundaries as data: Error.message is not enumerable. */
+export function errorRecord(error, depth = 0) {
+    const value = error;
+    const details = value?.details && typeof value.details === "object" && !Array.isArray(value.details) ? value.details : {};
+    return {
+        code: typeof value?.code === "string" ? value.code : "unexpected",
+        message: typeof value?.message === "string" ? value.message : String(error),
+        exitCode: typeof value?.exitCode === "number" ? value.exitCode : 1,
+        details,
+        ...(value?.cause && depth < 3 ? { cause: errorRecord(value.cause, depth + 1) } : {})
+    };
+}
 export function isAppError(error) {
     return error instanceof AppError;
 }