javi-forge 1.15.0 → 1.16.0

package/dist/cli/dispatch/ci.js

@@ -50,7 +50,8 @@ export async function handleCi(cli, ctx) {
                 if (gates.length > 0) {
                     console.log(`  ${gates.length} gate(s):`);
                     for (const gate of gates) {
-                        console.log(`    - ${gate.id} (${gate.mode}, scope: ${gate.scope})`);
+                        const image = gate.image !== undefined ? `, image: ${gate.image}` : "";
+                        console.log(`    - ${gate.id} (${gate.mode}, scope: ${gate.scope}${image})`);
                     }
                 }
             }

package/dist/commands/ci-validate.d.ts

@@ -17,6 +17,8 @@ export interface CIValidateGateSummary {
     id: string;
     mode: string;
     scope: string;
+    /** Container image ref, present ONLY when the gate declares one. */
+    image?: string;
 }
 export interface CIValidateOk {
     ok: true;

package/dist/commands/ci-validate.js

@@ -59,6 +59,9 @@ export async function validateCIConfig(projectDir, config) {
                 id: g.id,
                 mode: g.mode,
                 scope: g.scope,
+                // Surface `image` ONLY when declared, so an image-less gate summary
+                // stays byte-identical to today (no `image` key).
+                ...(g.image !== undefined ? { image: g.image } : {}),
             })),
         };
     }

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
@@ -112,7 +124,7 @@ export declare function runCI(options: CIOptions, onStep: CIStepCallback, onGate
  * 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>, timeoutSec?: number): 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? }`
@@ -130,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

@@ -822,19 +822,25 @@ export async function runGateNative(cmd, cwd, env, timeoutSec) {
                 // 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);
+                // 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();
@@ -974,13 +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) {
                 // 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);
+                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
             }
@@ -993,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,13 @@ export interface CIGateConfig {
     baseline?: string;
     /** Optional env injected via the child-process env map (slice 4). */
     env?: Record<string, string>;
+    /**
+     * Optional container image ref (containerized-gates). A plain,
+     * digest-pinnable image ref; when present the gate runs inside this image
+     * instead of host-native. Omitted → host-native (unchanged). Execution
+     * routing lands in a later slice; this slice validates the schema only.
+     */
+    image?: 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 →

package/dist/lib/ci-config.js

@@ -221,6 +221,7 @@ const GATE_FIELDS = new Set([
     "scope",
     "baseline",
     "env",
+    "image",
     "timeout",
 ]);
 function validateGate(raw, index, errors) {
@@ -318,6 +319,28 @@ function validateGate(raw, index, errors) {
             env = raw.env;
         }
     }
+    let image;
+    if (raw.image !== undefined) {
+        if (typeof raw.image !== "string" || !raw.image.trim()) {
+            errors.push({
+                path: `${base}.image`,
+                message: "image must be a non-empty string",
+            });
+        }
+        else if (raw.image.trim().startsWith("-")) {
+            // Harden against docker-flag injection: an image ref like "--privileged"
+            // or "-v /:/host" would be parsed by `docker run` as a FLAG, not an
+            // image argument, if it reached argv. Reject leading-dash refs at
+            // validation with a named error (JDB-004).
+            errors.push({
+                path: `${base}.image`,
+                message: "image must not start with '-' (would be parsed as a docker flag)",
+            });
+        }
+        else {
+            image = raw.image;
+        }
+    }
     let timeout;
     if (raw.timeout !== undefined) {
         if (typeof raw.timeout !== "number" ||
@@ -339,6 +362,7 @@ function validateGate(raw, index, errors) {
         scope,
         baseline,
         env,
+        image,
         timeout,
     };
 }

package/package.json

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