@ai-hero/sandcastle 0.3.0 → 0.4.1

package/dist/sandboxes/podman.js

@@ -0,0 +1,195 @@
+/**
+ * Podman sandbox provider — creates Podman containers with bind-mounts.
+ *
+ * Usage:
+ *   import { podman } from "sandcastle/sandboxes/podman";
+ *   await run({ agent: claudeCode("claude-opus-4-6"), sandbox: podman() });
+ */
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { createBindMountSandboxProvider, } from "../SandboxProvider.js";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+/**
+ * Create a Podman sandbox provider.
+ *
+ * The returned provider creates Podman containers with bind-mounts
+ * for the worktree and git directories. Calls the `podman` binary
+ * on PATH directly — no Podman Machine detection or special
+ * macOS/Windows handling.
+ */
+export const podman = (options) => {
+    const configuredImageName = options?.imageName;
+    const selinuxLabel = options?.selinuxLabel ?? "z";
+    const userMounts = options?.mounts ? resolveUserMounts(options.mounts) : [];
+    return createBindMountSandboxProvider({
+        name: "podman",
+        env: options?.env,
+        create: async (createOptions) => {
+            const containerName = `sandcastle-${randomUUID()}`;
+            const workspacePath = createOptions.mounts.find((m) => m.hostPath === createOptions.worktreePath)?.sandboxPath ?? "/home/agent/workspace";
+            // Build volume mount strings with optional SELinux label (internal + user mounts)
+            const labelSuffix = selinuxLabel ? `:${selinuxLabel}` : "";
+            const allMounts = [...createOptions.mounts, ...userMounts];
+            const volumeMounts = allMounts.map((m) => {
+                const base = `${m.hostPath}:${m.sandboxPath}`;
+                if (m.readonly)
+                    return `${base}:ro${labelSuffix}`;
+                return `${base}${labelSuffix}`;
+            });
+            // Resolve image name
+            const imageName = configuredImageName ?? defaultImageName(createOptions.hostRepoPath);
+            const hostUid = process.getuid?.() ?? 1000;
+            const hostGid = process.getgid?.() ?? 1000;
+            const env = { ...createOptions.env, HOME: "/home/agent" };
+            const envArgs = Object.entries(env).flatMap(([key, value]) => [
+                "-e",
+                `${key}=${value}`,
+            ]);
+            const volumeArgs = volumeMounts.flatMap((v) => ["-v", v]);
+            // Start container via podman run
+            await new Promise((resolve, reject) => {
+                execFile("podman", [
+                    "run",
+                    "-d",
+                    "--name",
+                    containerName,
+                    "--user",
+                    `${hostUid}:${hostGid}`,
+                    "-w",
+                    workspacePath,
+                    ...envArgs,
+                    ...volumeArgs,
+                    imageName,
+                    "sleep",
+                    "infinity",
+                ], (error) => {
+                    if (error) {
+                        reject(new Error(`podman run failed: ${error.message}`));
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+            // Set up signal handlers for cleanup
+            const onExit = () => {
+                try {
+                    execFileSync("podman", ["rm", "-f", containerName], {
+                        stdio: "ignore",
+                    });
+                }
+                catch {
+                    /* best-effort */
+                }
+            };
+            const onSignal = () => {
+                onExit();
+                process.exit(1);
+            };
+            process.on("exit", onExit);
+            process.on("SIGINT", onSignal);
+            process.on("SIGTERM", onSignal);
+            const handle = {
+                workspacePath,
+                exec: (command, opts) => {
+                    const args = ["exec"];
+                    if (opts?.cwd)
+                        args.push("-w", opts.cwd);
+                    args.push(containerName, "sh", "-c", command);
+                    if (opts?.onLine) {
+                        const onLine = opts.onLine;
+                        return new Promise((resolve, reject) => {
+                            const proc = spawn("podman", args, {
+                                stdio: ["ignore", "pipe", "pipe"],
+                            });
+                            const stdoutChunks = [];
+                            const stderrChunks = [];
+                            const rl = createInterface({ input: proc.stdout });
+                            rl.on("line", (line) => {
+                                stdoutChunks.push(line);
+                                onLine(line);
+                            });
+                            proc.stderr.on("data", (chunk) => {
+                                stderrChunks.push(chunk.toString());
+                            });
+                            proc.on("error", (error) => {
+                                reject(new Error(`podman exec failed: ${error.message}`));
+                            });
+                            proc.on("close", (code) => {
+                                resolve({
+                                    stdout: stdoutChunks.join("\n"),
+                                    stderr: stderrChunks.join(""),
+                                    exitCode: code ?? 0,
+                                });
+                            });
+                        });
+                    }
+                    return new Promise((resolve, reject) => {
+                        execFile("podman", args, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+                            if (error && error.code === undefined) {
+                                reject(new Error(`podman exec failed: ${error.message}`));
+                            }
+                            else {
+                                resolve({
+                                    stdout: stdout.toString(),
+                                    stderr: stderr.toString(),
+                                    exitCode: typeof error?.code === "number" ? error.code : 0,
+                                });
+                            }
+                        });
+                    });
+                },
+                close: async () => {
+                    process.removeListener("exit", onExit);
+                    process.removeListener("SIGINT", onSignal);
+                    process.removeListener("SIGTERM", onSignal);
+                    await new Promise((resolve, reject) => {
+                        execFile("podman", ["rm", "-f", containerName], (error) => {
+                            if (error) {
+                                reject(new Error(`podman rm failed: ${error.message}`));
+                            }
+                            else {
+                                resolve();
+                            }
+                        });
+                    });
+                },
+            };
+            return handle;
+        },
+    });
+};
+/**
+ * Derive the default Podman image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for image tag rules.
+ */
+export const defaultImageName = (repoDir) => {
+    const dirName = repoDir.replace(/\/+$/, "").split("/").pop() || "local";
+    const sanitized = dirName.toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    return `sandcastle:${sanitized}`;
+};
+const expandTilde = (p) => {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return homedir() + p.slice(1);
+    return p;
+};
+const resolveUserMounts = (mounts) => mounts.map((m) => {
+    const resolvedHostPath = expandTilde(m.hostPath);
+    if (!existsSync(resolvedHostPath)) {
+        throw new Error(`Mount hostPath does not exist: ${m.hostPath}` +
+            (m.hostPath !== resolvedHostPath
+                ? ` (resolved to ${resolvedHostPath})`
+                : ""));
+    }
+    return {
+        hostPath: resolvedHostPath,
+        sandboxPath: m.sandboxPath,
+        ...(m.readonly ? { readonly: true } : {}),
+    };
+});
+//# sourceMappingURL=podman.js.map

package/dist/sandboxes/podman.js.map

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

package/dist/sandboxes/test-isolated.d.ts

@@ -10,7 +10,7 @@ import { type IsolatedSandboxProvider } from "../SandboxProvider.js";
  * Create a filesystem-based test isolated sandbox provider.
  *
  * The "sandbox" is a temp directory. `exec` runs shell commands in it,
- * `copyIn`/`copyOut` copy files between host and the temp dir,
+ * `copyIn`/`copyFileOut` copy files between host and the temp dir,
  * and `close` removes the temp dir.
  */
 export declare const testIsolated: () => IsolatedSandboxProvider;

package/dist/sandboxes/test-isolated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-isolated.d.ts","sourceRoot":"","sources":["../../src/sandboxes/test-isolated.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,+BA+FrB,CAAC"}
+{"version":3,"file":"test-isolated.d.ts","sourceRoot":"","sources":["../../src/sandboxes/test-isolated.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,+BAmGrB,CAAC"}

package/dist/sandboxes/test-isolated.js

@@ -6,7 +6,7 @@
  * requiring a real remote environment.
  */
 import { execFile, spawn } from "node:child_process";
-import { copyFile, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { copyFile, cp, mkdir, mkdtemp, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
@@ -15,7 +15,7 @@ import { createIsolatedSandboxProvider, } from "../SandboxProvider.js";
  * Create a filesystem-based test isolated sandbox provider.
  *
  * The "sandbox" is a temp directory. `exec` runs shell commands in it,
- * `copyIn`/`copyOut` copy files between host and the temp dir,
+ * `copyIn`/`copyFileOut` copy files between host and the temp dir,
  * and `close` removes the temp dir.
  */
 export const testIsolated = () => createIsolatedSandboxProvider({
@@ -26,54 +26,65 @@ export const testIsolated = () => createIsolatedSandboxProvider({
         await mkdir(workspacePath, { recursive: true });
         return {
             workspacePath,
-            exec: (command, options) => new Promise((resolve, reject) => {
-                execFile("sh", ["-c", command], {
-                    cwd: options?.cwd ?? workspacePath,
-                    maxBuffer: 10 * 1024 * 1024,
-                }, (error, stdout, stderr) => {
-                    if (error && error.code === undefined) {
-                        reject(new Error(`exec failed: ${error.message}`));
-                    }
-                    else {
-                        resolve({
-                            stdout: stdout.toString(),
-                            stderr: stderr.toString(),
-                            exitCode: typeof error?.code === "number" ? error.code : 0,
+            exec: (command, options) => {
+                if (options?.onLine) {
+                    const onLine = options.onLine;
+                    return new Promise((resolve, reject) => {
+                        const proc = spawn("sh", ["-c", command], {
+                            cwd: options?.cwd ?? workspacePath,
+                            stdio: ["ignore", "pipe", "pipe"],
+                        });
+                        const stdoutChunks = [];
+                        const stderrChunks = [];
+                        const rl = createInterface({ input: proc.stdout });
+                        rl.on("line", (line) => {
+                            stdoutChunks.push(line);
+                            onLine(line);
+                        });
+                        proc.stderr.on("data", (chunk) => {
+                            stderrChunks.push(chunk.toString());
+                        });
+                        proc.on("error", (error) => {
+                            reject(new Error(`exec failed: ${error.message}`));
+                        });
+                        proc.on("close", (code) => {
+                            resolve({
+                                stdout: stdoutChunks.join("\n"),
+                                stderr: stderrChunks.join(""),
+                                exitCode: code ?? 0,
+                            });
                         });
-                    }
-                });
-            }),
-            execStreaming: (command, onLine, options) => new Promise((resolve, reject) => {
-                const proc = spawn("sh", ["-c", command], {
-                    cwd: options?.cwd ?? workspacePath,
-                    stdio: ["ignore", "pipe", "pipe"],
-                });
-                const stdoutChunks = [];
-                const stderrChunks = [];
-                const rl = createInterface({ input: proc.stdout });
-                rl.on("line", (line) => {
-                    stdoutChunks.push(line);
-                    onLine(line);
-                });
-                proc.stderr.on("data", (chunk) => {
-                    stderrChunks.push(chunk.toString());
-                });
-                proc.on("error", (error) => {
-                    reject(new Error(`exec streaming failed: ${error.message}`));
-                });
-                proc.on("close", (code) => {
-                    resolve({
-                        stdout: stdoutChunks.join("\n"),
-                        stderr: stderrChunks.join(""),
-                        exitCode: code ?? 0,
+                    });
+                }
+                return new Promise((resolve, reject) => {
+                    execFile("sh", ["-c", command], {
+                        cwd: options?.cwd ?? workspacePath,
+                        maxBuffer: 10 * 1024 * 1024,
+                    }, (error, stdout, stderr) => {
+                        if (error && error.code === undefined) {
+                            reject(new Error(`exec failed: ${error.message}`));
+                        }
+                        else {
+                            resolve({
+                                stdout: stdout.toString(),
+                                stderr: stderr.toString(),
+                                exitCode: typeof error?.code === "number" ? error.code : 0,
+                            });
+                        }
                     });
                 });
-            }),
+            },
             copyIn: async (hostPath, sandboxPath) => {
-                await mkdir(dirname(sandboxPath), { recursive: true });
-                await copyFile(hostPath, sandboxPath);
+                const info = await stat(hostPath);
+                if (info.isDirectory()) {
+                    await cp(hostPath, sandboxPath, { recursive: true });
+                }
+                else {
+                    await mkdir(dirname(sandboxPath), { recursive: true });
+                    await copyFile(hostPath, sandboxPath);
+                }
             },
-            copyOut: async (sandboxPath, hostPath) => {
+            copyFileOut: async (sandboxPath, hostPath) => {
                 await mkdir(dirname(hostPath), { recursive: true });
                 await copyFile(sandboxPath, hostPath);
             },

package/dist/sandboxes/test-isolated.js.map

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

package/dist/sandboxes/vercel.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Vercel isolated sandbox provider — wraps `@vercel/sandbox` into a SandboxProvider.
+ *
+ * Usage:
+ *   import { vercel } from "sandcastle/sandboxes/vercel";
+ *   await run({ agent: claudeCode("claude-opus-4-6"), sandbox: vercel() });
+ */
+import { type IsolatedSandboxProvider } from "../SandboxProvider.js";
+/**
+ * Options for creating a Vercel sandbox provider.
+ *
+ * All `@vercel/sandbox` `Sandbox.create()` options are accepted as pass-through,
+ * plus Sandcastle-specific options for auth and branch strategy.
+ */
+export interface VercelOptions {
+    /**
+     * Vercel access token.
+     *
+     * Falls back to the SDK's default auth behavior, which reads
+     * `VERCEL_OIDC_TOKEN` (recommended for Vercel-hosted environments) or
+     * `VERCEL_TOKEN` from the environment.
+     */
+    readonly token?: string;
+    /**
+     * The source of the sandbox (git repo, tarball, or snapshot).
+     * Omit to start an empty sandbox.
+     */
+    readonly source?: {
+        type: "git";
+        url: string;
+        depth?: number;
+        revision?: string;
+        username?: string;
+        password?: string;
+    } | {
+        type: "tarball";
+        url: string;
+    } | {
+        type: "snapshot";
+        snapshotId: string;
+    };
+    /** Array of port numbers to expose from the sandbox (up to 4). */
+    readonly ports?: number[];
+    /** Timeout in milliseconds before the sandbox auto-terminates. */
+    readonly timeout?: number;
+    /**
+     * Resources to allocate to the sandbox.
+     * Each vCPU gets 2048 MB of memory.
+     */
+    readonly resources?: {
+        vcpus: number;
+    };
+    /**
+     * The runtime of the sandbox (e.g. `"node24"`, `"node22"`, `"python3.13"`).
+     * Defaults to `"node24"`.
+     */
+    readonly runtime?: string;
+    /**
+     * Network policy for the sandbox.
+     * Defaults to full internet access if not specified.
+     */
+    readonly networkPolicy?: Record<string, unknown>;
+    /**
+     * Vercel project ID to associate sandbox operations with.
+     */
+    readonly projectId?: string;
+    /**
+     * Vercel team ID to associate sandbox operations with.
+     */
+    readonly teamId?: string;
+    /**
+     * Timeout in milliseconds (alias for `timeout`, kept for discoverability).
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Sandbox template shorthand (e.g. `"node-22"`).
+     * Maps to the `runtime` option.
+     */
+    readonly template?: string;
+    /** Environment variables injected by this provider. Merged at launch time with env resolver and agent provider env. */
+    readonly env?: Record<string, string>;
+}
+/**
+ * Create a Vercel isolated sandbox provider.
+ *
+ * The returned provider creates Vercel Firecracker microVM sandboxes via
+ * the `@vercel/sandbox` SDK. Each sandbox is ephemeral — one sandbox per run.
+ *
+ * Requires `@vercel/sandbox` to be installed as a peer dependency.
+ */
+export declare const vercel: (options?: VercelOptions | undefined) => IsolatedSandboxProvider;
+//# sourceMappingURL=vercel.d.ts.map

package/dist/sandboxes/vercel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../../src/sandboxes/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAK/B;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAIxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EACZ;QACE,IAAI,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACD;QACE,IAAI,EAAE,SAAS,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;KACb,GACD;QACE,IAAI,EAAE,UAAU,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IAEN,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IAEF;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjD;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,uHAAuH;IACvH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,kEAqKf,CAAC"}

package/dist/sandboxes/vercel.js

@@ -0,0 +1,165 @@
+/**
+ * Vercel isolated sandbox provider — wraps `@vercel/sandbox` into a SandboxProvider.
+ *
+ * Usage:
+ *   import { vercel } from "sandcastle/sandboxes/vercel";
+ *   await run({ agent: claudeCode("claude-opus-4-6"), sandbox: vercel() });
+ */
+import { execSync } from "node:child_process";
+import { readFile, unlink, writeFile, mkdir, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { Writable } from "node:stream";
+import { createIsolatedSandboxProvider, } from "../SandboxProvider.js";
+/** Workspace path inside the Vercel sandbox. */
+const VERCEL_WORKSPACE_PATH = "/vercel/sandbox/workspace";
+/**
+ * Create a Vercel isolated sandbox provider.
+ *
+ * The returned provider creates Vercel Firecracker microVM sandboxes via
+ * the `@vercel/sandbox` SDK. Each sandbox is ephemeral — one sandbox per run.
+ *
+ * Requires `@vercel/sandbox` to be installed as a peer dependency.
+ */
+export const vercel = (options) => createIsolatedSandboxProvider({
+    name: "vercel",
+    env: options?.env,
+    create: async (createOptions) => {
+        // Dynamic import so the peer dependency is only loaded at runtime
+        const { Sandbox } = await import("@vercel/sandbox");
+        const createParams = {};
+        // Pass through SDK options
+        if (options?.source)
+            createParams.source = options.source;
+        if (options?.ports)
+            createParams.ports = options.ports;
+        if (options?.resources)
+            createParams.resources = options.resources;
+        if (options?.networkPolicy)
+            createParams.networkPolicy = options.networkPolicy;
+        // runtime takes precedence over the template convenience alias
+        const resolvedRuntime = options?.runtime ?? options?.template;
+        if (resolvedRuntime)
+            createParams.runtime = resolvedRuntime;
+        // Timeout: prefer explicit timeout, fall back to timeoutMs alias
+        const timeoutValue = options?.timeout ?? options?.timeoutMs;
+        if (timeoutValue !== undefined)
+            createParams.timeout = timeoutValue;
+        // Merge provider env with Sandcastle env
+        createParams.env = createOptions.env;
+        // Auth: pass token and team/project IDs if provided
+        if (options?.token)
+            createParams.token = options.token;
+        if (options?.projectId)
+            createParams.projectId = options.projectId;
+        if (options?.teamId)
+            createParams.teamId = options.teamId;
+        const sandbox = await Sandbox.create(createParams);
+        // Ensure workspace directory exists
+        await sandbox.mkDir(VERCEL_WORKSPACE_PATH);
+        const handle = {
+            workspacePath: VERCEL_WORKSPACE_PATH,
+            exec: async (command, opts) => {
+                if (opts?.onLine) {
+                    const onLine = opts.onLine;
+                    const stdoutLines = [];
+                    const stderrChunks = [];
+                    let partial = "";
+                    const stdoutWritable = new Writable({
+                        write(chunk, _encoding, callback) {
+                            const text = partial + chunk.toString();
+                            const lines = text.split("\n");
+                            partial = lines.pop() ?? "";
+                            for (const line of lines) {
+                                stdoutLines.push(line);
+                                onLine(line);
+                            }
+                            callback();
+                        },
+                        final(callback) {
+                            if (partial) {
+                                stdoutLines.push(partial);
+                                onLine(partial);
+                                partial = "";
+                            }
+                            callback();
+                        },
+                    });
+                    const stderrWritable = new Writable({
+                        write(chunk, _encoding, callback) {
+                            stderrChunks.push(chunk.toString());
+                            callback();
+                        },
+                    });
+                    const result = await sandbox.runCommand({
+                        cmd: "sh",
+                        args: ["-c", command],
+                        cwd: opts?.cwd ?? VERCEL_WORKSPACE_PATH,
+                        stdout: stdoutWritable,
+                        stderr: stderrWritable,
+                    });
+                    return {
+                        stdout: stdoutLines.join("\n"),
+                        stderr: stderrChunks.join(""),
+                        exitCode: result.exitCode,
+                    };
+                }
+                const result = await sandbox.runCommand({
+                    cmd: "sh",
+                    args: ["-c", command],
+                    cwd: opts?.cwd ?? VERCEL_WORKSPACE_PATH,
+                });
+                const stdout = await result.stdout();
+                const stderr = await result.stderr();
+                return {
+                    stdout,
+                    stderr,
+                    exitCode: result.exitCode,
+                };
+            },
+            copyIn: async (hostPath, sandboxPath) => {
+                const info = await stat(hostPath);
+                if (info.isDirectory()) {
+                    const tarPath = join(tmpdir(), `sandcastle-copyin-${Date.now()}.tar.gz`);
+                    execSync(`tar -czf "${tarPath}" -C "${hostPath}" .`);
+                    try {
+                        const tarContent = await readFile(tarPath);
+                        const sandboxTarPath = `/tmp/sandcastle-copyin-${Date.now()}.tar.gz`;
+                        await sandbox.writeFiles([
+                            { path: sandboxTarPath, content: tarContent },
+                        ]);
+                        await sandbox.runCommand({
+                            cmd: "sh",
+                            args: [
+                                "-c",
+                                `mkdir -p "${sandboxPath}" && tar -xzf "${sandboxTarPath}" -C "${sandboxPath}" && rm -f "${sandboxTarPath}"`,
+                            ],
+                        });
+                    }
+                    finally {
+                        await unlink(tarPath).catch(() => { });
+                    }
+                }
+                else {
+                    const content = await readFile(hostPath);
+                    await sandbox.writeFiles([{ path: sandboxPath, content }]);
+                }
+            },
+            copyFileOut: async (sandboxPath, hostPath) => {
+                const buffer = await sandbox.readFileToBuffer({
+                    path: sandboxPath,
+                });
+                if (!buffer) {
+                    throw new Error(`File not found in Vercel sandbox: ${sandboxPath}`);
+                }
+                await mkdir(dirname(hostPath), { recursive: true });
+                await writeFile(hostPath, buffer);
+            },
+            close: async () => {
+                await sandbox.stop();
+            },
+        };
+        return handle;
+    },
+});
+//# sourceMappingURL=vercel.js.map

package/dist/sandboxes/vercel.js.map

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