javi-forge 1.11.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/lib/git-diff.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolve the base ref to diff HEAD against, forge-agnostic. Precedence:
+ * 1. `$CI_MERGE_REQUEST_DIFF_BASE_SHA` (GitLab MR) when non-empty.
+ * 2. `$CI_COMMIT_BEFORE_SHA` (GitLab push) when non-empty AND not the
+ *    all-zeros new-branch sentinel.
+ * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`.
+ * 4. Local fallback: `git merge-base <candidate> HEAD` over
+ *    `origin/main`, `origin/master`, `main`, `master` — first that resolves.
+ * 5. Nothing resolves → `null` (caller loud-degrades).
+ */
+export declare function resolveBaseRef(env: Record<string, string | undefined>, cwd: string): Promise<string | null>;
+/**
+ * The union (deduped) of files changed relative to `base`:
+ * - committed: `git diff --name-only --diff-filter=ACMR <base>...HEAD`
+ *   (three-dot; ACMR keeps Added/Copied/Modified/Renamed, drops deletions)
+ * - unstaged: `git diff --name-only`
+ * - staged:   `git diff --name-only --cached`
+ *
+ * Invoked as `execFileAsync("git", [...], { cwd })` — an argv array, never a
+ * shell string.
+ *
+ * THROWS if any git invocation fails. A base sha absent from local history
+ * (CI shallow clone / bad object) makes the committed diff error; that failure
+ * MUST propagate so the caller can skip the scope:changed gate with a named
+ * warning. It MUST NOT be swallowed into an empty set — an empty set means
+ * "no changed files" and would silently pass a scope:changed gate.
+ */
+export declare function changedFiles(base: string, cwd: string): Promise<string[]>;
+//# sourceMappingURL=git-diff.d.ts.map

package/dist/lib/git-diff.js

@@ -0,0 +1,132 @@
+import { execFileAsync } from "./exec.js";
+/**
+ * Forge-agnostic changed-file diff engine for `scope: changed` gates.
+ *
+ * Two injectable functions:
+ * - {@link resolveBaseRef} — resolve the base commit to diff HEAD against,
+ *   following a forge-agnostic precedence chain (GitLab MR / GitLab push /
+ *   GitHub PR / local merge-base). Returns `null` when nothing resolves so the
+ *   caller can loud-degrade (skip the scope:changed gate with a named warning).
+ * - {@link changedFiles} — the union of committed (Added/Copied/Modified/Renamed,
+ *   deletions dropped), unstaged, and staged changes. THROWS on a git failure
+ *   (e.g. a base sha absent from local history under a CI shallow clone) so the
+ *   caller can skip-with-warning; it MUST NOT swallow the failure into an empty
+ *   set (that would look like "no changes" and silently pass a scope gate).
+ *
+ * This module is UNWIRED: nothing in the run path imports it yet. The gate
+ * phase consumes it in a later slice.
+ */
+/** The all-zeros sha git emits for a brand-new branch's "before" ref. */
+const NEW_BRANCH_SENTINEL = "0".repeat(40);
+/**
+ * Local base-ref candidates, tried in order. The first whose `git merge-base
+ * <candidate> HEAD` resolves wins.
+ */
+const LOCAL_BASE_CANDIDATES = [
+    "origin/main",
+    "origin/master",
+    "main",
+    "master",
+];
+function isNonEmpty(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * Compute `git merge-base <ref> HEAD` in `cwd`, returning the resolved sha or
+ * `null` when the ref does not exist / has no common ancestor.
+ */
+async function tryMergeBase(ref, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["merge-base", ref, "HEAD"], {
+            cwd,
+        });
+        const sha = stdout.trim();
+        return sha.length > 0 ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the base ref to diff HEAD against, forge-agnostic. Precedence:
+ * 1. `$CI_MERGE_REQUEST_DIFF_BASE_SHA` (GitLab MR) when non-empty.
+ * 2. `$CI_COMMIT_BEFORE_SHA` (GitLab push) when non-empty AND not the
+ *    all-zeros new-branch sentinel.
+ * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`.
+ * 4. Local fallback: `git merge-base <candidate> HEAD` over
+ *    `origin/main`, `origin/master`, `main`, `master` — first that resolves.
+ * 5. Nothing resolves → `null` (caller loud-degrades).
+ */
+export async function resolveBaseRef(env, cwd) {
+    // 1. GitLab merge request — the base sha is provided directly.
+    if (isNonEmpty(env.CI_MERGE_REQUEST_DIFF_BASE_SHA)) {
+        return env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+    }
+    // 2. GitLab push — the previous sha, unless it is the new-branch sentinel.
+    if (isNonEmpty(env.CI_COMMIT_BEFORE_SHA) &&
+        env.CI_COMMIT_BEFORE_SHA !== NEW_BRANCH_SENTINEL) {
+        return env.CI_COMMIT_BEFORE_SHA;
+    }
+    // 3. GitHub Actions — a PR sets GITHUB_BASE_REF (merge-base against the
+    //    target branch); a push has no base ref and falls back to GITHUB_SHA.
+    if (isNonEmpty(env.GITHUB_BASE_REF)) {
+        const base = await tryMergeBase(`origin/${env.GITHUB_BASE_REF}`, cwd);
+        if (base !== null)
+            return base;
+    }
+    else if (isNonEmpty(env.GITHUB_SHA)) {
+        return env.GITHUB_SHA;
+    }
+    // 4. Local fallback — first candidate whose merge-base resolves.
+    for (const candidate of LOCAL_BASE_CANDIDATES) {
+        const base = await tryMergeBase(candidate, cwd);
+        if (base !== null)
+            return base;
+    }
+    // 5. Nothing resolved.
+    return null;
+}
+/**
+ * Parse `git diff --name-only` stdout into a list of repo-root-relative paths,
+ * dropping blank lines.
+ */
+function parseNameOnly(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+/**
+ * The union (deduped) of files changed relative to `base`:
+ * - committed: `git diff --name-only --diff-filter=ACMR <base>...HEAD`
+ *   (three-dot; ACMR keeps Added/Copied/Modified/Renamed, drops deletions)
+ * - unstaged: `git diff --name-only`
+ * - staged:   `git diff --name-only --cached`
+ *
+ * Invoked as `execFileAsync("git", [...], { cwd })` — an argv array, never a
+ * shell string.
+ *
+ * THROWS if any git invocation fails. A base sha absent from local history
+ * (CI shallow clone / bad object) makes the committed diff error; that failure
+ * MUST propagate so the caller can skip the scope:changed gate with a named
+ * warning. It MUST NOT be swallowed into an empty set — an empty set means
+ * "no changed files" and would silently pass a scope:changed gate.
+ */
+export async function changedFiles(base, cwd) {
+    const invocations = [
+        ["diff", "--name-only", "--diff-filter=ACMR", `${base}...HEAD`],
+        ["diff", "--name-only"],
+        ["diff", "--name-only", "--cached"],
+    ];
+    const seen = new Set();
+    for (const args of invocations) {
+        // Deliberately NOT wrapped in try/catch: a git failure here (shallow
+        // clone / missing base object) must surface to the caller.
+        const { stdout } = await execFileAsync("git", args, { cwd });
+        for (const file of parseNameOnly(stdout)) {
+            seen.add(file);
+        }
+    }
+    return [...seen];
+}
+//# sourceMappingURL=git-diff.js.map

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