javi-forge 1.6.0 → 1.7.0

package/dist/lib/crash-recovery.js

@@ -0,0 +1,123 @@
+/**
+ * Crash recovery — reconstruct pipeline state from git commit history
+ * when checkpoint files are corrupted or lost. Git is the single
+ * source of truth for what was actually done.
+ */
+import { execFileAsync } from "./exec.js";
+// ── Git operations ──
+export async function getGitLog(projectDir, options = {}) {
+    const args = [
+        "log",
+        `--max-count=${options.maxCommits ?? 50}`,
+        "--pretty=format:%H|%s|%aI",
+        "--name-only",
+    ];
+    if (options.since)
+        args.push(`--since=${options.since}`);
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            cwd: projectDir,
+            timeout: 10_000,
+        });
+        return stdout;
+    }
+    catch {
+        return "";
+    }
+}
+export async function getCurrentBranch(projectDir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { cwd: projectDir, timeout: 5_000 });
+        return stdout.trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+// ── Parsing ──
+const CONVENTIONAL_RE = /^(feat|fix|test|refactor|docs|chore|ci|perf|style|build)(?:\(([^)]*)\))?:\s*(.+)/;
+const TASK_ID_RE = /#(\d+)|task[- ](\d+[.\d]*)/i;
+export function parseCommitPhase(message) {
+    const match = CONVENTIONAL_RE.exec(message);
+    return match ? (match[1] ?? null) : null;
+}
+export function extractTaskId(message) {
+    const match = TASK_ID_RE.exec(message);
+    if (match)
+        return match[1] ?? match[2] ?? null;
+    return null;
+}
+export function parseGitLog(raw) {
+    if (!raw.trim())
+        return [];
+    const tasks = [];
+    const blocks = raw.split("\n\n").filter((b) => b.trim());
+    for (const block of blocks) {
+        const lines = block.split("\n").filter((l) => l.trim());
+        if (lines.length === 0)
+            continue;
+        const headerLine = lines[0];
+        if (!headerLine)
+            continue;
+        const parts = headerLine.split("|");
+        if (parts.length < 3)
+            continue;
+        const [hash, message, timestamp] = parts;
+        const filesChanged = lines.slice(1).filter((l) => !l.includes("|"));
+        tasks.push({
+            commitHash: hash.slice(0, 7),
+            message,
+            timestamp,
+            filesChanged,
+            taskId: extractTaskId(message),
+            phase: parseCommitPhase(message),
+        });
+    }
+    return tasks;
+}
+// ── Recovery ──
+export async function recoverFromGit(projectDir, options = {}) {
+    const branch = await getCurrentBranch(projectDir);
+    const raw = await getGitLog(projectDir, options);
+    const tasks = parseGitLog(raw);
+    const phases = {};
+    for (const task of tasks) {
+        if (task.phase) {
+            phases[task.phase] = (phases[task.phase] ?? 0) + 1;
+        }
+    }
+    return {
+        branch,
+        totalCommits: tasks.length,
+        tasks,
+        phases,
+        lastActivity: tasks[0]?.timestamp ?? null,
+    };
+}
+// ── Formatting ──
+export function formatRecovery(report) {
+    const lines = [];
+    lines.push(`## Crash Recovery Report`);
+    lines.push(`**Branch**: ${report.branch} | **Commits**: ${report.totalCommits}`);
+    if (report.lastActivity) {
+        lines.push(`**Last activity**: ${report.lastActivity}`);
+    }
+    lines.push("");
+    if (Object.keys(report.phases).length > 0) {
+        const phaseStr = Object.entries(report.phases)
+            .map(([p, c]) => `${p}: ${c}`)
+            .join(", ");
+        lines.push(`**Phases**: ${phaseStr}`);
+        lines.push("");
+    }
+    for (const task of report.tasks.slice(0, 10)) {
+        const tag = task.phase ? `[${task.phase}]` : "";
+        const id = task.taskId ? ` #${task.taskId}` : "";
+        lines.push(`- \`${task.commitHash}\` ${tag}${id} ${task.message} (${task.filesChanged.length} files)`);
+    }
+    if (report.totalCommits > 10) {
+        lines.push(`\n... and ${report.totalCommits - 10} more commits`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=crash-recovery.js.map

package/dist/lib/docker.d.ts

@@ -1,7 +1,13 @@
-import type { Stack } from '../types/index.js';
+import type { Stack } from "../types/index.js";
 export interface DockerRunOptions {
     /** Absolute path to mount as /home/runner/work */
     projectDir: string;
+    /**
+     * Pre-resolved image from the CI runner (required). Passed through
+     * verbatim, including digest pins (`name@sha256:...`). runInContainer
+     * never performs marker detection — resolution happens once, upstream.
+     */
+    image: string;
     /** Command to run inside the container */
     command: string;
     /** Timeout in seconds (default: 600) */
@@ -22,6 +28,14 @@ export interface DockerImageOptions {
     javaVersion?: string;
     /** Directory where Dockerfiles are stored (defaults to package-bundled dir) */
     dockerfilesDir?: string;
+    /**
+     * Custom build context directory (must contain a Dockerfile, which is
+     * the source of truth and is never overwritten). Mutually exclusive
+     * with dockerfilesDir.
+     */
+    buildContext?: string;
+    /** Image tag for build-context builds (default: derived from the stack) */
+    imageTag?: string;
 }
 export declare function getImageName(stack: Stack): string;
 export declare function getDockerfileContent(stack: Stack): string;
@@ -30,6 +44,12 @@ export declare function isDockerAvailable(): Promise<boolean>;
  * Ensure a CI Docker image exists and is up-to-date.
  * Rebuilds only if the Dockerfile content has changed (hash-based staleness check).
  * Returns the image name.
+ *
+ * Two modes:
+ *   - per-stack (default): the Dockerfile is generated/managed by javi-forge
+ *   - build-context: the configured context directory provides its own
+ *     Dockerfile (source of truth, never overwritten); fails closed if
+ *     the Dockerfile is missing.
  */
 export declare function ensureImage(options: DockerImageOptions): Promise<string>;
 /**
@@ -40,6 +60,7 @@ export declare function ensureImage(options: DockerImageOptions): Promise<string
 export declare function runInContainer(options: DockerRunOptions): Promise<DockerRunResult>;
 /**
  * Open an interactive shell inside the CI container.
+ * The image must be pre-resolved by the caller (no marker detection here).
  */
-export declare function openShell(projectDir: string): Promise<void>;
+export declare function openShell(projectDir: string, image: string): Promise<void>;
 //# sourceMappingURL=docker.d.ts.map

package/dist/lib/docker.js

@@ -1,9 +1,8 @@
-import { execFile, spawn } from 'child_process';
-import { promisify } from 'util';
-import crypto from 'crypto';
-import fs from 'fs-extra';
-import path from 'path';
-const execFileAsync = promisify(execFile);
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import path from "node:path";
+import fs from "fs-extra";
+import { execFileAsync } from "./exec.js";
 // =============================================================================
 // Image name
 // =============================================================================
@@ -15,66 +14,66 @@ export function getImageName(stack) {
 // =============================================================================
 export function getDockerfileContent(stack) {
     switch (stack) {
-        case 'java-gradle':
-        case 'java-maven':
+        case "java-gradle":
+        case "java-maven":
             return [
-                'ARG JAVA_VERSION=21',
-                'FROM eclipse-temurin:${JAVA_VERSION}-jdk-noble',
-                'RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*',
-                'RUN useradd -m -s /bin/bash runner',
-                'USER runner',
-                'WORKDIR /home/runner/work',
+                "ARG JAVA_VERSION=21",
+                "FROM eclipse-temurin:${JAVA_VERSION}-jdk-noble",
+                "RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*",
+                "RUN useradd -m -s /bin/bash runner",
+                "USER runner",
+                "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
-            ].join('\n');
-        case 'node':
+            ].join("\n");
+        case "node":
             return [
-                'FROM node:22-slim',
-                'RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*',
-                'RUN npm install -g pnpm',
-                'RUN useradd -m -s /bin/bash runner',
-                'USER runner',
-                'WORKDIR /home/runner/work',
+                "FROM node:22-slim",
+                "RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*",
+                "RUN npm install -g pnpm",
+                "RUN useradd -m -s /bin/bash runner",
+                "USER runner",
+                "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
-            ].join('\n');
-        case 'python':
+            ].join("\n");
+        case "python":
             return [
-                'FROM python:3.12-slim',
-                'RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*',
-                'RUN pip install --no-cache-dir pytest ruff pylint poetry',
-                'RUN useradd -m -s /bin/bash runner',
-                'USER runner',
-                'WORKDIR /home/runner/work',
+                "FROM python:3.12-slim",
+                "RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*",
+                "RUN pip install --no-cache-dir pytest ruff pylint poetry",
+                "RUN useradd -m -s /bin/bash runner",
+                "USER runner",
+                "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
-            ].join('\n');
-        case 'go':
+            ].join("\n");
+        case "go":
             return [
-                'FROM golang:1.23-bookworm',
-                'RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*',
-                'RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && mv /root/go/bin/golangci-lint /usr/local/bin/',
-                'RUN useradd -m -s /bin/bash runner',
-                'USER runner',
-                'WORKDIR /home/runner/work',
+                "FROM golang:1.23-bookworm",
+                "RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*",
+                "RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && mv /root/go/bin/golangci-lint /usr/local/bin/",
+                "RUN useradd -m -s /bin/bash runner",
+                "USER runner",
+                "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
-            ].join('\n');
-        case 'rust':
+            ].join("\n");
+        case "rust":
             return [
-                'FROM rust:1.83-slim',
-                'RUN apt-get update && apt-get install -y git pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*',
-                'RUN rustup component add clippy rustfmt',
-                'RUN useradd -m -s /bin/bash runner',
-                'USER runner',
-                'WORKDIR /home/runner/work',
+                "FROM rust:1.83-slim",
+                "RUN apt-get update && apt-get install -y git pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*",
+                "RUN rustup component add clippy rustfmt",
+                "RUN useradd -m -s /bin/bash runner",
+                "USER runner",
+                "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
-            ].join('\n');
+            ].join("\n");
         default:
             return [
-                'FROM ubuntu:24.04',
-                'RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*',
-                'RUN useradd -m -s /bin/bash runner',
-                'USER runner',
-                'WORKDIR /home/runner/work',
+                "FROM ubuntu:24.04",
+                "RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*",
+                "RUN useradd -m -s /bin/bash runner",
+                "USER runner",
+                "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
-            ].join('\n');
+            ].join("\n");
     }
 }
 // =============================================================================
@@ -82,7 +81,7 @@ export function getDockerfileContent(stack) {
 // =============================================================================
 export async function isDockerAvailable() {
     try {
-        await execFileAsync('docker', ['info'], { timeout: 5000 });
+        await execFileAsync("docker", ["info"], { timeout: 5000 });
         return true;
     }
     catch {
@@ -96,25 +95,51 @@ export async function isDockerAvailable() {
  * Ensure a CI Docker image exists and is up-to-date.
  * Rebuilds only if the Dockerfile content has changed (hash-based staleness check).
  * Returns the image name.
+ *
+ * Two modes:
+ *   - per-stack (default): the Dockerfile is generated/managed by javi-forge
+ *   - build-context: the configured context directory provides its own
+ *     Dockerfile (source of truth, never overwritten); fails closed if
+ *     the Dockerfile is missing.
  */
 export async function ensureImage(options) {
-    const { stack, javaVersion, dockerfilesDir } = options;
-    const imageName = getImageName(stack);
-    // Resolve Dockerfile path
-    const dockerDir = dockerfilesDir ?? path.join(path.dirname(new URL(import.meta.url).pathname), '../../ci-local/docker');
-    const dockerfilePath = path.join(dockerDir, `${stack}.Dockerfile`);
-    // Write Dockerfile if it doesn't exist yet (first run)
-    if (!await fs.pathExists(dockerfilePath)) {
-        await fs.ensureDir(dockerDir);
-        await fs.writeFile(dockerfilePath, getDockerfileContent(stack), 'utf-8');
+    const { stack, javaVersion, dockerfilesDir, buildContext, imageTag } = options;
+    let imageName;
+    let dockerfilePath;
+    let contextDir;
+    if (buildContext) {
+        imageName = imageTag ?? getImageName(stack);
+        dockerfilePath = path.join(buildContext, "Dockerfile");
+        contextDir = buildContext;
+        // Fail closed: a build context without a Dockerfile is a config error,
+        // never something to silently work around.
+        if (!(await fs.pathExists(dockerfilePath))) {
+            throw new Error(`build-context "${buildContext}" has no Dockerfile — ` +
+                "add one or use image/stack defaults instead");
+        }
+    }
+    else {
+        imageName = getImageName(stack);
+        const dockerDir = dockerfilesDir ??
+            path.join(path.dirname(new URL(import.meta.url).pathname), "../../ci-local/docker");
+        dockerfilePath = path.join(dockerDir, `${stack}.Dockerfile`);
+        contextDir = dockerDir;
+        // Write Dockerfile if it doesn't exist yet (first run)
+        if (!(await fs.pathExists(dockerfilePath))) {
+            await fs.ensureDir(dockerDir);
+            await fs.writeFile(dockerfilePath, getDockerfileContent(stack), "utf-8");
+        }
     }
     // Staleness check: compare Dockerfile hash with the one embedded in the image label
-    const content = await fs.readFile(dockerfilePath, 'utf-8');
-    const currentHash = crypto.createHash('sha256').update(content).digest('hex');
-    let imageHash = '';
+    const content = await fs.readFile(dockerfilePath, "utf-8");
+    const currentHash = crypto.createHash("sha256").update(content).digest("hex");
+    let imageHash = "";
     try {
-        const { stdout } = await execFileAsync('docker', [
-            'inspect', '--format', '{{index .Config.Labels "dockerfile-hash"}}', imageName,
+        const { stdout } = await execFileAsync("docker", [
+            "inspect",
+            "--format",
+            '{{index .Config.Labels "dockerfile-hash"}}',
+            imageName,
         ]);
         imageHash = stdout.trim();
     }
@@ -126,19 +151,26 @@ export async function ensureImage(options) {
     }
     // Build image
     const buildArgs = [
-        'build',
-        '--label', `dockerfile-hash=${currentHash}`,
-        '-f', dockerfilePath,
-        '-t', imageName,
+        "build",
+        "--label",
+        `dockerfile-hash=${currentHash}`,
+        "-f",
+        dockerfilePath,
+        "-t",
+        imageName,
     ];
-    if (javaVersion && (stack === 'java-gradle' || stack === 'java-maven')) {
-        buildArgs.push('--build-arg', `JAVA_VERSION=${javaVersion}`);
+    if (!buildContext &&
+        javaVersion &&
+        (stack === "java-gradle" || stack === "java-maven")) {
+        buildArgs.push("--build-arg", `JAVA_VERSION=${javaVersion}`);
     }
-    buildArgs.push(dockerDir);
+    buildArgs.push(contextDir);
     await new Promise((resolve, reject) => {
-        const proc = spawn('docker', buildArgs, { stdio: 'inherit' });
-        proc.on('close', code => code === 0 ? resolve() : reject(new Error(`docker build exited with code ${code}`)));
-        proc.on('error', reject);
+        const proc = spawn("docker", buildArgs, { stdio: "inherit" });
+        proc.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`docker build exited with code ${code}`)));
+        proc.on("error", reject);
     });
     return imageName;
 }
@@ -151,74 +183,79 @@ export async function ensureImage(options) {
  * Streams output to process.stdout/stderr by default.
  */
 export async function runInContainer(options) {
-    const { projectDir, command, timeout = 600, stream = true, user } = options;
-    const stack = await detectStackFromDir(projectDir);
-    const imageName = getImageName(stack);
+    const { projectDir, image, command, timeout = 600, stream = true, user, } = options;
+    // The image is always pre-resolved by the caller (resolveCIRunners →
+    // ensureImage or an explicit/digest-pinned config image). No marker
+    // detection happens on this path — ever.
+    const imageName = image;
     const isInteractive = process.stdin.isTTY && stream;
+    // 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
+    // comma-separated key=value pairs and is colon-safe.
     const dockerArgs = [
-        'run', '--rm',
-        ...(isInteractive ? ['-it'] : []),
-        '--stop-timeout', '30',
-        '--entrypoint', '',
-        ...(user ? ['--user', user] : []),
-        '-v', `${projectDir}:/home/runner/work`,
-        '-e', 'CI=true',
+        "run",
+        "--rm",
+        ...(isInteractive ? ["-it"] : []),
+        "--stop-timeout",
+        "30",
+        "--entrypoint",
+        "",
+        ...(user ? ["--user", user] : []),
+        "--mount",
+        `type=bind,source=${projectDir},target=/home/runner/work`,
+        "-e",
+        "CI=true",
         imageName,
-        'timeout', String(timeout), 'bash', '-c', command,
+        "timeout",
+        String(timeout),
+        "bash",
+        "-c",
+        command,
     ];
     return new Promise((resolve, reject) => {
-        const proc = spawn('docker', dockerArgs, {
-            stdio: stream ? 'inherit' : 'pipe',
+        const proc = spawn("docker", dockerArgs, {
+            stdio: stream ? "inherit" : "pipe",
         });
-        let stdout = '';
-        let stderr = '';
+        let stdout = "";
+        let stderr = "";
         if (!stream) {
-            proc.stdout?.on('data', (d) => { stdout += d.toString(); });
-            proc.stderr?.on('data', (d) => { stderr += d.toString(); });
+            proc.stdout?.on("data", (d) => {
+                stdout += d.toString();
+            });
+            proc.stderr?.on("data", (d) => {
+                stderr += d.toString();
+            });
         }
-        proc.on('close', code => resolve({ exitCode: code ?? 1, stdout, stderr }));
-        proc.on('error', reject);
+        proc.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+        proc.on("error", reject);
     });
 }
 /**
  * Open an interactive shell inside the CI container.
+ * The image must be pre-resolved by the caller (no marker detection here).
  */
-export async function openShell(projectDir) {
-    const stack = await detectStackFromDir(projectDir);
-    const imageName = getImageName(stack);
+export async function openShell(projectDir, image) {
+    const imageName = image;
     await new Promise((resolve, reject) => {
-        const proc = spawn('docker', [
-            'run', '--rm', '-it',
-            '--entrypoint', '',
-            '-v', `${projectDir}:/home/runner/work`,
-            '-e', 'CI=true',
+        const proc = spawn("docker", [
+            "run",
+            "--rm",
+            "-it",
+            "--entrypoint",
+            "",
+            // --mount is colon-safe; see runInContainer for the rationale.
+            "--mount",
+            `type=bind,source=${projectDir},target=/home/runner/work`,
+            "-e",
+            "CI=true",
             imageName,
-            'bash', '-c', 'cd /home/runner/work && exec bash',
-        ], { stdio: 'inherit' });
-        proc.on('close', () => resolve());
-        proc.on('error', reject);
+            "bash",
+            "-c",
+            "cd /home/runner/work && exec bash",
+        ], { stdio: "inherit" });
+        proc.on("close", () => resolve());
+        proc.on("error", reject);
     });
 }
-// =============================================================================
-// Internal helpers
-// =============================================================================
-async function detectStackFromDir(projectDir) {
-    if (await fs.pathExists(path.join(projectDir, 'build.gradle.kts')))
-        return 'java-gradle';
-    if (await fs.pathExists(path.join(projectDir, 'build.gradle')))
-        return 'java-gradle';
-    if (await fs.pathExists(path.join(projectDir, 'pom.xml')))
-        return 'java-maven';
-    if (await fs.pathExists(path.join(projectDir, 'package.json')))
-        return 'node';
-    if (await fs.pathExists(path.join(projectDir, 'go.mod')))
-        return 'go';
-    if (await fs.pathExists(path.join(projectDir, 'Cargo.toml')))
-        return 'rust';
-    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')))
-        return 'python';
-    return 'node'; // fallback
-}
 //# sourceMappingURL=docker.js.map

package/dist/lib/exec.d.ts

@@ -0,0 +1,10 @@
+import { execFile } from "node:child_process";
+/**
+ * Promisified `execFile` for shelling out to subprocesses with arguments
+ * (safer than `exec` because arguments are NOT shell-interpreted).
+ *
+ * Centralized helper used across the codebase by command modules and
+ * init steps that invoke external CLIs (git, javi-ai, etc.).
+ */
+export declare const execFileAsync: typeof execFile.__promisify__;
+//# sourceMappingURL=exec.d.ts.map

package/dist/lib/exec.js

@@ -0,0 +1,11 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+/**
+ * Promisified `execFile` for shelling out to subprocesses with arguments
+ * (safer than `exec` because arguments are NOT shell-interpreted).
+ *
+ * Centralized helper used across the codebase by command modules and
+ * init steps that invoke external CLIs (git, javi-ai, etc.).
+ */
+export const execFileAsync = promisify(execFile);
+//# sourceMappingURL=exec.js.map

package/dist/lib/frontmatter.d.ts

@@ -14,5 +14,5 @@ export interface ValidationError {
 /**
  * Validate frontmatter against schema rules for agent or skill definitions.
  */
-export declare function validateFrontmatter(frontmatter: Record<string, unknown>, type: 'agent' | 'skill'): ValidationError[];
+export declare function validateFrontmatter(frontmatter: Record<string, unknown>, type: "agent" | "skill"): ValidationError[];
 //# sourceMappingURL=frontmatter.d.ts.map