javi-forge 1.14.0 → 1.15.0

package/dist/commands/ci.d.ts

@@ -96,10 +96,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<number>;
 /**
  * A single gate's structured result, collected for the headless JSON run path.
  * Mirrors the `{ id, mode, scope, status, blocking, changedFiles?, exitCode? }`

package/dist/commands/ci.js

@@ -773,13 +773,59 @@ 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.
+                resolve(GATE_TIMEOUT_EXIT_CODE);
+                return;
+            }
             if (code !== null) {
                 resolve(code);
                 return;
@@ -790,9 +836,21 @@ export async function runGateNative(cmd, cwd, env) {
             const signum = signal ? os.constants.signals[signal] : undefined;
             resolve(signum !== undefined ? 128 + signum : 1);
         });
-        proc.on("error", reject);
+        proc.on("error", (e) => {
+            clearTimers();
+            reject(e);
+        });
     });
 }
+/** 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 +878,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
@@ -916,7 +977,10 @@ async function runGates(gates, projectDir, onStep, onOutcome) {
         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.
+                exitCode = await runGateNative(cmd, projectDir, gateEnv, gate.timeout);
                 if (exitCode !== 0)
                     break; // fail-fast: skip the remaining commands
             }

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.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {