javi-forge 1.10.0 → 1.11.0

package/dist/cli/dispatch/ci.js

@@ -33,14 +33,26 @@ export async function handleCi(cli, ctx) {
                 }
             }
             else if (cli.flags.json) {
-                console.log(JSON.stringify({ ok: true, runners: result.runners }, null, 2));
+                const gates = result.gates ?? [];
+                console.log(JSON.stringify({
+                    ok: true,
+                    runners: result.runners,
+                    ...(gates.length > 0 ? { gates } : {}),
+                }, null, 2));
             }
             else {
+                const gates = result.gates ?? [];
                 console.log(`✓ CI config valid: ${result.configPath}`);
                 console.log(`  ${result.runners.length} runner(s):`);
                 for (const runner of result.runners) {
                     console.log(`    - ${runner.name} (${runner.stack})`);
                 }
+                if (gates.length > 0) {
+                    console.log(`  ${gates.length} gate(s):`);
+                    for (const gate of gates) {
+                        console.log(`    - ${gate.id} (${gate.mode}, scope: ${gate.scope})`);
+                    }
+                }
             }
             process.exit(0);
         }

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

@@ -12,6 +12,12 @@ export interface CIValidateRunnerSummary {
     name: string;
     stack: string;
 }
+/** One validated gate, reduced to what the report shows. */
+export interface CIValidateGateSummary {
+    id: string;
+    mode: string;
+    scope: string;
+}
 export interface CIValidateOk {
     ok: true;
     /**
@@ -24,6 +30,8 @@ export interface CIValidateOk {
     /** Resolved config path, or null in auto-detect mode. */
     configPath: string | null;
     runners: CIValidateRunnerSummary[];
+    /** Declared gates (version 2). Empty when none are declared. */
+    gates: CIValidateGateSummary[];
 }
 export interface CIValidateErr {
     ok: false;

package/dist/commands/ci-validate.js

@@ -35,7 +35,13 @@ export async function validateCIConfig(projectDir, config) {
     else {
         const discovered = await findCIConfig(projectDir);
         if (!discovered) {
-            return { ok: true, mode: "auto-detect", configPath: null, runners: [] };
+            return {
+                ok: true,
+                mode: "auto-detect",
+                configPath: null,
+                runners: [],
+                gates: [],
+            };
         }
         configPath = discovered;
     }
@@ -49,6 +55,11 @@ export async function validateCIConfig(projectDir, config) {
                 name: r.name,
                 stack: r.stack,
             })),
+            gates: (ciConfig.gates ?? []).map((g) => ({
+                id: g.id,
+                mode: g.mode,
+                scope: g.scope,
+            })),
         };
     }
     catch (e) {

package/dist/commands/ci.js

@@ -83,13 +83,13 @@ async function buildCICommands(stack, buildTool, projectDir) {
         case "java-gradle":
             return {
                 lintCmd: "./gradlew spotlessCheck --no-daemon",
-                compileCmd: "./gradlew clean classes testClasses --no-daemon && chown -R runner:runner build/ .gradle/ 2>/dev/null || true",
+                compileCmd: "./gradlew clean classes testClasses --no-daemon",
                 testCmd: "./gradlew test --no-daemon",
             };
         case "java-maven":
             return {
                 lintCmd: "./mvnw spotless:check",
-                compileCmd: "./mvnw clean compile test-compile && chown -R runner:runner target/ .mvn/ 2>/dev/null || true",
+                compileCmd: "./mvnw clean compile test-compile",
                 testCmd: "./mvnw test",
             };
         case "node": {
@@ -101,14 +101,14 @@ async function buildCICommands(stack, buildTool, projectDir) {
             catch {
                 /* no package.json */
             }
-            // Clean dist/ before build and chown after so tests (as runner) can access output.
-            // Runs as root inside the container to handle host-owned output dirs.
+            // Clean dist/ before build so a stale directory never masks a broken
+            // build. The container runs as the host uid (see runInContainer,
+            // ENV-1), so output lands host-owned — no chown needed.
             const buildPrefix = "rm -rf dist/ && ";
-            const buildSuffix = " && chown -R runner:runner dist/ 2>/dev/null || true";
             return {
                 lintCmd: pkgContent.includes('"lint"') ? `${buildTool} run lint` : null,
                 compileCmd: pkgContent.includes('"build"')
-                    ? `${buildPrefix}${buildTool} run build${buildSuffix}`
+                    ? `${buildPrefix}${buildTool} run build`
                     : null,
                 testCmd: pkgContent.includes('"test"')
                     ? `${buildTool} ${buildTool === "npm" ? "test" : "run test"}`
@@ -124,13 +124,13 @@ async function buildCICommands(stack, buildTool, projectDir) {
         case "go":
             return {
                 lintCmd: "golangci-lint run",
-                compileCmd: "go clean -cache && go build ./... && chown -R runner:runner . 2>/dev/null || true",
+                compileCmd: "go clean -cache && go build ./...",
                 testCmd: "go test ./...",
             };
         case "rust":
             return {
                 lintCmd: "cargo clippy -- -D warnings",
-                compileCmd: "cargo clean && cargo build && chown -R runner:runner target/ 2>/dev/null || true",
+                compileCmd: "cargo clean && cargo build",
                 testCmd: "cargo test",
             };
         default:
@@ -349,10 +349,26 @@ export async function runCI(options, onStep) {
         report(onStep, "docker-image", "Building Docker image", "running");
         let shellImage;
         try {
-            shellImage = await ensureImage({
-                stack: stackInfo.stackType,
-                javaVersion: stackInfo.javaVersion,
-            });
+            // B2: honor a per-runner pinned image / build context the same way the
+            // runner loop does, instead of always deriving the stack default. An
+            // explicit image passes through verbatim; a build context is built with
+            // the deterministic per-runner tag; otherwise fall back to the stack image.
+            if (primary.image) {
+                shellImage = primary.image;
+            }
+            else if (primary.buildContext) {
+                shellImage = await ensureImage({
+                    stack: primary.stack,
+                    buildContext: path.resolve(projectDir, primary.buildContext),
+                    imageTag: `javi-forge-ci-${primary.name}`,
+                });
+            }
+            else {
+                shellImage = await ensureImage({
+                    stack: stackInfo.stackType,
+                    javaVersion: stackInfo.javaVersion,
+                });
+            }
             report(onStep, "docker-image", "Docker image ready", "done");
         }
         catch (e) {
@@ -411,10 +427,16 @@ export async function runCI(options, onStep) {
         report(onStep, stepContext, "Refresh .context/ directory", "error", String(e));
     }
     // ── Runner execution ─────────────────────────────────────────────────────────
-    // ONE executor for every resolution source. Naming is a function of
-    // `resolved.source` alone — never of `resolved.runners.length`, which would
-    // silently rename a single-runner CONFIG.
-    const naming = resolved.source === "auto" ? NAMING_MODE.BARE : NAMING_MODE.SUFFIXED;
+    // ONE executor for every resolution source. Naming is a function of whether
+    // the runner NAME is IMPLICIT or EXPLICIT — never of `resolved.runners.length`,
+    // which would silently rename a single-runner CONFIG (B1):
+    //   - IMPLICIT name → BARE ids: `auto` (zero-config) OR `stack-override`
+    //     (`--stack`, the user never named the runner).
+    //   - EXPLICIT name → SUFFIXED ids: `config` (a runner named in ci.yaml).
+    const implicitName = resolved.source === "auto" || resolved.source === "stack-override";
+    const naming = implicitName
+        ? NAMING_MODE.BARE
+        : NAMING_MODE.SUFFIXED;
     for (const runner of resolved.runners) {
         await runRunner(runner, {
             projectDir,
@@ -499,7 +521,10 @@ async function runRunner(runner, ctx) {
             imageName = ctx.preresolvedImage;
         }
         else {
-            const stepImage = `docker-image:${runner.name}`;
+            // Under an IMPLICIT name (bare) the image step id is unsuffixed too, so a
+            // `--stack` run reads identically to zero-config auto. A CONFIG runner
+            // (suffixed) keeps `docker-image:<name>` (the R3 guard).
+            const stepImage = bare ? "docker-image" : `docker-image:${runner.name}`;
             try {
                 if (runner.buildContext) {
                     report(onStep, stepImage, `Building image for ${runner.name} from ${runner.buildContext}`, "running");
@@ -565,7 +590,6 @@ async function runRunner(runner, ctx) {
             id: "compile",
             label: "Compile",
             cmds: runner.compileCmds,
-            user: "root",
             skip: false,
         },
         {

package/dist/lib/ci-config.d.ts

@@ -10,6 +10,20 @@
  */
 import type { Stack } from "../types/index.js";
 export declare const CI_CONFIG_VERSION = 1;
+/** Config schema versions this loader accepts. v2 is additive (unlocks gates). */
+export declare const CI_CONFIG_VERSIONS: readonly number[];
+/** Gate outcome mode: a blocking gate fails the build, informative degrades. */
+export declare const GATE_MODE: {
+    readonly BLOCKING: "blocking";
+    readonly INFORMATIVE: "informative";
+};
+export type GateMode = (typeof GATE_MODE)[keyof typeof GATE_MODE];
+/** Gate file scope: all files, or only the changed set (slice 4 wiring). */
+export declare const GATE_SCOPE: {
+    readonly ALL: "all";
+    readonly CHANGED: "changed";
+};
+export type GateScope = (typeof GATE_SCOPE)[keyof typeof GATE_SCOPE];
 /** Default config locations, in discovery order, relative to the project root. */
 export declare const CI_CONFIG_CANDIDATES: readonly [".javi-forge/ci.yaml", ".javi-forge/ci.yml"];
 export interface CIRunnerConfig {
@@ -32,9 +46,26 @@ export interface CIRunnerConfig {
     /** Tools that must exist in the runner environment (validated fail-closed) */
     requires: string[];
 }
+/** A declarable named quality gate (version 2 only). Runs host-native. */
+export interface CIGateConfig {
+    /** Unique, tag-safe identifier (reuses RUNNER_NAME_RE). */
+    id: string;
+    /** Command(s) to run — string or list, normalized to a list. */
+    run: string[];
+    /** blocking (default) fails the build; informative degrades to a warning. */
+    mode: GateMode;
+    /** all (default) or changed — the file scope the gate cares about. */
+    scope: GateScope;
+    /** Optional baseline artifact path (slice 4). */
+    baseline?: string;
+    /** Optional env injected via the child-process env map (slice 4). */
+    env?: Record<string, string>;
+}
 export interface CIConfig {
     version: number;
     runners: CIRunnerConfig[];
+    /** Present only under version 2 when `gates:` is declared. */
+    gates?: CIGateConfig[];
 }
 export interface CIConfigValidationError {
     path: string;
@@ -46,6 +77,12 @@ export declare class CIConfigError extends Error {
 }
 /** Stacks accepted by the CI config schema and the --stack override. */
 export declare const CI_STACKS: readonly string[];
+/**
+ * Validate the `gates:` block (version 2 only). Every schema error names the
+ * offending field; a duplicate id is reported once. Returns the parsed gates
+ * (the caller discards them all if `errors` is non-empty — fail closed).
+ */
+export declare function validateGates(raw: unknown, errors: CIConfigValidationError[]): CIGateConfig[];
 /**
  * Parse and validate CI config YAML text. Throws CIConfigError listing every
  * validation problem; never returns a partially valid config.

package/dist/lib/ci-config.js

@@ -15,6 +15,18 @@ import YAML from "yaml";
 // Types
 // =============================================================================
 export const CI_CONFIG_VERSION = 1;
+/** Config schema versions this loader accepts. v2 is additive (unlocks gates). */
+export const CI_CONFIG_VERSIONS = [1, 2];
+/** Gate outcome mode: a blocking gate fails the build, informative degrades. */
+export const GATE_MODE = {
+    BLOCKING: "blocking",
+    INFORMATIVE: "informative",
+};
+/** Gate file scope: all files, or only the changed set (slice 4 wiring). */
+export const GATE_SCOPE = {
+    ALL: "all",
+    CHANGED: "changed",
+};
 /** Default config locations, in discovery order, relative to the project root. */
 export const CI_CONFIG_CANDIDATES = [
     ".javi-forge/ci.yaml",
@@ -202,6 +214,144 @@ function validateRunner(raw, index, errors) {
         requires,
     };
 }
+const GATE_FIELDS = new Set(["id", "run", "mode", "scope", "baseline", "env"]);
+function validateGate(raw, index, errors) {
+    const base = `gates[${index}]`;
+    if (!isRecord(raw)) {
+        errors.push({ path: base, message: "gate must be an object" });
+        return null;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!GATE_FIELDS.has(key)) {
+            errors.push({
+                path: `${base}.${key}`,
+                message: `unknown field "${key}"`,
+            });
+        }
+    }
+    const id = raw.id;
+    if (typeof id !== "string" || !id.trim()) {
+        errors.push({
+            path: `${base}.id`,
+            message: "id is required and must be a non-empty string",
+        });
+    }
+    else if (!RUNNER_NAME_RE.test(id.trim())) {
+        errors.push({
+            path: `${base}.id`,
+            message: "id must start with a letter, digit or underscore and contain only [a-zA-Z0-9._-] (it is used as a tag)",
+        });
+    }
+    const run = normalizeCommands(raw.run, `${base}.run`, errors);
+    if (raw.run === undefined) {
+        errors.push({
+            path: `${base}.run`,
+            message: "run is required and must be a non-empty string or a list of non-empty strings",
+        });
+    }
+    else if (run.length === 0 &&
+        !errors.some((e) => e.path === `${base}.run`)) {
+        errors.push({
+            path: `${base}.run`,
+            message: "run must be a non-empty string or a list of non-empty strings",
+        });
+    }
+    let mode = GATE_MODE.BLOCKING;
+    if (raw.mode !== undefined) {
+        if (raw.mode === GATE_MODE.BLOCKING || raw.mode === GATE_MODE.INFORMATIVE) {
+            mode = raw.mode;
+        }
+        else {
+            errors.push({
+                path: `${base}.mode`,
+                message: `mode must be one of: ${GATE_MODE.BLOCKING}, ${GATE_MODE.INFORMATIVE} (got "${String(raw.mode)}")`,
+            });
+        }
+    }
+    let scope = GATE_SCOPE.ALL;
+    if (raw.scope !== undefined) {
+        if (raw.scope === GATE_SCOPE.ALL || raw.scope === GATE_SCOPE.CHANGED) {
+            scope = raw.scope;
+        }
+        else {
+            errors.push({
+                path: `${base}.scope`,
+                message: `scope must be one of: ${GATE_SCOPE.ALL}, ${GATE_SCOPE.CHANGED} (got "${String(raw.scope)}")`,
+            });
+        }
+    }
+    let baseline;
+    if (raw.baseline !== undefined) {
+        if (typeof raw.baseline !== "string" || !raw.baseline.trim()) {
+            errors.push({
+                path: `${base}.baseline`,
+                message: "baseline must be a non-empty string (path)",
+            });
+        }
+        else {
+            baseline = raw.baseline;
+        }
+    }
+    let env;
+    if (raw.env !== undefined) {
+        if (!isRecord(raw.env)) {
+            errors.push({
+                path: `${base}.env`,
+                message: "env must be a mapping of string keys to string values",
+            });
+        }
+        else if (Object.values(raw.env).some((v) => typeof v !== "string")) {
+            errors.push({
+                path: `${base}.env`,
+                message: "env values must all be strings",
+            });
+        }
+        else {
+            env = raw.env;
+        }
+    }
+    return {
+        id: typeof id === "string" ? id.trim() : "",
+        run,
+        mode,
+        scope,
+        baseline,
+        env,
+    };
+}
+/**
+ * Validate the `gates:` block (version 2 only). Every schema error names the
+ * offending field; a duplicate id is reported once. Returns the parsed gates
+ * (the caller discards them all if `errors` is non-empty — fail closed).
+ */
+export function validateGates(raw, errors) {
+    if (!Array.isArray(raw)) {
+        errors.push({ path: "gates", message: "gates must be a non-empty list" });
+        return [];
+    }
+    if (raw.length === 0) {
+        errors.push({ path: "gates", message: "gates must be a non-empty list" });
+        return [];
+    }
+    const gates = [];
+    const seen = new Set();
+    raw.forEach((item, index) => {
+        const gate = validateGate(item, index, errors);
+        if (!gate)
+            return;
+        if (gate.id) {
+            if (seen.has(gate.id)) {
+                errors.push({
+                    path: `gates[${index}].id`,
+                    message: `duplicate gate id "${gate.id}"`,
+                });
+            }
+            seen.add(gate.id);
+        }
+        gates.push(gate);
+    });
+    return gates;
+}
 // =============================================================================
 // Public API
 // =============================================================================
@@ -226,23 +376,54 @@ export function parseCIConfig(rawYaml, source) {
     if (!isRecord(doc)) {
         throw new CIConfigError([{ path: "<document>", message: "config must be a YAML object/mapping" }], source);
     }
-    for (const key of Object.keys(doc)) {
-        if (!TOP_LEVEL_FIELDS.has(key)) {
-            errors.push({ path: key, message: `unknown field "${key}"` });
-        }
-    }
-    if (doc.version !== CI_CONFIG_VERSION) {
+    // Read the version FIRST: the allowed-key set is a function of the accepted
+    // version, so `gates` under v1 reports the named "gates require version: 2"
+    // error, never the generic unknown-field error (JDA-006).
+    const version = typeof doc.version === "number" && CI_CONFIG_VERSIONS.includes(doc.version)
+        ? doc.version
+        : undefined;
+    if (version === undefined) {
         errors.push({
             path: "version",
-            message: `version is required and must be the number ${CI_CONFIG_VERSION}`,
+            message: `version is required and must be one of: ${CI_CONFIG_VERSIONS.join(", ")}`,
         });
     }
-    if (!Array.isArray(doc.runners) || doc.runners.length === 0) {
+    const isV2 = version === 2;
+    const hasGates = doc.gates !== undefined;
+    for (const key of Object.keys(doc)) {
+        if (TOP_LEVEL_FIELDS.has(key))
+            continue;
+        if (key === "gates") {
+            // `gates` is only a known key under v2; under any other version it is a
+            // named schema error that takes precedence over the generic path.
+            if (!isV2) {
+                errors.push({ path: "gates", message: "gates require version: 2" });
+            }
+            continue;
+        }
+        errors.push({ path: key, message: `unknown field "${key}"` });
+    }
+    if (isV2) {
+        // v2: runners OPTIONAL when gates present; NEITHER runners nor gates fails
+        // closed (nothing to run).
+        if (!hasGates &&
+            (!Array.isArray(doc.runners) || doc.runners.length === 0)) {
+            errors.push({
+                path: "runners",
+                message: "a version 2 config must declare runners or gates (nothing to run otherwise)",
+            });
+        }
+    }
+    else if (!Array.isArray(doc.runners) || doc.runners.length === 0) {
+        // v1 (and invalid-version) still hard-require a non-empty runners list.
         errors.push({
             path: "runners",
             message: "runners is required and must be a non-empty list",
         });
     }
+    // Gates are validated ONLY under v2 — a v1+gates config is already rejected
+    // above and must not surface a second, confusing wave of gate-field errors.
+    const gates = isV2 && hasGates ? validateGates(doc.gates, errors) : [];
     const runners = [];
     if (Array.isArray(doc.runners)) {
         doc.runners.forEach((raw, index) => {
@@ -266,7 +447,12 @@ export function parseCIConfig(rawYaml, source) {
     if (errors.length > 0) {
         throw new CIConfigError(errors, source);
     }
-    return { version: CI_CONFIG_VERSION, runners };
+    // `version` is defined here (an undefined version pushed an error above and
+    // would have thrown). A v1 config carries NO gates key — byte-identical shape.
+    const config = { version: version ?? CI_CONFIG_VERSION, runners };
+    if (gates.length > 0)
+        config.gates = gates;
+    return config;
 }
 /**
  * Load and validate a CI config file. Fails closed: a missing file or any

package/dist/lib/docker.js

@@ -189,6 +189,20 @@ export async function runInContainer(options) {
     // detection happens on this path — ever.
     const imageName = image;
     const isInteractive = process.stdin.isTTY && stream;
+    // ENV-1: match the container process to the HOST user. The images bake a
+    // `runner` user whose uid depends on the base (1001 on node:22-slim, where
+    // uid 1000 is already `node`). When that uid differs from the host uid,
+    // everything the container writes to the bind-mounted workspace (dist/,
+    // node_modules/.vite-temp, build output) lands owned by the wrong user,
+    // and the host's local vitest then fails with EACCES. Running as the host
+    // uid:gid makes artifacts host-owned — no chown dance, ever. An explicit
+    // `user` override still wins (e.g. a caller that needs root). getuid/getgid
+    // are undefined on non-POSIX platforms (Windows); there we omit the flag
+    // and keep the image default.
+    const uid = process.getuid?.();
+    const gid = process.getgid?.();
+    const runAsUser = user ??
+        (uid !== undefined && gid !== undefined ? `${uid}:${gid}` : undefined);
     // Use --mount instead of -v: the -v form parses the value as a single
     // "src:dst[:opt]" colon-separated string, which breaks (and could be
     // hijacked) when projectDir itself contains a colon. --mount takes
@@ -201,7 +215,7 @@ export async function runInContainer(options) {
         "30",
         "--entrypoint",
         "",
-        ...(user ? ["--user", user] : []),
+        ...(runAsUser ? ["--user", runAsUser] : []),
         "--mount",
         `type=bind,source=${projectDir},target=/home/runner/work`,
         "-e",
@@ -237,6 +251,11 @@ export async function runInContainer(options) {
  */
 export async function openShell(projectDir, image) {
     const imageName = image;
+    // ENV-1: run the interactive shell as the host user too, so anything
+    // written from the debug shell stays host-owned. See runInContainer.
+    const uid = process.getuid?.();
+    const gid = process.getgid?.();
+    const runAsUser = uid !== undefined && gid !== undefined ? `${uid}:${gid}` : undefined;
     await new Promise((resolve, reject) => {
         const proc = spawn("docker", [
             "run",
@@ -244,6 +263,7 @@ export async function openShell(projectDir, image) {
             "-it",
             "--entrypoint",
             "",
+            ...(runAsUser ? ["--user", runAsUser] : []),
             // --mount is colon-safe; see runInContainer for the rationale.
             "--mount",
             `type=bind,source=${projectDir},target=/home/runner/work`,

package/package.json

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