@getforgeai/cli 0.1.0-beta.1

package/dist/vm/native-addon.js

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { vmLog } from "./log.js";
+// ---------------------------------------------------------------------------
+// Singleton loader
+// ---------------------------------------------------------------------------
+let addon = null;
+/**
+ * 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 function loadNativeAddon() {
+    if (addon)
+        return addon;
+    // import.meta.dirname points to the directory of this file (src/vm/ or dist/vm/)
+    // The CLI package root is two levels up: vm/ -> src|dist/ -> cli/
+    const cliRoot = join(import.meta.dirname, "..", "..");
+    const paths = [
+        join(cliRoot, "native", "prebuilds", `${process.platform}-${process.arch}`, "forgevm.node"),
+        join(cliRoot, "native", "build", "Release", "forgevm.node"),
+    ];
+    const require = createRequire(import.meta.url);
+    for (const p of paths) {
+        if (existsSync(p)) {
+            addon = require(p);
+            vmLog.info("native-addon", `Loaded native addon from ${p}`);
+            return addon;
+        }
+    }
+    throw new Error("Native VM addon not found. Build it with: cd packages/cli/native && swift build && node-gyp rebuild");
+}
+// ---------------------------------------------------------------------------
+// VM state constants (match native addon values)
+// ---------------------------------------------------------------------------
+export const VmState = {
+    CREATED: 0,
+    BOOTING: 1,
+    RUNNING: 2,
+    STOPPING: 3,
+    STOPPED: 4,
+    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 function isAddonAvailable() {
+    try {
+        loadNativeAddon();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=native-addon.js.map

package/dist/vm/provider-resolver.d.ts

@@ -0,0 +1,7 @@
+import type { VmProvider } from "./types.js";
+/**
+ * Resolve the appropriate VM provider based on the current platform.
+ * Caches the provider instance for reuse across the CLI session.
+ */
+export declare function resolveVmProvider(): VmProvider;
+//# sourceMappingURL=provider-resolver.d.ts.map

package/dist/vm/provider-resolver.js

@@ -0,0 +1,27 @@
+import { VfkitProvider } from "./providers/vfkit.js";
+import { QemuProvider } from "./providers/qemu.js";
+import { Wsl2Provider } from "./providers/wsl2.js";
+let cachedProvider = null;
+/**
+ * Resolve the appropriate VM provider based on the current platform.
+ * Caches the provider instance for reuse across the CLI session.
+ */
+export function resolveVmProvider() {
+    if (cachedProvider)
+        return cachedProvider;
+    switch (process.platform) {
+        case "darwin":
+            cachedProvider = new VfkitProvider();
+            break;
+        case "linux":
+            cachedProvider = new QemuProvider();
+            break;
+        case "win32":
+            cachedProvider = new Wsl2Provider();
+            break;
+        default:
+            throw new Error(`Unsupported platform for VM execution: ${process.platform}`);
+    }
+    return cachedProvider;
+}
+//# sourceMappingURL=provider-resolver.js.map

package/dist/vm/providers/lima.d.ts

@@ -0,0 +1,17 @@
+import type { VmConfig, VmInfo, VmProvider, ExecResult } from "../types.js";
+/**
+ * Lima provider for macOS (M-series and Intel).
+ * Manages VM lifecycle using limactl CLI.
+ */
+export declare class LimaProvider implements VmProvider {
+    readonly name = "lima";
+    isAvailable(): Promise<boolean>;
+    start(id: string, config: VmConfig): Promise<VmInfo>;
+    exec(id: string, cmd: string, args?: string[]): Promise<ExecResult>;
+    stop(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+    getInfo(id: string): Promise<VmInfo | null>;
+    getVsockCid(id: string): number;
+    private generateLimaYaml;
+}
+//# sourceMappingURL=lima.d.ts.map

package/dist/vm/providers/lima.js

@@ -0,0 +1,191 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import chalk from "chalk";
+const execFileAsync = promisify(execFile);
+const VM_BASE_DIR = join(homedir(), ".forgeai", "vm", "instances");
+/**
+ * Lima provider for macOS (M-series and Intel).
+ * Manages VM lifecycle using limactl CLI.
+ */
+export class LimaProvider {
+    name = "lima";
+    async isAvailable() {
+        try {
+            await execFileAsync("limactl", ["--version"]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async start(id, config) {
+        const instanceDir = join(VM_BASE_DIR, id);
+        mkdirSync(instanceDir, { recursive: true, mode: 0o700 });
+        const limaYamlPath = join(instanceDir, "lima.yaml");
+        const yaml = this.generateLimaYaml(id, config);
+        writeFileSync(limaYamlPath, yaml, "utf-8");
+        console.log(chalk.cyan(`[lima] Starting VM "${id}" with config: ${config.cpus} CPUs, ${config.memoryMB} MB RAM`));
+        try {
+            await execFileAsync("limactl", ["start", "--name", id, limaYamlPath]);
+        }
+        catch (error) {
+            console.error(chalk.red(`[lima] Failed to start VM: ${error instanceof Error ? error.message : String(error)}`));
+            throw error;
+        }
+        const info = await this.getInfo(id);
+        if (!info) {
+            throw new Error(`Failed to retrieve VM info after start for "${id}"`);
+        }
+        console.log(chalk.green(`[lima] VM "${id}" started successfully`));
+        return info;
+    }
+    async exec(id, cmd, args) {
+        const cmdParts = args ? [cmd, ...args] : [cmd];
+        try {
+            const { stdout, stderr } = await execFileAsync("limactl", [
+                "shell",
+                id,
+                "--",
+                ...cmdParts,
+            ]);
+            return {
+                stdout,
+                stderr,
+                exitCode: 0,
+            };
+        }
+        catch (error) {
+            const execError = error;
+            return {
+                stdout: execError.stdout ?? "",
+                stderr: execError.stderr ?? String(error),
+                exitCode: execError.code ?? 1,
+            };
+        }
+    }
+    async stop(id) {
+        console.log(chalk.cyan(`[lima] Stopping VM "${id}"`));
+        try {
+            await execFileAsync("limactl", ["stop", id]);
+            console.log(chalk.green(`[lima] VM "${id}" stopped`));
+        }
+        catch (error) {
+            console.error(chalk.red(`[lima] Failed to stop VM: ${error instanceof Error ? error.message : String(error)}`));
+            throw error;
+        }
+    }
+    async destroy(id) {
+        console.log(chalk.cyan(`[lima] Destroying VM "${id}"`));
+        try {
+            await execFileAsync("limactl", ["delete", id, "--force"]);
+            console.log(chalk.green(`[lima] VM "${id}" destroyed`));
+        }
+        catch (error) {
+            console.error(chalk.red(`[lima] Failed to destroy VM: ${error instanceof Error ? error.message : String(error)}`));
+            throw error;
+        }
+        const instanceDir = join(VM_BASE_DIR, id);
+        if (existsSync(instanceDir)) {
+            rmSync(instanceDir, { recursive: true, force: true });
+        }
+    }
+    async getInfo(id) {
+        try {
+            const { stdout } = await execFileAsync("limactl", ["list", "--json"]);
+            const instances = JSON.parse(stdout);
+            const instance = instances.find((i) => i.name === id);
+            if (!instance)
+                return null;
+            const vsockCid = this.getVsockCid(id);
+            return {
+                id,
+                status: instance.status === "Running" ? "RUNNING" : "STOPPED",
+                pid: instance.pid,
+                vsockCid,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    getVsockCid(id) {
+        const instanceDir = join(VM_BASE_DIR, id);
+        const configPath = join(instanceDir, "lima.yaml");
+        if (!existsSync(configPath)) {
+            throw new Error(`Lima config not found for VM "${id}"`);
+        }
+        try {
+            const content = readFileSync(configPath, "utf-8");
+            const match = content.match(/guest-cid:\s*(\d+)/);
+            if (match && match[1]) {
+                return parseInt(match[1], 10);
+            }
+        }
+        catch {
+            // Fall through to default
+        }
+        return 3;
+    }
+    generateLimaYaml(id, config) {
+        const vsockPort = config.vsockPort;
+        const cpus = config.cpus;
+        const memoryMB = config.memoryMB;
+        // Validate CIDR format and generate iptables rules
+        const cidrRegex = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\/\d{1,2}$/;
+        const rules = config.networkAllowlist
+            .filter((rule) => cidrRegex.test(rule.cidr))
+            .map((rule) => `iptables -A OUTPUT -p ${rule.protocol} -d ${rule.cidr} --dport ${rule.port} -j ACCEPT`)
+            .join("\n      ");
+        return `images:
+  - location: "https://cloud-images.ubuntu.com/releases/24.04/release-20240423/ubuntu-24.04-server-cloudimg-arm64.img"
+    arch: "aarch64"
+    digest: "sha256:..." # Placeholder; Lima will verify
+
+cpus: ${cpus}
+memory: "${memoryMB}M"
+vmType: vz
+rosetta: true
+
+mounts:
+  - location: ${JSON.stringify(config.sessionDir)}
+    mountPoint: "/session"
+    writable: false
+
+networking:
+  - socket: "vsock://:${vsockPort}"
+    protocol: "tcp"
+
+provision:
+  - mode: system
+    script: |
+      #!/bin/bash
+      set -e
+      apt-get update -qq
+      apt-get install -y -qq iptables openssh-server
+
+      # Default policy: DROP all outbound
+      iptables -P OUTPUT DROP
+      iptables -P INPUT DROP
+      iptables -P FORWARD DROP
+
+      # Allow loopback
+      iptables -A OUTPUT -o lo -j ACCEPT
+      iptables -A INPUT -i lo -j ACCEPT
+
+      # Allow established/related connections
+      iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+      iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+      # Per-rule allowlist (CIDR + port + protocol)
+      ${rules}
+
+hostResolver:
+  enabled: true
+  ipv6: false
+`;
+    }
+}
+//# sourceMappingURL=lima.js.map

package/dist/vm/providers/qemu.d.ts

@@ -0,0 +1,28 @@
+import { type ChildProcess } from "node:child_process";
+import type { VmConfig, VmInfo, VmProvider, ExecResult } from "../types.js";
+/**
+ * QEMU+KVM provider for Linux.
+ * Manages VM lifecycle by spawning QEMU processes with KVM acceleration.
+ */
+export declare class QemuProvider implements VmProvider {
+    readonly name = "qemu";
+    private vms;
+    private nextCid;
+    isAvailable(): Promise<boolean>;
+    start(id: string, config: VmConfig): Promise<VmInfo>;
+    exec(id: string, cmd: string, args?: string[]): Promise<ExecResult>;
+    /**
+     * Spawn a long-lived process in the VM via SSH with piped stdout/stderr.
+     */
+    spawnStreaming(id: string, cmd: string, args: string[], cwd: string): {
+        pid: number;
+        process: ChildProcess;
+    };
+    private generateSetupScript;
+    private getInstanceDir;
+    stop(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+    getInfo(id: string): Promise<VmInfo | null>;
+    getVsockPath(id: string): string;
+}
+//# sourceMappingURL=qemu.d.ts.map

package/dist/vm/providers/qemu.js

@@ -0,0 +1,260 @@
+import { spawn, execFile } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import chalk from "chalk";
+const execFileAsync = promisify(execFile);
+/**
+ * QEMU+KVM provider for Linux.
+ * Manages VM lifecycle by spawning QEMU processes with KVM acceleration.
+ */
+export class QemuProvider {
+    name = "qemu";
+    vms = new Map();
+    nextCid = 3;
+    async isAvailable() {
+        try {
+            const { execSync } = await import("node:child_process");
+            execSync("which qemu-system-x86_64", { stdio: "ignore" });
+            if (!existsSync("/dev/kvm")) {
+                console.warn(chalk.yellow("[qemu] /dev/kvm not found; KVM acceleration unavailable"));
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async start(id, config) {
+        const cid = this.nextCid++;
+        const sshPort = 2222 + cid;
+        console.log(chalk.cyan(`[qemu] Starting VM "${id}" with ${config.cpus} CPUs, ${config.memoryMB} MB RAM, vsock CID ${cid}`));
+        // Generate setup script for network filtering
+        const setupScript = this.generateSetupScript(config);
+        const instanceDir = this.getInstanceDir(id);
+        const setupPath = join(instanceDir, "setup.sh");
+        // Create instance directory and write setup script
+        try {
+            mkdirSync(instanceDir, { recursive: true, mode: 0o700 });
+        }
+        catch {
+            // Directory may already exist
+        }
+        writeFileSync(setupPath, setupScript, { mode: 0o755 });
+        const qemuArgs = [
+            "-machine",
+            "pc,accelerator=kvm",
+            "-cpu",
+            "host",
+            "-smp",
+            `cores=${config.cpus}`,
+            "-m",
+            `${config.memoryMB}`,
+            "-drive",
+            `file=${config.rootfsPath},if=virtio,format=raw`,
+            "-device",
+            `vhost-vsock-pci,guest-cid=${cid}`,
+            "-netdev",
+            `user,id=net0,hostfwd=tcp:127.0.0.1:${sshPort}-:22`,
+            "-device",
+            "virtio-net-pci,netdev=net0",
+            "-nographic",
+            "-monitor",
+            "none",
+        ];
+        return new Promise((resolve, reject) => {
+            const qemuProcess = spawn("qemu-system-x86_64", qemuArgs, {
+                stdio: "ignore",
+                detached: true,
+            });
+            const pid = qemuProcess.pid;
+            if (!pid) {
+                reject(new Error("Failed to spawn QEMU process"));
+                return;
+            }
+            qemuProcess.unref();
+            this.vms.set(id, { pid, cid, sshPort });
+            console.log(chalk.green(`[qemu] VM "${id}" started with PID ${pid}`));
+            resolve({
+                id,
+                status: "RUNNING",
+                pid,
+                vsockCid: cid,
+            });
+        });
+    }
+    async exec(id, cmd, args) {
+        const vm = this.vms.get(id);
+        if (!vm) {
+            return {
+                stdout: "",
+                stderr: `VM "${id}" not found in running VMs`,
+                exitCode: 1,
+            };
+        }
+        console.log(chalk.dim(`[qemu] Executing in "${id}": ${cmd} ${args?.join(" ") ?? ""}`));
+        try {
+            // Shell-escape each argument for SSH remote command
+            const escapedArgs = [cmd, ...(args ?? [])]
+                .map((a) => `'${a.replace(/'/g, "'\\''")}'`)
+                .join(" ");
+            const { stdout, stderr } = await execFileAsync("ssh", [
+                "-p",
+                String(vm.sshPort),
+                "-o",
+                "StrictHostKeyChecking=no",
+                "-o",
+                "UserKnownHostsFile=/dev/null",
+                "-i",
+                join(this.getInstanceDir(id), "ssh_key"),
+                "root@127.0.0.1",
+                "--",
+                escapedArgs,
+            ]);
+            return { stdout, stderr, exitCode: 0 };
+        }
+        catch (error) {
+            const execError = error;
+            return {
+                stdout: execError.stdout ?? "",
+                stderr: execError.stderr ?? String(error),
+                exitCode: execError.code ?? 1,
+            };
+        }
+    }
+    /**
+     * Spawn a long-lived process in the VM via SSH with piped stdout/stderr.
+     */
+    spawnStreaming(id, cmd, args, cwd) {
+        const vm = this.vms.get(id);
+        if (!vm)
+            throw new Error(`VM "${id}" not running`);
+        const remoteCmd = args.length > 0
+            ? `cd '${cwd}' && '${cmd}' ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(" ")}`
+            : `cd '${cwd}' && '${cmd}'`;
+        const sshProcess = spawn("ssh", [
+            "-p",
+            String(vm.sshPort),
+            "-o",
+            "StrictHostKeyChecking=no",
+            "-o",
+            "UserKnownHostsFile=/dev/null",
+            "-o",
+            "ServerAliveInterval=30",
+            "-i",
+            join(this.getInstanceDir(id), "ssh_key"),
+            "root@127.0.0.1",
+            "--",
+            remoteCmd,
+        ], {
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: false,
+        });
+        if (sshProcess.pid === undefined) {
+            throw new Error("Failed to spawn SSH process — no PID assigned");
+        }
+        return { pid: sshProcess.pid, process: sshProcess };
+    }
+    generateSetupScript(config) {
+        // Validate CIDR format and generate iptables rules
+        const cidrRegex = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\/\d{1,2}$/;
+        const rules = config.networkAllowlist
+            .filter((rule) => cidrRegex.test(rule.cidr))
+            .map((rule) => `iptables -A OUTPUT -p ${rule.protocol} -d ${rule.cidr} --dport ${rule.port} -j ACCEPT`)
+            .join("\n");
+        return `#!/bin/bash
+set -e
+
+apt-get update -qq
+apt-get install -y -qq iptables openssh-server git
+
+# Default policy: DROP all outbound
+iptables -P OUTPUT DROP
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+
+# Allow loopback
+iptables -A OUTPUT -o lo -j ACCEPT
+iptables -A INPUT -i lo -j ACCEPT
+
+# Allow established/related connections
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Per-rule allowlist (CIDR + port + protocol)
+${rules}
+
+echo "[qemu] Setup complete"
+`;
+    }
+    getInstanceDir(id) {
+        return join(homedir(), ".forgeai", "vm", "instances", id);
+    }
+    async stop(id) {
+        const vm = this.vms.get(id);
+        if (!vm) {
+            console.warn(chalk.yellow(`[qemu] VM "${id}" not found in running VMs`));
+            return;
+        }
+        console.log(chalk.cyan(`[qemu] Stopping VM "${id}" (PID ${vm.pid})`));
+        try {
+            process.kill(vm.pid, "SIGTERM");
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+        catch {
+            // Process may already be dead
+        }
+        this.vms.delete(id);
+        console.log(chalk.green(`[qemu] VM "${id}" stopped`));
+    }
+    async destroy(id) {
+        const vm = this.vms.get(id);
+        if (vm) {
+            try {
+                process.kill(vm.pid, "SIGKILL");
+            }
+            catch {
+                // Process may already be dead
+            }
+            this.vms.delete(id);
+        }
+        const instanceDir = join(homedir(), ".forgeai", "vm", "instances", id);
+        if (existsSync(instanceDir)) {
+            rmSync(instanceDir, { recursive: true, force: true });
+        }
+        console.log(chalk.green(`[qemu] VM "${id}" destroyed`));
+    }
+    async getInfo(id) {
+        const vm = this.vms.get(id);
+        if (!vm)
+            return null;
+        try {
+            process.kill(vm.pid, 0);
+            return {
+                id,
+                status: "RUNNING",
+                pid: vm.pid,
+                vsockCid: vm.cid,
+            };
+        }
+        catch {
+            this.vms.delete(id);
+            return {
+                id,
+                status: "STOPPED",
+                vsockCid: vm.cid,
+            };
+        }
+    }
+    getVsockPath(id) {
+        const vm = this.vms.get(id);
+        if (!vm) {
+            throw new Error(`VM "${id}" not found in running VMs`);
+        }
+        // QEMU uses TCP for vsock bridging
+        return `tcp:127.0.0.1:${6789 + vm.cid}`;
+    }
+}
+//# sourceMappingURL=qemu.js.map

package/dist/vm/providers/vfkit.d.ts

@@ -0,0 +1,40 @@
+import { type ChildProcess } from "node:child_process";
+import type { VmConfig, VmInfo, VmProvider, ExecResult } from "../types.js";
+/**
+ * vfkit provider for macOS.
+ * Uses Apple's Virtualization Framework via the vfkit binary (auto-downloaded).
+ * No brew install needed — single binary CLI.
+ */
+export declare class VfkitProvider implements VmProvider {
+    readonly name = "vfkit";
+    private vms;
+    isAvailable(): Promise<boolean>;
+    start(id: string, config: VmConfig): Promise<VmInfo>;
+    /**
+     * Discover the guest IP from the ARP table (NAT networking gives 192.168.64.x).
+     */
+    private waitForBoot;
+    /**
+     * Get all candidate guest IPs from the ARP table (192.168.64.x range).
+     */
+    private discoverCandidateIps;
+    exec(id: string, cmd: string, args?: string[]): Promise<ExecResult>;
+    /**
+     * Spawn a long-lived process in the VM via SSH with piped stdout/stderr.
+     * Returns the SSH ChildProcess which satisfies AgentProcess.
+     */
+    spawnStreaming(id: string, cmd: string, args: string[], cwd: string, options?: {
+        reverseTunnels?: Array<{
+            remotePort: number;
+            localPort: number;
+        }>;
+    }): {
+        pid: number;
+        process: ChildProcess;
+    };
+    stop(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+    getInfo(id: string): Promise<VmInfo | null>;
+    getVsockPath(id: string): string;
+}
+//# sourceMappingURL=vfkit.d.ts.map