@getforgeai/cli 0.1.0-beta.1

package/dist/vm/git-credentials.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Git credential injection for in-container git operations.
+ *
+ * The developer's git credential (often a GitHub PAT) must NOT:
+ *   - appear in the host `docker exec` argv (readable via ps / /proc/<pid>/cmdline)
+ *   - persist in the cloned repo's .git/config (remote.origin.url), where a
+ *     prompt-injectable agent could `cat` it out of the container.
+ *
+ * So we clone with a CLEAN url (no userinfo) and supply the credential
+ * out-of-band via an inline git credential helper that reads the value from
+ * environment variables. Those env vars are passed to the container with
+ * docker's name-only `-e KEY` form (see docker-executor `secretEnv`), so the
+ * value is sourced from the daemon's environment and never lands in any argv.
+ * The helper script itself only references the env var NAMES.
+ *
+ * The value therefore exists only transiently, in the environment of the
+ * specific CLI-driven git process (clone / push), and nowhere durable.
+ */
+export type GitCredentials = {
+    username: string;
+    password: string;
+};
+/** Env var names the inline credential helper reads at run time. */
+export declare const GIT_CRED_USER_ENV = "FORGE_GIT_USER";
+export declare const GIT_CRED_PASS_ENV = "FORGE_GIT_PASS";
+/**
+ * `git -c` arguments that install an inline credential helper.
+ *
+ * The first (empty) helper resets any helper inherited from the container's
+ * git config, so only ours is consulted. The second echoes the credential from
+ * the FORGE_GIT_* env vars — the values are expanded by git's own `sh -c` at
+ * helper run time, so they never appear in this process's argv.
+ */
+export declare function gitCredentialConfigArgs(): string[];
+/**
+ * The same inline helper, ready to embed inside a `bash -c "..."` string.
+ * Single-quoted so neither the host-side string construction nor the
+ * container's bash expands the env vars — only git's helper `sh -c` does.
+ */
+export declare function gitCredentialConfigShellFragment(): string;
+/** secretEnv map (name-only docker -e) carrying the credential values. */
+export declare function gitCredentialSecretEnv(creds: GitCredentials): Record<string, string>;
+//# sourceMappingURL=git-credentials.d.ts.map

package/dist/vm/git-credentials.js

@@ -0,0 +1,53 @@
+/**
+ * Git credential injection for in-container git operations.
+ *
+ * The developer's git credential (often a GitHub PAT) must NOT:
+ *   - appear in the host `docker exec` argv (readable via ps / /proc/<pid>/cmdline)
+ *   - persist in the cloned repo's .git/config (remote.origin.url), where a
+ *     prompt-injectable agent could `cat` it out of the container.
+ *
+ * So we clone with a CLEAN url (no userinfo) and supply the credential
+ * out-of-band via an inline git credential helper that reads the value from
+ * environment variables. Those env vars are passed to the container with
+ * docker's name-only `-e KEY` form (see docker-executor `secretEnv`), so the
+ * value is sourced from the daemon's environment and never lands in any argv.
+ * The helper script itself only references the env var NAMES.
+ *
+ * The value therefore exists only transiently, in the environment of the
+ * specific CLI-driven git process (clone / push), and nowhere durable.
+ */
+/** Env var names the inline credential helper reads at run time. */
+export const GIT_CRED_USER_ENV = "FORGE_GIT_USER";
+export const GIT_CRED_PASS_ENV = "FORGE_GIT_PASS";
+/**
+ * `git -c` arguments that install an inline credential helper.
+ *
+ * The first (empty) helper resets any helper inherited from the container's
+ * git config, so only ours is consulted. The second echoes the credential from
+ * the FORGE_GIT_* env vars — the values are expanded by git's own `sh -c` at
+ * helper run time, so they never appear in this process's argv.
+ */
+export function gitCredentialConfigArgs() {
+    return [
+        "-c",
+        "credential.helper=",
+        "-c",
+        `credential.helper=!f() { echo username=$${GIT_CRED_USER_ENV}; echo password=$${GIT_CRED_PASS_ENV}; }; f`,
+    ];
+}
+/**
+ * The same inline helper, ready to embed inside a `bash -c "..."` string.
+ * Single-quoted so neither the host-side string construction nor the
+ * container's bash expands the env vars — only git's helper `sh -c` does.
+ */
+export function gitCredentialConfigShellFragment() {
+    return `-c credential.helper= -c 'credential.helper=!f() { echo username=$${GIT_CRED_USER_ENV}; echo password=$${GIT_CRED_PASS_ENV}; }; f'`;
+}
+/** secretEnv map (name-only docker -e) carrying the credential values. */
+export function gitCredentialSecretEnv(creds) {
+    return {
+        [GIT_CRED_USER_ENV]: creds.username,
+        [GIT_CRED_PASS_ENV]: creds.password,
+    };
+}
+//# sourceMappingURL=git-credentials.js.map

package/dist/vm/image-manager.d.ts

@@ -0,0 +1,7 @@
+/** Docker image name for ForgeAI agent containers */
+export declare const FORGEAI_IMAGE: string;
+export declare function imageExists(): Promise<boolean>;
+export declare function pullImage(): Promise<void>;
+export declare function buildImage(): Promise<void>;
+export declare function ensureImage(): Promise<string>;
+//# sourceMappingURL=image-manager.d.ts.map

package/dist/vm/image-manager.js

@@ -0,0 +1,61 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import chalk from "chalk";
+const execFileAsync = promisify(execFile);
+/** Docker image name for ForgeAI agent containers */
+export const FORGEAI_IMAGE = process.env.FORGEAI_DOCKER_IMAGE ?? "forgeai/agent:latest";
+/** Path to the Dockerfile for building the agent image */
+function getDockerfilePath() {
+    // From dist/vm/ or src/vm/, go up to cli root, then rootfs/
+    const cliRoot = join(import.meta.dirname, "..", "..");
+    return join(cliRoot, "rootfs");
+}
+export async function imageExists() {
+    try {
+        await execFileAsync("docker", ["image", "inspect", FORGEAI_IMAGE], {
+            timeout: 10_000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function pullImage() {
+    console.log(chalk.cyan(`[image-manager] Pulling Docker image ${FORGEAI_IMAGE}...`));
+    try {
+        await execFileAsync("docker", ["pull", FORGEAI_IMAGE], {
+            timeout: 600_000,
+        });
+        console.log(chalk.green(`[image-manager] Image pulled: ${FORGEAI_IMAGE}`));
+    }
+    catch {
+        console.log(chalk.yellow(`[image-manager] Pull failed, will try local build`));
+        throw new Error(`Failed to pull ${FORGEAI_IMAGE}`);
+    }
+}
+export async function buildImage() {
+    const contextDir = getDockerfilePath();
+    if (!existsSync(join(contextDir, "Dockerfile"))) {
+        throw new Error(`Dockerfile not found at ${contextDir}/Dockerfile`);
+    }
+    console.log(chalk.cyan(`[image-manager] Building Docker image ${FORGEAI_IMAGE}...`));
+    await execFileAsync("docker", ["build", "--platform", "linux/arm64", "-t", FORGEAI_IMAGE, contextDir], { timeout: 600_000 });
+    console.log(chalk.green(`[image-manager] Image built: ${FORGEAI_IMAGE}`));
+}
+export async function ensureImage() {
+    if (await imageExists()) {
+        return FORGEAI_IMAGE;
+    }
+    // Try pull first, fall back to local build
+    try {
+        await pullImage();
+    }
+    catch {
+        await buildImage();
+    }
+    return FORGEAI_IMAGE;
+}
+//# sourceMappingURL=image-manager.js.map

package/dist/vm/log.d.ts

@@ -0,0 +1,9 @@
+export declare const vmLog: {
+    info: (prefix: string, msg: string, sessionId?: string) => void;
+    warn: (prefix: string, msg: string, sessionId?: string) => void;
+    error: (prefix: string, msg: string, sessionId?: string) => void;
+    dim: (prefix: string, msg: string, sessionId?: string) => void;
+    cyan: (prefix: string, msg: string, sessionId?: string) => void;
+    magenta: (prefix: string, msg: string, sessionId?: string) => void;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/vm/log.js

@@ -0,0 +1,18 @@
+import chalk from "chalk";
+function utc() {
+    return new Date().toISOString().replace("T", " ").slice(0, 19) + "Z";
+}
+function fmt(prefix, msg, sessionId) {
+    const ts = chalk.dim(utc());
+    const sid = sessionId ? chalk.dim(`{${sessionId.slice(0, 20)}}`) + " " : "";
+    return `${ts} ${sid}[${prefix}] ${msg}`;
+}
+export const vmLog = {
+    info: (prefix, msg, sessionId) => console.log(fmt(prefix, chalk.green(msg), sessionId)),
+    warn: (prefix, msg, sessionId) => console.log(fmt(prefix, chalk.yellow(msg), sessionId)),
+    error: (prefix, msg, sessionId) => console.log(fmt(prefix, chalk.red(msg), sessionId)),
+    dim: (prefix, msg, sessionId) => console.log(fmt(prefix, chalk.dim(msg), sessionId)),
+    cyan: (prefix, msg, sessionId) => console.log(fmt(prefix, chalk.cyan(msg), sessionId)),
+    magenta: (prefix, msg, sessionId) => console.log(fmt(prefix, chalk.magenta(msg), sessionId)),
+};
+//# sourceMappingURL=log.js.map

package/dist/vm/mcp-bridge.d.ts

@@ -0,0 +1,63 @@
+/**
+ * TCP MCP Bridge — Host-side bridge for Docker agent containers.
+ *
+ * Creates a TCP server on a per-session port. When the in-container
+ * forge-mcp-relay connects, pipes the TCP socket to an MCP server
+ * running in the daemon process.
+ *
+ * Data flow:
+ *   Container: Claude Code → forge-mcp-relay → TCP connect to host
+ *   Host: TCP socket → PassThrough → MCP server (stdio transport) → Cloud API
+ *
+ * Security:
+ *   - The listener binds to 127.0.0.1 (macOS/Windows Docker Desktop forwards
+ *     host.docker.internal to the host loopback) or the Docker bridge gateway
+ *     on Linux — never 0.0.0.0, so the port is not exposed on the LAN.
+ *   - Every connection must authenticate with a per-session shared secret
+ *     before any MCP handling: the first newline-delimited line must be
+ *     `FORGEAI_AUTH <secret>` (constant-time compare). The secret is passed
+ *     to the in-container relay via the MCP config env (FORGEAI_MCP_TOKEN),
+ *     so other containers / processes on the host network cannot invoke
+ *     ForgeAI tools with the org's credentials.
+ */
+import { type Socket } from "node:net";
+import type { McpSessionContext } from "../mcp/types.js";
+export type McpBridgeOptions = {
+    /** Override the auth handshake timeout (for tests). */
+    authTimeoutMs?: number;
+    /** Override the bind host (for tests). */
+    bindHost?: string;
+};
+/**
+ * Constant-time check that an auth line equals `FORGEAI_AUTH <secret>`.
+ * Exported for unit tests.
+ */
+export declare function verifyAuthLine(line: string, secret: string): boolean;
+/**
+ * Read the first newline-delimited line from a socket and verify it against
+ * the per-session secret. Resolves with any bytes received after the auth
+ * line (they belong to the MCP stream). Rejects on bad/missing auth, buffer
+ * overflow, timeout, or socket close.
+ *
+ * The socket is paused on success so no data is lost before the caller
+ * pipes it into the MCP transport. Exported for unit tests.
+ */
+export declare function authenticateSocket(socket: Socket, secret: string, timeoutMs?: number): Promise<Buffer>;
+/**
+ * Start a TCP MCP bridge for a session.
+ *
+ * Creates a TCP server on the given port. When the container's
+ * forge-mcp-relay connects and authenticates with the per-session secret,
+ * creates an MCP server with all ForgeAI tools and pipes JSON-RPC messages
+ * bidirectionally. Unauthenticated connections are destroyed.
+ */
+export declare function startMcpBridge(sessionId: string, port: number, context: McpSessionContext, authSecret: string, options?: McpBridgeOptions): Promise<void>;
+/**
+ * Stop and clean up an MCP bridge for a session.
+ */
+export declare function stopMcpBridge(sessionId: string): Promise<void>;
+/**
+ * Stop all active MCP bridges.
+ */
+export declare function stopAllMcpBridges(): Promise<void>;
+//# sourceMappingURL=mcp-bridge.d.ts.map

package/dist/vm/mcp-bridge.js

@@ -0,0 +1,243 @@
+/**
+ * TCP MCP Bridge — Host-side bridge for Docker agent containers.
+ *
+ * Creates a TCP server on a per-session port. When the in-container
+ * forge-mcp-relay connects, pipes the TCP socket to an MCP server
+ * running in the daemon process.
+ *
+ * Data flow:
+ *   Container: Claude Code → forge-mcp-relay → TCP connect to host
+ *   Host: TCP socket → PassThrough → MCP server (stdio transport) → Cloud API
+ *
+ * Security:
+ *   - The listener binds to 127.0.0.1 (macOS/Windows Docker Desktop forwards
+ *     host.docker.internal to the host loopback) or the Docker bridge gateway
+ *     on Linux — never 0.0.0.0, so the port is not exposed on the LAN.
+ *   - Every connection must authenticate with a per-session shared secret
+ *     before any MCP handling: the first newline-delimited line must be
+ *     `FORGEAI_AUTH <secret>` (constant-time compare). The secret is passed
+ *     to the in-container relay via the MCP config env (FORGEAI_MCP_TOKEN),
+ *     so other containers / processes on the host network cannot invoke
+ *     ForgeAI tools with the org's credentials.
+ */
+import { createServer } from "node:net";
+import { timingSafeEqual } from "node:crypto";
+import { PassThrough } from "node:stream";
+import { createMcpServer, createStdioTransport } from "../mcp/mcp-server.js";
+import { getDockerBridgeGatewayIp } from "./docker-executor.js";
+import { vmLog } from "./log.js";
+// Active bridges keyed by sessionId
+const bridges = new Map();
+// ---------------------------------------------------------------------------
+// Auth handshake
+// ---------------------------------------------------------------------------
+const AUTH_PREFIX = "FORGEAI_AUTH ";
+const MAX_AUTH_LINE_BYTES = 1024;
+const DEFAULT_AUTH_TIMEOUT_MS = 10_000;
+/**
+ * Constant-time check that an auth line equals `FORGEAI_AUTH <secret>`.
+ * Exported for unit tests.
+ */
+export function verifyAuthLine(line, secret) {
+    const expected = Buffer.from(`${AUTH_PREFIX}${secret}`, "utf8");
+    const actual = Buffer.from(line, "utf8");
+    if (actual.length !== expected.length)
+        return false;
+    return timingSafeEqual(actual, expected);
+}
+/**
+ * Read the first newline-delimited line from a socket and verify it against
+ * the per-session secret. Resolves with any bytes received after the auth
+ * line (they belong to the MCP stream). Rejects on bad/missing auth, buffer
+ * overflow, timeout, or socket close.
+ *
+ * The socket is paused on success so no data is lost before the caller
+ * pipes it into the MCP transport. Exported for unit tests.
+ */
+export function authenticateSocket(socket, secret, timeoutMs = DEFAULT_AUTH_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        let buffered = Buffer.alloc(0);
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.off("data", onData);
+            socket.off("close", onClose);
+            socket.off("error", onError);
+            socket.pause();
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error("Auth handshake timed out"));
+        }, timeoutMs);
+        const onData = (chunk) => {
+            buffered = Buffer.concat([buffered, chunk]);
+            const newlineIdx = buffered.indexOf(0x0a);
+            if (newlineIdx === -1) {
+                if (buffered.length > MAX_AUTH_LINE_BYTES) {
+                    cleanup();
+                    reject(new Error("Auth line exceeds maximum length"));
+                }
+                return;
+            }
+            if (newlineIdx > MAX_AUTH_LINE_BYTES) {
+                cleanup();
+                reject(new Error("Auth line exceeds maximum length"));
+                return;
+            }
+            const line = buffered
+                .subarray(0, newlineIdx)
+                .toString("utf8")
+                .replace(/\r$/, "");
+            const remainder = Buffer.from(buffered.subarray(newlineIdx + 1));
+            cleanup();
+            if (verifyAuthLine(line, secret)) {
+                resolve(remainder);
+            }
+            else {
+                reject(new Error("Invalid auth line"));
+            }
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error("Socket closed before auth completed"));
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err);
+        };
+        socket.on("data", onData);
+        socket.on("close", onClose);
+        socket.on("error", onError);
+    });
+}
+// ---------------------------------------------------------------------------
+// Bind host resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the host interface the bridge should bind to.
+ *
+ * - Linux: the Docker bridge gateway (containers reach the host through it
+ *   via `--add-host host.docker.internal:host-gateway`).
+ * - macOS/Windows: Docker Desktop proxies host.docker.internal connections
+ *   to the host loopback, so 127.0.0.1 is sufficient and keeps the port
+ *   off the LAN.
+ */
+async function resolveBridgeBindHost() {
+    if (process.platform === "linux") {
+        return getDockerBridgeGatewayIp();
+    }
+    return "127.0.0.1";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Start a TCP MCP bridge for a session.
+ *
+ * Creates a TCP server on the given port. When the container's
+ * forge-mcp-relay connects and authenticates with the per-session secret,
+ * creates an MCP server with all ForgeAI tools and pipes JSON-RPC messages
+ * bidirectionally. Unauthenticated connections are destroyed.
+ */
+export async function startMcpBridge(sessionId, port, context, authSecret, options) {
+    if (!authSecret) {
+        throw new Error("MCP bridge requires a non-empty auth secret");
+    }
+    // Clean up any existing bridge on this port
+    await stopMcpBridge(sessionId);
+    const bindHost = options?.bindHost ?? (await resolveBridgeBindHost());
+    const authTimeoutMs = options?.authTimeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        const tcpServer = createServer((clientSocket) => {
+            const remote = `${clientSocket.remoteAddress ?? "?"}:${clientSocket.remotePort ?? "?"}`;
+            clientSocket.on("error", (err) => {
+                vmLog.warn("mcp-bridge", `Socket error for ${sessionId}: ${err.message}`, sessionId);
+            });
+            authenticateSocket(clientSocket, authSecret, authTimeoutMs)
+                .then((remainder) => {
+                vmLog.info("mcp-bridge", `Relay authenticated for session ${sessionId} on port ${port} (${remote})`, sessionId);
+                wireMcpServer(sessionId, clientSocket, remainder, context);
+            })
+                .catch((err) => {
+                vmLog.warn("mcp-bridge", `Rejected unauthenticated connection from ${remote} on port ${port}: ${err.message}`, sessionId);
+                clientSocket.destroy();
+            });
+        });
+        tcpServer.on("error", (err) => {
+            vmLog.error("mcp-bridge", `TCP server error on port ${port}: ${err.message}`, sessionId);
+            reject(err);
+        });
+        tcpServer.listen(port, bindHost, () => {
+            vmLog.info("mcp-bridge", `Listening on ${bindHost}:${port} for session ${sessionId}`, sessionId);
+            bridges.set(sessionId, {
+                port,
+                server: tcpServer,
+                mcpServer: null,
+                socket: null,
+            });
+            resolve();
+        });
+    });
+}
+/**
+ * Wire an authenticated socket into a fresh MCP server instance.
+ */
+function wireMcpServer(sessionId, clientSocket, remainder, context) {
+    // Create PassThrough streams to pipe between TCP and MCP server
+    const mcpInput = new PassThrough(); // relay → MCP server (requests)
+    const mcpOutput = new PassThrough(); // MCP server → relay (responses)
+    // Bytes that arrived in the same packet as the auth line belong to the
+    // MCP stream — feed them in before piping the live socket.
+    if (remainder.length > 0) {
+        mcpInput.write(remainder);
+    }
+    // Pipe TCP socket ↔ PassThrough streams (resumes the paused socket)
+    clientSocket.pipe(mcpInput);
+    mcpOutput.pipe(clientSocket);
+    // Create MCP server with the PassThrough streams as transport
+    const mcpServer = createMcpServer(context);
+    const transport = createStdioTransport(mcpInput, mcpOutput);
+    mcpServer
+        .connect(transport)
+        .then(() => {
+        vmLog.info("mcp-bridge", `MCP server connected for session ${sessionId}`, sessionId);
+    })
+        .catch((err) => {
+        vmLog.error("mcp-bridge", `MCP server connect failed: ${err.message}`, sessionId);
+    });
+    // Update bridge state
+    const bridge = bridges.get(sessionId);
+    if (bridge) {
+        bridge.mcpServer = mcpServer;
+        bridge.socket = clientSocket;
+    }
+    clientSocket.on("close", () => {
+        vmLog.info("mcp-bridge", `Relay disconnected for session ${sessionId}`, sessionId);
+    });
+}
+/**
+ * Stop and clean up an MCP bridge for a session.
+ */
+export async function stopMcpBridge(sessionId) {
+    const bridge = bridges.get(sessionId);
+    if (!bridge)
+        return;
+    try {
+        if (bridge.socket) {
+            bridge.socket.destroy();
+        }
+        bridge.server.close();
+    }
+    catch {
+        /* best effort */
+    }
+    bridges.delete(sessionId);
+}
+/**
+ * Stop all active MCP bridges.
+ */
+export async function stopAllMcpBridges() {
+    for (const sessionId of bridges.keys()) {
+        await stopMcpBridge(sessionId);
+    }
+}
+//# sourceMappingURL=mcp-bridge.js.map

package/dist/vm/mcp-stub.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * forge-mcp-stub — In-VM MCP forwarder for ForgeAI.
+ *
+ * Launched by Claude Code inside the VM as its MCP server.
+ * Reads JSON-RPC from stdin, forwards to host via vsock channel 3,
+ * and pipes responses back to stdout.
+ *
+ * This script contains NO credentials and has NO direct Cloud access.
+ * All MCP tool calls are handled by the host-side MCP bridge.
+ *
+ * Baked into the VM rootfs image at /usr/local/bin/forge-mcp-stub
+ */
+export {};
+//# sourceMappingURL=mcp-stub.d.ts.map

package/dist/vm/mcp-stub.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * forge-mcp-stub — In-VM MCP forwarder for ForgeAI.
+ *
+ * Launched by Claude Code inside the VM as its MCP server.
+ * Reads JSON-RPC from stdin, forwards to host via vsock channel 3,
+ * and pipes responses back to stdout.
+ *
+ * This script contains NO credentials and has NO direct Cloud access.
+ * All MCP tool calls are handled by the host-side MCP bridge.
+ *
+ * Baked into the VM rootfs image at /usr/local/bin/forge-mcp-stub
+ */
+import { createConnection } from "node:net";
+const CHANNEL_MCP = 3;
+const HEADER_SIZE = 5;
+const VSOCK_PORT = parseInt(process.argv[2] ?? process.env.FORGE_VSOCK_PORT ?? "6789", 10);
+let hostSocket = null;
+let vsockBuffer = Buffer.alloc(0);
+function sendFrame(socket, channel, data) {
+    const payload = typeof data === "string" ? Buffer.from(data) : data;
+    const header = Buffer.alloc(HEADER_SIZE);
+    header[0] = channel;
+    header.writeUInt32BE(payload.length, 1);
+    socket.write(Buffer.concat([header, payload]));
+}
+function processVsockBuffer() {
+    while (vsockBuffer.length >= HEADER_SIZE) {
+        const channel = vsockBuffer[0];
+        const length = vsockBuffer.readUInt32BE(1);
+        if (vsockBuffer.length < HEADER_SIZE + length)
+            break;
+        const payload = vsockBuffer.subarray(HEADER_SIZE, HEADER_SIZE + length);
+        vsockBuffer = vsockBuffer.subarray(HEADER_SIZE + length);
+        if (channel === CHANNEL_MCP) {
+            // Forward MCP response to Claude Code via stdout
+            process.stdout.write(payload);
+        }
+    }
+}
+// Connect to host via vsock (TCP fallback for development)
+const socket = createConnection({ host: "127.0.0.1", port: VSOCK_PORT }, () => {
+    hostSocket = socket;
+    // Forward stdin (from Claude Code) to host via vsock MCP channel
+    process.stdin.on("data", (data) => {
+        if (hostSocket) {
+            sendFrame(hostSocket, CHANNEL_MCP, data);
+        }
+    });
+    process.stdin.on("end", () => {
+        socket.end();
+        process.exit(0);
+    });
+});
+// Receive responses from host
+socket.on("data", (data) => {
+    vsockBuffer = Buffer.concat([vsockBuffer, data]);
+    processVsockBuffer();
+});
+socket.on("error", (err) => {
+    process.stderr.write(`[forge-mcp-stub] Connection error: ${err.message}\n`);
+    process.exit(1);
+});
+socket.on("close", () => {
+    process.exit(0);
+});
+//# sourceMappingURL=mcp-stub.js.map

package/dist/vm/native-addon.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Typed wrapper around the native Swift N-API addon (forgevm.node).
+ * Loads the prebuilt binary or falls back to a local build directory.
+ *
+ * The addon exposes low-level VM lifecycle, vsock communication, and VirtioFS
+ * mount primitives. This module re-exports them with TypeScript types so the
+ * rest of the CLI can use them safely.
+ */
+/** Native addon handle type (opaque — only the addon knows the internal shape) */
+export type VmHandle = unknown;
+/** Configuration for VM creation */
+export type NativeVmConfig = {
+    cpus: number;
+    memoryMB: number;
+    diskPath: string;
+    efiStorePath: string;
+    /** Path to uncompressed ARM64 kernel Image (enables VZLinuxBootLoader) */
+    kernelPath?: string;
+    /** Path to initrd/initramfs image */
+    initrdPath?: string;
+    /** Kernel command line (default: "console=hvc0 root=/dev/vda rw quiet") */
+    cmdline?: string;
+};
+/** VirtioFS mount configuration */
+export type VirtioFsMount = {
+    tag: string;
+    hostPath: string;
+    readOnly: boolean;
+};
+/** Raw addon interface — matches the N-API exports from the Swift addon */
+type ForgeVmAddon = {
+    create(config: NativeVmConfig): VmHandle;
+    start(handle: VmHandle): Promise<void>;
+    stop(handle: VmHandle): Promise<void>;
+    destroy(handle: VmHandle): void;
+    /** Enable NAT networking (requires com.apple.vm.networking entitlement + provisioning profile) */
+    enableNetwork(handle: VmHandle): void;
+    addVirtioFs(handle: VmHandle, tag: string, hostPath: string, readOnly: boolean): void;
+    configureVsock(handle: VmHandle): void;
+    vsockSend(handle: VmHandle, port: number, data: Buffer): void;
+    onVsockData(handle: VmHandle, port: number, callback: (data: Buffer) => void): void;
+    /** Register callback for serial console output from the VM */
+    onSerialData(handle: VmHandle, callback: (data: Buffer) => void): void;
+    /** 0 = created, 1 = booting, 2 = running, 3 = stopping, 4 = stopped, 5 = error */
+    getState(handle: VmHandle): number;
+};
+/**
+ * Load the native addon synchronously.
+ * Searches for the prebuilt binary first, then falls back to a local build.
+ *
+ * Uses `createRequire` to load `.node` binaries in an ESM context
+ * (native addons cannot be loaded with dynamic `import()`).
+ */
+export declare function loadNativeAddon(): ForgeVmAddon;
+export declare const VmState: {
+    readonly CREATED: 0;
+    readonly BOOTING: 1;
+    readonly RUNNING: 2;
+    readonly STOPPING: 3;
+    readonly STOPPED: 4;
+    readonly ERROR: 5;
+};
+/**
+ * Check whether the native addon binary is available on this machine.
+ * Returns false if the addon cannot be loaded (e.g. wrong platform, not built).
+ */
+export declare function isAddonAvailable(): boolean;
+export {};
+//# sourceMappingURL=native-addon.d.ts.map