javi-forge 1.14.0 → 1.15.1

package/dist/commands/ci.d.ts

@@ -80,6 +80,18 @@ export interface ResolveRunnerOptions {
  */
 export declare function resolveCIRunners(projectDir: string, options?: ResolveRunnerOptions): Promise<ResolvedRunners>;
 export declare function runCI(options: CIOptions, onStep: CIStepCallback, onGateOutcome?: (outcome: GateOutcome) => void): Promise<void>;
+/**
+ * Result of a single host-native gate command. `code` is the resolved exit code
+ * (a timed-out command resolves the `timeout(1)` sentinel 124); `timedOut` is
+ * `true` IFF the internal wall-clock `killTimer` fired. The flag exists so a
+ * caller can tell a wall-clock timeout apart from a child that itself exits 124
+ * (a `curl` op-timeout, a nested `timeout(1)`, a script returning 124) — both
+ * carry `code: 124`, but only a real timeout carries `timedOut: true` (R3-004).
+ */
+export interface GateRunResult {
+    code: number;
+    timedOut: boolean;
+}
 /**
  * Execute a single gate command HOST-NATIVE via `bash -c`, at the repo root,
  * with the provided env MAP. Modeled on `runSemgrep`/`runGhagga` (a spawned
@@ -96,10 +108,23 @@ export declare function runCI(options: CIOptions, onStep: CIStepCallback, onGate
  * eliminate. A null code therefore resolves to a NON-ZERO code using the shell
  * convention `128 + <signal number>` when the signal is resolvable, else 1.
  *
+ * TIMEOUT (GATE-2): when `timeoutSec` is set, a command still running after that
+ * many wall-clock seconds is killed — SIGTERM first, escalated to SIGKILL after a
+ * short grace if it ignores SIGTERM. A `timedOut` flag is set BEFORE the SIGTERM
+ * lands, and on `close` it OVERRIDES the child's reported code with the timeout
+ * sentinel 124 — REGARDLESS of what the child reported. This closes the false-green
+ * where a child that TRAPS SIGTERM and exits 0 gracefully (dev servers, watchers,
+ * SIGTERM-handling CLIs) would otherwise resolve 0 and PASS a timed-out blocking
+ * gate. INVARIANT: `timedOut ⇒ non-zero, ALWAYS` (124, the GNU `timeout(1)`
+ * convention — distinct from a signal-death 143/137). Timers are cleared on
+ * `close`/`error` so no dangling handle keeps the process alive. Omitting
+ * `timeoutSec` preserves the pre-GATE-2 behavior exactly (no timer, runs to
+ * completion).
+ *
  * Env values arrive as discrete map entries — never string-spliced into the
  * `bash -c` command — so metacharacters in a value cannot break out of the shell.
  */
-export declare function runGateNative(cmd: string, cwd: string, env: Record<string, string>): Promise<number>;
+export declare function runGateNative(cmd: string, cwd: string, env: Record<string, string>, timeoutSec?: number): Promise<GateRunResult>;
 /**
  * A single gate's structured result, collected for the headless JSON run path.
  * Mirrors the `{ id, mode, scope, status, blocking, changedFiles?, exitCode? }`
@@ -117,10 +142,12 @@ export interface GateOutcome {
     /** First non-zero command code for a failed gate. */
     exitCode?: number;
     /**
-     * Human-readable cause of a degrade/skip, surfaced so the headless JSON
-     * consumer sees the degrade LOUDLY — not just in the Ink stream. Populated for
-     * the scope:changed skip variants: base ref null, changed-file resolution
-     * failure (shallow clone / missing ref), and the empty changed-set skip.
+     * Human-readable cause of a degrade/skip/timeout, surfaced so the headless
+     * JSON consumer sees it LOUDLY — not just in the Ink stream. Populated for the
+     * scope:changed skip variants (base ref null, changed-file resolution failure
+     * under a shallow clone / missing ref, empty changed-set skip) AND for a gate
+     * that timed out (so a 124 wall-clock kill is distinguishable from a command
+     * that itself exits 124).
      */
     reason?: string;
 }

package/dist/commands/ci.js

@@ -773,26 +773,90 @@ function filterDefinedEnv(env) {
  * eliminate. A null code therefore resolves to a NON-ZERO code using the shell
  * convention `128 + <signal number>` when the signal is resolvable, else 1.
  *
+ * TIMEOUT (GATE-2): when `timeoutSec` is set, a command still running after that
+ * many wall-clock seconds is killed — SIGTERM first, escalated to SIGKILL after a
+ * short grace if it ignores SIGTERM. A `timedOut` flag is set BEFORE the SIGTERM
+ * lands, and on `close` it OVERRIDES the child's reported code with the timeout
+ * sentinel 124 — REGARDLESS of what the child reported. This closes the false-green
+ * where a child that TRAPS SIGTERM and exits 0 gracefully (dev servers, watchers,
+ * SIGTERM-handling CLIs) would otherwise resolve 0 and PASS a timed-out blocking
+ * gate. INVARIANT: `timedOut ⇒ non-zero, ALWAYS` (124, the GNU `timeout(1)`
+ * convention — distinct from a signal-death 143/137). Timers are cleared on
+ * `close`/`error` so no dangling handle keeps the process alive. Omitting
+ * `timeoutSec` preserves the pre-GATE-2 behavior exactly (no timer, runs to
+ * completion).
+ *
  * Env values arrive as discrete map entries — never string-spliced into the
  * `bash -c` command — so metacharacters in a value cannot break out of the shell.
  */
-export async function runGateNative(cmd, cwd, env) {
+export async function runGateNative(cmd, cwd, env, timeoutSec) {
     return await new Promise((resolve, reject) => {
         const proc = spawn("bash", ["-c", cmd], { cwd, env, stdio: "inherit" });
+        let killTimer;
+        let graceTimer;
+        let timedOut = false;
+        const clearTimers = () => {
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            if (graceTimer !== undefined)
+                clearTimeout(graceTimer);
+        };
+        if (timeoutSec !== undefined) {
+            killTimer = setTimeout(() => {
+                // The wall-clock budget expired: mark the run as timed out BEFORE the
+                // SIGTERM lands. A child that traps SIGTERM and exits 0 gracefully would
+                // otherwise report code=0 → a false-green; the `timedOut` flag overrides
+                // that below so a timed-out gate is ALWAYS a FAILURE.
+                timedOut = true;
+                // Ask politely, then force: SIGKILL if the child is still alive after
+                // the grace window.
+                proc.kill("SIGTERM");
+                graceTimer = setTimeout(() => {
+                    proc.kill("SIGKILL");
+                }, GATE_TIMEOUT_GRACE_MS);
+            }, timeoutSec * 1000);
+        }
         proc.on("close", (code, signal) => {
+            clearTimers();
+            if (timedOut) {
+                // INVARIANT: timedOut ⇒ non-zero, ALWAYS. Even a child that trapped the
+                // SIGTERM and exited 0 before the SIGKILL escalation is a timeout, not a
+                // pass. Resolve the GNU `timeout(1)` sentinel 124 ("command timed out"),
+                // semantically distinct from a signal-death 143/137. The `timedOut` flag
+                // travels with the code so the caller can tell a wall-clock timeout apart
+                // from a child that itself exits 124 (both are 124, but only one is a
+                // timeout — R3-004 observability).
+                resolve({ code: GATE_TIMEOUT_EXIT_CODE, timedOut: true });
+                return;
+            }
             if (code !== null) {
-                resolve(code);
+                resolve({ code, timedOut: false });
                 return;
             }
             // Signal death: map to a non-zero code so the collector records a
             // blocking failure. `128 + signum` mirrors the shell; fall back to 1
             // when the signal name is not resolvable.
             const signum = signal ? os.constants.signals[signal] : undefined;
-            resolve(signum !== undefined ? 128 + signum : 1);
+            resolve({
+                code: signum !== undefined ? 128 + signum : 1,
+                timedOut: false,
+            });
+        });
+        proc.on("error", (e) => {
+            clearTimers();
+            reject(e);
         });
-        proc.on("error", reject);
     });
 }
+/** Grace between the timeout SIGTERM and the escalated SIGKILL. */
+const GATE_TIMEOUT_GRACE_MS = 2000;
+/**
+ * Exit code resolved for a timed-out gate, regardless of how the child died.
+ * 124 is the GNU `timeout(1)` convention for "command timed out" — semantically
+ * distinct from a signal-death 143 (SIGTERM) / 137 (SIGKILL), and it CANNOT be a
+ * false-green because it is non-zero. Enforces `timedOut ⇒ non-zero, always`.
+ */
+const GATE_TIMEOUT_EXIT_CODE = 124;
 /**
  * Env var carrying a scope:changed gate's newline-joined, root-relative paths.
  *
@@ -820,7 +884,10 @@ const BASELINE_ENV = "JAVI_FORGE_BASELINE";
  * contribute to the accumulator, so the exit code stays 0.
  *
  * Multi-command gates run in order and STOP at the first non-zero exit
- * (fail-fast, matching the runner precedent); that first code is reported.
+ * (fail-fast, matching the runner precedent); that first code is reported. An
+ * optional per-gate `timeout` (seconds) is applied PER COMMAND: a command that
+ * exceeds it is killed and resolves non-zero, so the timed-out gate fails
+ * (blocking) or warns (informative) — never a false-green.
  *
  * `scope: changed` consumes the injectable `git-diff.ts` engine: the base ref is
  * resolved and the changed set computed ONCE, then shared. A non-empty set runs
@@ -913,10 +980,16 @@ async function runGates(gates, projectDir, onStep, onOutcome) {
             Object.assign(gateEnv, gate.env);
         }
         let exitCode = 0;
+        let timedOut = false;
         let spawnError;
         try {
             for (const cmd of gate.run) {
-                exitCode = await runGateNative(cmd, projectDir, gateEnv);
+                // 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);
+                exitCode = result.code;
+                timedOut = result.timedOut;
                 if (exitCode !== 0)
                     break; // fail-fast: skip the remaining commands
             }
@@ -929,15 +1002,31 @@ async function runGates(gates, projectDir, onStep, onOutcome) {
             emit("done", { changedFiles: gateChangedFiles });
             continue;
         }
+        // R3-004: a timed-out gate carries a `reason` naming the timeout so the
+        // JSON/dashboard consumer can distinguish "this gate timed out (bump the
+        // timeout)" from "the command failed with 124 (fix the command)". A
+        // non-timeout failure leaves `reason` undefined. Never key on the 124 value
+        // itself — that IS the ambiguity; only the real `timedOut` signal disambiguates.
+        const timeoutReason = timedOut
+            ? `timed out after ${gate.timeout}s`
+            : undefined;
         const detail = spawnError !== undefined ? String(spawnError) : `exit ${exitCode}`;
         if (blocking) {
             blockingFailures.push(gate.id);
             report(onStep, stepId, `${label} failed`, "error", detail);
-            emit("error", { changedFiles: gateChangedFiles, exitCode });
+            emit("error", {
+                changedFiles: gateChangedFiles,
+                exitCode,
+                reason: timeoutReason,
+            });
         }
         else {
             report(onStep, stepId, `${label} failed (informative)`, "warning", detail);
-            emit("warning", { changedFiles: gateChangedFiles, exitCode });
+            emit("warning", {
+                changedFiles: gateChangedFiles,
+                exitCode,
+                reason: timeoutReason,
+            });
         }
     }
     if (blockingFailures.length > 0) {

package/dist/lib/ci-config.d.ts

@@ -60,6 +60,12 @@ export interface CIGateConfig {
     baseline?: string;
     /** Optional env injected via the child-process env map (slice 4). */
     env?: Record<string, string>;
+    /**
+     * Optional per-command wall-clock timeout in seconds (GATE-2). When set, a
+     * command exceeding it is killed and the gate FAILS (non-zero). Omitted →
+     * no timeout (unchanged behavior).
+     */
+    timeout?: number;
 }
 export interface CIConfig {
     version: number;

package/dist/lib/ci-config.js

@@ -214,7 +214,15 @@ function validateRunner(raw, index, errors) {
         requires,
     };
 }
-const GATE_FIELDS = new Set(["id", "run", "mode", "scope", "baseline", "env"]);
+const GATE_FIELDS = new Set([
+    "id",
+    "run",
+    "mode",
+    "scope",
+    "baseline",
+    "env",
+    "timeout",
+]);
 function validateGate(raw, index, errors) {
     const base = `gates[${index}]`;
     if (!isRecord(raw)) {
@@ -310,6 +318,20 @@ function validateGate(raw, index, errors) {
             env = raw.env;
         }
     }
+    let timeout;
+    if (raw.timeout !== undefined) {
+        if (typeof raw.timeout !== "number" ||
+            !Number.isFinite(raw.timeout) ||
+            raw.timeout <= 0) {
+            errors.push({
+                path: `${base}.timeout`,
+                message: `timeout must be a positive number of seconds (got "${String(raw.timeout)}")`,
+            });
+        }
+        else {
+            timeout = raw.timeout;
+        }
+    }
     return {
         id: typeof id === "string" ? id.trim() : "",
         run,
@@ -317,6 +339,7 @@ function validateGate(raw, index, errors) {
         scope,
         baseline,
         env,
+        timeout,
     };
 }
 /**

package/package.json

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