javi-forge 1.12.0 → 1.13.0

package/dist/commands/ci.d.ts

@@ -1,3 +1,4 @@
+import { type CIGateConfig } from "../lib/ci-config.js";
 import type { Stack } from "../types/index.js";
 export type CIMode = "full" | "quick" | "shell" | "detect";
 export interface CIOptions {
@@ -16,7 +17,7 @@ export interface CIOptions {
     /** Explicit single-stack override (--stack). Insufficient for hybrid repos */
     stack?: string;
 }
-export type CIStepStatus = "pending" | "running" | "done" | "error" | "skipped";
+export type CIStepStatus = "pending" | "running" | "done" | "error" | "skipped" | "warning";
 export interface CIStep {
     id: string;
     label: string;
@@ -60,6 +61,8 @@ export type RunnerSource = "auto" | "config" | "stack-override";
 export interface ResolvedRunners {
     readonly source: RunnerSource;
     readonly runners: readonly ResolvedRunner[];
+    /** Declared quality gates (version 2 only); empty for auto/stack-override. */
+    readonly gates: readonly CIGateConfig[];
 }
 export interface ResolveRunnerOptions {
     /** Explicit config path (--config). Wins over default discovery */
@@ -77,6 +80,26 @@ export interface ResolveRunnerOptions {
  */
 export declare function resolveCIRunners(projectDir: string, options?: ResolveRunnerOptions): Promise<ResolvedRunners>;
 export declare function runCI(options: CIOptions, onStep: CIStepCallback): Promise<void>;
+/**
+ * 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
+ * process, NOT `runStep`'s Docker branch — gates have no runner or image).
+ *
+ * RESOLVES the child exit code (it does NOT throw on a non-zero exit) so the
+ * collector and the JSON `exitCode` field are populatable. A spawn error (e.g.
+ * `bash` missing) rejects, and the collector treats that as a failure.
+ *
+ * SIGNAL DEATH IS A FAILURE, NEVER A FALSE-GREEN: when the child is terminated
+ * by a signal (OOM kill, SIGSEGV/SIGABRT, external SIGTERM) `close` reports a
+ * NULL code. Mapping that to 0 would report a signal-killed blocking gate as
+ * `done` and let the build PASS — the exact false-green this phase exists to
+ * 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.
+ *
+ * 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>;
 /**
  * Classification of an existing `.git/hooks/<name>` before anything is written
  * (design D6). Every state has exactly one write policy, so no hook is ever

package/dist/commands/ci.js

@@ -2,10 +2,11 @@ import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import fsp from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import { HOOK_ASSETS_DIR } from "../constants.js";
-import { CI_STACKS, findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
+import { CI_STACKS, findCIConfig, GATE_MODE, loadCIConfig, } from "../lib/ci-config.js";
 import { refreshContextDir } from "../lib/context.js";
 import { ensureImage, isDockerAvailable, openShell, runInContainer, } from "../lib/docker.js";
 import { execFileAsync } from "../lib/exec.js";
@@ -148,8 +149,12 @@ function freezeRunner(runner) {
         requiredTools: Object.freeze([...runner.requiredTools]),
     });
 }
-function freezeRunners(source, runners) {
-    return Object.freeze({ source, runners: Object.freeze(runners) });
+function freezeRunners(source, runners, gates = []) {
+    return Object.freeze({
+        source,
+        runners: Object.freeze(runners),
+        gates: Object.freeze([...gates]),
+    });
 }
 /** Build-tool heuristic for a known stack in a given directory. */
 async function detectBuildTool(stack, dir) {
@@ -247,7 +252,7 @@ export async function resolveCIRunners(projectDir, options = {}) {
         for (const runnerConfig of ciConfig.runners) {
             runners.push(await resolveConfiguredRunner(projectDir, runnerConfig));
         }
-        return freezeRunners("config", runners);
+        return freezeRunners("config", runners, ciConfig.gates ?? []);
     }
     // Zero-config default: single auto-detected runner (unchanged behavior).
     const info = await detectCIStack(projectDir);
@@ -288,11 +293,12 @@ function report(onStep, id, label, status, detail) {
 /**
  * Detect-step label: legacy format for auto, explicit otherwise.
  *
- * INVARIANT (holds for every `ResolvedRunners` value): `runners` is never
- * empty. The config path rejects an empty list before resolving
- * (`src/lib/ci-config.ts` — "runners is required and must be a non-empty
- * list"), and the `auto` and `stack-override` paths each yield exactly one
- * runner. `runners[0]` therefore needs no fallback.
+ * RUNNER COUNT: the `auto` and `stack-override` paths each yield exactly one
+ * runner, so their branches deref `runners[0]` safely. A gates-only v2 config
+ * (version 2, `runners` omitted) reaches here with ZERO runners on the `config`
+ * source; that branch never dereferences `runners[0]` — it only reads
+ * `runners.length` and maps over the (possibly empty) list — so an empty list
+ * is handled without a fallback.
  */
 function describeRunners(resolved) {
     const first = resolved.runners[0];
@@ -324,9 +330,24 @@ export async function runCI(options, onStep) {
         report(onStep, stepDetect, "Detecting stack", "error", String(e));
         throw e;
     }
+    // ── Gates-only v2 repo (zero runners) ──────────────────────────────────────
+    // A `version: 2` config MAY declare `gates:` with NO `runners`. Such a repo
+    // has no stack to detect, no image to build, and no runner loop, so the
+    // runner prologue below (which dereferences `resolved.runners[0]`) must be
+    // skipped entirely. `detect`/`shell` have nothing to target → named error;
+    // `full`/`quick` jump straight to the gate phase and return.
+    if (resolved.runners.length === 0) {
+        if (mode === "detect" || mode === "shell") {
+            const detail = "no runners resolved — nothing to detect or shell into";
+            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);
+        return;
+    }
     // Legacy single-runner view for the zero-config auto path. Keeping this
     // shape guarantees single-stack repositories behave exactly as before.
-    // `runners[0]` is always present — see the invariant on `describeRunners`.
+    // `runners[0]` is always present here — the zero-runner case returned above.
     // The command lists CAN be empty, so those keep their `?? null`.
     const primary = resolved.runners[0];
     const stackInfo = {
@@ -487,6 +508,14 @@ export async function runCI(options, onStep) {
             report(onStep, stepGhagga, "GHAGGA review", "skipped", "ghagga not installed");
         }
     }
+    // ── Gate phase (full || quick — skipped in detect/shell) ────────────────────
+    // Gates run on every REAL CI run, including `--quick` (the pre-push path where
+    // a blocking gate matters most). `detect`/`shell` return earlier, so mode is
+    // 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);
+    }
 }
 // =============================================================================
 // Step runners
@@ -716,6 +745,117 @@ async function runGhagga(projectDir) {
     });
 }
 // =============================================================================
+// Gate phase (version 2) — host-native, repo-level
+// =============================================================================
+/** Drop `undefined` entries so `process.env` fits the spawn env-map contract. */
+function filterDefinedEnv(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * 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
+ * process, NOT `runStep`'s Docker branch — gates have no runner or image).
+ *
+ * RESOLVES the child exit code (it does NOT throw on a non-zero exit) so the
+ * collector and the JSON `exitCode` field are populatable. A spawn error (e.g.
+ * `bash` missing) rejects, and the collector treats that as a failure.
+ *
+ * SIGNAL DEATH IS A FAILURE, NEVER A FALSE-GREEN: when the child is terminated
+ * by a signal (OOM kill, SIGSEGV/SIGABRT, external SIGTERM) `close` reports a
+ * NULL code. Mapping that to 0 would report a signal-killed blocking gate as
+ * `done` and let the build PASS — the exact false-green this phase exists to
+ * 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.
+ *
+ * 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) {
+    return await new Promise((resolve, reject) => {
+        const proc = spawn("bash", ["-c", cmd], { cwd, env, stdio: "inherit" });
+        proc.on("close", (code, signal) => {
+            if (code !== null) {
+                resolve(code);
+                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);
+        });
+        proc.on("error", reject);
+    });
+}
+/**
+ * Repo-level gate phase. Each gate runs host-native via `runGateNative` at the
+ * repo root. Outcome semantics:
+ *   - exit 0                         → `done`
+ *   - non-zero/spawn error, blocking → `error`, gate id recorded (NOT re-thrown)
+ *   - non-zero/spawn error, informative → `warning`, build never fails
+ *
+ * A blocking failure does NOT abort the phase — every gate reports its own
+ * status first. After the loop, if ANY blocking gate failed, ONE aggregate
+ * error is thrown so a single blocking failure never hides a later gate's
+ * result (the top-level catch yields exit 1). Informative failures never
+ * 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.
+ *
+ * Slice 3 wires `mode` and `scope: all` gates with the engine-injected env
+ * (`CI=true`). `scope: changed` wiring, `baseline`, and gate `env` injection
+ * land in slice 4.
+ */
+async function runGates(gates, projectDir, onStep) {
+    if (gates.length === 0)
+        return;
+    const blockingFailures = [];
+    // Engine-injected keys only in slice 3; gate `env` + JAVI_FORGE_CHANGED_FILES
+    // are added in slice 4.
+    const baseEnv = {
+        ...filterDefinedEnv(process.env),
+        CI: "true",
+    };
+    for (const gate of gates) {
+        const stepId = `gate:${gate.id}`;
+        const label = `Gate: ${gate.id}`;
+        report(onStep, stepId, label, "running");
+        let exitCode = 0;
+        let spawnError;
+        try {
+            for (const cmd of gate.run) {
+                exitCode = await runGateNative(cmd, projectDir, baseEnv);
+                if (exitCode !== 0)
+                    break; // fail-fast: skip the remaining commands
+            }
+        }
+        catch (e) {
+            spawnError = e;
+        }
+        if (spawnError === undefined && exitCode === 0) {
+            report(onStep, stepId, `${label} passed`, "done");
+            continue;
+        }
+        const detail = spawnError !== undefined ? String(spawnError) : `exit ${exitCode}`;
+        if (gate.mode === GATE_MODE.BLOCKING) {
+            blockingFailures.push(gate.id);
+            report(onStep, stepId, `${label} failed`, "error", detail);
+        }
+        else {
+            report(onStep, stepId, `${label} failed (informative)`, "warning", detail);
+        }
+    }
+    if (blockingFailures.length > 0) {
+        throw new Error(`blocking gate(s) failed: ${blockingFailures.join(", ")}`);
+    }
+}
+// =============================================================================
 // CI Hooks Installation
 // =============================================================================
 /**

package/dist/ui/CI.js

@@ -13,6 +13,7 @@ const STATUS_ICON = {
     done: "✓",
     error: "✗",
     skipped: "–",
+    warning: "⚠",
 };
 const STATUS_COLOR = {
     pending: theme.muted,
@@ -20,6 +21,7 @@ const STATUS_COLOR = {
     done: theme.success,
     error: theme.error,
     skipped: theme.muted,
+    warning: theme.warning,
 };
 // =============================================================================
 // Component

package/package.json

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