javi-forge 1.16.0 → 1.18.0

package/dist/commands/ci.js

@@ -316,6 +316,18 @@ function describeRunners(resolved) {
 }
 export async function runCI(options, onStep, onGateOutcome) {
     const { projectDir = process.cwd(), mode = "full", noDocker = false, noGhagga = false, noSecurity = false, timeout = 600, } = options;
+    // ── Run-scoped Docker availability (lazy-memoized) ─────────────────────────
+    // Computed at most ONCE per run and only when an image gate needs it. The
+    // full/quick prologue below assigns its own `isDockerAvailable()` result back
+    // into this cache so `runGates` never re-probes; the gates-only path leaves it
+    // undefined until an image gate lazily triggers the probe (a native-only
+    // gates-only repo never touches Docker — behaves exactly as before slice 3).
+    let dockerAvailableCache;
+    const dockerAvailable = async () => (dockerAvailableCache ??= await isDockerAvailable());
+    const dockerGate = {
+        noDocker,
+        isAvailable: dockerAvailable,
+    };
     // ── Resolve runners (once — nothing downstream re-detects) ─────────────────
     const stepDetect = "detect";
     report(onStep, stepDetect, "Detecting stack", "running");
@@ -343,7 +355,7 @@ export async function runCI(options, onStep, onGateOutcome) {
             report(onStep, mode, `${mode} mode`, "error", detail);
             throw new Error(`no runners resolved — ${mode} mode requires at least one runner`);
         }
-        await runGates(resolved.gates, projectDir, onStep, onGateOutcome);
+        await runGates(resolved.gates, projectDir, onStep, dockerGate, onGateOutcome);
         return;
     }
     // Legacy single-runner view for the zero-config auto path. Keeping this
@@ -409,6 +421,9 @@ export async function runCI(options, onStep, onGateOutcome) {
         const stepDocker = "docker-check";
         report(onStep, stepDocker, "Checking Docker", "running");
         const dockerOk = await isDockerAvailable();
+        // Reuse this result for the gate fail-closed check — `runGates` must not
+        // run a second `docker info` (memoization seam).
+        dockerAvailableCache = dockerOk;
         if (!dockerOk) {
             report(onStep, stepDocker, "Docker not available", "error", "Start Docker or use --no-docker");
             throw new Error("Docker is not available");
@@ -515,7 +530,7 @@ export async function runCI(options, onStep, onGateOutcome) {
     // already `full` or `quick` here; the guard makes the contract explicit.
     // `runGates` no-ops on an empty gate list (a v1 repo carries none).
     if (mode === "full" || mode === "quick") {
-        await runGates(resolved.gates, projectDir, onStep, onGateOutcome);
+        await runGates(resolved.gates, projectDir, onStep, dockerGate, onGateOutcome);
     }
 }
 // =============================================================================
@@ -900,7 +915,48 @@ const BASELINE_ENV = "JAVI_FORGE_BASELINE";
  * `onOutcome` (optional) receives each gate's structured result for the headless
  * JSON run path.
  */
-async function runGates(gates, projectDir, onStep, onOutcome) {
+/**
+ * Route a single gate command to its execution path and normalize the result to
+ * the EXACT `GateRunResult` shape the collector consumes, so the JSON/reason
+ * semantics are byte-identical for native and containerized gates.
+ *
+ *   - `gate.image === undefined` → `runGateNative` (UNCHANGED), fed the full host
+ *     env MAP (`nativeEnv`). A spawn env map never lands in argv, so the host env
+ *     is safe there.
+ *   - `gate.image !== undefined` → `runInContainer`, fed ONLY `containerEnv` — the
+ *     EXPLICIT ALLOWLIST (`CI` + injected JAVI_FORGE_* + gate.env), NEVER
+ *     `process.env` (JDB-001: no host secret in the `-e` argv / `ps aux`).
+ *
+ * The container's `timedOut` flag is normalized to `GATE_TIMEOUT_EXIT_CODE` (124)
+ * HERE — the one place gate semantics live — so `docker.ts` stays gate-agnostic
+ * and the collector's existing `timeoutReason` branch fires identically.
+ *
+ * NOTE: fail-closed (image gate + no Docker → refuse) is slice 3. In slice 2 an
+ * image gate always routes to the container when reached.
+ */
+async function runGateCommand(gate, cmd, projectDir, nativeEnv, containerEnv) {
+    if (gate.image === undefined) {
+        return await runGateNative(cmd, projectDir, nativeEnv, gate.timeout);
+    }
+    const result = await runInContainer({
+        projectDir,
+        image: gate.image,
+        // Gates run at the mount root (native gates run at the repo root).
+        command: `cd /home/runner/work && ${cmd}`,
+        timeout: gate.timeout, // undefined ⇒ unbounded (docker.ts gate 7)
+        env: containerEnv,
+        stream: true,
+    });
+    // Enforce the native invariant in ONE place: timedOut ⇒ 124.
+    return {
+        code: result.timedOut ? GATE_TIMEOUT_EXIT_CODE : result.exitCode,
+        timedOut: result.timedOut,
+    };
+}
+async function runGates(gates, projectDir, onStep, 
+// REQUIRED, so it MUST precede the optional `onOutcome` (TS1016: a required
+// parameter cannot follow an optional one). Both call sites pass it positionally.
+docker, onOutcome) {
     if (gates.length === 0)
         return;
     const blockingFailures = [];
@@ -951,8 +1007,44 @@ async function runGates(gates, projectDir, onStep, onOutcome) {
             ...extra,
         });
         report(onStep, stepId, label, "running");
-        // Per-gate env map: engine keys, then baseline, then gate.env LAST (last-wins).
-        const gateEnv = { ...baseEnv };
+        // Fail-closed matrix (slice 3): an image gate that cannot reach Docker is
+        // REFUSED — it MUST NOT fall through to native/unpinned execution and MUST
+        // NOT be silently skipped/passed. Blocking → build failure (feeds the
+        // aggregate throw); informative → `warning` (never a false-green). A gate
+        // WITHOUT `image` is unaffected and runs native regardless of --no-docker.
+        //
+        // `isAvailable()` is touched ONLY for an image gate under Docker: the
+        // `noDocker` short-circuit means an image-less set (or a --no-docker run)
+        // never shells out to `docker info`, keeping the native path zero-cost.
+        if (gate.image !== undefined) {
+            if (docker.noDocker || !(await docker.isAvailable())) {
+                const why = docker.noDocker
+                    ? "--no-docker set"
+                    : "Docker not available";
+                const reason = `gate "${gate.id}" requires image "${gate.image}" but ${why} — refusing (never runs native/unpinned)`;
+                if (blocking) {
+                    blockingFailures.push(gate.id);
+                    report(onStep, stepId, `${label} failed`, "error", reason);
+                    emit("error", { reason });
+                }
+                else {
+                    report(onStep, stepId, `${label} failed (informative)`, "warning", reason);
+                    emit("warning", { reason });
+                }
+                continue; // NEVER falls through to native execution.
+            }
+        }
+        // Per-gate env: build the INJECTED allowlist (engine keys + baseline) once,
+        // then split into two maps (JDB-001):
+        //   - nativeEnv: full host env + injected + gate.env — a spawn env MAP (never
+        //     argv), so the host env is safe there.
+        //   - containerEnv: EXPLICIT ALLOWLIST ONLY (CI + injected + gate.env), NEVER
+        //     process.env — every entry becomes a `-e KEY=VALUE` argv element, so
+        //     forwarding process.env would leak host secrets to `ps aux` and defeat
+        //     the container's isolation.
+        // Gate env spreads LAST in BOTH — a gate MAY override CI / CHANGED_FILES /
+        // BASELINE (documented last-wins).
+        const injected = {};
         let gateChangedFiles;
         if (gate.scope === GATE_SCOPE.CHANGED) {
             const scope = await resolveChangedScope();
@@ -970,15 +1062,22 @@ async function runGates(gates, projectDir, onStep, onOutcome) {
                 continue;
             }
             gateChangedFiles = scope.files;
-            gateEnv[CHANGED_FILES_ENV] = scope.files.join("\n");
+            injected[CHANGED_FILES_ENV] = scope.files.join("\n");
         }
         if (gate.baseline !== undefined) {
-            gateEnv[BASELINE_ENV] = gate.baseline;
-        }
-        if (gate.env !== undefined) {
-            // Gate env spreads LAST — a gate MAY override CI / CHANGED_FILES / BASELINE.
-            Object.assign(gateEnv, gate.env);
+            injected[BASELINE_ENV] = gate.baseline;
         }
+        const gateOverrides = gate.env ?? {};
+        const nativeEnv = {
+            ...baseEnv,
+            ...injected,
+            ...gateOverrides,
+        };
+        const containerEnv = {
+            CI: "true",
+            ...injected,
+            ...gateOverrides,
+        };
         let exitCode = 0;
         let timedOut = false;
         let spawnError;
@@ -987,7 +1086,7 @@ async function runGates(gates, projectDir, onStep, onOutcome) {
                 // timeout is per-command (matches the fail-fast model): each command
                 // gets its own wall-clock budget. A timed-out command is killed and
                 // resolves non-zero, so fail-fast stops the gate here.
-                const result = await runGateNative(cmd, projectDir, gateEnv, gate.timeout);
+                const result = await runGateCommand(gate, cmd, projectDir, nativeEnv, containerEnv);
                 exitCode = result.code;
                 timedOut = result.timedOut;
                 if (exitCode !== 0)

package/dist/lib/docker.d.ts

@@ -10,17 +10,35 @@ export interface DockerRunOptions {
     image: string;
     /** Command to run inside the container */
     command: string;
-    /** Timeout in seconds (default: 600) */
+    /**
+     * Wall-clock timeout in seconds, enforced HOST-SIDE (a host timer → `docker
+     * stop`), NOT by an in-container `timeout` binary. Omitted → the container
+     * runs UNBOUNDED (no timer armed) — there is no silent default cap.
+     */
     timeout?: number;
     /** Stream output to stdout/stderr (default: true) */
     stream?: boolean;
     /** Override the user to run as inside the container (default: runner) */
     user?: string;
+    /**
+     * Extra env vars injected as discrete `-e KEY=VALUE` argv elements (one per
+     * entry), NEVER shell-spliced. Values with spaces/`=`/newlines survive
+     * verbatim (argv, not a shell string); Docker splits only on the first `=`.
+     * A caller passing no map yields the same argv as today (only `-e CI=true`).
+     */
+    env?: Record<string, string>;
 }
 export interface DockerRunResult {
     exitCode: number;
     stdout: string;
     stderr: string;
+    /**
+     * `true` IFF the host wall-clock timer fired and terminated the container —
+     * set DETERMINISTICALLY by the host BEFORE the kill, never inferred from a
+     * raw 124 exit code. Lets a caller tell a real timeout apart from a command
+     * that itself exits 124 (both surface non-zero, only one is a timeout).
+     */
+    timedOut: boolean;
 }
 export interface DockerImageOptions {
     stack: Stack;

package/dist/lib/docker.js

@@ -183,7 +183,7 @@ export async function ensureImage(options) {
  * Streams output to process.stdout/stderr by default.
  */
 export async function runInContainer(options) {
-    const { projectDir, image, command, timeout = 600, stream = true, user, } = options;
+    const { projectDir, image, command, timeout, stream = true, user, env, } = options;
     // The image is always pre-resolved by the caller (resolveCIRunners →
     // ensureImage or an explicit/digest-pinned config image). No marker
     // detection happens on this path — ever.
@@ -203,14 +203,33 @@ export async function runInContainer(options) {
     const gid = process.getgid?.();
     const runAsUser = user ??
         (uid !== undefined && gid !== undefined ? `${uid}:${gid}` : undefined);
+    // Env injection (containerized-gates gate 2): CI=true FIRST, then one
+    // discrete `-e KEY=VALUE` argv pair per caller entry. These are argv
+    // elements handed to spawn (no shell), so values with spaces/`=`/newlines
+    // survive verbatim — Docker splits only on the first `=`. A caller passing
+    // no map yields the same argv as before (only `-e CI=true`).
+    const envArgs = ["-e", "CI=true"];
+    for (const [k, v] of Object.entries(env ?? {})) {
+        envArgs.push("-e", `${k}=${v}`);
+    }
+    // A unique container name so the HOST-SIDE timeout can `docker stop <cid>`
+    // a concrete target (design gate 1) rather than guessing.
+    const cid = `javi-forge-ci-${crypto.randomBytes(6).toString("hex")}`;
     // Use --mount instead of -v: the -v form parses the value as a single
     // "src:dst[:opt]" colon-separated string, which breaks (and could be
     // hijacked) when projectDir itself contains a colon. --mount takes
     // comma-separated key=value pairs and is colon-safe.
+    //
+    // NOTE (containerized-gates gate 1): the in-container `timeout <N>` wrapper
+    // is REMOVED. The timeout is enforced host-side below (host wall-clock timer
+    // → `docker stop`), so the container command is just `bash -c <cmd>`. This
+    // mirrors runGateNative (ci.ts) one level up, at the docker-run process.
     const dockerArgs = [
         "run",
         "--rm",
         ...(isInteractive ? ["-it"] : []),
+        "--name",
+        cid,
         "--stop-timeout",
         "30",
         "--entrypoint",
@@ -218,11 +237,8 @@ export async function runInContainer(options) {
         ...(runAsUser ? ["--user", runAsUser] : []),
         "--mount",
         `type=bind,source=${projectDir},target=/home/runner/work`,
-        "-e",
-        "CI=true",
+        ...envArgs,
         imageName,
-        "timeout",
-        String(timeout),
         "bash",
         "-c",
         command,
@@ -233,6 +249,40 @@ export async function runInContainer(options) {
         });
         let stdout = "";
         let stderr = "";
+        // HOST-SIDE timeout (design gate 1): arm a host wall-clock timer ONLY when
+        // a timeout is provided. When it fires, set `timedOut = true` BEFORE the
+        // kill (authoritative — never inferred from the exit code), then
+        // `docker stop -t <grace> <cid>` (SIGTERM → SIGKILL after grace) to tear
+        // the CONTAINER down by name — NOT `proc.kill()` on the client, which would
+        // orphan the container. A `backstopTimer` SIGKILLs the docker-run CLIENT
+        // only as a LAST RESORT: if `docker stop` itself wedges (dead daemon) the
+        // client would never `close` and the gate would hang forever. `--rm` +
+        // `--name <cid>` keep any orphan bounded and identifiable. No timeout →
+        // no timer → the container runs UNBOUNDED (no silent cap).
+        let killTimer;
+        let backstopTimer;
+        let timedOut = false;
+        const clearTimers = () => {
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            if (backstopTimer !== undefined)
+                clearTimeout(backstopTimer);
+        };
+        if (timeout !== undefined) {
+            killTimer = setTimeout(() => {
+                timedOut = true;
+                // Fire-and-forget teardown: swallow spawn errors (e.g. the docker
+                // binary vanished mid-run) so an unhandled 'error' event can't crash
+                // the process. The armed backstopTimer still guarantees the run
+                // promise resolves via the client SIGKILL. (jd A+B convergent finding)
+                spawn("docker", ["stop", "-t", String(DOCKER_STOP_GRACE_SEC), cid], {
+                    stdio: "ignore",
+                }).on("error", () => { });
+                backstopTimer = setTimeout(() => {
+                    proc.kill("SIGKILL");
+                }, (DOCKER_STOP_GRACE_SEC + 1) * 1000);
+            }, timeout * 1000);
+        }
         if (!stream) {
             proc.stdout?.on("data", (d) => {
                 stdout += d.toString();
@@ -241,10 +291,22 @@ export async function runInContainer(options) {
                 stderr += d.toString();
             });
         }
-        proc.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
-        proc.on("error", reject);
+        proc.on("close", (code) => {
+            clearTimers();
+            resolve({ exitCode: code ?? 1, stdout, stderr, timedOut });
+        });
+        proc.on("error", (e) => {
+            clearTimers();
+            reject(e);
+        });
     });
 }
+/**
+ * Grace (seconds) passed to `docker stop -t` between the container SIGTERM and
+ * the daemon's escalated SIGKILL. The client-side backstop fires one second
+ * after this window to guarantee the run promise always resolves.
+ */
+const DOCKER_STOP_GRACE_SEC = 10;
 /**
  * Open an interactive shell inside the CI container.
  * The image must be pre-resolved by the caller (no marker detection here).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.16.0",
+	"version": "1.18.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {