javi-forge 1.9.1 → 1.10.1

package/dist/cli/dispatch/ci.js

@@ -11,7 +11,49 @@ import { render } from "ink";
 import React from "react";
 import CI from "../../ui/CI.js";
 import { CIProvider as CIContextProvider } from "../../ui/CIContext.js";
+import { CI_HELP_TEXT } from "../help.js";
 export async function handleCi(cli, ctx) {
+    // Per-command help: `javi-forge ci --help` shows ci-specific usage, not the
+    // global banner (autoHelp is disabled at the entrypoint).
+    if (cli.flags.help === true) {
+        console.log(CI_HELP_TEXT);
+        process.exit(0);
+    }
+    // Sub-command: javi-forge ci validate → dry config validation, no execution.
+    if (cli.input[1] === "validate") {
+        const { validateCIConfig } = await import("../../commands/ci-validate.js");
+        const result = await validateCIConfig(process.cwd(), cli.flags.config || undefined);
+        if (result.ok) {
+            if (result.mode === "auto-detect") {
+                if (cli.flags.json) {
+                    console.log(JSON.stringify({ ok: true, mode: "auto-detect", runners: [] }, null, 2));
+                }
+                else {
+                    console.log("✓ No .javi-forge/ci.yaml — auto-detect mode (no config to validate)");
+                }
+            }
+            else if (cli.flags.json) {
+                console.log(JSON.stringify({ ok: true, runners: result.runners }, null, 2));
+            }
+            else {
+                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})`);
+                }
+            }
+            process.exit(0);
+        }
+        if (cli.flags.json) {
+            console.log(JSON.stringify({ ok: false, errors: result.errors }, null, 2));
+        }
+        else {
+            for (const err of result.errors) {
+                console.error(`${err.path}: ${err.message}`);
+            }
+        }
+        process.exit(1);
+    }
     // Sub-command: javi-forge ci init → install git hooks
     if (cli.input[1] === "init") {
         const { installCIHooks } = await import("../../commands/ci.js");
@@ -36,6 +78,12 @@ export async function handleCi(cli, ctx) {
         }
         process.exit(errors.length > 0 ? 1 : 0);
     }
+    // Any other positional is an unknown subcommand — show ci usage, don't run
+    // the pipeline against a typo.
+    if (cli.input[1] !== undefined) {
+        console.log(CI_HELP_TEXT);
+        process.exit(1);
+    }
     const ciMode = cli.flags.detect
         ? "detect"
         : cli.flags.shell

package/dist/cli/help.d.ts

@@ -8,8 +8,19 @@
  * Help banner shown by meow when `--help` is passed or invalid args are supplied.
  * Multi-line template literal — preserve exact formatting (whitespace is significant).
  */
-export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+/**
+ * Per-command help for `ci`, shown by `javi-forge ci --help` (or when `ci` is
+ * given an unknown subcommand). Kept consistent with the global HELP_TEXT
+ * layout — whitespace is significant.
+ */
+export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand] [options]\n\n    Run a local CI simulation (lint + compile + test + security + ghagga).\n    With no subcommand, the full pipeline runs.\n\n  Subcommands\n    init            Install git hooks that call javi-forge ci\n    validate        Validate .javi-forge/ci.yaml without running anything\n\n  Options\n    --quick         Lint + compile only (fast, for pre-commit)\n    --no-docker     Run commands natively (no Docker)\n    --no-security   Skip Semgrep security scan\n    --no-ci-ghagga  Skip GHAGGA review\n    --force         (ci init) Overwrite a foreign or modified hook (backs up first)\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only)\n    --json          (ci validate) Emit the result as JSON\n    --help          Show this help\n\n  Examples\n    $ javi-forge ci\n    $ javi-forge ci --quick\n    $ javi-forge ci validate\n    $ javi-forge ci validate --json\n    $ javi-forge ci init --force\n";
 export declare const FLAGS_SCHEMA: {
+    readonly help: {
+        readonly type: "boolean";
+        readonly shortFlag: "h";
+        readonly default: false;
+    };
     readonly dryRun: {
         readonly type: "boolean";
         readonly default: false;

package/dist/cli/help.js

@@ -15,6 +15,8 @@ export const HELP_TEXT = `
   Commands
     init              Bootstrap a new project (default)
     ci                Run CI simulation (lint + compile + test + security + ghagga)
+    ci validate       Validate .javi-forge/ci.yaml without running anything
+    ci init           Install git hooks that call javi-forge ci
     tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)
     tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)
     analyze           Run repoforge skills analysis
@@ -99,12 +101,52 @@ export const HELP_TEXT = `
     $ javi-forge ci --no-docker
     $ javi-forge ci --shell
     $ javi-forge ci --config .javi-forge/ci.yaml
+    $ javi-forge ci validate
+    $ javi-forge ci --help
     $ javi-forge analyze
     $ javi-forge doctor
     $ javi-forge plugin add mapbox/agent-skills
     $ javi-forge plugin list
 `;
+/**
+ * Per-command help for `ci`, shown by `javi-forge ci --help` (or when `ci` is
+ * given an unknown subcommand). Kept consistent with the global HELP_TEXT
+ * layout — whitespace is significant.
+ */
+export const CI_HELP_TEXT = `
+  Usage
+    $ javi-forge ci [subcommand] [options]
+
+    Run a local CI simulation (lint + compile + test + security + ghagga).
+    With no subcommand, the full pipeline runs.
+
+  Subcommands
+    init            Install git hooks that call javi-forge ci
+    validate        Validate .javi-forge/ci.yaml without running anything
+
+  Options
+    --quick         Lint + compile only (fast, for pre-commit)
+    --no-docker     Run commands natively (no Docker)
+    --no-security   Skip Semgrep security scan
+    --no-ci-ghagga  Skip GHAGGA review
+    --force         (ci init) Overwrite a foreign or modified hook (backs up first)
+    --config PATH   Load ordered CI runners from a versioned config file
+                    (default discovery: .javi-forge/ci.yaml)
+    --stack STACK   Force a single explicit stack (single-stack repos only)
+    --json          (ci validate) Emit the result as JSON
+    --help          Show this help
+
+  Examples
+    $ javi-forge ci
+    $ javi-forge ci --quick
+    $ javi-forge ci validate
+    $ javi-forge ci validate --json
+    $ javi-forge ci init --force
+`;
 export const FLAGS_SCHEMA = {
+    // `--help` is handled manually (autoHelp is disabled at the entrypoint so
+    // `ci --help` can show ci-specific usage instead of the global banner).
+    help: { type: "boolean", shortFlag: "h", default: false },
     dryRun: { type: "boolean", default: false },
     stack: { type: "string", default: "" },
     ci: { type: "string", default: "" },

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

@@ -0,0 +1,42 @@
+/**
+ * `javi-forge ci validate` — dry validation of `.javi-forge/ci.yaml`.
+ *
+ * Pure parse-and-report over the existing validator (src/lib/ci-config.ts):
+ * resolve the config path (same discovery `runCI` uses), call `loadCIConfig`,
+ * and return a structured result. It NEVER builds images, runs Docker, or
+ * executes any phase — the CLI surface stops BEFORE execution.
+ */
+import { type CIConfigValidationError } from "../lib/ci-config.js";
+/** One validated runner, reduced to what the report shows. */
+export interface CIValidateRunnerSummary {
+    name: string;
+    stack: string;
+}
+export interface CIValidateOk {
+    ok: true;
+    /**
+     * "config" — a config file was found and validated.
+     * "auto-detect" — no config exists and none was explicitly requested, so
+     * `runCI` would use its zero-config single-runner auto-detect path
+     * (ci.ts:396-406). There is nothing to validate, and that is valid.
+     */
+    mode: "config" | "auto-detect";
+    /** Resolved config path, or null in auto-detect mode. */
+    configPath: string | null;
+    runners: CIValidateRunnerSummary[];
+}
+export interface CIValidateErr {
+    ok: false;
+    /** Resolved path we looked at, or null when discovery found nothing. */
+    configPath: string | null;
+    errors: CIConfigValidationError[];
+}
+export type CIValidateResult = CIValidateOk | CIValidateErr;
+/**
+ * Validate a project's CI config without executing anything.
+ *
+ * @param projectDir Project root to discover `.javi-forge/ci.yaml` in.
+ * @param config Optional explicit config path (from `--config`).
+ */
+export declare function validateCIConfig(projectDir: string, config?: string): Promise<CIValidateResult>;
+//# sourceMappingURL=ci-validate.d.ts.map

package/dist/commands/ci-validate.js

@@ -0,0 +1,61 @@
+/**
+ * `javi-forge ci validate` — dry validation of `.javi-forge/ci.yaml`.
+ *
+ * Pure parse-and-report over the existing validator (src/lib/ci-config.ts):
+ * resolve the config path (same discovery `runCI` uses), call `loadCIConfig`,
+ * and return a structured result. It NEVER builds images, runs Docker, or
+ * executes any phase — the CLI surface stops BEFORE execution.
+ */
+import fs from "fs-extra";
+import { CIConfigError, findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
+/**
+ * Validate a project's CI config without executing anything.
+ *
+ * @param projectDir Project root to discover `.javi-forge/ci.yaml` in.
+ * @param config Optional explicit config path (from `--config`).
+ */
+export async function validateCIConfig(projectDir, config) {
+    // Discriminator: was a config path explicitly requested (`--config`)?
+    //   - explicit path that is missing → ERROR (the user asserted a file that
+    //     isn't there).
+    //   - discovery finds nothing → VALID auto-detect: `runCI` runs fine in this
+    //     exact state via its zero-config single-runner path (ci.ts:396-406), so
+    //     there is nothing to validate and that is not a failure.
+    let configPath;
+    if (config) {
+        if (!(await fs.pathExists(config))) {
+            return {
+                ok: false,
+                configPath: config,
+                errors: [{ path: config, message: `no CI config found at ${config}` }],
+            };
+        }
+        configPath = config;
+    }
+    else {
+        const discovered = await findCIConfig(projectDir);
+        if (!discovered) {
+            return { ok: true, mode: "auto-detect", configPath: null, runners: [] };
+        }
+        configPath = discovered;
+    }
+    try {
+        const ciConfig = await loadCIConfig(configPath);
+        return {
+            ok: true,
+            mode: "config",
+            configPath,
+            runners: ciConfig.runners.map((r) => ({
+                name: r.name,
+                stack: r.stack,
+            })),
+        };
+    }
+    catch (e) {
+        if (e instanceof CIConfigError) {
+            return { ok: false, configPath, errors: e.errors };
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=ci-validate.js.map

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:
@@ -565,7 +565,6 @@ async function runRunner(runner, ctx) {
             id: "compile",
             label: "Compile",
             cmds: runner.compileCmds,
-            user: "root",
             skip: false,
         },
         {

package/dist/index.js

@@ -17,8 +17,17 @@ setupUpdateNotifier(pkg);
 const cli = meow(HELP_TEXT, {
     importMeta: import.meta,
     flags: FLAGS_SCHEMA,
+    // Handle --help manually so `ci --help` can show ci-specific usage instead
+    // of the global banner (meow's autoHelp would print + exit before dispatch).
+    autoHelp: false,
 });
 const subcommand = cli.input[0] ?? "init";
+// Global --help: every command except `ci` shows the global banner here. `ci`
+// owns its per-command help inside handleCi.
+if (cli.flags.help && subcommand !== "ci") {
+    console.log(HELP_TEXT);
+    process.exit(0);
+}
 const isCI = detectCI(cli.flags);
 const inkStdin = createInkStdin();
 switch (subcommand) {

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