@bridge4dev/runner 0.11.0 → 0.22.1

package/dist/verify-queue.d.ts

@@ -0,0 +1,17 @@
+import type { VerifyReport } from './verify.js';
+export declare class VerifyReportQueue {
+    private readonly file;
+    private entries;
+    constructor(dir?: string);
+    private load;
+    private persist;
+    /** Record a verdict. Re-queuing the same run replaces it rather than doubling. */
+    add(report: VerifyReport, now?: number): void;
+    /** Verdicts still waiting for an ack, oldest first. */
+    pending(now?: number): VerifyReport[];
+    markAttempted(runId: string): void;
+    /** The API stored it — stop redelivering. */
+    ack(runId: string): boolean;
+    get size(): number;
+}
+//# sourceMappingURL=verify-queue.d.ts.map

package/dist/verify-queue.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from './paths.js';
+/**
+ * Verdicts that have not been acknowledged yet (session 14).
+ *
+ * A build runs for minutes; a relayed command lives for seconds. So the verdict
+ * does not travel as a command answer — it is its own frame, and this queue is
+ * what makes that frame safe to lose. Three things can eat it: a closed browser
+ * tab, a runner that reconnects mid-build, and an API deployed BEFORE this
+ * release, which drops a frame type it has never heard of without a word.
+ *
+ * The last one is the reason for the acknowledgement rather than fire-and-
+ * forget: on an older API the report is simply never acked, stays here, and is
+ * delivered when the API catches up. Risk 7 of the session plan, and the one
+ * that would rot unnoticed without a test.
+ */
+/** More than this and the oldest goes — a queue is not an archive. */
+const MAX_QUEUED = 50;
+/** A verdict nobody could deliver in a week is not going to be delivered. */
+const MAX_AGE_MS = 7 * 24 * 3_600_000;
+export class VerifyReportQueue {
+    file;
+    entries = [];
+    constructor(dir = path.join(stateDir(), 'verify')) {
+        this.file = path.join(dir, 'reports.ndjson');
+        this.load(dir);
+    }
+    load(dir) {
+        try {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            const raw = fs.readFileSync(this.file, 'utf8');
+            for (const line of raw.split('\n')) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (parsed?.report?.runId)
+                        this.entries.push(parsed);
+                }
+                catch {
+                    // A torn tail write after a crash — the rest of the file is still good.
+                }
+            }
+        }
+        catch {
+            // No queue yet, or an unreadable state dir. Neither is fatal.
+        }
+    }
+    persist() {
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+            const body = this.entries.map((entry) => JSON.stringify(entry)).join('\n');
+            const tmp = `${this.file}.${process.pid}.tmp`;
+            fs.writeFileSync(tmp, body ? `${body}\n` : '', { mode: 0o600 });
+            fs.renameSync(tmp, this.file);
+        }
+        catch {
+            // Losing the file costs redelivery, never correctness: the API is the
+            // one that decides what a run's final status is.
+        }
+    }
+    /** Record a verdict. Re-queuing the same run replaces it rather than doubling. */
+    add(report, now = Date.now()) {
+        this.entries = this.entries.filter((entry) => entry.report.runId !== report.runId);
+        this.entries.push({ report, queuedAt: now, attempts: 0 });
+        if (this.entries.length > MAX_QUEUED) {
+            this.entries = this.entries.slice(this.entries.length - MAX_QUEUED);
+        }
+        this.persist();
+    }
+    /** Verdicts still waiting for an ack, oldest first. */
+    pending(now = Date.now()) {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((entry) => now - entry.queuedAt < MAX_AGE_MS);
+        if (this.entries.length !== before)
+            this.persist();
+        return this.entries.map((entry) => entry.report);
+    }
+    markAttempted(runId) {
+        const entry = this.entries.find((item) => item.report.runId === runId);
+        if (!entry)
+            return;
+        entry.attempts += 1;
+        this.persist();
+    }
+    /** The API stored it — stop redelivering. */
+    ack(runId) {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((entry) => entry.report.runId !== runId);
+        if (this.entries.length === before)
+            return false;
+        this.persist();
+        return true;
+    }
+    get size() {
+        return this.entries.length;
+    }
+}
+//# sourceMappingURL=verify-queue.js.map

package/dist/verify.d.ts

@@ -0,0 +1,203 @@
+import { type ProjectRecipe, type RecipeStepName } from './recipe-schema.js';
+/**
+ * Running an approved project recipe (session 14).
+ *
+ * This is the first thing DevBridge executes on a user's machine that is not an
+ * agent, so every constraint is here and none of them is optional:
+ *
+ *  - **Only an approved recipe.** The caller sends the fingerprint of the copy a
+ *    human approved; a run whose recipe hashes differently is refused. An
+ *    approval is an approval of specific commands.
+ *  - **Layer 1 still applies.** Every command goes through the same denylist as
+ *    the agent's Bash tool. An approved recipe does not ASK — there is nobody to
+ *    ask during a twenty-minute build — but it cannot get past a refusal.
+ *  - **We choose the working directory**, and the command cannot change it: it
+ *    is passed as `cwd`, never interpolated.
+ *  - **The environment is an allowlist.** The runner's own token lives in this
+ *    process's environment and must not reach a build script.
+ *  - **One run per machine.** A half-hour build next to three agent sessions on
+ *    a small VPS is the resource story; one at a time is the answer.
+ *  - **Free disk is checked before anything starts** — 2026-07-13 is the day
+ *    this machine's root filled up and took sshd with it.
+ *  - **The owner has a veto**: `[verify] enabled = false` in the runner's own
+ *    root-owned config, and the capability is not announced at all.
+ */
+export type VerifyTarget = 'BASE' | 'SESSION' | 'PREVIEW';
+export type VerifyStatus = 'RUNNING' | 'PASSED' | 'FAILED' | 'CANCELLED';
+/** Free space a run refuses to start below. Builds are not small. */
+export declare const VERIFY_MIN_FREE_BYTES: number;
+export interface VerifyStepResult {
+    step: string;
+    ok: boolean;
+    exitCode: number | null;
+    durationMs: number;
+    /** The step ran out of its own budget rather than failing. */
+    timedOut?: boolean;
+}
+export interface VerifyHealthResult {
+    ok: boolean;
+    /** HTTP status, or null when the request never completed. */
+    status: number | null;
+    /** The sha the running build reported, when `health.shaPath` said where. */
+    sha: string | null;
+    detail?: string;
+}
+/** The verdict, as it travels to the API and lands in `dev_verify_runs`. */
+export interface VerifyReport {
+    runId: string;
+    target: VerifyTarget;
+    status: Exclude<VerifyStatus, 'RUNNING'>;
+    recipeSha: string;
+    branch: string | null;
+    commitSha: string | null;
+    dirty: boolean;
+    steps: string[];
+    completedSteps: string[];
+    failedStep: string | null;
+    exitCode: number | null;
+    durationMs: number;
+    logTail: string;
+    health: VerifyHealthResult | null;
+    previewUrl: string | null;
+    startedAt: string;
+    finishedAt: string;
+}
+export interface VerifyStatusResult {
+    runId: string;
+    status: VerifyStatus;
+    target: VerifyTarget;
+    currentStep: string | null;
+    completedSteps: string[];
+    failedStep: string | null;
+    exitCode: number | null;
+    /** Byte offset the caller should ask from next time. */
+    offset: number;
+    chunk: string;
+    /** More log is already on disk than this answer carried. */
+    hasMore: boolean;
+    startedAt: string;
+    finishedAt: string | null;
+    health: VerifyHealthResult | null;
+    previewUrl: string | null;
+}
+export interface VerifyStartInput {
+    /** Issued by the API — it is the primary key of the row this run reports to. */
+    runId: string;
+    target: VerifyTarget;
+    /** The approved recipe, and the fingerprint it must still hash to. */
+    recipe: ProjectRecipe;
+    recipeSha: string;
+    /** Where the commands run. Ours to choose; a command cannot change it. */
+    cwd: string;
+    /** Which steps to run, in recipe order. `deploy` only when asked for. */
+    steps: RecipeStepName[];
+    branch: string | null;
+    commitSha: string | null;
+    dirty: boolean;
+    /** PREVIEW runs `preview.run` instead of the step list. */
+    preview?: boolean;
+}
+/**
+ * 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 declare function completeUtf8Length(buffer: Buffer): number;
+/** Offset of the first byte that STARTS a character — for a slice cut anywhere. */
+export declare function firstUtf8Start(buffer: Buffer): number;
+/**
+ * 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 declare function freeBytesFor(target: string): number | null;
+export interface VerifyRunnerOptions {
+    /** `[verify] enabled = false` in the runner's own config is a hard veto. */
+    enabled: boolean;
+    /** Called with each finished verdict, for delivery to the API. */
+    onReport: (report: VerifyReport) => void;
+    /** Injected in tests. */
+    now?: () => number;
+}
+export declare class VerifyRunner {
+    private readonly opts;
+    private active;
+    /** Finished runs stay readable until the next one starts. */
+    private last;
+    constructor(opts: VerifyRunnerOptions);
+    get enabled(): boolean;
+    get busy(): boolean;
+    /** The run currently holding the machine, if any — for a truthful refusal. */
+    get activeRunId(): string | null;
+    /** What kind of run is holding it — `preview_stop` only owns its own. */
+    get activeTarget(): VerifyTarget | null;
+    start(input: VerifyStartInput): {
+        started: boolean;
+        error?: string;
+    };
+    status(runId: string, offset?: number): VerifyStatusResult | null;
+    cancel(runId: string): {
+        cancelled: boolean;
+        error?: string;
+    };
+    /**
+     * 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(): void;
+    private now;
+    private find;
+    /**
+     * 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.
+     */
+    private resolveCommands;
+    private execute;
+    private runStep;
+    /** SIGTERM to the whole group, SIGKILL to whatever is still there after. */
+    private killGroup;
+    /**
+     * 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.
+     */
+    private append;
+    private tail;
+}
+/**
+ * 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 declare function runOneOffCommand(command: string, cwd: string, timeoutSec?: number): Promise<{
+    ok: boolean;
+    exitCode: number | null;
+    output: string;
+}>;
+/**
+ * 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 declare function probeHealth(health: {
+    url: string;
+    shaPath?: string;
+}): Promise<VerifyHealthResult>;
+/** `data.build.sha` → the string at that path, if it is a plausible sha. */
+export declare function extractSha(body: unknown, dottedPath: string): string | null;
+//# sourceMappingURL=verify.d.ts.map