@loucompanion/forge-bridge 0.1.3-dev.bd0c67bbf352 → 0.1.3-dev.c24058d57ab3

package/dist/cli/cli.service.js

@@ -5,13 +5,19 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 import { resolveCursorAgentDirectLaunch } from "../shared/cursor-agent/cursor-agent.launch.js";
+import { buildWindowsCmdLaunch } from "../shared/process/windows-launch.js";
+import { supportsDraftImageAttachmentsFor } from "../shared/provider-capabilities.js";
 import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
 import { defaultBridgeServiceConfig, ForgeBridgeService } from "../bridge/bridge.service.js";
 import { forgeBridgeVersion } from "../version.js";
 import { addRepoMapping, applyLocalConfigDefaults, providerStatusesFor, readLocalConfigSync, removeRepoMapping, resolveLocalConfigPath, writeLocalConfig } from "./local-config.js";
 import { BridgeSessionService } from "../session/session.service.js";
+import { validateDockerfilePolicy, validateSandboxContract } from "../sandbox/contract.js";
+import { DockerPreflight } from "../sandbox/preflight.js";
+import { DockerSandboxRuntime } from "../sandbox/runtime.js";
 import { parseCompletionMcpArgs, runCompletionMcpServer } from "../session/phase-completion.js";
 import { failureResult, parseRunOnceDispatchPacket } from "../session/session.types.js";
+import { commandHelpText, helpText } from "./cli.help.js";
 const apiKeySecretGrantEnv = "FORGE_API_KEY_SECRET_GRANT";
 const execFileAsync = promisify(execFile);
 export class ForgeBridgeCliService {
@@ -86,6 +92,7 @@ export class ForgeBridgeCliService {
         if (args.command === "pair") {
             try {
                 const current = readLocalConfigSync();
+                io.stdout.write(`Pairing with server: ${args.serverUrl}\n`);
                 const code = await resolvePairingCode(args.code);
                 const repoRoot = await resolvePairRepoRoot(args.repoRoot, current.defaultRepoRoot);
                 await fs.mkdir(repoRoot, { recursive: true });
@@ -122,6 +129,15 @@ export class ForgeBridgeCliService {
         if (args.command === "cleanup") {
             return await cleanupRepos(args.config, args.mode, args.force, io);
         }
+        if (args.command === "sandbox-init") {
+            return await initializeSandbox(args.repoPath, io);
+        }
+        if (args.command === "sandbox-doctor") {
+            return await diagnoseSandbox(args.repoPath, args.requirePinnedBase, io);
+        }
+        if (args.command === "sandbox-reap") {
+            return await reapSandboxes(io);
+        }
         if (args.command === "mcp") {
             const parsed = parseCompletionMcpArgs(args.argv);
             if (!parsed.ok) {
@@ -250,10 +266,13 @@ export function parseArgs(argv) {
     if (argv[0] === "mcp") {
         return { ok: true, command: "mcp", argv };
     }
+    if (argv[0] === "sandbox") {
+        return parseSandboxArgs(argv);
+    }
     if (argv[0] !== "run-once") {
         return {
             ok: false,
-            error: usage()
+            error: helpText()
         };
     }
     let dispatchPath = null;
@@ -280,6 +299,151 @@ export function parseArgs(argv) {
         resultPath: path.resolve(resultPath)
     };
 }
+function parseSandboxArgs(argv) {
+    const action = argv[1];
+    let repoPath = process.cwd();
+    let requirePinnedBase = false;
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--repo") {
+            repoPath = argv[++index] ?? "";
+            if (!repoPath)
+                return { ok: false, error: "--repo requires a path." };
+        }
+        else if (arg === "--require-pinned-base" && action === "doctor") {
+            requirePinnedBase = true;
+        }
+        else {
+            return { ok: false, error: `Unknown sandbox argument: ${arg}` };
+        }
+    }
+    if (action === "init")
+        return { ok: true, command: "sandbox-init", repoPath: path.resolve(repoPath) };
+    if (action === "doctor")
+        return { ok: true, command: "sandbox-doctor", repoPath: path.resolve(repoPath), requirePinnedBase };
+    if (action === "reap" && argv.length === 2)
+        return { ok: true, command: "sandbox-reap" };
+    return { ok: false, error: "Usage: forge-bridge sandbox <init|doctor|reap> [--repo <path>] [--require-pinned-base]" };
+}
+const sandboxContractTemplate = `schemaVersion: 1
+workingDirectory: /workspace
+commands:
+  install: npm ci
+  test: npm test
+caches:
+  - name: npm
+    mode: readonly
+services: []
+environment: []
+artifacts: []
+logs: []
+browser: false
+`;
+const sandboxDockerfileTemplate = `# Pin this base by digest before enabling sandbox_required.
+FROM node:22.17.0-bookworm-slim
+WORKDIR /workspace
+`;
+async function initializeSandbox(repoPath, io) {
+    const forgePath = path.join(repoPath, ".forge");
+    const files = [
+        ["forge.sandbox.yml", sandboxContractTemplate],
+        ["Dockerfile", sandboxDockerfileTemplate],
+        ["forge.env.example", "# List non-secret variable names in forge.sandbox.yml. Never commit secret values.\n"]
+    ];
+    await fs.mkdir(forgePath, { recursive: true });
+    let created = 0;
+    for (const [name, contents] of files) {
+        const target = path.join(forgePath, name);
+        try {
+            const handle = await fs.open(target, "wx", 0o600);
+            await handle.writeFile(contents);
+            await handle.close();
+            io.stdout.write(`Created ${path.relative(repoPath, target)}\n`);
+            created += 1;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            io.stdout.write(`Kept existing ${path.relative(repoPath, target)}\n`);
+        }
+    }
+    io.stdout.write(created > 0 ? "Sandbox scaffold is ready. Run `forge-bridge sandbox doctor`.\n" : "Sandbox scaffold already exists.\n");
+    return 0;
+}
+async function diagnoseSandbox(repoPath, requirePinnedBase, io) {
+    try {
+        const forgePath = path.join(repoPath, ".forge");
+        const contractSource = await fs.readFile(path.join(forgePath, "forge.sandbox.yml"), "utf8");
+        const dockerfile = await fs.readFile(path.join(forgePath, "Dockerfile"), "utf8");
+        const contract = validateSandboxContract(contractSource);
+        const warnings = validateDockerfilePolicy(dockerfile, requirePinnedBase);
+        io.stdout.write(`Contract: valid (${contract.digest})\n`);
+        for (const warning of warnings)
+            io.stdout.write(`Warning: ${warning}\n`);
+        const config = defaultBridgeServiceConfig();
+        const preflight = new DockerPreflight({
+            dockerExecutable: config.dockerExecutable,
+            dockerContext: config.dockerContext,
+            stateRoot: config.sandboxStateRoot,
+            maxConcurrentSandboxes: config.maxConcurrentSandboxes,
+            diskHighWatermarkPercent: config.diskHighWatermarkPercent,
+            diskLowWatermarkPercent: config.diskLowWatermarkPercent,
+            minimumWorkspaceBytes: config.minimumWorkspaceBytes,
+            requireRootless: config.requireRootlessDocker
+        });
+        try {
+            const result = await preflight.refresh();
+            if (!result.healthy) {
+                io.stderr.write(`Docker: unavailable (${result.unavailableCode ?? "preflight_failed"}): ${result.unavailableReason ?? "unknown reason"}\n`);
+                return 1;
+            }
+            io.stdout.write(`Docker: healthy (${result.runtimeVersion}; capacity ${result.maxConcurrentSandboxes})\n`);
+            return 0;
+        }
+        finally {
+            await preflight.release();
+        }
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function reapSandboxes(io) {
+    const config = defaultBridgeServiceConfig();
+    if (!/^[0-9a-f-]{32,36}$/iu.test(config.runnerId)) {
+        io.stderr.write("FORGE_RUNNER_ID must identify the runner whose exact-labeled resources may be reaped.\n");
+        return 2;
+    }
+    const preflight = new DockerPreflight({
+        dockerExecutable: config.dockerExecutable,
+        dockerContext: config.dockerContext,
+        stateRoot: config.sandboxStateRoot,
+        maxConcurrentSandboxes: config.maxConcurrentSandboxes,
+        diskHighWatermarkPercent: config.diskHighWatermarkPercent,
+        diskLowWatermarkPercent: config.diskLowWatermarkPercent,
+        minimumWorkspaceBytes: config.minimumWorkspaceBytes,
+        requireRootless: config.requireRootlessDocker
+    });
+    try {
+        const result = await preflight.refresh();
+        if (!result.healthy && result.unavailableCode !== "docker_disk_low") {
+            io.stderr.write(`Docker: unavailable (${result.unavailableCode ?? "preflight_failed"}): ${result.unavailableReason ?? "unknown reason"}\n`);
+            return 1;
+        }
+        const runtime = new DockerSandboxRuntime(config);
+        await runtime.reap({ diskLow: result.diskLow });
+        io.stdout.write(`Sandbox reaper completed for runner ${config.runnerId}.\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        await preflight.release();
+    }
+}
 function parseConnectArgs(argv) {
     let serverUrl = null;
     let runnerId = null;
@@ -468,7 +632,7 @@ async function claimBridgeRunner(args) {
         })
     });
     if (!response.ok) {
-        throw new Error(`Pairing failed (${response.status}): ${await response.text()}`);
+        throw new Error(formatPairingFailure(response.status, args.serverUrl, await response.text()));
     }
     const value = await response.json();
     if (!value.runnerId || !value.deviceToken) {
@@ -497,6 +661,8 @@ function pairedConfig(current, args, claim) {
         supportsManagedForgeArtifacts: current.supportsManagedForgeArtifacts ?? true,
         supportsRunnerAuthoredPhaseArtifacts: current.supportsRunnerAuthoredPhaseArtifacts ?? true,
         supportsDraftRunOnce: current.supportsDraftRunOnce ?? true,
+        supportsDraftAttachments: current.supportsDraftAttachments ?? true,
+        supportsDraftImageAttachments: supportsDraftImageAttachmentsFor(args.cliProviders),
         repoMappings: current.repoMappings ?? []
     };
 }
@@ -541,181 +707,15 @@ async function resolvePairRepoRoot(repoRoot, configuredRoot) {
 function normalizePairingCode(code) {
     return code?.replace(/[\s-]/g, "").trim() ?? "";
 }
+function formatPairingFailure(status, serverUrl, body) {
+    const hint = body.includes("runner.invalid_pairing_code")
+        ? " Make sure the code was generated by the same Forge server shown above."
+        : "";
+    return `Pairing failed (${status}) against ${serverUrl}: ${body}${hint}`;
+}
 function normalizeServerUrl(serverUrl) {
     return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
 }
-function usage() {
-    return helpText();
-}
-function helpText() {
-    const version = defaultBridgeServiceConfig().version ?? forgeBridgeVersion;
-    return [
-        `🛠 Forge Bridge ${version} — Local provider runners for Forge.`,
-        "",
-        "Usage: forge-bridge [options] [command]",
-        "",
-        "Options:",
-        "  -h, --help       Display help for command",
-        "  -v, --version    Output the version number",
-        "",
-        "Commands:",
-        "  Hint: commands suffixed with * have detailed help. Run <command> --help for details.",
-        "  connect *        Start the runner bridge and wait for Forge dispatches",
-        "  pair *           Pair this machine with Forge and save runner credentials",
-        "  status *         Show config, runner identity, repos, provider CLIs, and updates",
-        "  add-repo *       Map a Forge repo label/name to a local checkout path",
-        "  remove-repo *    Remove a saved repo mapping",
-        "  cleanup *        Prune managed bridge worktrees",
-        "  version *        Print the installed bridge package version",
-        "  help *           Display help for command",
-        "  run-once *       Internal: run one dispatch packet from JSON",
-        "  mcp *            Internal: run the phase-completion MCP server",
-        "",
-        "Examples:",
-        "  npm install -g @loucompanion/forge-bridge@next",
-        "  forge-bridge pair 1234-5678 --server https://srv1493013.tail66073d.ts.net:8443 --repo-root \"%USERPROFILE%\\ForgeRepos\"",
-        "  forge-bridge connect",
-        "  forge-bridge status --check-updates",
-        "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
-        "  forge-bridge cleanup --stale",
-        "",
-        "Troubleshooting:",
-        "  If Forge says the bridge is old: npm install -g @loucompanion/forge-bridge@next",
-        "  If connect shows 502/500: leave it open; it reconnects with backoff while dev restarts.",
-        "  If a provider is missing: run forge-bridge status --check-updates and verify CLI login.",
-        "",
-        "Docs:",
-        "  https://github.com/coleman399/Forge/tree/develop/tools/forge-bridge#readme",
-        "",
-    ].join("\n");
-}
-function commandHelpText(command) {
-    switch (command) {
-        case "pair":
-            return [
-                "Forge Bridge — pair",
-                "Pair this machine with Forge and save runner credentials.",
-                "",
-                "Usage:",
-                "  forge-bridge pair [code] [options]",
-                "",
-                "Options:",
-                "  --server <url>              Forge server URL.",
-                "  --repo-root <path>          Folder where bridge-managed repos/worktrees live.",
-                "  --name <name>               Display name for this runner.",
-                "  --fingerprint <value>       Stable device fingerprint override.",
-                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
-                "  --cleanup-worktrees         Enable managed worktree cleanup.",
-                "  --no-cleanup-worktrees      Disable managed worktree cleanup.",
-                "",
-                "Example:",
-                "  forge-bridge pair 1234-5678 --server https://forge.example.com --repo-root \"%USERPROFILE%\\ForgeRepos\"",
-                "",
-            ].join("\n");
-        case "connect":
-            return [
-                "Forge Bridge — connect",
-                "Start the runner bridge and keep it connected for Forge dispatches.",
-                "",
-                "Usage:",
-                "  forge-bridge connect [options]",
-                "",
-                "Options:",
-                "  --server <url>              Forge server URL; saved config is used when omitted.",
-                "  --runner-id <id>            Runner id; saved config is used when omitted.",
-                "  --device-token <token>      Device token; saved config is used when omitted.",
-                "  --repo-root <path>          Override repo/worktree folder for this run.",
-                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
-                "  --heartbeat-interval-ms <n> Heartbeat interval in milliseconds.",
-                "  --cleanup-worktrees         Enable managed worktree cleanup for this run.",
-                "  --no-cleanup-worktrees      Disable managed worktree cleanup for this run.",
-                "",
-                "Example:",
-                "  forge-bridge connect",
-                "",
-            ].join("\n");
-        case "status":
-            return [
-                "Forge Bridge — status",
-                "Show saved configuration, paired runner identity, repo mappings, detected provider CLIs, and optional update info.",
-                "",
-                "Usage:",
-                "  forge-bridge status [--check-updates]",
-                "",
-                "Example:",
-                "  forge-bridge status --check-updates",
-                "",
-            ].join("\n");
-        case "add-repo":
-            return [
-                "Forge Bridge — add-repo",
-                "Map a Forge repo label/name to an existing local checkout.",
-                "",
-                "Usage:",
-                "  forge-bridge add-repo <label> <path>",
-                "",
-                "Example:",
-                "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
-                "",
-            ].join("\n");
-        case "remove-repo":
-            return [
-                "Forge Bridge — remove-repo",
-                "Remove a saved local repo mapping.",
-                "",
-                "Usage:",
-                "  forge-bridge remove-repo <label>",
-                "",
-            ].join("\n");
-        case "cleanup":
-            return [
-                "Forge Bridge — cleanup",
-                "Prune managed bridge worktrees under the configured repo folder.",
-                "",
-                "Usage:",
-                "  forge-bridge cleanup [--stale|--merged|--all] [--force]",
-                "",
-                "Examples:",
-                "  forge-bridge cleanup --stale",
-                "  forge-bridge cleanup --all --force",
-                "",
-            ].join("\n");
-        case "run-once":
-            return [
-                "Forge Bridge — run-once",
-                "Internal command used by Forge to run a single dispatch packet.",
-                "",
-                "Usage:",
-                "  forge-bridge run-once --dispatch <dispatch-json-path> --result <result-json-path>",
-                "",
-            ].join("\n");
-        case "mcp":
-            return [
-                "Forge Bridge — mcp",
-                "Internal MCP server used by provider CLIs to report Forge phase artifacts.",
-                "",
-                "Usage:",
-                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>",
-                "",
-            ].join("\n");
-        case "version":
-            return [
-                "Forge Bridge — version",
-                "Print the installed bridge package version.",
-                "",
-                "Usage:",
-                "  forge-bridge version",
-                "",
-            ].join("\n");
-        default:
-            return [
-                `Unknown forge-bridge command: ${command}`,
-                "",
-                "Run `forge-bridge help` to see available commands.",
-                "",
-            ].join("\n");
-    }
-}
 function connectStartupText(config) {
     const runner = config.runnerId
         ? `${config.runnerId}${config.deviceName ? ` (${config.deviceName})` : ""}`
@@ -862,17 +862,9 @@ async function execVersionCommand(probe, timeout = 2000) {
         if (process.platform !== "win32") {
             throw error;
         }
-        return await execFileAsync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", windowsCommandLine(probe)], { timeout });
-    }
-}
-function windowsCommandLine(probe) {
-    return [probe.command, ...probe.args].map(quoteWindowsCommandLineArg).join(" ");
-}
-function quoteWindowsCommandLineArg(value) {
-    if (value.length > 0 && !/[\s"]/.test(value)) {
-        return value;
+        const launch = buildWindowsCmdLaunch(probe.command, probe.args);
+        return await execFileAsync(launch.command, [...launch.args], { timeout });
     }
-    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, "$1$1")}"`;
 }
 function versionLine(output) {
     const lines = output

package/dist/cli/local-config.d.ts

@@ -17,6 +17,8 @@ export interface BridgeLocalConfig {
     readonly supportsManagedForgeArtifacts?: boolean;
     readonly supportsRunnerAuthoredPhaseArtifacts?: boolean;
     readonly supportsDraftRunOnce?: boolean;
+    readonly supportsDraftAttachments?: boolean;
+    readonly supportsDraftImageAttachments?: boolean;
 }
 export interface LocalRepoMapping extends BridgeRepoMapping {
     readonly label: string;

package/dist/cli/local-config.js

@@ -54,7 +54,9 @@ export function applyLocalConfigDefaults(config, local) {
         supportsManagedWorktrees: local.supportsManagedWorktrees ?? config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: local.supportsManagedForgeArtifacts ?? config.supportsManagedForgeArtifacts,
         supportsRunnerAuthoredPhaseArtifacts: local.supportsRunnerAuthoredPhaseArtifacts ?? config.supportsRunnerAuthoredPhaseArtifacts,
-        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce
+        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce,
+        supportsDraftAttachments: local.supportsDraftAttachments ?? config.supportsDraftAttachments,
+        supportsDraftImageAttachments: local.supportsDraftImageAttachments ?? config.supportsDraftImageAttachments
     };
 }
 export async function addRepoMapping(label, repoPath) {
@@ -113,7 +115,9 @@ function normalizeLocalConfig(config) {
         supportsManagedWorktrees: config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: config.supportsManagedForgeArtifacts,
         supportsRunnerAuthoredPhaseArtifacts: config.supportsRunnerAuthoredPhaseArtifacts,
-        supportsDraftRunOnce: config.supportsDraftRunOnce
+        supportsDraftRunOnce: config.supportsDraftRunOnce,
+        supportsDraftAttachments: config.supportsDraftAttachments,
+        supportsDraftImageAttachments: config.supportsDraftImageAttachments
     };
 }
 function emptyConfig() {

package/dist/sandbox/command-runner.d.ts

@@ -0,0 +1,4 @@
+import type { CommandOptions, CommandResult, CommandRunner } from "./sandbox.types.js";
+export declare class BoundedCommandRunner implements CommandRunner {
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}

package/dist/sandbox/command-runner.js

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+export class BoundedCommandRunner {
+    async run(command, args, options = {}) {
+        const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
+        return await new Promise((resolve, reject) => {
+            const controller = new AbortController();
+            const abort = () => controller.abort(options.signal?.reason ?? "command cancelled");
+            options.signal?.addEventListener("abort", abort, { once: true });
+            const timeout = options.timeoutMs
+                ? setTimeout(() => controller.abort(`command exceeded ${options.timeoutMs}ms`), options.timeoutMs)
+                : null;
+            timeout?.unref?.();
+            const child = spawn(command, [...args], {
+                cwd: options.cwd,
+                env: options.env ? { ...options.env } : undefined,
+                stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+                signal: controller.signal,
+                windowsHide: true,
+            });
+            let stdout = Buffer.alloc(0);
+            let stderr = Buffer.alloc(0);
+            const append = (current, chunk) => {
+                if (current.length >= maxOutputBytes)
+                    return current;
+                return Buffer.concat([current, chunk.subarray(0, maxOutputBytes - current.length)]);
+            };
+            child.stdout.on("data", (chunk) => { stdout = append(stdout, chunk); });
+            child.stderr.on("data", (chunk) => { stderr = append(stderr, chunk); });
+            child.on("error", (error) => {
+                cleanup();
+                reject(error);
+            });
+            child.on("close", (code) => {
+                cleanup();
+                resolve({ exitCode: code ?? 1, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8") });
+            });
+            if (options.stdin !== undefined) {
+                child.stdin.end(options.stdin);
+            }
+            function cleanup() {
+                if (timeout)
+                    clearTimeout(timeout);
+                options.signal?.removeEventListener("abort", abort);
+            }
+        });
+    }
+}

package/dist/sandbox/contract.d.ts

@@ -0,0 +1,5 @@
+import type { ValidatedSandboxContract } from "./sandbox.types.js";
+export declare function validateSandboxContract(source: string): ValidatedSandboxContract;
+export declare function validateDockerfilePolicy(source: string, requirePinnedBase: boolean): readonly string[];
+export declare function dockerfileBaseImages(source: string): readonly string[];
+export declare function dockerfileUpstreamImages(source: string): readonly string[];