javi-forge 1.6.0 → 1.7.0

package/dist/commands/ci.js

@@ -1,73 +1,74 @@
-import { execFile, spawn } from 'child_process';
-import { promisify } from 'util';
-import fs from 'fs-extra';
-import path from 'path';
-import { isDockerAvailable, ensureImage, runInContainer, openShell } from '../lib/docker.js';
-const execFileAsync = promisify(execFile);
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "fs-extra";
+import { CI_STACKS, findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
+import { refreshContextDir } from "../lib/context.js";
+import { ensureImage, getImageName, isDockerAvailable, openShell, runInContainer, } from "../lib/docker.js";
+import { execFileAsync } from "../lib/exec.js";
 // =============================================================================
 // Stack detection
 // =============================================================================
 export async function detectCIStack(projectDir) {
-    let stackType = 'node';
-    let buildTool = 'npm';
-    let javaVersion = '21';
+    let stackType = "node";
+    let buildTool = "npm";
+    let javaVersion = "21";
     // Java Gradle
-    if (await fs.pathExists(path.join(projectDir, 'build.gradle.kts')) ||
-        await fs.pathExists(path.join(projectDir, 'build.gradle'))) {
-        stackType = 'java-gradle';
-        buildTool = 'gradle';
+    if ((await fs.pathExists(path.join(projectDir, "build.gradle.kts"))) ||
+        (await fs.pathExists(path.join(projectDir, "build.gradle")))) {
+        stackType = "java-gradle";
+        buildTool = "gradle";
         // Try to read java version from build files
-        const ktsPath = path.join(projectDir, 'build.gradle.kts');
-        const gradlePath = path.join(projectDir, 'build.gradle');
+        const ktsPath = path.join(projectDir, "build.gradle.kts");
+        const gradlePath = path.join(projectDir, "build.gradle");
         if (await fs.pathExists(ktsPath)) {
-            const content = await fs.readFile(ktsPath, 'utf-8');
+            const content = await fs.readFile(ktsPath, "utf-8");
             const match = content.match(/JavaLanguageVersion\.of\((\d+)\)/);
             if (match?.[1])
                 javaVersion = match[1];
         }
         else if (await fs.pathExists(gradlePath)) {
-            const content = await fs.readFile(gradlePath, 'utf-8');
+            const content = await fs.readFile(gradlePath, "utf-8");
             const match = content.match(/sourceCompatibility\s*=\s*['"]*(\d+)/);
             if (match?.[1])
                 javaVersion = match[1];
         }
     }
     // Java Maven
-    else if (await fs.pathExists(path.join(projectDir, 'pom.xml'))) {
-        stackType = 'java-maven';
-        buildTool = 'mvn';
+    else if (await fs.pathExists(path.join(projectDir, "pom.xml"))) {
+        stackType = "java-maven";
+        buildTool = "mvn";
     }
     // Node
-    else if (await fs.pathExists(path.join(projectDir, 'package.json'))) {
-        stackType = 'node';
-        if (await fs.pathExists(path.join(projectDir, 'pnpm-lock.yaml')))
-            buildTool = 'pnpm';
-        else if (await fs.pathExists(path.join(projectDir, 'yarn.lock')))
-            buildTool = 'yarn';
+    else if (await fs.pathExists(path.join(projectDir, "package.json"))) {
+        stackType = "node";
+        if (await fs.pathExists(path.join(projectDir, "pnpm-lock.yaml")))
+            buildTool = "pnpm";
+        else if (await fs.pathExists(path.join(projectDir, "yarn.lock")))
+            buildTool = "yarn";
         else
-            buildTool = 'npm';
+            buildTool = "npm";
     }
     // Go
-    else if (await fs.pathExists(path.join(projectDir, 'go.mod'))) {
-        stackType = 'go';
-        buildTool = 'go';
+    else if (await fs.pathExists(path.join(projectDir, "go.mod"))) {
+        stackType = "go";
+        buildTool = "go";
     }
     // Rust
-    else if (await fs.pathExists(path.join(projectDir, 'Cargo.toml'))) {
-        stackType = 'rust';
-        buildTool = 'cargo';
+    else if (await fs.pathExists(path.join(projectDir, "Cargo.toml"))) {
+        stackType = "rust";
+        buildTool = "cargo";
     }
     // Python
-    else if (await fs.pathExists(path.join(projectDir, 'pyproject.toml')) ||
-        await fs.pathExists(path.join(projectDir, 'requirements.txt')) ||
-        await fs.pathExists(path.join(projectDir, 'setup.py'))) {
-        stackType = 'python';
-        if (await fs.pathExists(path.join(projectDir, 'uv.lock')))
-            buildTool = 'uv';
-        else if (await fs.pathExists(path.join(projectDir, 'poetry.lock')))
-            buildTool = 'poetry';
+    else if ((await fs.pathExists(path.join(projectDir, "pyproject.toml"))) ||
+        (await fs.pathExists(path.join(projectDir, "requirements.txt"))) ||
+        (await fs.pathExists(path.join(projectDir, "setup.py")))) {
+        stackType = "python";
+        if (await fs.pathExists(path.join(projectDir, "uv.lock")))
+            buildTool = "uv";
+        else if (await fs.pathExists(path.join(projectDir, "poetry.lock")))
+            buildTool = "poetry";
         else
-            buildTool = 'pip';
+            buildTool = "pip";
     }
     // Build CI commands per stack
     const { lintCmd, compileCmd, testCmd } = await buildCICommands(stackType, buildTool, projectDir);
@@ -75,63 +76,199 @@ export async function detectCIStack(projectDir) {
 }
 async function buildCICommands(stack, buildTool, projectDir) {
     switch (stack) {
-        case 'java-gradle':
+        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',
-                testCmd: './gradlew test --no-daemon',
+                lintCmd: "./gradlew spotlessCheck --no-daemon",
+                compileCmd: "./gradlew clean classes testClasses --no-daemon && chown -R runner:runner build/ .gradle/ 2>/dev/null || true",
+                testCmd: "./gradlew test --no-daemon",
             };
-        case 'java-maven':
+        case "java-maven":
             return {
-                lintCmd: './mvnw spotless:check',
-                compileCmd: './mvnw clean compile test-compile && chown -R runner:runner target/ .mvn/ 2>/dev/null || true',
-                testCmd: './mvnw test',
+                lintCmd: "./mvnw spotless:check",
+                compileCmd: "./mvnw clean compile test-compile && chown -R runner:runner target/ .mvn/ 2>/dev/null || true",
+                testCmd: "./mvnw test",
             };
-        case 'node': {
-            const pkgPath = path.join(projectDir, 'package.json');
-            let pkgContent = '';
+        case "node": {
+            const pkgPath = path.join(projectDir, "package.json");
+            let pkgContent = "";
             try {
-                pkgContent = await fs.readFile(pkgPath, 'utf-8');
+                pkgContent = await fs.readFile(pkgPath, "utf-8");
+            }
+            catch {
+                /* no package.json */
             }
-            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.
-            const buildPrefix = 'rm -rf dist/ && ';
-            const buildSuffix = ' && chown -R runner:runner dist/ 2>/dev/null || true';
+            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}` : null,
-                testCmd: pkgContent.includes('"test"') ? `${buildTool} ${buildTool === 'npm' ? 'test' : 'run test'}` : null,
+                compileCmd: pkgContent.includes('"build"')
+                    ? `${buildPrefix}${buildTool} run build${buildSuffix}`
+                    : null,
+                testCmd: pkgContent.includes('"test"')
+                    ? `${buildTool} ${buildTool === "npm" ? "test" : "run test"}`
+                    : null,
             };
         }
-        case 'python':
+        case "python":
             return {
-                lintCmd: 'ruff check . && { pylint **/*.py 2>/dev/null || true; }',
+                lintCmd: "ruff check . && { pylint **/*.py 2>/dev/null || true; }",
                 compileCmd: null,
-                testCmd: 'pytest',
+                testCmd: "pytest",
             };
-        case 'go':
+        case "go":
             return {
-                lintCmd: 'golangci-lint run',
-                compileCmd: 'go clean -cache && go build ./... && chown -R runner:runner . 2>/dev/null || true',
-                testCmd: 'go test ./...',
+                lintCmd: "golangci-lint run",
+                compileCmd: "go clean -cache && go build ./... && chown -R runner:runner . 2>/dev/null || true",
+                testCmd: "go test ./...",
             };
-        case 'rust':
+        case "rust":
             return {
-                lintCmd: 'cargo clippy -- -D warnings',
-                compileCmd: 'cargo clean && cargo build && chown -R runner:runner target/ 2>/dev/null || true',
-                testCmd: 'cargo test',
+                lintCmd: "cargo clippy -- -D warnings",
+                compileCmd: "cargo clean && cargo build && chown -R runner:runner target/ 2>/dev/null || true",
+                testCmd: "cargo test",
             };
         default:
             return { lintCmd: null, compileCmd: null, testCmd: null };
     }
 }
+function freezeRunner(runner) {
+    return Object.freeze({
+        ...runner,
+        setupCmds: Object.freeze([...runner.setupCmds]),
+        lintCmds: Object.freeze([...runner.lintCmds]),
+        compileCmds: Object.freeze([...runner.compileCmds]),
+        testCmds: Object.freeze([...runner.testCmds]),
+        securityCmds: Object.freeze([...runner.securityCmds]),
+        requiredTools: Object.freeze([...runner.requiredTools]),
+    });
+}
+function freezeRunners(source, runners) {
+    return Object.freeze({ source, runners: Object.freeze(runners) });
+}
+/** Build-tool heuristic for a known stack in a given directory. */
+async function detectBuildTool(stack, dir) {
+    switch (stack) {
+        case "node":
+            if (await fs.pathExists(path.join(dir, "pnpm-lock.yaml")))
+                return "pnpm";
+            if (await fs.pathExists(path.join(dir, "yarn.lock")))
+                return "yarn";
+            return "npm";
+        case "python":
+            if (await fs.pathExists(path.join(dir, "uv.lock")))
+                return "uv";
+            if (await fs.pathExists(path.join(dir, "poetry.lock")))
+                return "poetry";
+            return "pip";
+        case "java-gradle":
+            return "gradle";
+        case "java-maven":
+            return "mvn";
+        case "go":
+            return "go";
+        case "rust":
+            return "cargo";
+        default:
+            return "";
+    }
+}
+function toList(command) {
+    return command ? [command] : [];
+}
+async function resolveConfiguredRunner(projectDir, config) {
+    const runnerDir = path.join(projectDir, config.directory);
+    const buildTool = await detectBuildTool(config.stack, runnerDir);
+    const defaults = await buildCICommands(config.stack, buildTool, runnerDir);
+    return freezeRunner({
+        name: config.name,
+        stack: config.stack,
+        buildTool,
+        javaVersion: "21",
+        directory: config.directory,
+        image: config.image,
+        buildContext: config.buildContext,
+        setupCmds: config.setup,
+        lintCmds: config.lint.length > 0 ? config.lint : toList(defaults.lintCmd),
+        compileCmds: config.build.length > 0 ? config.build : toList(defaults.compileCmd),
+        testCmds: config.test.length > 0 ? config.test : toList(defaults.testCmd),
+        securityCmds: config.security,
+        requiredTools: config.requires,
+    });
+}
+async function resolveExplicitStackRunner(projectDir, stack) {
+    const buildTool = await detectBuildTool(stack, projectDir);
+    const defaults = await buildCICommands(stack, buildTool, projectDir);
+    return freezeRunner({
+        name: stack,
+        stack,
+        buildTool,
+        javaVersion: "21",
+        directory: ".",
+        setupCmds: [],
+        lintCmds: toList(defaults.lintCmd),
+        compileCmds: toList(defaults.compileCmd),
+        testCmds: toList(defaults.testCmd),
+        securityCmds: [],
+        requiredTools: [],
+    });
+}
+/**
+ * Resolve the ordered runner list exactly once per CI run.
+ *
+ * Precedence (fail closed on ambiguity):
+ *   1. --config <path> (or discovered .javi-forge/ci.yaml) → configured runners
+ *   2. --stack <stack> → single explicit runner (single-stack repos only)
+ *   3. otherwise → single auto-detected runner (zero-config default)
+ */
+export async function resolveCIRunners(projectDir, options = {}) {
+    const { config, stack } = options;
+    if (config && stack) {
+        throw new Error("Ambiguous CI options: --config and --stack cannot be used together. " +
+            "Use --config for hybrid repositories.");
+    }
+    if (stack) {
+        if (!CI_STACKS.includes(stack)) {
+            throw new Error(`Unknown stack "${stack}". Valid stacks: ${CI_STACKS.join(", ")}`);
+        }
+        return freezeRunners("stack-override", [
+            await resolveExplicitStackRunner(projectDir, stack),
+        ]);
+    }
+    const configPath = config ?? (await findCIConfig(projectDir));
+    if (configPath) {
+        const ciConfig = await loadCIConfig(configPath);
+        const runners = [];
+        for (const runnerConfig of ciConfig.runners) {
+            runners.push(await resolveConfiguredRunner(projectDir, runnerConfig));
+        }
+        return freezeRunners("config", runners);
+    }
+    // Zero-config default: single auto-detected runner (unchanged behavior).
+    const info = await detectCIStack(projectDir);
+    return freezeRunners("auto", [
+        freezeRunner({
+            name: info.stackType,
+            stack: info.stackType,
+            buildTool: info.buildTool,
+            javaVersion: info.javaVersion,
+            directory: ".",
+            setupCmds: [],
+            lintCmds: toList(info.lintCmd),
+            compileCmds: toList(info.compileCmd),
+            testCmds: toList(info.testCmd),
+            securityCmds: [],
+            requiredTools: [],
+        }),
+    ]);
+}
 // =============================================================================
 // GHAGGA check
 // =============================================================================
 async function isGhaggaAvailable() {
     try {
-        await execFileAsync('ghagga', ['--version'], { timeout: 3000 });
+        await execFileAsync("ghagga", ["--version"], { timeout: 3000 });
         return true;
     }
     catch {
@@ -144,163 +281,354 @@ async function isGhaggaAvailable() {
 function report(onStep, id, label, status, detail) {
     onStep({ id, label, status, detail });
 }
+/** Detect-step label: legacy format for auto, explicit otherwise. */
+function describeRunners(resolved) {
+    const first = resolved.runners[0];
+    if (resolved.source === "auto" && first) {
+        return `Stack: ${first.stack} (${first.buildTool})`;
+    }
+    if (resolved.source === "stack-override" && first) {
+        return `Stack: ${first.stack} (${first.buildTool}, --stack override)`;
+    }
+    const summary = resolved.runners
+        .map((r) => `${r.name} (${r.stack})`)
+        .join(", ");
+    return `Config: ${resolved.runners.length} runner(s) — ${summary}`;
+}
 export async function runCI(options, onStep) {
-    const { projectDir = process.cwd(), mode = 'full', noDocker = false, noGhagga = false, noSecurity = false, timeout = 600, } = options;
-    // ── Detect stack ────────────────────────────────────────────────────────────
-    const stepDetect = 'detect';
-    report(onStep, stepDetect, 'Detecting stack', 'running');
-    let stackInfo;
+    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";
+    report(onStep, stepDetect, "Detecting stack", "running");
+    let resolved;
     try {
-        stackInfo = await detectCIStack(projectDir);
-        report(onStep, stepDetect, `Stack: ${stackInfo.stackType} (${stackInfo.buildTool})`, 'done');
+        resolved = await resolveCIRunners(projectDir, {
+            config: options.config,
+            stack: options.stack,
+        });
+        report(onStep, stepDetect, describeRunners(resolved), "done");
     }
     catch (e) {
-        report(onStep, stepDetect, 'Detecting stack', 'error', String(e));
+        report(onStep, stepDetect, "Detecting stack", "error", String(e));
         throw e;
     }
+    // Legacy single-runner view for the zero-config auto path. Keeping this
+    // shape guarantees single-stack repositories behave exactly as before.
+    const primary = resolved.runners[0];
+    const stackInfo = {
+        stackType: primary?.stack ?? "node",
+        buildTool: primary?.buildTool ?? "npm",
+        javaVersion: primary?.javaVersion ?? "21",
+        lintCmd: primary?.lintCmds[0] ?? null,
+        compileCmd: primary?.compileCmds[0] ?? null,
+        testCmd: primary?.testCmds[0] ?? null,
+    };
     // ── Detect mode ─────────────────────────────────────────────────────────────
-    if (mode === 'detect')
+    if (mode === "detect")
         return;
     // ── Shell mode ──────────────────────────────────────────────────────────────
-    if (mode === 'shell') {
+    if (mode === "shell") {
         if (noDocker) {
-            report(onStep, 'shell', 'Shell', 'error', '--shell requires Docker');
-            throw new Error('--shell requires Docker');
+            report(onStep, "shell", "Shell", "error", "--shell requires Docker");
+            throw new Error("--shell requires Docker");
         }
-        report(onStep, 'docker-image', 'Building Docker image', 'running');
+        report(onStep, "docker-image", "Building Docker image", "running");
+        let shellImage;
         try {
-            await ensureImage({ stack: stackInfo.stackType, javaVersion: stackInfo.javaVersion });
-            report(onStep, 'docker-image', 'Docker image ready', 'done');
+            shellImage = await ensureImage({
+                stack: stackInfo.stackType,
+                javaVersion: stackInfo.javaVersion,
+            });
+            report(onStep, "docker-image", "Docker image ready", "done");
         }
         catch (e) {
-            report(onStep, 'docker-image', 'Building Docker image', 'error', String(e));
+            report(onStep, "docker-image", "Building Docker image", "error", String(e));
             throw e;
         }
-        await openShell(projectDir);
+        await openShell(projectDir, shellImage);
         return;
     }
     // ── Check Docker ─────────────────────────────────────────────────────────────
     if (!noDocker) {
-        const stepDocker = 'docker-check';
-        report(onStep, stepDocker, 'Checking Docker', 'running');
+        const stepDocker = "docker-check";
+        report(onStep, stepDocker, "Checking Docker", "running");
         const dockerOk = await isDockerAvailable();
         if (!dockerOk) {
-            report(onStep, stepDocker, 'Docker not available', 'error', 'Start Docker or use --no-docker');
-            throw new Error('Docker is not available');
+            report(onStep, stepDocker, "Docker not available", "error", "Start Docker or use --no-docker");
+            throw new Error("Docker is not available");
         }
-        report(onStep, stepDocker, 'Docker available', 'done');
-        // Build image
-        const stepImage = 'docker-image';
-        report(onStep, stepImage, `Building image for ${stackInfo.stackType}`, 'running');
-        try {
-            await ensureImage({ stack: stackInfo.stackType, javaVersion: stackInfo.javaVersion });
-            report(onStep, stepImage, 'Docker image ready', 'done');
+        report(onStep, stepDocker, "Docker available", "done");
+        // Build image (auto path only — configured runners ensure their own
+        // image inside the runner loop)
+        if (resolved.source === "auto") {
+            const stepImage = "docker-image";
+            report(onStep, stepImage, `Building image for ${stackInfo.stackType}`, "running");
+            try {
+                await ensureImage({
+                    stack: stackInfo.stackType,
+                    javaVersion: stackInfo.javaVersion,
+                });
+                report(onStep, stepImage, "Docker image ready", "done");
+            }
+            catch (e) {
+                report(onStep, stepImage, "Building Docker image", "error", String(e));
+                throw e;
+            }
         }
-        catch (e) {
-            report(onStep, stepImage, 'Building Docker image', 'error', String(e));
-            throw e;
+    }
+    // ── Refresh .context/ ────────────────────────────────────────────────────────
+    const stepContext = "context-refresh";
+    report(onStep, stepContext, "Refresh .context/ directory", "running");
+    try {
+        const ctxResult = await refreshContextDir(projectDir);
+        if (ctxResult) {
+            report(onStep, stepContext, "Refresh .context/ directory", "done", "INDEX.md + summary.md updated");
+        }
+        else {
+            report(onStep, stepContext, "Refresh .context/ directory", "skipped", "no .context/ or no manifest");
+        }
+    }
+    catch (e) {
+        // Non-fatal: context refresh failure should not block CI
+        report(onStep, stepContext, "Refresh .context/ directory", "error", String(e));
+    }
+    // ── Runner execution ─────────────────────────────────────────────────────────
+    if (resolved.source === "auto" && primary) {
+        // Legacy zero-config path — unchanged single-stack behavior.
+        await runLegacySteps(stackInfo, primary, {
+            projectDir,
+            mode,
+            noDocker,
+            timeout,
+            onStep,
+        });
+    }
+    else {
+        // Configured (or --stack override) runners execute in declared order,
+        // each in its own working directory.
+        for (const runner of resolved.runners) {
+            await runConfiguredRunner(runner, {
+                projectDir,
+                mode,
+                noDocker,
+                noSecurity,
+                timeout,
+                onStep,
+            });
+        }
+    }
+    // ── Security scan (full mode only) ──────────────────────────────────────────
+    if (mode === "full" && !noSecurity) {
+        const stepSecurity = "security";
+        const semgrepAvailable = await isSemgrepAvailable();
+        if (semgrepAvailable) {
+            report(onStep, stepSecurity, "Security scan (Semgrep)", "running");
+            try {
+                await runSemgrep(projectDir);
+                report(onStep, stepSecurity, "Security scan passed", "done");
+            }
+            catch (e) {
+                report(onStep, stepSecurity, "Security scan failed", "error", String(e));
+                throw e;
+            }
+        }
+        else {
+            report(onStep, stepSecurity, "Security scan", "skipped", "Semgrep not available — install semgrep or Docker");
         }
     }
-    // ── Lint ─────────────────────────────────────────────────────────────────────
+    // ── GHAGGA review (full mode only) ──────────────────────────────────────────
+    if (mode === "full" && !noGhagga) {
+        const stepGhagga = "ghagga";
+        const ghagga = await isGhaggaAvailable();
+        if (ghagga) {
+            report(onStep, stepGhagga, "GHAGGA review", "running");
+            try {
+                await runGhagga(projectDir);
+                report(onStep, stepGhagga, "GHAGGA review passed", "done");
+            }
+            catch (e) {
+                report(onStep, stepGhagga, "GHAGGA review failed", "error", String(e));
+                throw e;
+            }
+        }
+        else {
+            report(onStep, stepGhagga, "GHAGGA review", "skipped", "ghagga not installed");
+        }
+    }
+}
+/** Legacy zero-config execution — identical to the pre-mixed-stack behavior. */
+async function runLegacySteps(stackInfo, runner, ctx) {
+    const { projectDir, mode, noDocker, timeout, onStep } = ctx;
     if (stackInfo.lintCmd) {
-        const stepLint = 'lint';
-        report(onStep, stepLint, `Lint: ${stackInfo.lintCmd}`, 'running');
+        const stepLint = "lint";
+        report(onStep, stepLint, `Lint: ${stackInfo.lintCmd}`, "running");
         try {
-            await runStep(stackInfo.lintCmd, projectDir, noDocker, timeout);
-            report(onStep, stepLint, 'Lint passed', 'done');
+            await runStep(stackInfo.lintCmd, projectDir, noDocker, timeout, runner);
+            report(onStep, stepLint, "Lint passed", "done");
         }
         catch (e) {
-            report(onStep, stepLint, 'Lint failed', 'error', String(e));
+            report(onStep, stepLint, "Lint failed", "error", String(e));
             throw e;
         }
     }
-    // ── Compile ──────────────────────────────────────────────────────────────────
     if (stackInfo.compileCmd) {
-        const stepCompile = 'compile';
-        report(onStep, stepCompile, `Compile: ${stackInfo.compileCmd}`, 'running');
+        const stepCompile = "compile";
+        report(onStep, stepCompile, `Compile: ${stackInfo.compileCmd}`, "running");
         try {
             // Run as root inside the container to rm/build output dirs owned by any host user,
             // then chown back to runner so subsequent test steps can read the output.
-            await runStep(stackInfo.compileCmd, projectDir, noDocker, timeout, 'root');
-            report(onStep, stepCompile, 'Compile passed', 'done');
+            await runStep(stackInfo.compileCmd, projectDir, noDocker, timeout, runner, "root");
+            report(onStep, stepCompile, "Compile passed", "done");
         }
         catch (e) {
-            report(onStep, stepCompile, 'Compile failed', 'error', String(e));
+            report(onStep, stepCompile, "Compile failed", "error", String(e));
             throw e;
         }
     }
-    // ── Test (full mode only) ────────────────────────────────────────────────────
-    if (mode === 'full' && stackInfo.testCmd) {
-        const stepTest = 'test';
-        report(onStep, stepTest, `Test: ${stackInfo.testCmd}`, 'running');
+    if (mode === "full" && stackInfo.testCmd) {
+        const stepTest = "test";
+        report(onStep, stepTest, `Test: ${stackInfo.testCmd}`, "running");
         try {
-            await runStep(stackInfo.testCmd, projectDir, noDocker, timeout);
-            report(onStep, stepTest, 'Tests passed', 'done');
+            await runStep(stackInfo.testCmd, projectDir, noDocker, timeout, runner);
+            report(onStep, stepTest, "Tests passed", "done");
         }
         catch (e) {
-            report(onStep, stepTest, 'Tests failed', 'error', String(e));
+            report(onStep, stepTest, "Tests failed", "error", String(e));
             throw e;
         }
     }
-    // ── Security scan (full mode only) ──────────────────────────────────────────
-    if (mode === 'full' && !noSecurity) {
-        const stepSecurity = 'security';
-        const semgrepAvailable = await isSemgrepAvailable();
-        if (semgrepAvailable) {
-            report(onStep, stepSecurity, 'Security scan (Semgrep)', 'running');
-            try {
-                await runSemgrep(projectDir);
-                report(onStep, stepSecurity, 'Security scan passed', 'done');
+}
+/**
+ * Execute one configured runner: resolve the image (default stack image,
+ * explicit/digest-pinned image, or deterministic build-context build),
+ * verify required tools fail-closed, then run setup/lint/compile/test/
+ * security commands in order, inside the runner's working directory.
+ * Any failure aborts the whole run — nothing is ever skipped silently.
+ */
+async function runConfiguredRunner(runner, ctx) {
+    const { projectDir, mode, noDocker, noSecurity, timeout, onStep } = ctx;
+    // ── Image resolution (Docker mode only) ────────────────────────────────────
+    let imageName;
+    if (!noDocker) {
+        const stepImage = `docker-image:${runner.name}`;
+        try {
+            if (runner.buildContext) {
+                report(onStep, stepImage, `Building image for ${runner.name} from ${runner.buildContext}`, "running");
+                imageName = await ensureImage({
+                    stack: runner.stack,
+                    buildContext: path.resolve(projectDir, runner.buildContext),
+                    imageTag: `javi-forge-ci-${runner.name}`,
+                });
             }
-            catch (e) {
-                report(onStep, stepSecurity, 'Security scan failed', 'error', String(e));
-                throw e;
+            else if (runner.image) {
+                // Explicit image (digest pins pass through verbatim).
+                imageName = runner.image;
+                report(onStep, stepImage, `Using configured image ${runner.image}`, "done");
+            }
+            else {
+                report(onStep, stepImage, `Building image for ${runner.name} (${runner.stack})`, "running");
+                imageName = await ensureImage({
+                    stack: runner.stack,
+                    javaVersion: runner.javaVersion,
+                });
+            }
+            if (!runner.image) {
+                report(onStep, stepImage, `Docker image ready (${imageName})`, "done");
             }
         }
-        else {
-            report(onStep, stepSecurity, 'Security scan', 'skipped', 'Semgrep not available — install semgrep or Docker');
+        catch (e) {
+            report(onStep, stepImage, "Building Docker image", "error", String(e));
+            throw e;
         }
     }
-    // ── GHAGGA review (full mode only) ──────────────────────────────────────────
-    if (mode === 'full' && !noGhagga) {
-        const stepGhagga = 'ghagga';
-        const ghagga = await isGhaggaAvailable();
-        if (ghagga) {
-            report(onStep, stepGhagga, 'GHAGGA review', 'running');
+    // ── Required tools (fail closed, before any phase) ─────────────────────────
+    if (runner.requiredTools.length > 0) {
+        const stepTools = `tools:${runner.name}`;
+        const envDesc = noDocker
+            ? `native environment (directory "${runner.directory}")`
+            : `image ${imageName}`;
+        report(onStep, stepTools, `Checking required tools [${runner.name}]: ${runner.requiredTools.join(", ")}`, "running");
+        for (const tool of runner.requiredTools) {
             try {
-                await runGhagga(projectDir);
-                report(onStep, stepGhagga, 'GHAGGA review passed', 'done');
+                await runStep(`command -v ${tool}`, projectDir, noDocker, timeout, runner, undefined, imageName);
+            }
+            catch {
+                const message = `runner "${runner.name}": required tool "${tool}" not found in ${envDesc} — ` +
+                    "install it in the runner image/environment or remove it from requires";
+                report(onStep, stepTools, `Missing required tool [${runner.name}]: ${tool}`, "error", message);
+                throw new Error(message);
+            }
+        }
+        report(onStep, stepTools, `Required tools OK [${runner.name}]`, "done");
+    }
+    const phases = [
+        { id: "setup", label: "Setup", cmds: runner.setupCmds, skip: false },
+        { id: "lint", label: "Lint", cmds: runner.lintCmds, skip: false },
+        {
+            id: "compile",
+            label: "Compile",
+            cmds: runner.compileCmds,
+            user: "root",
+            skip: false,
+        },
+        {
+            id: "test",
+            label: "Test",
+            cmds: runner.testCmds,
+            skip: mode !== "full",
+        },
+        {
+            id: "security",
+            label: "Security",
+            cmds: runner.securityCmds,
+            skip: mode !== "full" || noSecurity,
+        },
+    ];
+    for (const phase of phases) {
+        if (phase.skip)
+            continue;
+        const stepId = `${phase.id}:${runner.name}`;
+        for (const cmd of phase.cmds) {
+            report(onStep, stepId, `${phase.label} [${runner.name}]: ${cmd}`, "running");
+            try {
+                await runStep(cmd, projectDir, noDocker, timeout, runner, phase.user, imageName);
+                report(onStep, stepId, `${phase.label} [${runner.name}] passed`, "done");
             }
             catch (e) {
-                report(onStep, stepGhagga, 'GHAGGA review failed', 'error', String(e));
+                report(onStep, stepId, `${phase.label} [${runner.name}] failed`, "error", String(e));
                 throw e;
             }
         }
-        else {
-            report(onStep, stepGhagga, 'GHAGGA review', 'skipped', 'ghagga not installed');
-        }
     }
 }
-// =============================================================================
-// Step runners
-// =============================================================================
-async function runStep(command, projectDir, noDocker, timeout, user) {
+async function runStep(command, projectDir, noDocker, timeout, runner, user, imageOverride) {
     if (noDocker) {
-        // Run natively
+        // Run natively, in the runner's working directory.
+        const cwd = path.join(projectDir, runner.directory);
         await new Promise((resolve, reject) => {
-            const proc = spawn('bash', ['-c', command], {
-                cwd: projectDir,
-                stdio: 'inherit',
-                env: { ...process.env, CI: 'true' },
+            const proc = spawn("bash", ["-c", command], {
+                cwd,
+                stdio: "inherit",
+                env: { ...process.env, CI: "true" },
             });
-            proc.on('close', code => code === 0 ? resolve() : reject(new Error(`Command failed with code ${code}`)));
-            proc.on('error', reject);
+            proc.on("close", (code) => code === 0
+                ? resolve()
+                : reject(new Error(`Command failed with code ${code}`)));
+            proc.on("error", reject);
         });
     }
     else {
+        // The image is always resolved upstream (per-runner ensureImage,
+        // explicit config image, or the default per-stack image). Docker
+        // receives it verbatim and never re-detects anything.
+        const image = imageOverride ?? runner.image ?? getImageName(runner.stack);
+        const workdir = runner.directory !== "."
+            ? `/home/runner/work/${runner.directory}`
+            : "/home/runner/work";
         const result = await runInContainer({
             projectDir,
-            command: `cd /home/runner/work && ${command}`,
+            image,
+            command: `cd ${workdir} && ${command}`,
             timeout,
             stream: true,
             user,
@@ -312,7 +640,7 @@ async function runStep(command, projectDir, noDocker, timeout, user) {
 }
 async function isSemgrepAvailable() {
     try {
-        await execFileAsync('semgrep', ['--version'], { timeout: 3000 });
+        await execFileAsync("semgrep", ["--version"], { timeout: 3000 });
         return true;
     }
     catch {
@@ -321,26 +649,30 @@ async function isSemgrepAvailable() {
 }
 async function runSemgrep(projectDir) {
     // Look for semgrep config in project or use auto
-    const semgrepConfig = await fs.pathExists(path.join(projectDir, '.semgrep.yml'))
-        ? path.join(projectDir, '.semgrep.yml')
-        : 'auto';
+    const semgrepConfig = (await fs.pathExists(path.join(projectDir, ".semgrep.yml")))
+        ? path.join(projectDir, ".semgrep.yml")
+        : "auto";
     await new Promise((resolve, reject) => {
-        const proc = spawn('semgrep', ['--config', semgrepConfig, '--severity', 'ERROR', '--quiet', '.'], {
+        const proc = spawn("semgrep", ["--config", semgrepConfig, "--severity", "ERROR", "--quiet", "."], {
             cwd: projectDir,
-            stdio: 'inherit',
+            stdio: "inherit",
         });
-        proc.on('close', code => code === 0 ? resolve() : reject(new Error(`Semgrep found issues (exit ${code})`)));
-        proc.on('error', reject);
+        proc.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`Semgrep found issues (exit ${code})`)));
+        proc.on("error", reject);
     });
 }
 async function runGhagga(projectDir) {
     await new Promise((resolve, reject) => {
-        const proc = spawn('ghagga', ['review', '--plain', '--exit-on-issues'], {
+        const proc = spawn("ghagga", ["review", "--plain", "--exit-on-issues"], {
             cwd: projectDir,
-            stdio: 'inherit',
+            stdio: "inherit",
         });
-        proc.on('close', code => code === 0 ? resolve() : reject(new Error(`GHAGGA review found issues (exit ${code})`)));
-        proc.on('error', reject);
+        proc.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`GHAGGA review found issues (exit ${code})`)));
+        proc.on("error", reject);
     });
 }
 // =============================================================================
@@ -386,8 +718,8 @@ fi || {
 const COMMIT_MSG_HOOK = `#!/bin/bash
 # Commit-msg: block AI attribution in commit messages
 set -e
-COMMIT_MSG_FILE="\$1"
-COMMIT_MSG=\$(cat "\$COMMIT_MSG_FILE")
+COMMIT_MSG_FILE="$1"
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
 
 AI_PATTERNS=(
   "co-authored-by:.*claude" "co-authored-by:.*anthropic"
@@ -403,10 +735,10 @@ AI_PATTERNS=(
 )
 
 for pattern in "\${AI_PATTERNS[@]}"; do
-  if echo "\$COMMIT_MSG" | grep -iqE "\$pattern"; then
+  if echo "$COMMIT_MSG" | grep -iqE "$pattern"; then
     echo ""
     echo "COMMIT BLOCKED: AI Attribution Detected"
-    echo "  Pattern: \$pattern"
+    echo "  Pattern: $pattern"
     echo "  Remove AI attribution. You are the sole author."
     echo ""
     exit 1
@@ -415,22 +747,45 @@ done
 exit 0
 `;
 export async function installCIHooks(projectDir) {
-    const gitDir = path.join(projectDir, '.git');
-    if (!await fs.pathExists(gitDir)) {
-        return { installed: [], errors: ['Not a git repository. Run git init first.'] };
+    const gitDir = path.join(projectDir, ".git");
+    if (!(await fs.pathExists(gitDir))) {
+        return {
+            installed: [],
+            errors: ["Not a git repository. Run git init first."],
+        };
     }
-    const hooksDir = path.join(gitDir, 'hooks');
+    const hooksDir = path.join(gitDir, "hooks");
     await fs.ensureDir(hooksDir);
     const hooks = [
-        { name: 'pre-commit', content: PRE_COMMIT_HOOK },
-        { name: 'pre-push', content: PRE_PUSH_HOOK },
-        { name: 'commit-msg', content: COMMIT_MSG_HOOK },
+        { name: "pre-commit", content: PRE_COMMIT_HOOK },
+        { name: "pre-push", content: PRE_PUSH_HOOK },
+        { name: "commit-msg", content: COMMIT_MSG_HOOK },
     ];
     const installed = [];
     const errors = [];
     for (const hook of hooks) {
         const hookPath = path.join(hooksDir, hook.name);
         try {
+            // Refuse to follow symlinks. .git/hooks/<name> as a symlink to a
+            // sensitive file (e.g., ~/.ssh/authorized_keys) would otherwise be
+            // clobbered by writeFile. lstat reports the link, not the target.
+            let isSymlink = false;
+            try {
+                const stat = await fs.lstat(hookPath);
+                isSymlink = stat.isSymbolicLink();
+            }
+            catch (statErr) {
+                const code = statErr && typeof statErr === "object" && "code" in statErr
+                    ? statErr.code
+                    : "";
+                if (code !== "ENOENT") {
+                    throw statErr;
+                }
+                // ENOENT is expected if the hook file doesn't exist yet.
+            }
+            if (isSymlink) {
+                throw new Error(`refusing to write through a symlink at ${hookPath}`);
+            }
             await fs.writeFile(hookPath, hook.content, { mode: 0o755 });
             installed.push(hook.name);
         }