@loucompanion/forge-bridge 0.1.3-dev.09aeeb7ccadf → 0.1.3-dev.1fe428dd78ab

package/dist/bridge/bridge.types.d.ts

@@ -1,7 +1,26 @@
-import type { RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+import type { ApiKeySecretGrant, RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+import type { SandboxFeatureMatrix } from "../sandbox/sandbox.types.js";
 export interface BridgeServiceConfig {
     readonly serverUrl: string;
     readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly trustDomainId: string;
+    readonly maxConcurrentSandboxes: number;
+    readonly maxConcurrentSandboxBuilds: number;
+    readonly sandboxPidCapacity: number;
+    readonly dockerEnabled: boolean;
+    readonly sandboxPublicationMode?: "bridge_push" | "shared_filesystem";
+    readonly dockerExecutable: string;
+    readonly dockerContext: string;
+    readonly sandboxStateRoot: string;
+    readonly requireRootlessDocker: boolean;
+    readonly diskHighWatermarkPercent: number;
+    readonly diskLowWatermarkPercent: number;
+    readonly minimumWorkspaceBytes: number;
+    readonly imageRetentionCount: number;
+    readonly imageRetentionTtlMs: number;
+    readonly auditRetentionCount: number;
+    readonly auditRetentionTtlMs: number;
     readonly deviceToken: string;
     readonly deviceName: string;
     readonly defaultRepoRoot: string;
@@ -54,6 +73,25 @@ export interface BridgeCapabilities {
     readonly repoMappings?: readonly BridgeRepoMapping[] | null;
     readonly os?: string | null;
     readonly sandboxProfiles?: readonly string[] | null;
+    readonly runnerInstanceId?: string | null;
+    readonly trustDomainId?: string | null;
+    readonly sandboxRuntimes?: readonly string[] | null;
+    readonly sandboxRuntimeVersion?: string | null;
+    readonly sandboxFeatures?: SandboxFeatureMatrix | null;
+    readonly sandboxPublicationModes?: readonly string[] | null;
+    readonly sandboxAuthModes?: Readonly<Record<string, readonly string[]>> | null;
+    readonly maxConcurrentSandboxes?: number | null;
+    readonly reservedSandboxCount?: number | null;
+    readonly activeSandboxCount?: number | null;
+    readonly startingSandboxCount?: number | null;
+    readonly degradedReservationCount?: number | null;
+    readonly availableMemoryBytes?: number | null;
+    readonly availableCpuMillis?: number | null;
+    readonly availableWorkspaceBytes?: number | null;
+    readonly diskLow?: boolean | null;
+    readonly preflightGeneration?: number | null;
+    readonly sandboxUnavailableCode?: string | null;
+    readonly sandboxUnavailableReason?: string | null;
     readonly supportsApiSecretGrant?: boolean | null;
     readonly supportsManagedWorktrees?: boolean | null;
     readonly supportsManagedForgeArtifacts?: boolean | null;
@@ -67,6 +105,19 @@ export interface BridgeHelloRequest {
     readonly protocolVersion: number;
     readonly capabilities: BridgeCapabilities;
     readonly minServerVersion?: string | null;
+    readonly runnerInstanceId: string;
+}
+export interface BridgePublishCredential {
+    readonly username: string;
+    readonly secret: string;
+    readonly remoteUrl: string;
+    readonly expiresAt: string;
+}
+export interface BridgePublishGrantRedemptionResponse {
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+    readonly credential?: BridgePublishCredential | null;
 }
 export interface BridgeHeartbeatRequest {
     readonly status?: string | null;
@@ -82,17 +133,75 @@ export interface BridgeCallbackAck {
 export interface BridgeDispatchEventCallback {
     readonly leaseId: string;
     readonly fencingToken: string;
+    readonly dispatchAttemptId?: string | null;
+    readonly runnerInstanceId?: string | null;
     readonly event: RunnerDispatchEvent;
 }
 export interface BridgeDispatchResultCallback {
     readonly leaseId: string;
     readonly fencingToken: string;
+    readonly dispatchAttemptId?: string | null;
+    readonly runnerInstanceId?: string | null;
     readonly result: RunOnceResultPacket;
 }
+export interface BridgeOfferDecisionCallback {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+    readonly reservedUntil?: string | null;
+}
+export interface BridgeDispatchStartedCallback {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+}
+export interface BridgeSecretGrantRedemptionRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly grantId: string;
+}
+export interface BridgeSecretGrantRedemptionResponse extends BridgeCallbackAck {
+    readonly grant?: ApiKeySecretGrant | null;
+}
+export interface BridgeLeaseUpdateRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly expiresAt: string;
+}
 export interface BridgeCancelRequest {
     readonly leaseId: string;
     readonly fencingToken: string;
     readonly reason?: string | null;
 }
+export interface BridgeReapRequest {
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly requestedAt: string;
+    readonly reason?: string | null;
+}
+export interface BridgeAttemptSnapshotItem {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly status: string;
+    readonly expiresAt: string;
+}
+export interface BridgeAttemptSnapshotResponse extends BridgeCallbackAck {
+    readonly attempts?: readonly BridgeAttemptSnapshotItem[] | null;
+    readonly generatedAt?: string | null;
+}
 export type BridgeDispatchHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeOfferHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeStartHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeLeaseUpdateHandler = (request: BridgeLeaseUpdateRequest) => Promise<void>;
 export type BridgeCancelHandler = (request: BridgeCancelRequest) => Promise<void>;
+export type BridgeReapHandler = (request: BridgeReapRequest) => Promise<void>;

package/dist/cli/cli.help.js

@@ -19,6 +19,7 @@ export function helpText() {
         "  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",
+        "  sandbox *        Initialize, diagnose, or reap Docker sandboxes",
         "  version *        Print the installed bridge package version",
         "  help *           Display help for command",
         "  run-once *       Internal: run one dispatch packet from JSON",
@@ -133,6 +134,17 @@ export function commandHelpText(command) {
                 "  forge-bridge cleanup --all --force",
                 "",
             ].join("\n");
+        case "sandbox":
+            return [
+                "Forge Bridge — sandbox",
+                "Initialize or diagnose a repository-owned Forge sandbox contract.",
+                "",
+                "Usage:",
+                "  forge-bridge sandbox init [--repo <path>]",
+                "  forge-bridge sandbox doctor [--repo <path>] [--require-pinned-base]",
+                "  forge-bridge sandbox reap",
+                "",
+            ].join("\n");
         case "run-once":
             return [
                 "Forge Bridge — run-once",

package/dist/cli/cli.service.d.ts

@@ -45,6 +45,18 @@ export declare function parseArgs(argv: readonly string[]): {
     readonly config: BridgeServiceConfig;
     readonly mode: CleanupMode;
     readonly force: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-init";
+    readonly repoPath: string;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-doctor";
+    readonly repoPath: string;
+    readonly requirePinnedBase: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-reap";
 } | {
     readonly ok: false;
     readonly error: string;

package/dist/cli/cli.service.js

@@ -12,6 +12,9 @@ import { defaultBridgeServiceConfig, ForgeBridgeService } from "../bridge/bridge
 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";
@@ -89,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 });
@@ -125,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) {
@@ -253,6 +266,9 @@ 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,
@@ -283,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;
@@ -471,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) {
@@ -546,6 +707,12 @@ 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}/`;
 }

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[];