@bridge4dev/runner 0.13.1 → 0.22.1

package/dist/verify.js

@@ -0,0 +1,788 @@
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { log } from './log.js';
+import { maskString } from './policy.js';
+import { evaluateRecipeCommand } from './policy.js';
+import { recipeFingerprint } from './recipe.js';
+import { StringDecoder } from 'node:string_decoder';
+import { stateDir } from './paths.js';
+import { RECIPE_DEFAULT_TIMEOUT_SEC, RECIPE_MAX_TIMEOUT_SEC, RECIPE_STEP_NAMES, } from './recipe-schema.js';
+/** Free space a run refuses to start below. Builds are not small. */
+export const VERIFY_MIN_FREE_BYTES = 2 * 1024 * 1024 * 1024;
+/** How much of a build log is worth keeping on disk. */
+const LOG_CAP_BYTES = 2 * 1024 * 1024;
+/** How much of it travels in one `verify_status` answer. */
+const LOG_CHUNK_BYTES = 64 * 1024;
+/** The tail that goes into the report frame and, from there, into the row. */
+const LOG_TAIL_BYTES = 8 * 1024;
+/** SIGTERM, then this long, then SIGKILL. */
+const KILL_GRACE_MS = 10_000;
+/** After a step's process exits, how long to wait for its output to drain. */
+const STDIO_GRACE_MS = 2_000;
+/** A health probe answers in seconds or it is not answering. */
+const HEALTH_TIMEOUT_MS = 8_000;
+const HEALTH_BODY_CAP = 64 * 1024;
+/**
+ * Everything a build is allowed to see of the runner's environment.
+ *
+ * An allowlist for the same reason the Claude adapter has one (QA-96 F12): this
+ * process holds `dbr_` runner tokens and whatever else the machine's owner
+ * exported, and a build script is a program somebody else wrote.
+ */
+const ENV_ALLOWLIST = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'LANG',
+    'LANGUAGE',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'TMPDIR',
+    'XDG_RUNTIME_DIR',
+    'XDG_DATA_HOME',
+    'XDG_CONFIG_HOME',
+    'XDG_CACHE_HOME',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+    'http_proxy',
+    'https_proxy',
+    'no_proxy',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'NODE_EXTRA_CA_CERTS',
+    'DOCKER_HOST',
+];
+function buildEnv(extra) {
+    const env = {};
+    for (const key of ENV_ALLOWLIST) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    // `TERM=dumb` and `CI=1` are how build tools are told nobody is watching:
+    // without them a progress spinner writes escape codes into the log and an
+    // interactive prompt waits for a keystroke that will never come.
+    env['TERM'] = 'dumb';
+    env['CI'] = '1';
+    env['DEVBRIDGE_VERIFY'] = '1';
+    for (const [key, value] of Object.entries(extra ?? {})) {
+        // Never let a recipe put back what the allowlist took out.
+        if (key === 'PATH' ||
+            key === 'HOME' ||
+            key.startsWith('LD_') ||
+            key.startsWith('NODE_OPTIONS')) {
+            continue;
+        }
+        env[key] = value;
+    }
+    return env;
+}
+const execFileAsync = promisify(execFile);
+/**
+ * The sha the commands are about to run against.
+ *
+ * Read HERE and not sent by the API, because only this side knows what is in
+ * the directory at the moment the build starts. Without it every run stored
+ * `commitSha: null`, and «current», «running now» and the `Verified:` trailer
+ * — all three of which compare a run's sha with the branch tip — could never
+ * be true. The evidence table would have been decorative.
+ */
+async function headShaOf(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            timeout: 10_000,
+        });
+        const sha = stdout.trim();
+        return /^[0-9a-f]{7,64}$/i.test(sha) ? sha : null;
+    }
+    catch {
+        // Not a git directory, or git is unavailable. A run without a sha still
+        // runs — it simply cannot support the words that compare shas.
+        return null;
+    }
+}
+/**
+ * Was the tree dirty when the commands started?
+ *
+ * Read here for the same reason as the sha, and it matters just as much: it is
+ * half of «current» and the whole of the clean-tree condition on the
+ * `Verified:` trailer. Neither side used to set it — the API never sent it and
+ * the runner only read what it was sent — so both guards were permanently
+ * `false`, which is to say permanently off (QA-108).
+ *
+ * `null` on error, which callers must not read as «clean».
+ */
+async function isDirty(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+            cwd,
+            timeout: 15_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return null;
+    }
+}
+/** How many finished build logs are worth keeping on somebody's machine. */
+const KEEP_VERIFY_LOGS = 20;
+/**
+ * Delete all but the newest build logs.
+ *
+ * A twenty-minute build writes megabytes, one file per run, and nothing ever
+ * removed them: the directory grew without bound on the user's own disk. This
+ * is not a hypothetical on this project — 2026-07-13 is the day a root disk
+ * filled with build cache and took `sshd` and `journald` with it, which is also
+ * why `start` refuses to begin without free space. Pruning at start, not at
+ * finish: a crashed run must not be the reason its own log survives forever,
+ * and the newest ones are the only ones anybody reads (session 15).
+ */
+function pruneVerifyLogs() {
+    try {
+        const dir = verifyDir();
+        const entries = fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith('.log'))
+            .map((name) => {
+            const full = path.join(dir, name);
+            return { full, mtime: fs.statSync(full).mtimeMs };
+        })
+            .sort((a, b) => b.mtime - a.mtime);
+        for (const stale of entries.slice(KEEP_VERIFY_LOGS)) {
+            fs.rmSync(stale.full, { force: true });
+        }
+    }
+    catch {
+        // Housekeeping must never be the reason a build refuses to start.
+    }
+}
+/**
+ * How many bytes of `buffer` end on a complete UTF-8 character.
+ *
+ * UTF-8 is self-synchronising: a lead byte announces its length, and every
+ * continuation byte is `10xxxxxx`. So the only work is to walk back from the
+ * end over at most three bytes and drop a sequence that is not finished yet.
+ */
+export function completeUtf8Length(buffer) {
+    for (let back = 1; back <= 3 && back <= buffer.length; back += 1) {
+        const byte = buffer[buffer.length - back] ?? 0;
+        if ((byte & 0b1100_0000) === 0b1000_0000)
+            continue; // continuation — keep walking
+        const needed = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+        return needed > back ? buffer.length - back : buffer.length;
+    }
+    return buffer.length;
+}
+/** Offset of the first byte that STARTS a character — for a slice cut anywhere. */
+export function firstUtf8Start(buffer) {
+    let start = 0;
+    while (start < buffer.length && start < 3) {
+        if (((buffer[start] ?? 0) & 0b1100_0000) !== 0b1000_0000)
+            break;
+        start += 1;
+    }
+    return start;
+}
+function verifyDir() {
+    return path.join(stateDir(), 'verify');
+}
+/**
+ * Free bytes on the filesystem the build would write to.
+ *
+ * `null` when the platform cannot answer — which is treated as «go ahead»
+ * rather than «refuse», because refusing every run on a system without statfs
+ * would be a worse failure than the one this guards against.
+ */
+export function freeBytesFor(target) {
+    try {
+        const stat = fs.statfsSync(target);
+        return Number(stat.bavail) * Number(stat.bsize);
+    }
+    catch {
+        return null;
+    }
+}
+export class VerifyRunner {
+    opts;
+    active = null;
+    /** Finished runs stay readable until the next one starts. */
+    last = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get enabled() {
+        return this.opts.enabled;
+    }
+    get busy() {
+        return this.active !== null && this.active.status === 'RUNNING';
+    }
+    /** The run currently holding the machine, if any — for a truthful refusal. */
+    get activeRunId() {
+        return this.busy ? (this.active?.runId ?? null) : null;
+    }
+    /** What kind of run is holding it — `preview_stop` only owns its own. */
+    get activeTarget() {
+        return this.busy ? (this.active?.target ?? null) : null;
+    }
+    start(input) {
+        if (!this.opts.enabled) {
+            return {
+                started: false,
+                error: 'Verification is switched off on this machine (`[verify] enabled = false`)',
+            };
+        }
+        if (this.busy) {
+            return {
+                started: false,
+                error: `A verification is already running on this machine (${this.active?.runId})`,
+            };
+        }
+        // The approval is of specific commands. A recipe that no longer hashes to
+        // what was approved is not the approved recipe.
+        const actual = recipeFingerprint(input.recipe);
+        if (actual !== input.recipeSha) {
+            return {
+                started: false,
+                error: 'The approved recipe changed — approve it again before verifying',
+            };
+        }
+        if (!fs.existsSync(input.cwd)) {
+            return { started: false, error: `The working directory ${input.cwd} does not exist` };
+        }
+        const commands = this.resolveCommands(input);
+        if ('error' in commands)
+            return { started: false, error: commands.error };
+        if (commands.list.length === 0) {
+            return {
+                started: false,
+                error: input.preview
+                    ? 'This project has no `preview` command in its recipe'
+                    : 'This project has no build steps in its recipe — there is nothing to run',
+            };
+        }
+        const free = freeBytesFor(input.cwd);
+        if (free !== null && free < VERIFY_MIN_FREE_BYTES) {
+            return {
+                started: false,
+                error: `Only ${Math.round(free / 1024 / 1024)} MB free on this disk — a build needs at least ${Math.round(VERIFY_MIN_FREE_BYTES / 1024 / 1024)} MB. Free some space and try again.`,
+            };
+        }
+        fs.mkdirSync(verifyDir(), { recursive: true, mode: 0o700 });
+        pruneVerifyLogs();
+        const logPath = path.join(verifyDir(), `${sanitizeRunId(input.runId)}.log`);
+        try {
+            fs.writeFileSync(logPath, '', { mode: 0o600 });
+        }
+        catch (error) {
+            return { started: false, error: `Could not open a log file: ${String(error)}` };
+        }
+        const run = {
+            runId: input.runId,
+            target: input.target,
+            recipe: input.recipe,
+            recipeSha: input.recipeSha,
+            cwd: input.cwd,
+            steps: commands.list.map((entry) => entry.name),
+            completed: [],
+            currentStep: null,
+            failedStep: null,
+            exitCode: null,
+            status: 'RUNNING',
+            startedAt: new Date(this.now()).toISOString(),
+            finishedAt: null,
+            logPath,
+            logBytes: 0,
+            child: null,
+            cancelled: false,
+            branch: input.branch,
+            commitSha: input.commitSha,
+            dirty: input.dirty,
+            health: null,
+            previewUrl: input.preview ? (input.recipe.preview?.url ?? null) : null,
+        };
+        this.active = run;
+        this.last = run;
+        void this.execute(run, commands.list);
+        return { started: true };
+    }
+    status(runId, offset = 0) {
+        const run = this.find(runId);
+        if (!run)
+            return null;
+        const from = Math.max(0, Math.trunc(offset));
+        let chunk = '';
+        let next;
+        try {
+            const size = fs.statSync(run.logPath).size;
+            if (from < size) {
+                const length = Math.min(size - from, LOG_CHUNK_BYTES);
+                const fd = fs.openSync(run.logPath, 'r');
+                let read = length;
+                try {
+                    const buffer = Buffer.alloc(length);
+                    fs.readSync(fd, buffer, 0, length, from);
+                    // Back the window off to the last COMPLETE character and let the
+                    // next poll start there. Decoding an arbitrary byte window put a
+                    // U+FFFD at every page boundary, in text the dashboard then
+                    // concatenates (session 15).
+                    read = completeUtf8Length(buffer);
+                    chunk = buffer.subarray(0, read).toString('utf8');
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                // `read` can be 0 only for a lone incomplete character at the very end
+                // of the file; advancing by nothing is right — the rest arrives next
+                // time — but never leave `next` behind `from`.
+                next = from + Math.max(read, 0);
+            }
+            else {
+                next = size;
+            }
+            return {
+                runId: run.runId,
+                status: run.status,
+                target: run.target,
+                currentStep: run.currentStep,
+                completedSteps: [...run.completed],
+                failedStep: run.failedStep,
+                exitCode: run.exitCode,
+                offset: next,
+                chunk,
+                hasMore: next < size,
+                startedAt: run.startedAt,
+                finishedAt: run.finishedAt,
+                health: run.health,
+                previewUrl: run.previewUrl,
+            };
+        }
+        catch {
+            return {
+                runId: run.runId,
+                status: run.status,
+                target: run.target,
+                currentStep: run.currentStep,
+                completedSteps: [...run.completed],
+                failedStep: run.failedStep,
+                exitCode: run.exitCode,
+                offset: from,
+                chunk: '',
+                hasMore: false,
+                startedAt: run.startedAt,
+                finishedAt: run.finishedAt,
+                health: run.health,
+                previewUrl: run.previewUrl,
+            };
+        }
+    }
+    cancel(runId) {
+        const run = this.active;
+        if (!run || run.runId !== runId)
+            return { cancelled: false, error: 'No such run is active' };
+        if (run.status !== 'RUNNING')
+            return { cancelled: false, error: 'That run has already finished' };
+        run.cancelled = true;
+        this.killGroup(run);
+        return { cancelled: true };
+    }
+    /**
+     * Stop whatever is running because the daemon is going away.
+     *
+     * The run is NOT reported as passed or failed — it is simply abandoned, and
+     * the API turns its still-RUNNING row into `LOST`. A verdict nobody observed
+     * is not a verdict.
+     */
+    shutdown() {
+        if (this.active?.status === 'RUNNING') {
+            this.active.cancelled = true;
+            this.killGroup(this.active);
+        }
+    }
+    now() {
+        return this.opts.now ? this.opts.now() : Date.now();
+    }
+    find(runId) {
+        if (this.active?.runId === runId)
+            return this.active;
+        if (this.last?.runId === runId)
+            return this.last;
+        return null;
+    }
+    /**
+     * The commands this run will execute, each one already past layer 1.
+     *
+     * Resolved BEFORE anything starts, so a recipe whose `deploy` step is refused
+     * fails immediately instead of half-way through a release.
+     */
+    resolveCommands(input) {
+        const list = [];
+        if (input.preview) {
+            const preview = input.recipe.preview;
+            if (!preview?.run)
+                return { list: [] };
+            list.push({
+                name: 'preview',
+                step: {
+                    run: preview.run,
+                    ...(preview.timeoutSec !== undefined ? { timeoutSec: preview.timeoutSec } : {}),
+                },
+            });
+        }
+        else {
+            const wanted = new Set(input.steps);
+            for (const name of RECIPE_STEP_NAMES) {
+                if (!wanted.has(name))
+                    continue;
+                const step = input.recipe.steps?.[name];
+                if (step?.run)
+                    list.push({ name, step });
+            }
+        }
+        for (const entry of list) {
+            const decision = evaluateRecipeCommand(entry.step.run);
+            if (!decision.allowed) {
+                return {
+                    error: `The \`${entry.name}\` command is refused by runner policy: ${decision.reason}`,
+                };
+            }
+        }
+        return { list };
+    }
+    async execute(run, commands) {
+        const started = this.now();
+        // What is in the directory RIGHT NOW, before anything runs. The caller may
+        // have supplied a sha, but only this side can see what is actually there.
+        run.commitSha = (await headShaOf(run.cwd)) ?? run.commitSha;
+        // A dirty tree cannot be «verified at a sha»: what ran is not what the sha
+        // describes. Unknown counts as dirty — the safe direction is the one that
+        // withholds a claim rather than the one that makes it.
+        run.dirty = (await isDirty(run.cwd)) ?? true;
+        this.append(run, `# DevBridge verification ${run.runId} (${run.target})\n`);
+        this.append(run, `# ${run.cwd}${run.commitSha ? ` @ ${run.commitSha.slice(0, 7)}` : ''}\n`);
+        try {
+            for (const { name, step } of commands) {
+                if (run.cancelled)
+                    break;
+                run.currentStep = name;
+                this.append(run, `\n$ [${name}] ${step.run}\n`);
+                const outcome = await this.runStep(run, step);
+                run.exitCode = outcome.exitCode;
+                if (!outcome.ok) {
+                    run.failedStep = name;
+                    this.append(run, outcome.timedOut
+                        ? `\n# [${name}] timed out after ${Math.round(outcome.durationMs / 1000)}s\n`
+                        : `\n# [${name}] exited with ${outcome.exitCode}\n`);
+                    break;
+                }
+                run.completed.push(name);
+            }
+            // The health probe is not a step: it answers «is the thing we just built
+            // actually the thing that is running», which no exit code can.
+            if (!run.cancelled && run.failedStep === null && run.recipe.health) {
+                run.health = await probeHealth(run.recipe.health);
+                this.append(run, `\n# health ${run.recipe.health.url} → ${run.health.status ?? 'no answer'}` +
+                    `${run.health.sha ? ` (sha ${run.health.sha})` : ''}\n`);
+            }
+        }
+        catch (error) {
+            run.failedStep = run.currentStep;
+            this.append(run, `\n# runner error: ${maskString(String(error)).slice(0, 500)}\n`);
+        }
+        run.currentStep = null;
+        run.status = run.cancelled ? 'CANCELLED' : run.failedStep === null ? 'PASSED' : 'FAILED';
+        run.finishedAt = new Date(this.now()).toISOString();
+        const durationMs = this.now() - started;
+        if (this.active === run)
+            this.active = null;
+        const report = {
+            runId: run.runId,
+            target: run.target,
+            status: run.status,
+            recipeSha: run.recipeSha,
+            branch: run.branch,
+            commitSha: run.commitSha,
+            dirty: run.dirty,
+            steps: run.steps,
+            completedSteps: [...run.completed],
+            failedStep: run.failedStep,
+            exitCode: run.exitCode,
+            durationMs,
+            logTail: this.tail(run),
+            health: run.health,
+            previewUrl: run.previewUrl,
+            startedAt: run.startedAt,
+            finishedAt: run.finishedAt,
+        };
+        try {
+            this.opts.onReport(report);
+        }
+        catch (error) {
+            log.warn('verify: could not hand over the report', { error: String(error) });
+        }
+    }
+    runStep(run, step) {
+        const timeoutSec = Math.min(step.timeoutSec ?? RECIPE_DEFAULT_TIMEOUT_SEC, RECIPE_MAX_TIMEOUT_SEC);
+        const startedAt = this.now();
+        return new Promise((resolve) => {
+            let settled = false;
+            let timedOut = false;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                run.child = null;
+                resolve({
+                    step: run.currentStep ?? '',
+                    durationMs: this.now() - startedAt,
+                    ...result,
+                    ...(timedOut ? { timedOut: true } : {}),
+                });
+            };
+            let child;
+            try {
+                // `detached` so the whole process tree gets the signal: a build script
+                // is a shell that spawns compilers, and killing only the shell leaves
+                // them running with the disk and the CPU.
+                child = spawn('/bin/sh', ['-c', step.run], {
+                    cwd: run.cwd,
+                    env: buildEnv(step.env),
+                    detached: true,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+            }
+            catch (error) {
+                this.append(run, `# could not start: ${maskString(String(error)).slice(0, 300)}\n`);
+                finish({ ok: false, exitCode: null });
+                return;
+            }
+            run.child = child;
+            // A StringDecoder per stream, not `buffer.toString('utf8')` per chunk.
+            //
+            // A pipe read ends wherever the kernel filled the buffer, which is
+            // regularly mid-character: decoding each chunk on its own replaced every
+            // straddling character with U+FFFD, PERMANENTLY, because the mangled
+            // text is what gets written to the log. This project's own tooling
+            // prints Russian throughout, so it is the common case rather than an
+            // exotic one (session 15). A decoder holds the incomplete bytes until
+            // the next chunk completes them.
+            const outDecoder = new StringDecoder('utf8');
+            const errDecoder = new StringDecoder('utf8');
+            child.stdout?.on('data', (buffer) => this.append(run, outDecoder.write(buffer)));
+            child.stderr?.on('data', (buffer) => this.append(run, errDecoder.write(buffer)));
+            const timer = setTimeout(() => {
+                timedOut = true;
+                this.killGroup(run);
+            }, timeoutSec * 1000);
+            timer.unref();
+            child.on('error', (error) => {
+                this.append(run, `# ${maskString(String(error)).slice(0, 300)}\n`);
+                finish({ ok: false, exitCode: null });
+            });
+            // `exit` and not `close`: a step that backgrounds a daemon (`… &`, and
+            // every `docker compose up -d` that leaves a log follower behind) hands
+            // the inherited stdout to a child that never ends, and `close` waits for
+            // EOF on it. That wedges the single verify slot on the whole machine
+            // until the step timeout. `close` still gets a short grace afterwards so
+            // the last lines of output are not lost.
+            let exited = false;
+            child.on('exit', (code, signal) => {
+                exited = true;
+                const settle = () => finish({ ok: !timedOut && !run.cancelled && code === 0 && !signal, exitCode: code });
+                const grace = setTimeout(settle, STDIO_GRACE_MS);
+                grace.unref();
+                child.once('close', () => {
+                    clearTimeout(grace);
+                    settle();
+                });
+            });
+            child.on('close', (code, signal) => {
+                if (exited)
+                    return;
+                finish({ ok: !timedOut && !run.cancelled && code === 0 && !signal, exitCode: code });
+            });
+        });
+    }
+    /** SIGTERM to the whole group, SIGKILL to whatever is still there after. */
+    killGroup(run) {
+        const child = run.child;
+        if (!child?.pid)
+            return;
+        const pid = child.pid;
+        const signal = (name) => {
+            try {
+                process.kill(-pid, name);
+            }
+            catch {
+                try {
+                    child.kill(name);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        };
+        signal('SIGTERM');
+        const hard = setTimeout(() => signal('SIGKILL'), KILL_GRACE_MS);
+        hard.unref();
+        child.once('close', () => clearTimeout(hard));
+    }
+    /**
+     * Append to the log, masked, and stop at the cap.
+     *
+     * Masking happens per write rather than at the end, because the end may never
+     * come — a run the user cancels still leaves its log readable.
+     */
+    append(run, text) {
+        if (run.logBytes >= LOG_CAP_BYTES)
+            return;
+        const masked = maskString(text);
+        const room = LOG_CAP_BYTES - run.logBytes;
+        const slice = Buffer.byteLength(masked) > room
+            ? `${masked.slice(0, room)}\n…[log truncated at ${Math.round(LOG_CAP_BYTES / 1024)} KB]\n`
+            : masked;
+        try {
+            fs.appendFileSync(run.logPath, slice);
+            run.logBytes += Buffer.byteLength(slice);
+        }
+        catch {
+            // A log we cannot write must not fail the build it is describing.
+            run.logBytes = LOG_CAP_BYTES;
+        }
+    }
+    tail(run) {
+        try {
+            const size = fs.statSync(run.logPath).size;
+            const from = Math.max(0, size - LOG_TAIL_BYTES);
+            const fd = fs.openSync(run.logPath, 'r');
+            try {
+                const buffer = Buffer.alloc(size - from);
+                fs.readSync(fd, buffer, 0, size - from, from);
+                // The START of the tail is the arbitrary cut here, so skip any
+                // continuation bytes the slice began in the middle of. This text is
+                // stored in `logTail` and read long after the run.
+                return buffer.subarray(firstUtf8Start(buffer)).toString('utf8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            return '';
+        }
+    }
+}
+/**
+ * One command, run once, with no log and no report — the preview `stop`.
+ *
+ * Same working directory and same environment allowlist as a step; it just has
+ * nowhere to report to, because stopping a preview is bookkeeping rather than a
+ * verdict. Layer 1 has already been consulted by the caller (this is the one
+ * command allowed to take a compose project down, and only its own).
+ */
+export function runOneOffCommand(command, cwd, timeoutSec = 120) {
+    return new Promise((resolve) => {
+        let output = '';
+        let settled = false;
+        const finish = (ok, exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ ok, exitCode, output: maskString(output).slice(0, 4_000) });
+        };
+        let child;
+        try {
+            child = spawn('/bin/sh', ['-c', command], {
+                cwd,
+                env: buildEnv(undefined),
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            resolve({ ok: false, exitCode: null, output: maskString(String(error)).slice(0, 500) });
+            return;
+        }
+        const onData = (buffer) => {
+            if (output.length < 16_000)
+                output += buffer.toString('utf8');
+        };
+        child.stdout?.on('data', onData);
+        child.stderr?.on('data', onData);
+        const timer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        }, timeoutSec * 1000);
+        timer.unref();
+        child.on('error', () => finish(false, null));
+        child.on('close', (code) => finish(code === 0, code));
+    });
+}
+/** A run id becomes a file name — keep it to something that cannot escape. */
+function sanitizeRunId(runId) {
+    return runId.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 64) || 'run';
+}
+/**
+ * Ask the running application what it is.
+ *
+ * Two facts, and they are different: that it answered at all, and which build
+ * it says it is. Only the second can support «running the version we verified»,
+ * and a project that does not expose a sha simply never gets that sentence.
+ */
+export async function probeHealth(health) {
+    try {
+        const response = await fetch(health.url, {
+            signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+            redirect: 'manual',
+            headers: { accept: 'application/json' },
+        });
+        const ok = response.status >= 200 && response.status < 300;
+        let sha = null;
+        if (health.shaPath) {
+            const text = (await response.text()).slice(0, HEALTH_BODY_CAP);
+            try {
+                sha = extractSha(JSON.parse(text), health.shaPath);
+            }
+            catch {
+                sha = null;
+            }
+        }
+        return { ok, status: response.status, sha };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: null,
+            sha: null,
+            detail: maskString(String(error instanceof Error ? error.message : error)).slice(0, 300),
+        };
+    }
+}
+/** `data.build.sha` → the string at that path, if it is a plausible sha. */
+export function extractSha(body, dottedPath) {
+    let cursor = body;
+    for (const key of dottedPath.split('.')) {
+        if (!cursor || typeof cursor !== 'object')
+            return null;
+        cursor = cursor[key];
+    }
+    if (typeof cursor !== 'string')
+        return null;
+    const value = cursor.trim();
+    return /^[0-9a-f]{7,64}$/i.test(value) ? value : null;
+}
+//# sourceMappingURL=verify.js.map