@jwillert/forgeflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Willert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# Forgeflow
+
+Forgeflow externalizes repository workflows that would otherwise live inside GitHub Actions or GitLab CI. It polls enabled targets, turns matching labels/comments into durable Agent Commands, and lets a worker run user-defined TypeScript workflows on your own machine or internal infrastructure.
+
+The workflow can call anything: Sandcastle scripts, shell commands, local tools, Hermes, build scripts, or provider CLIs.
+
+## MVP commands
+
+```bash
+forgeflow poll --config forgeflow.config.ts --max-events 100
+forgeflow worker --config forgeflow.config.ts --parallel 3
+```
+
+`poll` is one-shot and intended for cron/systemd. `worker` claims queued commands and runs workflows concurrently. `--parallel` defaults to `3`; `--limit` defaults to the same value.
+
+## Scripted invocation
+
+You can call Forgeflow from your own `run.ts` instead of using the CLI directly:
+
+```ts
+import { createEnvReader, createGateway } from "@jwillert/forgeflow"
+import configFactory from "./.forgeflow/forgeflow.config"
+
+const config = await configFactory({ env: createEnvReader() })
+const gateway = createGateway(config)
+
+const result = await gateway.runOnce({
+  maxEvents: 100,
+  parallel: 3,
+})
+
+console.log(result)
+```
+
+Then run once:
+
+```bash
+npm run forgeflow:once
+```
+
+Or drain until idle:
+
+```bash
+npm run forgeflow:drain
+```
+
+## Config shape
+
+See `examples/forgeflow.config.ts` and `examples/run.ts` for fuller examples.
+
+```ts
+import { defineConfig, defineWorkflow, labelAdded, Match, runProcessOrThrow } from "@jwillert/forgeflow"
+import { github } from "forgeflow/github"
+import { sqliteState } from "forgeflow/sqlite"
+
+const implement = defineWorkflow("implement", {
+  match: ({ event }) => labelAdded(event, "agent:implement") ? Match.accept() : Match.ignore(),
+  run: async ({ command, workTracker }) => {
+    await workTracker.addLabel(command.workTarget, "agent:running")
+    await workTracker.removeLabel(command.workTarget, "agent:implement")
+
+    await runProcessOrThrow({
+      command: "npx",
+      args: ["tsx", ".sandcastle/agent-workflows/implement/implement.ts"],
+      cwd: process.env.WORKSPACE_DIR,
+      env: {
+        ISSUE_NUMBER: command.workTarget.id,
+        ISSUE_TITLE: command.title,
+        BRANCH: `agent/issue-${command.workTarget.id}`,
+      },
+    })
+
+    await workTracker.removeLabel(command.workTarget, "agent:running")
+    await workTracker.addLabel(command.workTarget, "agent:done")
+  },
+})
+
+export default defineConfig(({ env }) => {
+  const gh = github({ token: env.required("GITHUB_TOKEN") })
+
+  return {
+    state: sqliteState(env.optional("FORGEFLOW_DB", "./forgeflow.db")),
+    enabledTargets: [
+      gh.repo("owner/repo", { workflows: [implement] }),
+    ],
+  }
+})
+```
+
+## Design docs
+
+- `CONTEXT.md` — domain glossary
+- `docs/architecture.md` — architecture overview
+- `docs/adr/` — architectural decisions

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { config as loadEnv } from "dotenv";
+import { pathToFileURL } from "node:url";
+import { dirname, extname, join, resolve } from "node:path";
+import { tsImport } from "tsx/esm/api";
+import { createGateway } from "../core/engine.js";
+import { createEnvReader } from "../core/config.js";
+import { withLock, withLockBlocking } from "./lock.js";
+import { runInit } from "./init.js";
+async function loadConfig(path) {
+    const resolved = resolve(path);
+    const mod = extname(resolved) === ".ts"
+        ? await tsImport(resolved, import.meta.url)
+        : await import(pathToFileURL(resolved).href);
+    const exported = mod.default?.default ?? mod.default;
+    if (typeof exported === "function")
+        return await exported({ env: createEnvReader() });
+    return exported;
+}
+function loadEnvFile(configPath, envPath) {
+    loadEnv({ path: envPath ?? join(dirname(resolve(configPath)), ".env") });
+}
+const program = new Command()
+    .name("forgeflow")
+    .description("Agent workflow gateway")
+    .option("--config <path>", "config file", "forgeflow.config.ts");
+program.command("poll")
+    .option("--max-events <number>", "maximum events/rechecks to process", v => Number(v), 100)
+    .action(async (opts) => {
+    const configPath = program.opts().config;
+    const config = await loadConfig(configPath);
+    const result = await createGateway(config).poll({ maxEvents: opts.maxEvents });
+    console.log(JSON.stringify(result, null, 2));
+});
+program.command("worker")
+    .option("--limit <number>", "maximum commands to claim; defaults to --parallel", v => Number(v))
+    .option("--parallel <number>", "maximum commands to run concurrently", v => Number(v), 3)
+    .action(async (opts) => {
+    const configPath = program.opts().config;
+    const config = await loadConfig(configPath);
+    const result = await createGateway(config).worker({ limit: opts.limit, parallel: opts.parallel });
+    console.log(JSON.stringify(result, null, 2));
+});
+program.command("run")
+    .description("Poll once and process everything currently queued")
+    .option("--env <path>", "path to .env file (default: <config dir>/.env)")
+    .option("--max-events <number>", "maximum events/rechecks to process", v => Number(v), 100)
+    .option("--limit <number>", "maximum commands to claim; defaults to --parallel", v => Number(v))
+    .option("--parallel <number>", "maximum commands to run concurrently", v => Number(v), 3)
+    .option("--lock <path>", "lock file path (default: <config dir>/forgeflow.lock)")
+    .action(async (opts) => {
+    const configPath = program.opts().config;
+    loadEnvFile(configPath, opts.env);
+    const lockPath = opts.lock ?? join(dirname(resolve(configPath)), "forgeflow.lock");
+    const result = await withLock(lockPath, async () => {
+        const config = await loadConfig(configPath);
+        return createGateway(config).runOnce({ maxEvents: opts.maxEvents, parallel: opts.parallel, limit: opts.limit });
+    });
+    console.log(JSON.stringify(result, null, 2));
+});
+program.command("drain")
+    .description("Run repeatedly until there is nothing left to do")
+    .option("--env <path>", "path to .env file (default: <config dir>/.env)")
+    .option("--max-events <number>", "maximum events/rechecks to process per iteration", v => Number(v), 100)
+    .option("--limit <number>", "maximum commands to claim per iteration; defaults to --parallel", v => Number(v))
+    .option("--parallel <number>", "maximum commands to run concurrently", v => Number(v), 3)
+    .option("--max-iterations <number>", "stop after this many iterations even if work remains", v => Number(v), 20)
+    .option("--lock <path>", "lock file path (default: <config dir>/forgeflow.lock)")
+    .action(async (opts) => {
+    const configPath = program.opts().config;
+    loadEnvFile(configPath, opts.env);
+    const lockPath = opts.lock ?? join(dirname(resolve(configPath)), "forgeflow.lock");
+    await withLockBlocking(lockPath, async () => {
+        const config = await loadConfig(configPath);
+        const gateway = createGateway(config);
+        for (let iteration = 1; iteration <= opts.maxIterations; iteration++) {
+            console.log(`\n=== Forgeflow drain iteration ${iteration}/${opts.maxIterations} ===`);
+            const result = await gateway.runOnce({ maxEvents: opts.maxEvents, parallel: opts.parallel, limit: opts.limit });
+            console.log(JSON.stringify(result, null, 2));
+            if (result.poll.events === 0 && result.poll.commands === 0 && result.worker.processed === 0) {
+                console.log("Forgeflow idle.");
+                return;
+            }
+        }
+        console.log(`Forgeflow drain stopped after ${opts.maxIterations} iteration(s).`);
+    });
+});
+program.command("init")
+    .description("Scaffold a forgeflow config, prompts, and sandbox image for a new project")
+    .requiredOption("--provider <provider>", "github or gitlab")
+    .requiredOption("--repo <repo>", "repository to watch, e.g. owner/repo (github) or group/project (gitlab)")
+    .option("--dir <path>", "directory to scaffold into", ".forgeflow")
+    .option("--base-branch <name>", "base branch (default: current git branch, else main)")
+    .option("--force", "overwrite existing files", false)
+    .action(async (opts) => {
+    if (opts.provider !== "github" && opts.provider !== "gitlab") {
+        console.error(`Unknown provider "${opts.provider}" — expected "github" or "gitlab"`);
+        process.exitCode = 1;
+        return;
+    }
+    const { written, skipped } = runInit({
+        provider: opts.provider,
+        repo: opts.repo,
+        dir: opts.dir,
+        baseBranch: opts.baseBranch,
+        force: opts.force,
+    });
+    for (const path of written)
+        console.log(`created  ${path}`);
+    for (const path of skipped)
+        console.log(`skipped  ${path} (already exists, use --force to overwrite)`);
+    console.log(`\nNext steps:
+  1. cp ${opts.dir}/.env.example ${opts.dir}/.env and fill in your access token
+  2. bash ${opts.dir}/build-image.sh
+  3. npx forgeflow run --config ${opts.dir}/forgeflow.config.ts`);
+});
+await program.parseAsync(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/init.d.ts

@@ -0,0 +1,11 @@
+export type InitOptions = {
+    provider: "github" | "gitlab";
+    repo: string;
+    dir: string;
+    baseBranch?: string;
+    force?: boolean;
+};
+export declare function runInit(options: InitOptions): {
+    written: string[];
+    skipped: string[];
+};

package/dist/cli/init.js

@@ -0,0 +1,198 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, appendFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+const here = dirname(fileURLToPath(import.meta.url));
+const bundledPromptsDir = join(here, "../workflows/prompts");
+const templatesDir = join(here, "templates");
+function detectBaseBranch() {
+    try {
+        return execFileSync("git", ["symbolic-ref", "--short", "HEAD"], { encoding: "utf8" }).trim() || "main";
+    }
+    catch {
+        return "main";
+    }
+}
+function writeFile(path, content, force, written, skipped) {
+    if (existsSync(path) && !force) {
+        skipped.push(path);
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    written.push(path);
+}
+function copyFile(from, to, force, written, skipped) {
+    if (existsSync(to) && !force) {
+        skipped.push(to);
+        return;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(from, to);
+    written.push(to);
+}
+function configTemplate(options, dir) {
+    const providerImport = options.provider === "github"
+        ? `import { github } from "@jwillert/forgeflow/github"`
+        : `import { gitlab } from "@jwillert/forgeflow/gitlab"`;
+    const targetSetup = options.provider === "github"
+        ? `  const gh = github({ token: env.required("GH_TOKEN") })
+  const target = gh.repo(env.required("FORGEFLOW_GITHUB_REPO"), {
+    baseBranch: env.optional("FORGEFLOW_BASE_REF", "${options.baseBranch}"),
+    workflows: [implement, review, updateBranch],
+  })`
+        : `  const gl = gitlab({
+    token: env.required("GITLAB_TOKEN"),
+    baseUrl: env.optional("FORGEFLOW_GITLAB_BASE_URL", "https://gitlab.com"),
+  })
+  const target = gl.project(env.required("FORGEFLOW_GITLAB_PROJECT"), {
+    baseBranch: env.optional("FORGEFLOW_BASE_REF", "${options.baseBranch}"),
+    workflows: [implement, review, updateBranch],
+  })`;
+    return `import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { defineConfig } from "@jwillert/forgeflow"
+${providerImport}
+import { sqliteState } from "@jwillert/forgeflow/sqlite"
+import { createImplementWorkflow, createReviewWorkflow, createUpdateBranchWorkflow } from "@jwillert/forgeflow/workflows"
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// Prompts below were copied from forgeflow/workflows by \`forgeflow init\` — edit
+// freely, or delete the promptFile/extractionPrompt overrides to fall back to
+// the package's bundled defaults.
+const implement = createImplementWorkflow({
+  promptFile: join(here, "prompts/implement.md"),
+})
+const review = createReviewWorkflow({
+  promptFile: join(here, "prompts/review/prompt.md"),
+  extractionPrompt: readFileSync(join(here, "prompts/review/extraction.md"), "utf8"),
+})
+const updateBranch = createUpdateBranchWorkflow({
+  promptFile: join(here, "prompts/update-branch/prompt.md"),
+  extractionPrompt: readFileSync(join(here, "prompts/update-branch/extraction.md"), "utf8"),
+})
+
+export default defineConfig(({ env }) => {
+${targetSetup}
+
+  return {
+    state: sqliteState(env.optional("FORGEFLOW_DB", "${dir}/forgeflow.db")),
+    defaultDeferInterval: env.optional("FORGEFLOW_DEFAULT_DEFER_INTERVAL", "15m"),
+    enabledTargets: [target],
+  }
+})
+`;
+}
+function envExampleTemplate(options, dir) {
+    const providerLines = options.provider === "github"
+        ? `# GitHub access token. Needs repo contents/issues/pull-request permissions.
+GH_TOKEN=
+
+# Repository this config watches, e.g. "owner/repo".
+FORGEFLOW_GITHUB_REPO=${options.repo}`
+        : `# GitLab access token. Needs api scope on the target project.
+GITLAB_TOKEN=
+
+# Self-managed GitLab instance base URL, if not gitlab.com.
+FORGEFLOW_GITLAB_BASE_URL=https://gitlab.com
+
+# Project this config watches, e.g. "group/project".
+FORGEFLOW_GITLAB_PROJECT=${options.repo}`;
+    return `${providerLines}
+
+# Base branch used for implementation work branches.
+FORGEFLOW_BASE_REF=${options.baseBranch}
+
+# SQLite database path for Forgeflow state.
+FORGEFLOW_DB=${dir}/forgeflow.db
+
+# Max provider events/deferred commands handled per run.
+FORGEFLOW_MAX_EVENTS=100
+
+# Number of queued commands run concurrently.
+FORGEFLOW_PARALLEL=3
+
+# Optional cap for commands claimed in one worker run. Empty means defaults to FORGEFLOW_PARALLEL.
+FORGEFLOW_LIMIT=
+
+# Podman image used by the Sandcastle sandbox provider. Build it with:
+#   bash ${dir}/build-image.sh
+FORGEFLOW_SANDBOX_IMAGE=forgeflow-agent
+FORGEFLOW_SANDBOX_DOCKERFILE=${dir}/Dockerfile
+FORGEFLOW_SANDBOX_BUILD_CONTEXT=.
+
+# Optional command executed inside the sandbox after creation, before the agent runs.
+# Example: npm ci
+FORGEFLOW_SANDBOX_PREFLIGHT=
+
+# Optional output directory used by workflows.
+FORGEFLOW_OUTPUT_DIR=/tmp/forgeflow-output
+
+# Pi agent model settings.
+PI_MODEL=openai-codex/gpt-5.5
+PI_THINKING=low
+`;
+}
+function ensureGitignore(root, dir, written) {
+    const gitignorePath = join(root, ".gitignore");
+    const relDir = relative(root, dir) || dir;
+    const lines = [
+        `${relDir}/*.db`,
+        `${relDir}/*.db-shm`,
+        `${relDir}/*.db-wal`,
+        `${relDir}/*.lock`,
+        `${relDir}/.env`,
+        `!${relDir}/.env.example`,
+    ];
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+    const missing = lines.filter(line => !existing.includes(line));
+    if (missing.length === 0)
+        return;
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    appendFileSync(gitignorePath, `${separator}${existing.length > 0 ? "\n" : ""}# Forgeflow\n${missing.join("\n")}\n`);
+    written.push(gitignorePath);
+}
+function mergePackageJsonScripts(root, dir, written, skipped) {
+    const pkgPath = join(root, "package.json");
+    if (!existsSync(pkgPath))
+        return;
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    pkg.scripts ??= {};
+    const desired = {
+        "forgeflow:once": `forgeflow run --config ${dir}/forgeflow.config.ts`,
+        "forgeflow:drain": `forgeflow drain --config ${dir}/forgeflow.config.ts`,
+    };
+    let changed = false;
+    for (const [key, value] of Object.entries(desired)) {
+        if (pkg.scripts[key]) {
+            skipped.push(`package.json#scripts.${key}`);
+            continue;
+        }
+        pkg.scripts[key] = value;
+        changed = true;
+    }
+    if (changed) {
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+        written.push(pkgPath);
+    }
+}
+export function runInit(options) {
+    const root = process.cwd();
+    const dir = resolve(root, options.dir);
+    const baseBranch = options.baseBranch ?? detectBaseBranch();
+    const written = [];
+    const skipped = [];
+    writeFile(join(dir, "forgeflow.config.ts"), configTemplate({ provider: options.provider, repo: options.repo, baseBranch }, options.dir), options.force, written, skipped);
+    writeFile(join(dir, ".env.example"), envExampleTemplate({ provider: options.provider, repo: options.repo, baseBranch }, options.dir), options.force, written, skipped);
+    for (const promptFile of ["implement.md", "review/prompt.md", "review/extraction.md", "update-branch/prompt.md", "update-branch/extraction.md"]) {
+        copyFile(join(bundledPromptsDir, promptFile), join(dir, "prompts", promptFile), options.force, written, skipped);
+    }
+    copyFile(join(templatesDir, "Dockerfile"), join(dir, "Dockerfile"), options.force, written, skipped);
+    copyFile(join(templatesDir, "build-image.sh"), join(dir, "build-image.sh"), options.force, written, skipped);
+    ensureGitignore(root, dir, written);
+    mergePackageJsonScripts(root, options.dir, written, skipped);
+    return { written, skipped };
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}

package/dist/cli/lock.d.ts

@@ -0,0 +1,4 @@
+/** Runs `fn` under an advisory PID-file lock at `lockPath`. Fails fast if already held. */
+export declare function withLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T>;
+/** Same as withLock, but waits (polling) for the lock to free up instead of failing immediately. */
+export declare function withLockBlocking<T>(lockPath: string, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/cli/lock.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tryAcquire(lockPath) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    if (existsSync(lockPath)) {
+        const pid = Number(readFileSync(lockPath, "utf8").trim());
+        if (pid && isProcessAlive(pid))
+            return false;
+    }
+    writeFileSync(lockPath, String(process.pid));
+    return true;
+}
+/** Runs `fn` under an advisory PID-file lock at `lockPath`. Fails fast if already held. */
+export async function withLock(lockPath, fn) {
+    if (!tryAcquire(lockPath)) {
+        throw new Error(`Another forgeflow run holds the lock at ${lockPath}. Skipping.`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            rmSync(lockPath);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** Same as withLock, but waits (polling) for the lock to free up instead of failing immediately. */
+export async function withLockBlocking(lockPath, fn, timeoutMs = 10 * 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (!tryAcquire(lockPath)) {
+        if (Date.now() > deadline)
+            throw new Error(`Timed out waiting for the lock at ${lockPath}`);
+        await new Promise(resolve => setTimeout(resolve, 500));
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            rmSync(lockPath);
+        }
+        catch { /* already gone */ }
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/cli/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/cli/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACpF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC;QAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAAC,OAAO,IAAI,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAA;IAAC,CAAC;AAClE,CAAC;AAED,SAAS,UAAU,CAAC,QAAgB;IAClC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACjD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;QACzD,IAAI,GAAG,IAAI,cAAc,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAA;IAC9C,CAAC;IACD,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5C,OAAO,IAAI,CAAA;AACb,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,QAAgB,EAAE,EAAoB;IACtE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,2CAA2C,QAAQ,aAAa,CAAC,CAAA;IACnF,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAA;IACnB,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IACvD,CAAC;AACH,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAI,QAAgB,EAAE,EAAoB,EAAE,SAAS,GAAG,EAAE,GAAG,MAAM;IACvG,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;IACvC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,QAAQ,EAAE,CAAC,CAAA;QAC3F,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAA;IACxD,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAA;IACnB,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/cli/templates/Dockerfile

@@ -0,0 +1,38 @@
+FROM node:22-bookworm
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+  git \
+  curl \
+  jq \
+  unzip \
+  ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+  | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+  | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+  && apt-get update && apt-get install -y gh \
+  && rm -rf /var/lib/apt/lists/*
+
+# Build-args for UID/GID alignment.
+ARG AGENT_UID=1000
+ARG AGENT_GID=1000
+
+RUN groupmod -o -g $AGENT_GID node \
+  && usermod -o -u $AGENT_UID -g $AGENT_GID -d /home/agent -m -l agent node
+
+USER ${AGENT_UID}:${AGENT_GID}
+WORKDIR /home/agent
+
+ENV NPM_CONFIG_PREFIX=/home/agent/.npm-global
+ENV PATH=/home/agent/.local/bin:/home/agent/.npm-global/bin:$PATH
+
+# Install Pi Agent. Runtime auth is mounted from the host at ~/.pi/agent.
+RUN npm install -g @earendil-works/pi-coding-agent
+RUN mkdir -p /home/agent/.pi/agent \
+  && echo '{"defaultProvider":"openai-codex","defaultModel":"gpt-5.5","theme":"dark"}' > /home/agent/.pi/agent/settings.json
+
+ENTRYPOINT ["sleep", "infinity"]

package/dist/cli/templates/build-image.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+image_name="${FORGEFLOW_SANDBOX_IMAGE:-forgeflow-agent}"
+context_dir="${FORGEFLOW_SANDBOX_BUILD_CONTEXT:-.}"
+dockerfile="${FORGEFLOW_SANDBOX_DOCKERFILE:-.forgeflow/Dockerfile}"
+
+podman build \
+  -t "$image_name" \
+  -f "$dockerfile" \
+  "$context_dir"