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

package/dist/services/review-copy.js

@@ -0,0 +1,165 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { ignoredWorkspacePaths } from "./code-checks.js";
+import { localEnvironmentAllowed, ownedWorkspaceHookPath, projectServicePathFilter, workspaceGitFiles } from "./workspace-files.js";
+export function reviewerSourceInputs(root, aspectIds) {
+    const criteria = [...new Set(aspectIds)].sort().map(id => {
+        if (!/^[a-z][a-z0-9_-]*$/.test(id))
+            throw new AppError("review_criterion_invalid", "Assigned aspect has an invalid identity", 1, { aspect_id: id });
+        return `.memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects/${id}.md`;
+    });
+    const orientation = [".memory-bank/index.md", ".memory-bank/spec/engineering/index.md", ".memory-bank/spec/engineering/coding-standards.md"].filter(relative => fs.existsSync(path.join(root, relative)));
+    return [...criteria, ...orientation].map(relative => {
+        const file = path.join(root, relative);
+        if (!fs.existsSync(file))
+            throw new AppError("review_criterion_missing", "Assigned reviewer criterion is missing", 1, { path: relative });
+        const inside = path.relative(fs.realpathSync(root), fs.realpathSync(file));
+        if (inside === ".." || inside.startsWith(`..${path.sep}`) || !fs.statSync(file).isFile())
+            throw new AppError("review_criterion_invalid", "Reviewer source must be a file in its workspace", 1, { path: relative });
+        return { path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
+    });
+}
+export function reviewerSourceInstruction(root, aspectIds) {
+    const inputs = reviewerSourceInputs(root, aspectIds);
+    return ["Read the assigned canonical criterion files and the available project orientation below before independent review. Apply each criterion's scope; a small behavior change is not by itself a reason to omit testing or evidence. These starting inputs do not limit relevant project investigation. Do not edit them.", ...inputs.map(input => `- ${path.join(root, input.path)} (SHA256 ${input.sha256})`)].join("\n");
+}
+export function reviewEnvironmentAllowed(file) {
+    // Relative evidence names are scoped to the project: a private parent also
+    // makes its children private. Absolute filesystem traversal checks each
+    // directory separately, without classifying ancestors outside the workspace.
+    return path.isAbsolute(file) || path.win32.isAbsolute(file)
+        ? localEnvironmentAllowed(file)
+        : file.split(/[\\/]/).every(part => localEnvironmentAllowed(part));
+}
+export function reviewSourcePaths(root, explicitInputs = [], base = "HEAD") {
+    const inventory = workspaceGitFiles(root, ["--cached", "--others", "--exclude-standard"]);
+    if (inventory === null)
+        return null;
+    const serviceAllowed = projectServicePathFilter(root, explicitInputs);
+    const hasHead = spawnSync("git", ["-C", root, "rev-parse", "--verify", "HEAD"], { encoding: "utf8" }).status === 0;
+    if (base === "unborn" && hasHead)
+        throw new AppError("review_git_evidence_failed", "Unborn review baseline no longer matches the workspace", 1, { workspace_root: root });
+    const hasBase = base === "unborn" ? false : base !== "HEAD" || hasHead;
+    const changes = hasBase ? spawnSync("git", ["-C", root, "diff", "--name-status", "-z", "--find-renames", base, "--"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }) : null;
+    if (changes && (changes.status !== 0 || changes.error))
+        throw new AppError("review_git_evidence_failed", "Could not classify renamed review paths", 1, { workspace_root: root, cause: changes.error?.message ?? changes.stderr });
+    const fields = changes?.stdout.split("\0").filter(Boolean) ?? [], tainted = new Set();
+    for (let index = 0; index < fields.length;) {
+        const status = fields[index++];
+        if (/^[RC]/.test(status)) {
+            const before = fields[index++], after = fields[index++];
+            if (!reviewEnvironmentAllowed(before) || !reviewEnvironmentAllowed(after)) {
+                tainted.add(before);
+                tainted.add(after);
+            }
+        }
+        else
+            index += 1;
+    }
+    return [...new Set([...inventory, ...explicitInputs])]
+        .filter(relative => reviewEnvironmentAllowed(relative) && !tainted.has(relative) && serviceAllowed(path.join(root, relative)))
+        .sort();
+}
+export function reviewSourceFilter(root, explicitInputs = [], base = "HEAD") {
+    const selected = reviewSourcePaths(root, explicitInputs, base);
+    const serviceAllowed = projectServicePathFilter(root, explicitInputs);
+    const retained = new Set(selected?.map(relative => path.resolve(root, relative)) ?? []);
+    const branches = new Set();
+    for (const file of retained)
+        for (let directory = path.dirname(file); directory !== path.dirname(directory); directory = path.dirname(directory))
+            branches.add(directory);
+    return file => {
+        const parts = path.relative(root, file).split(path.sep);
+        if (parts.some(part => [".git", "node_modules", ".dd-flow"].includes(part)) || !reviewEnvironmentAllowed(file))
+            return false;
+        return selected === null ? serviceAllowed(file) : retained.has(path.resolve(file)) || branches.has(path.resolve(file));
+    };
+}
+export function reviewSourceHash(root, explicitInputs = [], base = "HEAD") {
+    const allowed = reviewSourceFilter(root, explicitInputs, base), ownedHook = ownedWorkspaceHookPath(root);
+    return reviewCopyHash(root, file => path.relative(root, file) !== ownedHook && allowed(file));
+}
+/** The copied project has no Git index. Apply the source's exact service-file
+ * policy to it, while retaining only our frozen Git evidence under .dd-flow. */
+export function reviewExecutionCopyHash(copyRoot, sourceRoot, includeEvidence = true, explicitInputs = [], base = "HEAD") {
+    if (ownedWorkspaceHookPath(sourceRoot) && !ownedWorkspaceHookPath(copyRoot))
+        throw new AppError("read_only_input_changed", "Qualified review hook differs between execution copy and source", 2, { copy_root: copyRoot });
+    const sourceAllowed = reviewSourceFilter(sourceRoot, explicitInputs, base);
+    const serviceAllowed = projectServicePathFilter(sourceRoot, explicitInputs);
+    const ownedHook = ownedWorkspaceHookPath(sourceRoot);
+    const verifySelection = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const file = path.join(directory, entry.name), relative = path.relative(copyRoot, file);
+            const parts = relative.split(path.sep);
+            if (parts[0] === ".dd-flow" || parts.some(part => [".git", "node_modules"].includes(part)))
+                continue;
+            if (!reviewEnvironmentAllowed(file))
+                throw new AppError("read_only_input_changed", "Read-only execution copy contains a local environment file", 2, { path: relative });
+            if (!serviceAllowed(path.join(sourceRoot, relative)))
+                continue;
+            if (!sourceAllowed(path.join(sourceRoot, relative)) && ignoredWorkspacePaths(sourceRoot, [relative]).includes(relative.split(path.sep).join("/")))
+                continue;
+            if (!sourceAllowed(path.join(sourceRoot, relative)))
+                throw new AppError("read_only_input_changed", "Read-only execution copy contains an unselected product input", 2, { path: relative });
+            if (entry.isDirectory())
+                verifySelection(file);
+        }
+    };
+    verifySelection(copyRoot);
+    return reviewCopyHash(copyRoot, file => {
+        const relative = path.relative(copyRoot, file);
+        const parts = relative.split(path.sep);
+        if (parts[0] === ".dd-flow")
+            return includeEvidence && (parts.length === 1 || parts[1] === "review-evidence");
+        return relative !== ownedHook && sourceAllowed(path.join(sourceRoot, relative));
+    });
+}
+/** Exact bytes visible in a read-only execution copy, including symlink targets. */
+export function reviewCopyHash(root, allowed = () => true) {
+    const hash = crypto.createHash("sha256");
+    let canonicalRoot;
+    try {
+        canonicalRoot = fs.realpathSync(root);
+    }
+    catch {
+        throw new AppError("read_only_input_changed", "Read-only execution copy is missing", 2, { root });
+    }
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(directory, entry.name);
+            if (!allowed(file))
+                continue;
+            const relative = path.relative(root, file).split(path.sep).join("/");
+            const stat = fs.lstatSync(file);
+            const record = (kind, value = "") => hash.update(`${JSON.stringify([relative, kind, stat.mode & 0o111, value])}\n`);
+            if (entry.isDirectory()) {
+                record("directory");
+                visit(file);
+                continue;
+            }
+            if (entry.isSymbolicLink()) {
+                const link = fs.readlinkSync(file);
+                let target;
+                try {
+                    target = fs.realpathSync(file);
+                }
+                catch {
+                    throw new AppError("read_only_workspace_escape", "Read-only copy contains an unresolved symlink", 1, { path: relative });
+                }
+                const inside = path.relative(canonicalRoot, target);
+                if (path.isAbsolute(link) || inside === ".." || inside.startsWith(`..${path.sep}`))
+                    throw new AppError("read_only_workspace_escape", "Read-only copy contains a symlink outside its workspace", 1, { path: relative });
+                record("symlink", link);
+            }
+            else if (entry.isFile())
+                record("file", crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"));
+            else
+                throw new AppError("read_only_workspace_unsupported", "Read-only copy contains an unsupported file type", 1, { path: relative });
+        }
+    };
+    visit(root);
+    return hash.digest("hex");
+}

package/dist/services/review-deferral.js

@@ -0,0 +1,23 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertPortableArtifactRef } from "./portable-refs.js";
+/** A deferral names one project-local file, never an arbitrary path. */
+export function reviewDefEvidence(workspaceRoot, defId) {
+    try {
+        if (!defId || !/^DEF-[A-Za-z0-9][A-Za-z0-9_-]*$/.test(defId))
+            throw new Error("invalid DEF identifier");
+        const relative = `.memory-bank/defs/${defId}.md`;
+        const file = assertPortableArtifactRef(relative, { workspaceRoot, runHome: workspaceRoot, runId: "" });
+        const directory = fs.realpathSync(path.join(workspaceRoot, ".memory-bank", "defs"));
+        const root = fs.realpathSync(workspaceRoot);
+        const directoryRelative = path.relative(root, directory);
+        if (directoryRelative === ".." || directoryRelative.startsWith(`..${path.sep}`) || path.isAbsolute(directoryRelative) || path.dirname(file) !== directory || !fs.statSync(file).isFile())
+            throw new Error("DEF must be a regular file in the project defs directory");
+        return { def_id: defId, path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
+    }
+    catch (error) {
+        throw new AppError("deferral_invalid", "A deferral requires a readable project-local named DEF", 2, { def_id: defId ?? null, cause: error instanceof Error ? error.message : String(error) });
+    }
+}

package/dist/services/run-control-receipt.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const records = (value) => Array.isArray(value) ? value.map(object) : [];
+const text = (value) => typeof value === "string" && value.length ? value : null;
+/** Pure projection of durable evidence. Never infer quiescence from an ACK,
+ * a terminal RUN label, or a settlement captured before a subsequent resume. */
+export function controlStatusReceipt(observation, request = {}) {
+    const control = object(observation.control), worker = object(observation.worker), resume = object(observation.resume_operation);
+    const present = Boolean(control.control_id), current = control.current === true;
+    const activeResume = Boolean(resume.operation_id);
+    const historical = !current || activeResume || ["resuming", "resumed"].includes(String(control.status));
+    const settlement = object(control.settlement);
+    const snapshot = historical ? {} : control.admission === "sealed" ? settlement : object(worker.snapshot);
+    const nodes = records(snapshot.nodes).map((node, index) => {
+        const identity = Object.fromEntries(["operation_id", "controller_id", "process_id", "check_id", "merge_request_id", "work_id", "work_session_id", "session_id", "harness", "state_dir", "resource_home"].filter(key => node[key] !== undefined).map(key => [key, node[key]]));
+        const settled = node.status === "completed";
+        const role = ["subject", "worker", "merge", "judge", "probe", "check", "process"].includes(String(node.role)) ? node.role : node.check_id ? "check" : node.merge_request_id ? "merge" : node.process_id ? "process" : "unknown";
+        return { id: `node:${crypto.createHash("sha256").update(JSON.stringify(Object.keys(identity).length ? identity : { index, reason: node.reason })).digest("hex")}`, role, status: settled ? "completed" : node.status === "outcome_unknown" ? "unknown" : "pending", acknowledged: settled || object(node.receipt).cancelled === true, settled, reason: settled ? null : text(node.reason) ?? "node_settlement_required", details: node };
+    });
+    const settled = present && current && !historical && control.status === "settled" && control.admission === "sealed" && Boolean(control.capture_path) && settlement.settled === true && Array.isArray(settlement.nodes) && nodes.every(node => node.settled);
+    let state;
+    if (!present)
+        state = request.action && ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "terminal_noop" : "not_requested";
+    else if (!current)
+        state = "superseded";
+    else if (resume.status === "failed" || worker.status === "failed")
+        state = "recovery_required";
+    else if (control.status === "resumed" && control.admission === "recovered" && resume.status === "completed")
+        state = "running";
+    else if (activeResume || control.status === "resuming")
+        state = "resuming";
+    else if (settled)
+        state = control.requested_mode === "pause" ? "paused" : "stopped";
+    else
+        state = control.requested_mode === "pause" ? "pause_requested" : "stop_requested";
+    const reasons = settled ? [] : [...new Set([
+            ...nodes.filter(node => !node.settled).map(node => node.reason),
+            ...(Array.isArray(snapshot.pending_reasons) ? snapshot.pending_reasons.filter((reason) => typeof reason === "string" && Boolean(reason)) : []),
+            ...(!present ? [state === "terminal_noop" ? "terminal_settlement_not_observed" : "control_not_requested"]
+                : !current ? ["control_superseded"]
+                    : state === "running" ? ["run_active"]
+                        : state === "resuming" ? ["recovery_acceptance_pending"]
+                            : state === "recovery_required" ? [text(object(resume.error).code) ?? text(object(worker.error).code) ?? "control_recovery_required"]
+                                : control.admission === "sealed" ? ["recovery_capture_required"] : ["settlement_observation_required"])
+        ])];
+    return {
+        ...observation, schema_id: "dd-flow/run-control-receipt@1", ok: true,
+        request_id: request.requestId ?? text(resume.request_id) ?? text(control.request_id), control_id: text(control.control_id),
+        generation: Number.isSafeInteger(control.generation) ? control.generation : 0,
+        requested_mode: request.action ?? (activeResume ? "resume" : text(control.requested_mode)),
+        applied_mode: settled ? control.requested_mode : state === "running" ? "resume" : null,
+        state, settled, nodes, unsettled_reasons: reasons,
+        resumability: ["done", "failed", "cancelled"].includes(String(observation.run_status)) ? "not_applicable" : settled || state === "recovery_required" ? "recovery_required" : ["running", "not_requested", "terminal_noop", "superseded"].includes(state) ? "not_applicable" : "pending",
+        recovery_id: text(control.recovery_id)
+    };
+}