@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/executor/required-verification.js

@@ -0,0 +1,313 @@
+import { createProcessTerminationController, runProcessWithTimeout } from "./process.js";
+/** Grace between SIGTERM and SIGKILL for an interrupted check. */
+export const CHECK_TERM_GRACE_MS = 5_000;
+/** Bound on waiting for a check's pipes to reach EOF after it exits. */
+export const CHECK_DRAIN_BOUND_MS = 2_000;
+/** Bound on each git read of the final artifact. */
+export const ARTIFACT_GIT_TIMEOUT_MS = 30_000;
+/** Local-only output tail kept per check for the executor's own log. */
+export const CHECK_OUTPUT_TAIL_CHARS = 4_000;
+/** How often a running check re-asks whether the executor still owns the claim. */
+export const OWNERSHIP_POLL_MS = 1_000;
+// ---------------------------------------------------------------------------
+// Canonical JSON (mirror of the server's `canonical_json`)
+// ---------------------------------------------------------------------------
+/**
+ * Sorted keys, no whitespace, non-ASCII kept as-is. Byte-identical to Python's
+ * `json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`
+ * for the values a declaration holds (strings, integers, null, lists, objects
+ * with ASCII keys), which is what lets the executor recompute every digest.
+ */
+export function canonicalJson(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function tail(text) {
+    return text.length <= CHECK_OUTPUT_TAIL_CHARS ? text : "…" + text.slice(-CHECK_OUTPUT_TAIL_CHARS);
+}
+/**
+ * Run declared commands in declaration order.
+ *
+ * Every declared command gets exactly one fact, in order: a launched command
+ * reports how it ended, and one that was never launched reports `not_run` with
+ * the reason. Each launch is capped at `min(declared timeout, deadline - now)`;
+ * a command with no time left is `not_run` / `reservation_exhausted`, never
+ * given a fresh budget.
+ */
+export async function runRequiredVerificationCommands(input) {
+    const policy = input.onInterruption ?? "stop";
+    const facts = [];
+    let stopReason = null;
+    const notRun = (command, reason) => ({
+        identity: command.identity,
+        position: command.position,
+        name: command.name,
+        outcome: "not_run",
+        reason,
+        durationMs: 0,
+        output: "",
+    });
+    for (const command of input.commands) {
+        if (stopReason !== null) {
+            facts.push(notRun(command, stopReason));
+            continue;
+        }
+        if (input.signal.aborted) {
+            stopReason = "executor_cancelled";
+            facts.push(notRun(command, stopReason));
+            continue;
+        }
+        if (input.ownershipHeld && !input.ownershipHeld()) {
+            stopReason = "ownership_lost";
+            facts.push(notRun(command, stopReason));
+            continue;
+        }
+        const declaredMs = command.timeoutSeconds * 1000;
+        const remainingMs = input.deadlineAtMs - input.now();
+        const budgetMs = Math.min(declaredMs, remainingMs);
+        if (budgetMs <= 0) {
+            facts.push(notRun(command, "reservation_exhausted"));
+            if (policy === "stop")
+                stopReason = "reservation_exhausted";
+            continue;
+        }
+        const started = input.now();
+        let launched;
+        try {
+            launched = await input.launch({
+                argv: command.argv,
+                cwd: input.worktreePath,
+                env: input.env,
+                timeoutMs: budgetMs,
+                signal: input.signal,
+            });
+        }
+        catch {
+            launched = { outcome: { kind: "launch_error" } };
+        }
+        const durationMs = Math.max(0, input.now() - started);
+        const output = tail(launched.output ?? "");
+        let outcome;
+        let reason = null;
+        switch (launched.outcome.kind) {
+            case "exited":
+                outcome = launched.outcome.exitCode === 0 ? "exited_zero" : "exited_nonzero";
+                break;
+            case "timed_out":
+                outcome = "timed_out";
+                // The declared maximum was the binding limit, or the reservation was.
+                reason = budgetMs < declaredMs ? "reservation_exhausted" : "declared_timeout";
+                break;
+            case "cancelled":
+                outcome = "cancelled";
+                reason = input.ownershipHeld && !input.ownershipHeld() ? "ownership_lost" : "executor_cancelled";
+                break;
+            default:
+                outcome = "launch_error";
+                reason = "spawn_failed";
+        }
+        facts.push({
+            identity: command.identity,
+            position: command.position,
+            name: command.name,
+            outcome,
+            reason,
+            durationMs,
+            output,
+        });
+        const interrupted = outcome === "timed_out" || outcome === "cancelled";
+        if (interrupted && input.onInterrupted) {
+            try {
+                await input.onInterrupted();
+            }
+            catch {
+                /* cleanup is re-verified by the caller's own sweep */
+            }
+        }
+        if (policy === "stop" && (interrupted || outcome === "launch_error")) {
+            // A cancellation keeps its own reason for the commands it prevented.
+            stopReason =
+                reason === "ownership_lost" || reason === "executor_cancelled" ? reason : "stopped_after_interruption";
+        }
+    }
+    return { facts, stopReason };
+}
+/** The server-bound view of one fact: identity, closed tokens and duration only. */
+export function toCompletionCheckFact(fact) {
+    return {
+        identity: fact.identity,
+        position: fact.position,
+        outcome: fact.outcome,
+        reason: fact.reason,
+        duration_ms: Math.min(Math.max(0, Math.floor(fact.durationMs)), 2 * 60 * 60 * 1000),
+    };
+}
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+/**
+ * Read full HEAD and the tracked tree/index state. Untracked files are not
+ * read: the guarantee covers what a commit would carry, not every file.
+ */
+export async function observeFinalArtifact(runCommand, worktreePath) {
+    let head = null;
+    let trackedStatus = null;
+    try {
+        const r = await runCommand("git", ["rev-parse", "--verify", "HEAD"], {
+            cwd: worktreePath,
+            timeoutMs: ARTIFACT_GIT_TIMEOUT_MS,
+        });
+        const value = r.stdout.trim();
+        if (r.exitCode === 0 && FULL_SHA_RE.test(value))
+            head = value;
+    }
+    catch {
+        head = null;
+    }
+    try {
+        const r = await runCommand("git", ["status", "--porcelain=v1", "--untracked-files=no"], {
+            cwd: worktreePath,
+            timeoutMs: ARTIFACT_GIT_TIMEOUT_MS,
+        });
+        if (r.exitCode === 0)
+            trackedStatus = r.stdout.trim();
+    }
+    catch {
+        trackedStatus = null;
+    }
+    return { head, trackedStatus };
+}
+/** Whether the pre-check observation is a certifiable starting point, and why not. */
+export function preCheckArtifactState(before, expectedHead) {
+    if (before.head === null || before.trackedStatus === null)
+        return "head_unreadable";
+    if (expectedHead !== null && before.head !== expectedHead)
+        return "head_moved";
+    if (before.trackedStatus !== "")
+        return "dirty_before";
+    return null;
+}
+/** The artifact verdict after the checks and their descendant cleanup. */
+export function compareFinalArtifact(before, after) {
+    if (after.head === null || after.trackedStatus === null)
+        return "unobservable_after";
+    if (after.head !== before.head)
+        return "head_moved";
+    if (after.trackedStatus !== before.trackedStatus)
+        return "tracked_changed";
+    return "stable";
+}
+// ---------------------------------------------------------------------------
+// The covered lane's launcher and runner
+// ---------------------------------------------------------------------------
+/**
+ * A launch seam built on the executor's one spawn boundary.
+ *
+ * argv through `spawnProcess` (never a shell), the caller's explicit
+ * environment, a termination controller registered with the executor's
+ * live-process registry for the command's lifetime, a timeout the process
+ * supervisor enforces and reports, and cancellation through the same
+ * controller. Output is kept as a bounded local tail only.
+ */
+export function createSupervisedCommandLauncher(input) {
+    const { deps } = input;
+    return async (request) => {
+        const [file, ...args] = request.argv;
+        if (file === undefined)
+            return { outcome: { kind: "launch_error" } };
+        if (request.signal.aborted)
+            return { outcome: { kind: "cancelled" } };
+        let proc;
+        try {
+            proc = deps.spawnProcess(file, args, { cwd: request.cwd, env: request.env });
+        }
+        catch {
+            return { outcome: { kind: "launch_error" } };
+        }
+        const controller = createProcessTerminationController(proc, deps, CHECK_TERM_GRACE_MS);
+        const deregister = input.registerLive?.(controller);
+        let cancelled = false;
+        const onAbort = () => {
+            cancelled = true;
+            controller.requestTermination();
+        };
+        request.signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            // Whole seconds, rounded DOWN so the cap never exceeds the reservation.
+            const timeoutSeconds = Math.max(1, Math.floor(request.timeoutMs / 1000));
+            const result = await runProcessWithTimeout(proc, timeoutSeconds, deps, {
+                termGraceMs: CHECK_TERM_GRACE_MS,
+                terminationController: controller,
+                drainDeadlineMs: CHECK_DRAIN_BOUND_MS,
+            });
+            const output = `${result.stdoutExcerpt}\n${result.stderrExcerpt}`;
+            if (cancelled)
+                return { outcome: { kind: "cancelled" }, output };
+            if (result.classification === "timeout")
+                return { outcome: { kind: "timed_out" }, output };
+            if (result.exitUnconfirmed || result.exitCode === null) {
+                // Killed or vanished without an exit code we can trust: not an exit.
+                return { outcome: { kind: "cancelled" }, output };
+            }
+            return { outcome: { kind: "exited", exitCode: result.exitCode }, output };
+        }
+        finally {
+            request.signal.removeEventListener("abort", onAbort);
+            controller.dispose();
+            deregister?.();
+        }
+    };
+}
+/**
+ * The covered lane's {@link DeclaredCheckRunner}: every declared command, in
+ * order, from the prepared worktree root, stopping on an interruption.
+ *
+ * The runner reports facts; the job runner owns the artifact observations
+ * around it, the post-check cleanup sweep and the verdict.
+ */
+export function createRequiredVerificationRunner(input) {
+    return {
+        async run(request) {
+            const result = await runRequiredVerificationCommands({
+                commands: request.checks.map(toRequiredCommand),
+                worktreePath: request.worktreePath,
+                env: request.env,
+                launch: input.launch,
+                now: input.now,
+                deadlineAtMs: request.deadlineAtMs,
+                signal: request.signal,
+                ...(request.ownershipHeld ? { ownershipHeld: request.ownershipHeld } : {}),
+                onInterruption: "stop",
+            });
+            if (input.log) {
+                // Names and closed tokens only: no argv, no output, no path.
+                for (const fact of result.facts) {
+                    input.log(`[executor] declared check ${fact.position} (${fact.name.slice(0, 60)}): ${fact.outcome}${fact.reason ? ` (${fact.reason})` : ""}`);
+                }
+            }
+            const outcomes = result.facts.map((f) => f.outcome);
+            const verification = outcomes.length > 0 && outcomes.every((o) => o === "exited_zero")
+                ? "passed"
+                : outcomes.every((o) => o === "exited_zero" || o === "exited_nonzero")
+                    ? "failed"
+                    : "incomplete";
+            return { verification, facts: result.facts };
+        },
+    };
+}
+function toRequiredCommand(check) {
+    return {
+        identity: check.identity,
+        position: check.position,
+        name: check.name,
+        argv: check.argv,
+        timeoutSeconds: check.timeoutSeconds,
+    };
+}