javi-forge 1.13.0 → 1.14.0

package/dist/cli/dispatch/ci.js

@@ -103,6 +103,33 @@ export async function handleCi(cli, ctx) {
             : cli.flags.quick
                 ? "quick"
                 : "full";
+    // Headless gate-run JSON (slice 4): `--json` on the RUN path is a NEW branch,
+    // NOT flag reuse — the flag is otherwise consumed only by `ci validate`. It
+    // bypasses the Ink render, drives the gate phase collecting structured
+    // outcomes, prints `{ ok, gates }`, and sets the process exit code EXPLICITLY
+    // (CI.tsx's error boundary is unreachable without a render, so this branch
+    // owns its exit code). `ok` is false iff a BLOCKING gate errored.
+    //
+    // JDA-A-002 / JDB-101: `ok` is deliberately scoped to blocking GATES (spec
+    // contract), so a blocking RUNNER/phase failure makes runCI throw yet leaves
+    // `ok:true`. A consumer keying on the object alone would misread that as
+    // success. Surfacing the top-level `exitCode` (non-zero on ANY run failure,
+    // including a crash) closes that gap without reinterpreting `ok`.
+    if (cli.flags.json) {
+        const { collectGateOutcomes } = await import("../../commands/ci.js");
+        const result = await collectGateOutcomes({
+            projectDir: process.cwd(),
+            mode: ciMode,
+            noDocker: !cli.flags.docker,
+            noGhagga: !cli.flags.ciGhagga,
+            noSecurity: !cli.flags.security,
+            timeout: cli.flags.timeout,
+            config: cli.flags.config || undefined,
+            stack: cli.flags.stack || undefined,
+        });
+        console.log(JSON.stringify({ ok: result.ok, exitCode: result.exitCode, gates: result.gates }, null, 2));
+        process.exit(result.exitCode);
+    }
     render(React.createElement(CIContextProvider, { isCI: true },
         React.createElement(CI, { projectDir: process.cwd(), mode: ciMode, noDocker: !cli.flags.docker, noGhagga: !cli.flags.ciGhagga, noSecurity: !cli.flags.security, timeout: cli.flags.timeout, config: cli.flags.config || undefined, stack: cli.flags.stack || undefined })), { stdin: ctx.inkStdin });
 }

package/dist/commands/ci.d.ts

@@ -1,4 +1,4 @@
-import { type CIGateConfig } from "../lib/ci-config.js";
+import { type CIGateConfig, type GateMode, type GateScope } from "../lib/ci-config.js";
 import type { Stack } from "../types/index.js";
 export type CIMode = "full" | "quick" | "shell" | "detect";
 export interface CIOptions {
@@ -79,7 +79,7 @@ export interface ResolveRunnerOptions {
  *   3. otherwise → single auto-detected runner (zero-config default)
  */
 export declare function resolveCIRunners(projectDir: string, options?: ResolveRunnerOptions): Promise<ResolvedRunners>;
-export declare function runCI(options: CIOptions, onStep: CIStepCallback): Promise<void>;
+export declare function runCI(options: CIOptions, onStep: CIStepCallback, onGateOutcome?: (outcome: GateOutcome) => void): 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
@@ -100,6 +100,50 @@ export declare function runCI(options: CIOptions, onStep: CIStepCallback): Promi
  * `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>;
+/**
+ * A single gate's structured result, collected for the headless JSON run path.
+ * Mirrors the `{ id, mode, scope, status, blocking, changedFiles?, exitCode? }`
+ * JSON shape.
+ */
+export interface GateOutcome {
+    id: string;
+    mode: GateMode;
+    scope: GateScope;
+    status: CIStepStatus;
+    /** `true` when `mode === blocking` — an errored blocking gate drives `ok:false`. */
+    blocking: boolean;
+    /** The changed-file set a scope:changed gate saw (present only when resolved). */
+    changedFiles?: string[];
+    /** 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.
+     */
+    reason?: string;
+}
+/** Structured result of a headless (`--json`) gate run. */
+export interface HeadlessGateResult {
+    /** `false` iff a BLOCKING gate errored; informative failures keep it `true`. */
+    ok: boolean;
+    gates: GateOutcome[];
+    /** The process exit code to set explicitly (1 on a blocking failure or crash). */
+    exitCode: number;
+}
+/**
+ * Drive `runCI` headlessly (no Ink render), collecting each gate's structured
+ * outcome for the `--json` run path. `runCI` throws on a blocking gate failure
+ * (and on any non-gate error); the outcomes are captured regardless via the
+ * `onOutcome` callback, so the JSON is always complete.
+ *
+ * `ok` is `false` iff a BLOCKING gate errored (spec contract); informative
+ * failures keep `ok:true`. `exitCode` is `1` when a blocking gate errored OR
+ * `runCI` threw for any other reason (a real crash still exits non-zero), else
+ * `0`. The caller (dispatch) prints `{ ok, gates }` and sets `process.exitCode`.
+ */
+export declare function collectGateOutcomes(options: CIOptions): Promise<HeadlessGateResult>;
 /**
  * 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

@@ -6,10 +6,11 @@ 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, GATE_MODE, loadCIConfig, } from "../lib/ci-config.js";
+import { CI_STACKS, findCIConfig, GATE_MODE, GATE_SCOPE, 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";
+import { changedFiles, resolveBaseRef } from "../lib/git-diff.js";
 // =============================================================================
 // Stack detection
 // =============================================================================
@@ -313,7 +314,7 @@ function describeRunners(resolved) {
         .join(", ");
     return `Config: ${resolved.runners.length} runner(s) — ${summary}`;
 }
-export async function runCI(options, onStep) {
+export async function runCI(options, onStep, onGateOutcome) {
     const { projectDir = process.cwd(), mode = "full", noDocker = false, noGhagga = false, noSecurity = false, timeout = 600, } = options;
     // ── Resolve runners (once — nothing downstream re-detects) ─────────────────
     const stepDetect = "detect";
@@ -342,7 +343,7 @@ export async function runCI(options, onStep) {
             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);
+        await runGates(resolved.gates, projectDir, onStep, onGateOutcome);
         return;
     }
     // Legacy single-runner view for the zero-config auto path. Keeping this
@@ -514,7 +515,7 @@ export async function runCI(options, onStep) {
     // 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);
+        await runGates(resolved.gates, projectDir, onStep, onGateOutcome);
     }
 }
 // =============================================================================
@@ -792,6 +793,19 @@ export async function runGateNative(cmd, cwd, env) {
         proc.on("error", reject);
     });
 }
+/**
+ * Env var carrying a scope:changed gate's newline-joined, root-relative paths.
+ *
+ * KNOWN LIMITATION (JDB-103): the list is newline-joined, so a path that itself
+ * contains a literal `\n` (git can emit such a path when `core.quotePath` is off)
+ * would corrupt line-based parsing on the gate side. This is a low-likelihood
+ * edge — repo paths with embedded newlines are pathological — and is accepted as
+ * a documented caveat rather than switched to NUL-joining, which would force
+ * every gate consumer to change its parser.
+ */
+const CHANGED_FILES_ENV = "JAVI_FORGE_CHANGED_FILES";
+/** Env var carrying a gate's optional baseline artifact path. */
+const BASELINE_ENV = "JAVI_FORGE_BASELINE";
 /**
  * Repo-level gate phase. Each gate runs host-native via `runGateNative` at the
  * repo root. Outcome semantics:
@@ -808,29 +822,101 @@ export async function runGateNative(cmd, cwd, env) {
  * 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.
+ * `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
+ * the gate with `$JAVI_FORGE_CHANGED_FILES` (newline-joined, root-relative); an
+ * empty set skips the gate; a null base OR a `changedFiles` throw skips every
+ * scope:changed gate with a named warning (loud-degrade, never widens, never
+ * crashes). `baseline` is injected as `$JAVI_FORGE_BASELINE`. Gate `env` spreads
+ * LAST (documented last-wins over the engine-injected keys).
+ *
+ * `onOutcome` (optional) receives each gate's structured result for the headless
+ * JSON run path.
  */
-async function runGates(gates, projectDir, onStep) {
+async function runGates(gates, projectDir, onStep, onOutcome) {
     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",
     };
+    // Lazily resolved and memoized — computed only when a scope:changed gate
+    // exists, and only once (shared across all scope:changed gates).
+    let changedScope = null;
+    const resolveChangedScope = async () => {
+        if (changedScope !== null)
+            return changedScope;
+        const base = await resolveBaseRef(process.env, projectDir);
+        if (base === null) {
+            changedScope = {
+                kind: "skip",
+                reason: "no base ref resolved — skipping scope:changed",
+            };
+            return changedScope;
+        }
+        try {
+            changedScope = {
+                kind: "files",
+                files: await changedFiles(base, projectDir),
+            };
+        }
+        catch {
+            // Shallow clone / base sha absent from local history: caught here so the
+            // throw never aborts the phase and the gate never widens to scope:all.
+            changedScope = {
+                kind: "skip",
+                reason: "changed-file diff failed (shallow clone / missing ref) — skipping scope:changed",
+            };
+        }
+        return changedScope;
+    };
     for (const gate of gates) {
         const stepId = `gate:${gate.id}`;
         const label = `Gate: ${gate.id}`;
+        const blocking = gate.mode === GATE_MODE.BLOCKING;
+        const emit = (status, extra) => onOutcome?.({
+            id: gate.id,
+            mode: gate.mode,
+            scope: gate.scope,
+            status,
+            blocking,
+            ...extra,
+        });
         report(onStep, stepId, label, "running");
+        // Per-gate env map: engine keys, then baseline, then gate.env LAST (last-wins).
+        const gateEnv = { ...baseEnv };
+        let gateChangedFiles;
+        if (gate.scope === GATE_SCOPE.CHANGED) {
+            const scope = await resolveChangedScope();
+            if (scope.kind === "skip") {
+                report(onStep, stepId, `${label} skipped`, "skipped", scope.reason);
+                // Loud-degrade: carry the named reason into the JSON outcome too, not
+                // only the Ink `onStep` stream (which is a no-op under --json).
+                emit("skipped", { reason: scope.reason });
+                continue;
+            }
+            if (scope.files.length === 0) {
+                const noChanges = "no changed files";
+                report(onStep, stepId, `${label} skipped`, "skipped", noChanges);
+                emit("skipped", { changedFiles: [], reason: noChanges });
+                continue;
+            }
+            gateChangedFiles = scope.files;
+            gateEnv[CHANGED_FILES_ENV] = scope.files.join("\n");
+        }
+        if (gate.baseline !== undefined) {
+            gateEnv[BASELINE_ENV] = gate.baseline;
+        }
+        if (gate.env !== undefined) {
+            // Gate env spreads LAST — a gate MAY override CI / CHANGED_FILES / BASELINE.
+            Object.assign(gateEnv, gate.env);
+        }
         let exitCode = 0;
         let spawnError;
         try {
             for (const cmd of gate.run) {
-                exitCode = await runGateNative(cmd, projectDir, baseEnv);
+                exitCode = await runGateNative(cmd, projectDir, gateEnv);
                 if (exitCode !== 0)
                     break; // fail-fast: skip the remaining commands
             }
@@ -840,21 +926,53 @@ async function runGates(gates, projectDir, onStep) {
         }
         if (spawnError === undefined && exitCode === 0) {
             report(onStep, stepId, `${label} passed`, "done");
+            emit("done", { changedFiles: gateChangedFiles });
             continue;
         }
         const detail = spawnError !== undefined ? String(spawnError) : `exit ${exitCode}`;
-        if (gate.mode === GATE_MODE.BLOCKING) {
+        if (blocking) {
             blockingFailures.push(gate.id);
             report(onStep, stepId, `${label} failed`, "error", detail);
+            emit("error", { changedFiles: gateChangedFiles, exitCode });
         }
         else {
             report(onStep, stepId, `${label} failed (informative)`, "warning", detail);
+            emit("warning", { changedFiles: gateChangedFiles, exitCode });
         }
     }
     if (blockingFailures.length > 0) {
         throw new Error(`blocking gate(s) failed: ${blockingFailures.join(", ")}`);
     }
 }
+/**
+ * Drive `runCI` headlessly (no Ink render), collecting each gate's structured
+ * outcome for the `--json` run path. `runCI` throws on a blocking gate failure
+ * (and on any non-gate error); the outcomes are captured regardless via the
+ * `onOutcome` callback, so the JSON is always complete.
+ *
+ * `ok` is `false` iff a BLOCKING gate errored (spec contract); informative
+ * failures keep `ok:true`. `exitCode` is `1` when a blocking gate errored OR
+ * `runCI` threw for any other reason (a real crash still exits non-zero), else
+ * `0`. The caller (dispatch) prints `{ ok, gates }` and sets `process.exitCode`.
+ */
+export async function collectGateOutcomes(options) {
+    const gates = [];
+    let threw = false;
+    try {
+        await runCI(options, () => { }, (outcome) => gates.push(outcome));
+    }
+    catch {
+        // Blocking failure (aggregate throw) or a non-gate error — outcomes are
+        // already captured; the headless path never propagates the throw.
+        threw = true;
+    }
+    const blockingErrored = gates.some((g) => g.blocking && g.status === "error");
+    return {
+        ok: !blockingErrored,
+        gates,
+        exitCode: blockingErrored || threw ? 1 : 0,
+    };
+}
 // =============================================================================
 // CI Hooks Installation
 // =============================================================================

package/dist/lib/git-diff.d.ts

@@ -3,7 +3,10 @@
  * 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`.
+ * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`;
+ *    else on a push, `$GITHUB_EVENT_BEFORE` (github.event.before — the real push
+ *    base, unless the all-zeros new-branch sentinel) before falling to
+ *    `$GITHUB_SHA` (which equals HEAD after actions/checkout → empty diff).
  * 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).

package/dist/lib/git-diff.js

@@ -52,7 +52,10 @@ async function tryMergeBase(ref, cwd) {
  * 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`.
+ * 3. `$GITHUB_BASE_REF` (GitHub Actions PR) → `git merge-base origin/<ref> HEAD`;
+ *    else on a push, `$GITHUB_EVENT_BEFORE` (github.event.before — the real push
+ *    base, unless the all-zeros new-branch sentinel) before falling to
+ *    `$GITHUB_SHA` (which equals HEAD after actions/checkout → empty diff).
  * 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).
@@ -68,12 +71,21 @@ export async function resolveBaseRef(env, cwd) {
         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.
+    //    target branch). A push has no base ref: prefer github.event.before
+    //    (GITHUB_EVENT_BEFORE — the commit the branch pointed at before the push,
+    //    the real diff base), unless it is the all-zeros new-branch sentinel, and
+    //    only then fall back to GITHUB_SHA (which equals HEAD after
+    //    actions/checkout → an empty diff → scope:changed gates would silently
+    //    skip; a visible skip, not a false-green — the before-sha avoids it).
     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_EVENT_BEFORE) &&
+        env.GITHUB_EVENT_BEFORE !== NEW_BRANCH_SENTINEL) {
+        return env.GITHUB_EVENT_BEFORE;
+    }
     else if (isNonEmpty(env.GITHUB_SHA)) {
         return env.GITHUB_SHA;
     }

package/package.json

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