javi-forge 1.20.0 → 1.21.1

package/dist/commands/ci.js

@@ -8,7 +8,7 @@ import fs from "fs-extra";
 import { HOOK_ASSETS_DIR } from "../constants.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 { CONTAINER_WORKDIR, ensureImage, isDockerAvailable, openShell, runInContainer, } from "../lib/docker.js";
 import { execFileAsync } from "../lib/exec.js";
 import { changedFiles, resolveBaseRef } from "../lib/git-diff.js";
 // =============================================================================
@@ -880,9 +880,32 @@ const GATE_TIMEOUT_EXIT_CODE = 124;
  * 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.
+ * every gate consumer to change its parser. A NUL-joined variant is also
+ * infeasible for a deeper reason (see {@link CHANGED_FILES_ABS_ENV}): a NUL byte
+ * cannot be carried in an environment variable at all.
  */
 const CHANGED_FILES_ENV = "JAVI_FORGE_CHANGED_FILES";
+/**
+ * Env var carrying the SAME changed-file set as {@link CHANGED_FILES_ENV}, but as
+ * ABSOLUTE paths, newline-joined, in the SAME order.
+ *
+ * WHY absolute and not "cwd-relative": a literal cwd-relative variant is
+ * impossible for the engine to produce. A gate chooses its own working directory
+ * at runtime (its script may `cd` anywhere), while at injection time the engine's
+ * cwd is always the repo root — so a "cwd-relative" var would just equal the
+ * repo-root-relative {@link CHANGED_FILES_ENV}. The cwd-INDEPENDENT form that lets
+ * a gate resolve changed files from ANY working directory is absolute paths.
+ *
+ * CONTEXT-DEPENDENT base (JDA-001): this is the ONE injected var whose VALUE must
+ * differ between execution modes, so it is NOT placed in the shared `injected`
+ * map. A NATIVE gate runs at the host repo root, so its base is the HOST
+ * `<projectDir>/<relpath>`. A CONTAINER gate runs with the repo bind-mounted at
+ * `CONTAINER_WORKDIR` (docker.ts mount target + WORKDIR), so its base is
+ * `<CONTAINER_WORKDIR>/<relpath>` — the HOST projectDir does not exist inside the
+ * container. Same var NAME in both; each gate sees the value valid for its own
+ * execution context.
+ */
+const CHANGED_FILES_ABS_ENV = "JAVI_FORGE_CHANGED_FILES_ABS";
 /** Env var carrying a gate's optional baseline artifact path. */
 const BASELINE_ENV = "JAVI_FORGE_BASELINE";
 /**
@@ -942,7 +965,7 @@ async function runGateCommand(gate, cmd, projectDir, nativeEnv, containerEnv) {
         projectDir,
         image: gate.image,
         // Gates run at the mount root (native gates run at the repo root).
-        command: `cd /home/runner/work && ${cmd}`,
+        command: `cd ${CONTAINER_WORKDIR} && ${cmd}`,
         timeout: gate.timeout, // undefined ⇒ unbounded (docker.ts gate 7)
         env: containerEnv,
         stream: true,
@@ -1063,19 +1086,58 @@ docker, onOutcome) {
             }
             gateChangedFiles = scope.files;
             injected[CHANGED_FILES_ENV] = scope.files.join("\n");
+            // ABSOLUTE-path variant (GATE-4 / JDA-001) is DELIBERATELY NOT put in the
+            // shared `injected` map: it is the ONE var whose value MUST differ between
+            // native and container execution. A native gate runs at the host repo root
+            // (cwd = projectDir), so its base is the HOST projectDir. A containerized
+            // gate runs with the repo bind-mounted at CONTAINER_WORKDIR (docker.ts mount
+            // target + WORKDIR), so `<projectDir>/<relpath>` would point at a
+            // non-existent HOST path inside the container. Instead it is computed twice
+            // below — once per execution context — and added to nativeEnv / containerEnv
+            // separately. See the nativeEnv / containerEnv construction.
+            // NUL-joined variant (GATE-5) is DELIBERATELY NOT INJECTED. A `git -z`
+            // style NUL separator is unambiguous for paths containing a literal
+            // newline, BUT a NUL byte cannot live in an environment variable: execve's
+            // `environ` is an array of NUL-terminated C strings, so a NUL inside a
+            // value truncates it. Node's child_process refuses it outright — it throws
+            // ERR_INVALID_ARG_VALUE ("must be a string without null bytes") for a NUL
+            // in BOTH an argv element (container `-e KEY=VALUE`) AND a spawn env-map
+            // value (native gates). Empirically verified against Node + `docker run`.
+            // Injecting JAVI_FORGE_CHANGED_FILES_Z would therefore CRASH every
+            // scope:changed gate at spawn time (native and containerized alike), so it
+            // is omitted entirely rather than shipped broken. The documented caveat on
+            // CHANGED_FILES_ENV (paths with embedded newlines corrupt line parsing)
+            // stands; the cwd-independent alternative that IS deliverable is
+            // CHANGED_FILES_ABS_ENV above.
         }
         if (gate.baseline !== undefined) {
             injected[BASELINE_ENV] = gate.baseline;
         }
         const gateOverrides = gate.env ?? {};
+        // Context-dependent ABSOLUTE-path variant (JDA-001): the SAME env var NAME,
+        // but a DIFFERENT base per execution mode. Native gates resolve against the
+        // HOST projectDir (cwd = repo root); container gates resolve against
+        // CONTAINER_WORKDIR — the exact mount target from docker.ts (single source of
+        // truth), so the "absolute" path is valid INSIDE the container. Both use the
+        // SAME relpaths in the SAME order, newline-joined, only for scope:changed
+        // (gateChangedFiles defined). path.join for native normalizes a trailing
+        // slash; the container form is a POSIX join under a known-absolute root.
+        const nativeAbs = gateChangedFiles &&
+            gateChangedFiles.map((rel) => path.join(projectDir, rel)).join("\n");
+        const containerAbs = gateChangedFiles &&
+            gateChangedFiles.map((rel) => `${CONTAINER_WORKDIR}/${rel}`).join("\n");
         const nativeEnv = {
             ...baseEnv,
             ...injected,
+            ...(nativeAbs !== undefined && { [CHANGED_FILES_ABS_ENV]: nativeAbs }),
             ...gateOverrides,
         };
         const containerEnv = {
             CI: "true",
             ...injected,
+            ...(containerAbs !== undefined && {
+                [CHANGED_FILES_ABS_ENV]: containerAbs,
+            }),
             ...gateOverrides,
         };
         let exitCode = 0;

package/dist/lib/ci-config.js

@@ -77,6 +77,35 @@ const RUNNER_FIELDS = new Set([
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Validate an optional container `image` ref shared by the runner and gate
+ * paths (IMG-1). Rejects non-string / empty-after-trim and leading-dash refs
+ * (an image like "--privileged" or "-v /:/host" would be parsed by `docker run`
+ * as a FLAG, not an image, if it reached argv — JDB-004) with a named error at
+ * `fieldPath`. Returns the TRIMMED value to store, so a whitespace-padded ref
+ * fails cleanly at validation instead of reaching docker argv untrimmed.
+ * Returns undefined when the field is absent or invalid.
+ */
+function validateImageRef(value, fieldPath, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.trim()) {
+        errors.push({
+            path: fieldPath,
+            message: "image must be a non-empty string",
+        });
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed.startsWith("-")) {
+        errors.push({
+            path: fieldPath,
+            message: "image must not start with '-' (would be parsed as a docker flag)",
+        });
+        return undefined;
+    }
+    return trimmed;
+}
 function normalizeCommands(value, fieldPath, errors) {
     if (value === undefined)
         return [];
@@ -159,18 +188,7 @@ function validateRunner(raw, index, errors) {
             }
         }
     }
-    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 {
-            image = raw.image;
-        }
-    }
+    const image = validateImageRef(raw.image, `${base}.image`, errors);
     let buildContext;
     if (raw["build-context"] !== undefined) {
         if (typeof raw["build-context"] !== "string" ||
@@ -319,28 +337,7 @@ 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;
-        }
-    }
+    const image = validateImageRef(raw.image, `${base}.image`, errors);
     let timeout;
     if (raw.timeout !== undefined) {
         if (typeof raw.timeout !== "number" ||

package/dist/lib/docker.d.ts

@@ -1,4 +1,12 @@
 import type { Stack } from "../types/index.js";
+/**
+ * The in-container path the repo is bind-mounted at (and the WORKDIR gates run
+ * from). This is the SINGLE source of truth for the mount target: the `--mount`
+ * bind target below and the container-side `JAVI_FORGE_CHANGED_FILES_ABS` base
+ * in ci.ts MUST reference this same constant so they can never drift — the
+ * container absolute-path invariant is "abs base === mount target".
+ */
+export declare const CONTAINER_WORKDIR = "/home/runner/work";
 export interface DockerRunOptions {
     /** Absolute path to mount as /home/runner/work */
     projectDir: string;

package/dist/lib/docker.js

@@ -4,6 +4,17 @@ import path from "node:path";
 import fs from "fs-extra";
 import { execFileAsync } from "./exec.js";
 // =============================================================================
+// Constants
+// =============================================================================
+/**
+ * The in-container path the repo is bind-mounted at (and the WORKDIR gates run
+ * from). This is the SINGLE source of truth for the mount target: the `--mount`
+ * bind target below and the container-side `JAVI_FORGE_CHANGED_FILES_ABS` base
+ * in ci.ts MUST reference this same constant so they can never drift — the
+ * container absolute-path invariant is "abs base === mount target".
+ */
+export const CONTAINER_WORKDIR = "/home/runner/work";
+// =============================================================================
 // Image name
 // =============================================================================
 export function getImageName(stack) {
@@ -236,7 +247,7 @@ export async function runInContainer(options) {
         "",
         ...(runAsUser ? ["--user", runAsUser] : []),
         "--mount",
-        `type=bind,source=${projectDir},target=/home/runner/work`,
+        `type=bind,source=${projectDir},target=${CONTAINER_WORKDIR}`,
         ...envArgs,
         imageName,
         "bash",
@@ -328,13 +339,13 @@ export async function openShell(projectDir, image) {
             ...(runAsUser ? ["--user", runAsUser] : []),
             // --mount is colon-safe; see runInContainer for the rationale.
             "--mount",
-            `type=bind,source=${projectDir},target=/home/runner/work`,
+            `type=bind,source=${projectDir},target=${CONTAINER_WORKDIR}`,
             "-e",
             "CI=true",
             imageName,
             "bash",
             "-c",
-            "cd /home/runner/work && exec bash",
+            `cd ${CONTAINER_WORKDIR} && exec bash`,
         ], { stdio: "inherit" });
         proc.on("close", () => resolve());
         proc.on("error", reject);

package/package.json

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