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

package/dist/services/memory-init-preflight.js

@@ -0,0 +1,330 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { defaultMemoryLintConfiguration, validateMemoryLintConfig } from "./memory-lint-config.js";
+function refuse(reason, diagnostics) {
+    throw new AppError("memory_init_preflight_failed", "Memory init prerequisites are not admitted", 1, { reason, phase: "prepare", effect: "no_effect", next_action: reason === "existing_memory_bank" ? "audit_or_upgrade" : "repair_prerequisite_then_retry", ...(diagnostics ? { tool_probe: diagnostics } : {}) });
+}
+function executable(name, env) {
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        // Relative/empty PATH components must not execute project-owned files.
+        if (!path.isAbsolute(directory))
+            continue;
+        const candidate = path.join(directory, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            const resolved = fs.realpathSync(candidate);
+            if (fs.statSync(resolved).isFile())
+                return resolved;
+        }
+        catch { /* Continue the bounded, explicit PATH search. */ }
+    }
+    return refuse(`missing_tool:${name}`);
+}
+function root(value) {
+    if (!path.isAbsolute(value))
+        refuse("root_not_absolute");
+    try {
+        const resolved = fs.realpathSync(value);
+        if (!fs.statSync(resolved).isDirectory())
+            refuse("root_not_directory");
+        fs.accessSync(resolved, fs.constants.R_OK | fs.constants.W_OK | fs.constants.X_OK);
+        return resolved;
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("root_access_unavailable");
+    }
+}
+function noMemoryBank(directory) {
+    try {
+        fs.lstatSync(path.join(directory, ".memory-bank"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        return refuse("memory_bank_access_unavailable");
+    }
+    refuse("existing_memory_bank");
+}
+function probeTools(tools, env) {
+    const facts = Object.create(null);
+    const probeEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
+    for (const name of ["git", "wt", "mb-lint"]) {
+        const diagnostics = { name, executable: tools[name], args: ["--version"], timeout_ms: 5000, phase: "executable_read" };
+        try {
+            const digest = () => createHash("sha256").update(readBoundedReleaseFile(tools[name], 64 * 1024 * 1024)).digest("hex");
+            const executableSha256 = digest();
+            const started = performance.now();
+            const result = spawnSync(tools[name], ["--version"], { cwd: path.dirname(tools[name]), env: probeEnv,
+                timeout: 5000, maxBuffer: 64 * 1024, windowsHide: true, shell: false });
+            Object.assign(diagnostics, { phase: "version_probe", elapsed_ms: Math.round(performance.now() - started), status: result.status, signal: result.signal,
+                error_code: result.error?.code ?? null,
+                timed_out: result.error?.code === "ETIMEDOUT",
+                stdout_bytes: result.stdout?.length ?? null, stderr_bytes: result.stderr?.length ?? null,
+                // Tool output can contain environment secrets; retain bounded custody
+                // hashes rather than echoing uncontrolled stderr into public receipts.
+                stderr_sha256: result.stderr ? createHash("sha256").update(result.stderr).digest("hex") : null });
+            if (result.error || result.signal || result.status !== 0 || !result.stdout || !result.stderr)
+                refuse(`tool_probe_failed:${name}`, diagnostics);
+            const output = new TextDecoder("utf-8", { fatal: true }).decode(result.stdout);
+            const version = output.match(/\bv?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\b/)?.[1];
+            if (!version)
+                refuse(`tool_probe_failed:${name}`, { ...diagnostics, phase: "version_parse" });
+            if (digest() !== executableSha256)
+                refuse(`tool_probe_failed:${name}`, { ...diagnostics, phase: "executable_drift" });
+            facts[name] = { version, executable_sha256: executableSha256,
+                stdout_sha256: createHash("sha256").update(result.stdout).digest("hex"),
+                stderr_sha256: createHash("sha256").update(result.stderr).digest("hex") };
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_init_preflight_failed")
+                throw error;
+            refuse(`tool_probe_failed:${name}`, { ...diagnostics, error_code: error?.code ?? null });
+        }
+    }
+    return facts;
+}
+function inspect(input, env, ownedPublication = false, qualifyTools = true, observe, lintReservation, sourceTools) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(input.requestId))
+        refuse("invalid_request_id");
+    const project = root(input.projectRoot), workspace = root(input.workspaceRoot);
+    const lintFile = path.join(workspace, ".mb-lint.json"), lintBytes = defaultMemoryLintConfiguration();
+    let lintExists = false;
+    try {
+        fs.lstatSync(lintFile);
+        lintExists = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            refuse("lint_configuration_unavailable");
+    }
+    if (lintReservation === true && lintExists)
+        validateMemoryLintConfig(readBoundedReleaseFile(lintFile, 1024 * 1024), [".memory-bank/index.md", ".memory-bank/structure.md", ".memory-bank/project-policy.md"]);
+    const generatedLint = lintReservation === true ? (lintExists ? undefined : createHash("sha256").update(lintBytes).digest("hex")) : lintReservation;
+    const lintTemporary = `.dd-flow-write-${createHash("sha256").update(".mb-lint.json").digest("hex")}.tmp`;
+    if (typeof generatedLint === "string") {
+        if (generatedLint !== createHash("sha256").update(lintBytes).digest("hex"))
+            refuse("lint_configuration_reservation_changed");
+        if (lintExists && !readBoundedReleaseFile(lintFile, 1024 * 1024).equals(lintBytes))
+            refuse("generated_lint_configuration_changed");
+        if (ownedPublication) {
+            const temporary = path.join(workspace, lintTemporary);
+            let pending;
+            try {
+                pending = fs.lstatSync(temporary);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    refuse("lint_configuration_unavailable");
+            }
+            if (pending) {
+                if (!pending.isFile() || pending.size > lintBytes.length || ![1, 2].includes(pending.nlink))
+                    refuse("unsafe_lint_configuration_temporary");
+                const content = pending.size ? readBoundedReleaseFile(temporary, lintBytes.length) : Buffer.alloc(0);
+                if (!content.equals(lintBytes.subarray(0, content.length)))
+                    refuse("unsafe_lint_configuration_temporary");
+                if (pending.nlink === 2) {
+                    const destination = lintExists ? fs.lstatSync(lintFile) : undefined;
+                    if (!destination?.isFile() || destination.dev !== pending.dev || destination.ino !== pending.ino || destination.nlink !== 2)
+                        refuse("unsafe_lint_configuration_temporary");
+                }
+            }
+        }
+    }
+    if (!ownedPublication || workspace !== project)
+        noMemoryBank(project);
+    if (!ownedPublication && workspace !== project)
+        noMemoryBank(workspace);
+    const tools = sourceTools ?? { git: executable("git", env), wt: executable("wt", env), "mb-lint": executable("mb-lint", env) };
+    const toolProbes = qualifyTools ? probeTools(tools, env) : undefined;
+    const gitEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
+    const git = (directory, args, optional = false) => {
+        const result = spawnSync(tools.git, ["-c", "core.fsmonitor=false", "-c", "core.untrackedCache=false", "-C", directory, ...args], {
+            env: { ...gitEnv, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024,
+        });
+        if (result.error || result.signal || result.status !== 0 && !optional)
+            refuse("git_observation_failed");
+        return result.status === 0 ? result.stdout : null;
+    };
+    for (const directory of new Set([project, workspace])) {
+        if (git(directory, ["rev-parse", "--is-bare-repository"])?.trim() !== "false"
+            || root(git(directory, ["rev-parse", "--show-toplevel"]).trim()) !== directory)
+            refuse("not_repository_root");
+    }
+    const common = (directory) => root(path.resolve(directory, git(directory, ["rev-parse", "--git-common-dir"]).trim()));
+    const repository = common(project);
+    if (repository !== common(workspace))
+        refuse("foreign_workspace_repository");
+    const branch = git(workspace, ["symbolic-ref", "--quiet", "--short", "HEAD"], true)?.trim();
+    if (!branch)
+        refuse("workspace_branch_unavailable");
+    const head = git(workspace, ["rev-parse", "--verify", "HEAD"], true)?.trim() ?? null;
+    const status = git(workspace, ["status", "--porcelain=v1", "-z", "--untracked-files=normal",
+        ...(ownedPublication ? ["--", ".", ":(top,literal,exclude).memory-bank", ...(generatedLint ? [":(top,literal,exclude).mb-lint.json", `:(top,literal,exclude)${lintTemporary}`] : [])] : [])]);
+    const sourceHash = createHash("sha256");
+    let total = 0;
+    const files = [...new Set(git(workspace, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]).split("\0").filter(logical => logical
+            && (!ownedPublication || logical !== ".memory-bank" && !logical.startsWith(".memory-bank/")
+                && !(generatedLint && [".mb-lint.json", lintTemporary].includes(logical)))))].sort();
+    for (const logical of files) {
+        if (path.isAbsolute(logical) || logical.split("/").some(part => !part || part === "." || part === ".."))
+            refuse("unsafe_source_path");
+        let current = workspace;
+        for (const part of logical.split("/").slice(0, -1)) {
+            current = path.join(current, part);
+            try {
+                if (!fs.lstatSync(current).isDirectory())
+                    refuse("unsafe_source_directory");
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    break;
+                throw error;
+            }
+        }
+        const file = path.join(workspace, logical);
+        sourceHash.update(logical).update("\0");
+        let stat;
+        try {
+            stat = fs.lstatSync(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                sourceHash.update("missing\0");
+                observe?.({ path: logical, kind: "missing", sha256: null });
+                continue;
+            }
+            return refuse("source_unavailable");
+        }
+        if (stat.isSymbolicLink()) {
+            const sha256 = hybridDigest(fs.readlinkSync(file));
+            sourceHash.update("link\0").update(sha256).update("\0");
+            observe?.({ path: logical, kind: "link", sha256 });
+        }
+        else if (stat.isDirectory()) {
+            sourceHash.update("gitlink\0");
+            observe?.({ path: logical, kind: "gitlink", sha256: null });
+        }
+        else if (stat.isFile()) {
+            if (stat.size > 16 * 1024 * 1024 || (total += stat.size) > 64 * 1024 * 1024)
+                refuse("source_inventory_exceeds_bound");
+            const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+            try {
+                const bytes = Buffer.alloc(stat.size + 1);
+                let length = 0;
+                while (length < bytes.length) {
+                    const read = fs.readSync(fd, bytes, length, bytes.length - length, length);
+                    if (!read)
+                        break;
+                    length += read;
+                }
+                if (length !== stat.size || fs.fstatSync(fd).size !== stat.size)
+                    refuse("source_changed_during_observation");
+                const sha256 = createHash("sha256").update(bytes.subarray(0, length)).digest("hex");
+                sourceHash.update("file\0").update(sha256).update("\0");
+                observe?.({ path: logical, kind: "file", sha256 });
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        else
+            refuse("unsafe_source_kind");
+    }
+    return { schema_id: "dd-flow/memory-init-target-preflight@1", request_id: input.requestId,
+        project_root: project, workspace_root: workspace, repository, head, branch,
+        dirty: status.length > 0, status_sha256: hybridDigest(status), source_sha256: sourceHash.digest("hex"), tools,
+        ...(generatedLint ? { generated_lint_config_sha256: generatedLint } : {}),
+        ...(toolProbes ? { tool_probes: toolProbes } : {}) };
+}
+/** Check the prepared executable identities, not another version invocation. */
+function reinspect(facts, input, env, ownedPublication, lintReservation) {
+    const tools = { git: executable("git", env), wt: executable("wt", env), "mb-lint": executable("mb-lint", env) };
+    if (facts.tool_probes)
+        for (const name of ["git", "wt", "mb-lint"]) {
+            let checksum;
+            try {
+                checksum = createHash("sha256").update(readBoundedReleaseFile(tools[name], 64 * 1024 * 1024)).digest("hex");
+            }
+            catch {
+                return refuse("target_changed_after_preparation");
+            }
+            if (tools[name] !== facts.tools[name] || checksum !== facts.tool_probes[name]?.executable_sha256)
+                refuse("target_changed_after_preparation");
+        }
+    const current = inspect(input, env, ownedPublication, false, undefined, lintReservation, tools);
+    return facts.tool_probes ? { ...current, tool_probes: facts.tool_probes } : current;
+}
+/** Read-only inventory of the independently selected bootstrap baseline. The
+ * publisher/bootstrap must establish owned-publication custody first. This
+ * changes no legacy target fact/checksum and never follows a source symlink.
+ */
+export function observeMemoryInitSourceInventory(facts, expectedSha256, env) {
+    if (hybridDigest(facts) !== expectedSha256)
+        refuse("target_changed_after_preparation");
+    // Git is used to observe repository/source facts; wt and lint are not used
+    // here. Their accepted bootstrap capability is not a source-preservation test.
+    if (facts.tool_probes && createHash("sha256").update(readBoundedReleaseFile(facts.tools.git, 64 * 1024 * 1024)).digest("hex") !== facts.tool_probes.git.executable_sha256)
+        refuse("selected_git_changed");
+    const entries = [];
+    const current = inspect({ projectRoot: facts.project_root, workspaceRoot: facts.workspace_root, requestId: facts.request_id }, env, true, false, entry => entries.push(entry), facts.generated_lint_config_sha256, facts.tools);
+    const sourceFacts = ({ tools: _tools, tool_probes: _probes, ...source }) => source;
+    if (hybridDigest(sourceFacts(current)) !== hybridDigest(sourceFacts(facts)))
+        refuse("target_changed_after_preparation");
+    return { entries, sha256: hybridDigest(entries) };
+}
+/** Read-only prerequisites, before registration, workspace/scaffold writes or agent launch.
+ * Bounded version probes prove tool entrypoint response only, not full tool
+ * capability, minimum-version compatibility, bootstrap/storage or harness readiness.
+ */
+export class PreparedMemoryInitTarget {
+    sha256;
+    #facts;
+    #input;
+    #env;
+    constructor(facts, input, env) {
+        this.#facts = structuredClone(facts);
+        this.#input = structuredClone(input);
+        this.#env = { ...env };
+        this.sha256 = hybridDigest(facts);
+        Object.freeze(this);
+    }
+    static prepare(input, env) {
+        try {
+            return new PreparedMemoryInitTarget(inspect(input, env, false, true, undefined, true), input, env);
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("source_observation_failed");
+        }
+    }
+    facts() { return structuredClone(this.#facts); }
+    revalidate() {
+        if (hybridDigest(reinspect(this.#facts, this.#input, this.#env, false, this.#facts.generated_lint_config_sha256 ? true : undefined)) !== this.sha256)
+            refuse("target_changed_after_preparation");
+    }
+    /** Only the publisher may use this after independently verifying its CLI-home owner journal.
+     * Excludes published MB and, only for a fresh reservation, the exact generated
+     * lint policy/owned temporary. User sources, scope, HEAD and tools stay pinned.
+     */
+    static revalidateOwnedPublication(facts, expectedSha256, env) {
+        if (hybridDigest(facts) !== expectedSha256 || hybridDigest(reinspect(facts, { projectRoot: facts.project_root,
+            workspaceRoot: facts.workspace_root, requestId: facts.request_id }, env, true, facts.generated_lint_config_sha256)) !== expectedSha256)
+            refuse("target_changed_after_preparation");
+    }
+    /** Restore only after the publication service checks its independent journal and root owner.
+     * This never provides a fresh-init route for an existing Memory Bank.
+     */
+    static restoreOwnedPublication(facts, expectedSha256, env) {
+        PreparedMemoryInitTarget.revalidateOwnedPublication(facts, expectedSha256, env);
+        return new PreparedMemoryInitTarget(facts, { projectRoot: facts.project_root,
+            workspaceRoot: facts.workspace_root, requestId: facts.request_id }, env);
+    }
+}