modwright 0.1.0

package/dist/core/toolchain/locate.js

@@ -0,0 +1,275 @@
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { pathExists } from "../fsutil.js";
+import { userDataDir } from "../home.js";
+import { loadUserConfig } from "../userconfig.js";
+import { toolEnvironment } from "./env.js";
+import { TOOL_SPECS } from "./specs.js";
+import { batchFileArgv, isBatchFile } from "./run.js";
+const VERSION_PROBE_TIMEOUT_MS = 5_000;
+function pathEntries() {
+    const raw = process.env.PATH ?? process.env.Path ?? "";
+    return raw.split(path.delimiter).filter((entry) => entry.length > 0);
+}
+function pathExt() {
+    if (process.platform !== "win32")
+        return [""];
+    const raw = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+    return raw.split(";").map((ext) => ext.toLowerCase());
+}
+function executableMatchesEntry(name, entry) {
+    if (process.platform !== "win32")
+        return entry === name;
+    const entryLower = entry.toLowerCase();
+    const nameLower = name.toLowerCase();
+    if (entryLower === nameLower)
+        return true;
+    const ext = path.extname(nameLower);
+    if (ext)
+        return false;
+    return pathExt().some((candidateExt) => entryLower === nameLower + candidateExt);
+}
+async function findOnPath(spec) {
+    for (const dir of pathEntries()) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of spec.executables) {
+            const hit = entries.find((entry) => executableMatchesEntry(name, entry));
+            if (hit)
+                return path.join(dir, hit);
+        }
+    }
+    return undefined;
+}
+function naturalCompare(a, b) {
+    const chunk = /(\d+|\D+)/g;
+    const aParts = a.match(chunk) ?? [a];
+    const bParts = b.match(chunk) ?? [b];
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i++) {
+        const av = aParts[i] ?? "";
+        const bv = bParts[i] ?? "";
+        if (av === bv)
+            continue;
+        const an = Number(av);
+        const bn = Number(bv);
+        if (!Number.isNaN(an) && !Number.isNaN(bn))
+            return an - bn;
+        return av < bv ? -1 : 1;
+    }
+    return 0;
+}
+async function resolveOneCandidate(template) {
+    const normalized = template.replace(/\\/g, "/");
+    const segments = normalized.split("/");
+    const starIndex = segments.findIndex((segment) => segment.includes("*"));
+    if (starIndex === -1) {
+        return (await pathExists(normalized)) ? normalized : undefined;
+    }
+    const dir = segments.slice(0, starIndex).join("/") || "/";
+    const rest = segments.slice(starIndex + 1);
+    const patternSegment = segments[starIndex] ?? "*";
+    const regex = new RegExp("^" + patternSegment.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$", "i");
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return undefined;
+    }
+    const matches = entries.filter((entry) => regex.test(entry)).sort(naturalCompare).reverse();
+    for (const match of matches) {
+        const candidate = [dir, match, ...rest].join("/");
+        const resolved = await resolveOneCandidate(candidate);
+        if (resolved)
+            return resolved;
+    }
+    return undefined;
+}
+const probeCache = new Map();
+async function probeVersion(execPath, spec) {
+    const versionArgs = spec.versionArgs;
+    const versionPattern = spec.versionPattern;
+    if (!versionArgs || !versionPattern)
+        return "unknown";
+    let key;
+    try {
+        const stat = await fs.stat(execPath);
+        key = JSON.stringify([execPath, stat.size, stat.mtimeMs, versionArgs, versionPattern.source]);
+    }
+    catch {
+        key = undefined;
+    }
+    if (key === undefined)
+        return runVersionProbe(execPath, versionArgs, versionPattern);
+    let cached = probeCache.get(key);
+    if (!cached) {
+        cached = runVersionProbe(execPath, versionArgs, versionPattern);
+        probeCache.set(key, cached);
+        const settledKey = key;
+        void cached.then((version) => {
+            if (version === "unknown")
+                probeCache.delete(settledKey);
+        });
+    }
+    return cached;
+}
+async function runVersionProbe(execPath, versionArgs, versionPattern) {
+    const output = await new Promise((resolve) => {
+        let settled = false;
+        let child;
+        try {
+            const env = toolEnvironment().env;
+            const shim = process.platform === "win32" && isBatchFile(execPath) ? batchFileArgv(execPath, versionArgs, env) : undefined;
+            child = shim
+                ? spawn(shim.command, shim.argv, { stdio: ["ignore", "pipe", "pipe"], env, windowsVerbatimArguments: true })
+                : spawn(execPath, versionArgs, { stdio: ["ignore", "pipe", "pipe"], env });
+        }
+        catch {
+            resolve("");
+            return;
+        }
+        let out = "";
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(out);
+        }, VERSION_PROBE_TIMEOUT_MS);
+        const outDecoder = new StringDecoder("utf8");
+        const errDecoder = new StringDecoder("utf8");
+        child.stdout?.on("data", (chunk) => (out += outDecoder.write(chunk)));
+        child.stderr?.on("data", (chunk) => (out += errDecoder.write(chunk)));
+        child.on("error", () => finish(out));
+        child.on("close", () => finish(out));
+    });
+    const match = versionPattern.exec(output);
+    return match?.[1] ?? "unknown";
+}
+async function resolveOverride(override, spec) {
+    let stat;
+    try {
+        stat = await fs.stat(override);
+    }
+    catch {
+        return undefined;
+    }
+    if (!stat.isDirectory())
+        return override;
+    let entries;
+    try {
+        entries = await fs.readdir(override);
+    }
+    catch {
+        return undefined;
+    }
+    for (const name of spec.executables) {
+        const hit = entries.find((entry) => executableMatchesEntry(name, entry));
+        if (hit)
+            return path.join(override, hit);
+    }
+    return undefined;
+}
+async function findManaged(spec) {
+    const root = path.join(userDataDir(), "tools", spec.id);
+    let entries;
+    try {
+        entries = (await fs.readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return undefined;
+    }
+    for (const dir of [...entries.sort(naturalCompare).reverse().map((v) => path.join(root, v)), root]) {
+        for (const sub of [dir, path.join(dir, "bin"), path.join(dir, "Scripts")]) {
+            const hit = await resolveOverride(sub, spec);
+            if (hit && hit !== sub)
+                return hit;
+        }
+    }
+    return undefined;
+}
+export async function resolveToolPath(spec, given) {
+    return resolveOverride(given, spec);
+}
+export async function locateTool(spec, options = {}) {
+    const base = { id: spec.id, label: spec.label, usedBy: spec.usedBy };
+    const policy = options.probe ?? "all";
+    const found = async (execPath, source) => {
+        if (policy === "none") {
+            return { ...base, found: true, path: execPath, source, versionNotProbed: "this is a dry-run, which never runs a tool" };
+        }
+        if (policy === "trusted" && source === "project") {
+            return {
+                ...base,
+                found: true,
+                path: execPath,
+                source,
+                versionNotProbed: "a project toolchain override is only run by a build or another apply, never by a read-only check",
+            };
+        }
+        return { ...base, found: true, path: execPath, source, version: await probeVersion(execPath, spec) };
+    };
+    const envPath = process.env[spec.envVar];
+    const fromEnv = envPath ? await resolveOverride(envPath, spec) : undefined;
+    if (fromEnv)
+        return found(fromEnv, "env");
+    const override = options.projectOverrides?.[spec.id];
+    const fromProject = override ? await resolveOverride(override, spec) : undefined;
+    if (fromProject)
+        return found(fromProject, "project");
+    const userTools = options.userTools === undefined ? (await loadUserConfig()).config.tools : options.userTools;
+    const remembered = userTools?.[spec.id];
+    const fromUser = remembered ? await resolveOverride(remembered.path, spec) : undefined;
+    if (fromUser)
+        return found(fromUser, remembered.installedBy === "modwright" ? "managed" : "user");
+    const managed = await findManaged(spec);
+    if (managed)
+        return found(managed, "managed");
+    const onPath = await findOnPath(spec);
+    if (onPath)
+        return found(onPath, "path");
+    for (const candidate of spec.candidates) {
+        const resolved = await resolveOneCandidate(candidate);
+        if (resolved)
+            return found(resolved, "candidate");
+    }
+    return {
+        ...base,
+        found: false,
+        hint: hintFor(spec, remembered),
+    };
+}
+function hintFor(spec, staleEntry) {
+    const stale = staleEntry ? ` The path remembered in ModWright's config (${staleEntry.path}) no longer holds it.` : "";
+    const parts = [
+        ...(spec.managed ? [`ModWright can install it: check_toolchain action=install tool=${spec.id} (a dry run first shows the file, source, size and sha256)`] : []),
+        `${spec.managed ? "or point" : "point"} ModWright at an existing copy once with check_toolchain action=remember tool=${spec.id} toolPath=<path>`,
+        `or set ${spec.envVar}`,
+    ];
+    if (spec.homepage && !spec.managed)
+        parts.push(`or install it from ${spec.homepage}`);
+    return `${spec.label} was not found on PATH or in common install locations.${stale} To fix: ${parts.join(", ")}.`;
+}
+export async function checkToolchain(options = {}) {
+    const specs = options.surfaceId
+        ? TOOL_SPECS.filter((spec) => spec.usedBy.includes(options.surfaceId))
+        : TOOL_SPECS;
+    const results = [];
+    const userTools = options.userTools === undefined ? (await loadUserConfig()).config.tools : options.userTools;
+    for (const spec of specs) {
+        results.push(await locateTool(spec, { projectOverrides: options.projectOverrides, probe: options.probe ?? "trusted", userTools }));
+    }
+    return results;
+}

package/dist/core/toolchain/remember.js

@@ -0,0 +1,84 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { loadUserConfig, userConfigFile, userConfigWritePlan } from "../userconfig.js";
+import { resolveToolPath } from "./locate.js";
+import { TOOL_SPECS } from "./specs.js";
+export async function planDataMemory(action, dataId, dataPath, known, options = {}) {
+    const need = known.find((k) => k.id === dataId);
+    if (!need)
+        return { ok: false, error: `Unknown data folder "${dataId}". Known: ${known.map((k) => `${k.id} (${k.what})`).join(", ") || "none"}.` };
+    const file = options.file ?? userConfigFile();
+    const loaded = await loadUserConfig(file);
+    if (loaded.problems.length > 0)
+        return { ok: false, error: `${loaded.problems.join(" ")} Fix or remove ${file} before changing it through ModWright.` };
+    const previous = loaded.config.data[need.id];
+    if (action === "forget") {
+        if (!previous)
+            return { ok: false, error: `${need.id} is not remembered in ${file}; nothing to forget.` };
+        const { [need.id]: _dropped, ...rest } = loaded.config.data;
+        const config = { ...loaded.config, data: rest };
+        return { ok: true, action, data: need.id, file, plan: userConfigWritePlan(config, `forget the ${need.id} data folder in the per-user config`, file), config, previous };
+    }
+    if (!dataPath)
+        return { ok: false, error: `remember needs dataPath: ${need.what}.` };
+    if (!path.isAbsolute(dataPath))
+        return { ok: false, error: `dataPath must be absolute ("${dataPath}" is relative): the config is read from every session, whatever its working directory.` };
+    let isDir = false;
+    try {
+        isDir = (await fs.stat(dataPath)).isDirectory();
+    }
+    catch {
+    }
+    if (!isDir)
+        return { ok: false, error: `${dataPath} is not an existing folder; ${need.id} should be ${need.what}.` };
+    const entry = { path: path.resolve(dataPath), rememberedAt: (options.now ?? (() => new Date()))().toISOString() };
+    const config = { ...loaded.config, data: { ...loaded.config.data, [need.id]: entry } };
+    return {
+        ok: true,
+        action,
+        data: need.id,
+        file,
+        plan: userConfigWritePlan(config, `remember ${dataPath} as the ${need.id} data folder in the per-user config`, file),
+        config,
+        entry,
+        ...(previous ? { previous } : {}),
+    };
+}
+export async function planToolMemory(action, toolId, toolPath, options = {}) {
+    const spec = TOOL_SPECS.find((s) => s.id === toolId);
+    if (!spec)
+        return { ok: false, error: `Unknown tool "${toolId}". Known: ${TOOL_SPECS.map((s) => s.id).join(", ")}.` };
+    const file = options.file ?? userConfigFile();
+    const loaded = await loadUserConfig(file);
+    if (loaded.problems.length > 0) {
+        return { ok: false, error: `${loaded.problems.join(" ")} Fix or remove ${file} before changing it through ModWright.` };
+    }
+    const previous = loaded.config.tools[spec.id];
+    if (action === "forget") {
+        if (!previous)
+            return { ok: false, error: `${spec.id} is not remembered in ${file}; nothing to forget.` };
+        const { [spec.id]: _dropped, ...rest } = loaded.config.tools;
+        const config = { ...loaded.config, tools: rest };
+        return { ok: true, action, tool: spec.id, file, plan: userConfigWritePlan(config, `forget ${spec.label} in the per-user config`, file), config, previous };
+    }
+    if (!toolPath)
+        return { ok: false, error: `remember needs toolPath: the ${spec.label} executable, or the folder holding it.` };
+    if (!path.isAbsolute(toolPath))
+        return { ok: false, error: `toolPath must be absolute ("${toolPath}" is relative): the config is read from every session, whatever its working directory.` };
+    const resolved = await resolveToolPath(spec, toolPath);
+    if (!resolved) {
+        return { ok: false, error: `No ${spec.executables.join(" / ")} at ${toolPath}: give the executable itself, or the folder that directly holds it.` };
+    }
+    const entry = { path: resolved, installedBy: "user", rememberedAt: (options.now ?? (() => new Date()))().toISOString() };
+    const config = { ...loaded.config, tools: { ...loaded.config.tools, [spec.id]: entry } };
+    return {
+        ok: true,
+        action,
+        tool: spec.id,
+        file,
+        plan: userConfigWritePlan(config, `remember ${spec.label} at ${resolved} in the per-user config`, file),
+        config,
+        entry,
+        ...(previous ? { previous } : {}),
+    };
+}

package/dist/core/toolchain/run.js

@@ -0,0 +1,318 @@
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { toolEnvironment } from "./env.js";
+const MAX_CAPTURE_BYTES = 1_000_000;
+const TRUNCATION_NOTE = "\n...[truncated]";
+export function assertAbsolute(paths) {
+    const relative = paths.filter((p) => !path.isAbsolute(p));
+    if (relative.length === 0)
+        return;
+    const error = new Error(`expected absolute path(s), got: ${relative.join(", ")}`);
+    error.code = "relative-path";
+    error.hint = "divine.exe silently writes nothing and exits 0 when given a relative or malformed path; resolve to an absolute path first.";
+    throw error;
+}
+export function toNativePath(p) {
+    return process.platform === "win32" ? p.replace(/\//g, "\\") : p;
+}
+function appendCapped(buf, chunk, truncatedRef, cap = MAX_CAPTURE_BYTES) {
+    if (truncatedRef.value)
+        return buf;
+    const combined = buf + chunk;
+    if (combined.length <= cap)
+        return combined;
+    truncatedRef.value = true;
+    return combined.slice(0, cap) + TRUNCATION_NOTE;
+}
+async function findMissingOutputs(expected) {
+    const missing = [];
+    for (const p of expected) {
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isDirectory()) {
+                const entries = await fs.readdir(p);
+                if (entries.length === 0)
+                    missing.push(p);
+            }
+            else if (!stat.isFile() || stat.size === 0) {
+                missing.push(p);
+            }
+        }
+        catch {
+            missing.push(p);
+        }
+    }
+    return missing;
+}
+async function snapshotOutputs(expected) {
+    const before = new Map();
+    for (const p of expected) {
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isFile())
+                before.set(p, { size: stat.size, mtimeMs: stat.mtimeMs });
+        }
+        catch {
+        }
+    }
+    return before;
+}
+async function findStaleOutputs(before) {
+    const stale = [];
+    for (const [p, prev] of before) {
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isFile() && stat.size === prev.size && stat.mtimeMs === prev.mtimeMs)
+                stale.push(p);
+        }
+        catch {
+        }
+    }
+    return stale;
+}
+const CMD_UNSAFE = /["%!\r\n]/;
+export function batchFileArgv(file, args, env = process.env) {
+    for (const token of [file, ...args]) {
+        if (CMD_UNSAFE.test(token)) {
+            throw new Error(`cannot pass ${JSON.stringify(token)} to a batch file safely: it contains a character cmd.exe reinterprets (" % ! or a line break)`);
+        }
+    }
+    const line = [file, ...args].map((t) => `"${t}"`).join(" ");
+    const comspec = Object.entries(env).find(([k, v]) => k.toLowerCase() === "comspec" && v)?.[1];
+    return { command: comspec ?? "cmd.exe", argv: ["/d", "/s", "/c", `"${line}"`] };
+}
+export function isBatchFile(p) {
+    return /\.(bat|cmd)$/i.test(p);
+}
+function killTree(child) {
+    if (process.platform === "win32" && child.pid !== undefined) {
+        try {
+            spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => child.kill());
+            return;
+        }
+        catch {
+        }
+    }
+    child.kill();
+}
+export async function runTool(location, options) {
+    const command = location.path ?? location.label;
+    const args = options.args;
+    const started = Date.now();
+    if (!location.found || !location.path) {
+        return {
+            tool: location.id,
+            command,
+            args,
+            ok: false,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            durationMs: 0,
+            missingOutputs: [],
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            error: {
+                code: "not-found",
+                message: `${location.label} is not installed or could not be located.`,
+                hint: location.hint,
+            },
+        };
+    }
+    const { env, filled: envFilled } = toolEnvironment(options.env);
+    const before = await snapshotOutputs(options.expectOutputs ?? []);
+    const result = await new Promise((resolve) => {
+        let settled = false;
+        let stdout = "";
+        let stderr = "";
+        const stdoutTruncated = { value: false };
+        const stderrTruncated = { value: false };
+        let child;
+        try {
+            const [exe, ...prefix] = location.interpreter?.length
+                ? [...location.interpreter, location.path]
+                : [location.path];
+            const spawnOptions = {
+                cwd: options.cwd,
+                env,
+                stdio: ["ignore", "pipe", "pipe"],
+            };
+            if (process.platform === "win32" && isBatchFile(exe)) {
+                const shim = batchFileArgv(exe, [...prefix, ...args], env);
+                child = spawn(shim.command, shim.argv, { ...spawnOptions, windowsVerbatimArguments: true });
+            }
+            else {
+                child = spawn(exe, [...prefix, ...args], spawnOptions);
+            }
+        }
+        catch (err) {
+            resolve(spawnFailed(location, command, args, started, err));
+            return;
+        }
+        const timer = options.timeoutMs
+            ? setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                killTree(child);
+                resolve({
+                    tool: location.id,
+                    command,
+                    args,
+                    ok: false,
+                    exitCode: null,
+                    stdout,
+                    stderr,
+                    durationMs: Date.now() - started,
+                    missingOutputs: [],
+                    stdoutTruncated: stdoutTruncated.value,
+                    stderrTruncated: stderrTruncated.value,
+                    error: {
+                        code: "timeout",
+                        message: `${location.label} did not finish within ${options.timeoutMs}ms.`,
+                    },
+                });
+            }, options.timeoutMs)
+            : undefined;
+        const cap = options.maxCaptureBytes ?? MAX_CAPTURE_BYTES;
+        const stdoutDecoder = new StringDecoder("utf8");
+        const stderrDecoder = new StringDecoder("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout = appendCapped(stdout, stdoutDecoder.write(chunk), stdoutTruncated, cap);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = appendCapped(stderr, stderrDecoder.write(chunk), stderrTruncated, cap);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(spawnFailed(location, command, args, started, err));
+        });
+        child.on("close", (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(finish({
+                location,
+                command,
+                args,
+                started,
+                exitCode,
+                stdout,
+                stderr,
+                stdoutTruncated: stdoutTruncated.value,
+                stderrTruncated: stderrTruncated.value,
+                expectOutputs: options.expectOutputs ?? [],
+                before,
+                requireFreshOutputs: options.requireFreshOutputs ?? false,
+            }));
+        });
+    });
+    return envFilled.length > 0 ? { ...result, envFilled } : result;
+}
+function spawnFailed(location, command, args, started, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        tool: location.id,
+        command,
+        args,
+        ok: false,
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        durationMs: Date.now() - started,
+        missingOutputs: [],
+        stdoutTruncated: false,
+        stderrTruncated: false,
+        error: {
+            code: "spawn-failed",
+            message: `Failed to start ${location.label}: ${message}`,
+        },
+    };
+}
+async function finish(a) {
+    const durationMs = Date.now() - a.started;
+    const missingOutputs = await findMissingOutputs(a.expectOutputs);
+    const staleOutputs = await findStaleOutputs(a.before);
+    if (a.exitCode !== 0) {
+        return {
+            tool: a.location.id,
+            command: a.command,
+            args: a.args,
+            ok: false,
+            exitCode: a.exitCode,
+            stdout: a.stdout,
+            stderr: a.stderr,
+            durationMs,
+            missingOutputs,
+            stdoutTruncated: a.stdoutTruncated,
+            stderrTruncated: a.stderrTruncated,
+            error: {
+                code: "non-zero-exit",
+                message: `${a.location.label} exited with code ${a.exitCode}.`,
+            },
+        };
+    }
+    if (a.requireFreshOutputs && staleOutputs.length > 0) {
+        return {
+            tool: a.location.id,
+            command: a.command,
+            args: a.args,
+            ok: false,
+            exitCode: a.exitCode,
+            stdout: a.stdout,
+            stderr: a.stderr,
+            durationMs,
+            missingOutputs: staleOutputs,
+            staleOutputs,
+            stdoutTruncated: a.stdoutTruncated,
+            stderrTruncated: a.stderrTruncated,
+            error: {
+                code: "no-output",
+                message: `${a.location.label} exited 0 but did not rewrite: ${staleOutputs.join(", ")} (each is unchanged from before the run, so it is left over from an earlier one).`,
+                hint: "WolvenKit names a packed archive after its input folder, and some commands exit 0 without writing; check that the tool's own output name matches the one the step expects.",
+            },
+        };
+    }
+    if (missingOutputs.length > 0) {
+        return {
+            tool: a.location.id,
+            command: a.command,
+            args: a.args,
+            ok: false,
+            exitCode: a.exitCode,
+            stdout: a.stdout,
+            stderr: a.stderr,
+            durationMs,
+            missingOutputs,
+            stdoutTruncated: a.stdoutTruncated,
+            stderrTruncated: a.stderrTruncated,
+            error: {
+                code: "no-output",
+                message: `${a.location.label} exited 0 but did not produce: ${missingOutputs.join(", ")}.`,
+                hint: "divine.exe in particular is known to exit 0 and write nothing when given a malformed or relative path; double-check the source/destination arguments before assuming this run's inputs were wrong.",
+            },
+        };
+    }
+    return {
+        tool: a.location.id,
+        command: a.command,
+        args: a.args,
+        ok: true,
+        exitCode: a.exitCode,
+        stdout: a.stdout,
+        stderr: a.stderr,
+        durationMs,
+        missingOutputs: [],
+        staleOutputs,
+        stdoutTruncated: a.stdoutTruncated,
+        stderrTruncated: a.stderrTruncated,
+    };
+}