sandhop 0.1.0

package/dist/host/node.js

@@ -0,0 +1,198 @@
+import { execFileSync, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, openAsBlob, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, } from "node:fs";
+import { cp, mkdir, open, rm, writeFile } from "node:fs/promises";
+import * as tar from "tar";
+import { dirname } from "../core/paths.js";
+const listFiles = (dir) => {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const paths = [];
+    for (const entry of entries) {
+        const path = `${dir}/${entry.name}`;
+        if (entry.isDirectory())
+            paths.push(...listFiles(path));
+        else
+            paths.push(path);
+    }
+    return paths;
+};
+const sizeDir = (dir) => {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let size = 0;
+    for (const entry of entries) {
+        const path = `${dir}/${entry.name}`;
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink()) {
+            size += stat.size;
+            continue;
+        }
+        if (stat.isDirectory()) {
+            size += sizeDir(path);
+            continue;
+        }
+        size += stat.size;
+    }
+    return size;
+};
+const hasExcludedSegment = (path, excludes) => {
+    const segments = path.split("/");
+    return excludes.some((exclude) => segments.includes(exclude));
+};
+export class NodeHost {
+    env;
+    home;
+    constructor(env, home) {
+        this.env = env;
+        this.home = home;
+    }
+    readFile(path) {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    readBytes(path) {
+        return new Uint8Array(readFileSync(path));
+    }
+    async openBlob(path) {
+        return openAsBlob(path);
+    }
+    exists(path) {
+        return existsSync(path);
+    }
+    isDirectory(path) {
+        return statSync(path).isDirectory();
+    }
+    isSymlink(path) {
+        return lstatSync(path).isSymbolicLink();
+    }
+    readlink(path) {
+        return readlinkSync(path);
+    }
+    walk(dir) {
+        return listFiles(dir);
+    }
+    fileSize(path) {
+        return statSync(path).size;
+    }
+    dirSizeBytes(path) {
+        return sizeDir(path);
+    }
+    statMtimeMs(path) {
+        return statSync(path).mtimeMs;
+    }
+    keychain(service, account) {
+        try {
+            const args = account === null
+                ? ["find-generic-password", "-w", "-s", service]
+                : ["find-generic-password", "-w", "-s", service, "-a", account];
+            return execFileSync("security", args, { encoding: "utf8" }).trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    realpath(path) {
+        return realpathSync.native(path);
+    }
+    sha256Hex(input) {
+        return createHash("sha256").update(input).digest("hex");
+    }
+    exec(bin, args) {
+        return execFileSync(bin, args, { encoding: "utf8" });
+    }
+    async spawnPipe(cmd) {
+        await new Promise((resolve, reject) => {
+            const child = spawn("/bin/sh", ["-lc", cmd], {
+                env: { ...process.env, COPYFILE_DISABLE: "1" },
+                stdio: "inherit",
+            });
+            child.on("error", reject);
+            child.on("exit", (code, signal) => {
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+                reject(new Error(signal === null
+                    ? `Command failed with exit ${code}: ${cmd}`
+                    : `Command failed with signal ${signal}: ${cmd}`));
+            });
+        });
+    }
+    spawnDetached(bin, args, opts) {
+        spawn(bin, args, {
+            cwd: opts.cwd,
+            detached: true,
+            env: opts.env,
+            stdio: "ignore",
+        }).unref();
+    }
+    async splitFile(path, chunkBytes, outPrefix) {
+        const size = this.fileSize(path);
+        if (size === 0) {
+            const chunk = `${outPrefix}000000`;
+            await writeFile(chunk, new Uint8Array());
+            return [chunk];
+        }
+        const chunks = [];
+        const file = await open(path, "r");
+        try {
+            let offset = 0;
+            let index = 0;
+            while (offset < size) {
+                const length = Math.min(chunkBytes, size - offset);
+                const buffer = Buffer.allocUnsafe(length);
+                await file.read(buffer, 0, length, offset);
+                const chunk = `${outPrefix}${String(index).padStart(6, "0")}`;
+                await writeFile(chunk, buffer);
+                chunks.push(chunk);
+                offset += length;
+                index += 1;
+            }
+            return chunks;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async copyTree(cwd, entries, outPath, opts) {
+        await rm(outPath, { recursive: true, force: true });
+        await mkdir(outPath, { recursive: true });
+        for (const entry of entries) {
+            const source = `${cwd}/${entry}`;
+            const dest = `${outPath}/${entry}`;
+            await mkdir(dirname(dest), { recursive: true });
+            await cp(source, dest, {
+                recursive: true,
+                filter: opts === undefined
+                    ? undefined
+                    : (path) => !hasExcludedSegment(path, opts.excludes),
+            });
+        }
+    }
+    async tarGz(cwd, entries, outPath, opts) {
+        await tar.create({
+            gzip: true,
+            file: outPath,
+            cwd,
+            portable: true,
+            filter: opts === undefined
+                ? undefined
+                : (path) => !hasExcludedSegment(path, opts.excludes),
+        }, entries);
+    }
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+export * from "./agents/index.js";
+export * from "./core/encode.js";
+export * from "./core/errors.js";
+export * from "./core/manifest.js";
+export * from "./core/ports/agent.js";
+export * from "./core/ports/host.js";
+export * from "./core/ports/provider.js";
+export * from "./core/ports/transport.js";
+export * from "./core/services/auth.js";
+export * from "./core/services/bootstrap.js";
+export * from "./core/services/mcp-code.js";
+export * from "./core/services/profile.js";
+export * from "./core/services/reinstall.js";
+export * from "./core/services/secrets.js";
+export * from "./core/services/session.js";
+export * from "./core/services/teleport.js";
+export * from "./core/services/transfer.js";
+export * from "./core/services/version.js";
+export * from "./transports/cloudflared.js";
+export * from "./transports/public.js";

package/dist/providers/daytona/index.js

@@ -0,0 +1,97 @@
+import { shellQuote } from "../../core/shell.js";
+import { destroyOrFalse } from "../destroy.js";
+import { toBuffer } from "../encode.js";
+import { optionalCred, requireCred } from "../index.js";
+import { lazyImport, lazyOnce } from "../lazy-import.js";
+const COMMAND_TIMEOUT_SECONDS = 600;
+const PATH_UPLOAD_TIMEOUT_SECONDS = 3600;
+const DAYTONA_INSTALL_HINT = "The 'daytona' provider needs @daytonaio/sdk. Run: npm i @daytonaio/sdk";
+const DAYTONA_PACKAGE = "@daytonaio/sdk";
+const timeoutSeconds = (timeoutMs) => Math.ceil(timeoutMs / 1000);
+const autoStopMinutes = (timeoutMs) => Math.max(1, Math.ceil(timeoutMs / 60000));
+const buildCreateParams = (opts) => ({
+    autoStopInterval: autoStopMinutes(opts.timeoutMs),
+    envVars: opts.envs,
+    ephemeral: true,
+});
+class DaytonaSandboxAdapter {
+    id;
+    sandbox;
+    timeoutSeconds;
+    constructor(sandbox, timeoutSecondsValue) {
+        this.sandbox = sandbox;
+        this.timeoutSeconds = timeoutSecondsValue;
+        this.id = sandbox.id;
+    }
+    async uploadFile(path, data) {
+        await this.sandbox.fs.uploadFile(toBuffer(data), path, this.timeoutSeconds);
+    }
+    async uploadPath(remotePath, localPath) {
+        await this.sandbox.fs.uploadFile(localPath, remotePath, PATH_UPLOAD_TIMEOUT_SECONDS);
+    }
+    async exec(cmd) {
+        const result = await this.sandbox.process.executeCommand(`bash -lc ${shellQuote(cmd)}`, undefined, undefined, this.timeoutSeconds);
+        return { exitCode: result.exitCode, stdout: result.result, stderr: "" };
+    }
+    async spawn(cmd) {
+        await this.sandbox.process.executeCommand(`nohup bash -lc ${shellQuote(cmd)} >/dev/null 2>&1 &`, undefined, undefined, this.timeoutSeconds);
+    }
+    async exposePort(port) {
+        const preview = await this.sandbox.getPreviewLink(port);
+        return { url: preview.url };
+    }
+    async destroy() {
+        await this.sandbox.delete(this.timeoutSeconds);
+    }
+}
+export class DaytonaSandboxProvider {
+    name = "daytona";
+    host;
+    client;
+    constructor(host) {
+        this.host = host;
+        this.client = lazyOnce(() => this.createClient());
+    }
+    async create(opts) {
+        const timeout = timeoutSeconds(opts.timeoutMs);
+        const sandbox = (await (await this.client()).create(buildCreateParams(opts), { timeout }));
+        return new DaytonaSandboxAdapter(sandbox, timeout);
+    }
+    async connect(id) {
+        const sandbox = (await (await this.client()).get(id));
+        return new DaytonaSandboxAdapter(sandbox, COMMAND_TIMEOUT_SECONDS);
+    }
+    async list() {
+        const sandboxes = [];
+        for await (const sandbox of (await this.client()).list()) {
+            const instance = sandbox;
+            sandboxes.push({
+                id: instance.id,
+                startedAt: instance.createdAt === undefined
+                    ? new Date(0)
+                    : new Date(instance.createdAt),
+            });
+        }
+        return sandboxes;
+    }
+    async destroy(id) {
+        return destroyOrFalse((error) => error instanceof Error && error.name === "DaytonaNotFoundError", async () => {
+            const sandbox = (await (await this.client()).get(id));
+            await sandbox.delete(COMMAND_TIMEOUT_SECONDS);
+        });
+    }
+    async createClient() {
+        const { Daytona } = await lazyImport(DAYTONA_PACKAGE, DAYTONA_INSTALL_HINT);
+        const credentials = {
+            apiKey: requireCred(this.host, "daytona", "DAYTONA_API_KEY"),
+            apiUrl: optionalCred(this.host, "daytona", "DAYTONA_API_URL"),
+            target: optionalCred(this.host, "daytona", "DAYTONA_TARGET"),
+        };
+        const config = { apiKey: credentials.apiKey };
+        if (credentials.apiUrl !== undefined)
+            config.apiUrl = credentials.apiUrl;
+        if (credentials.target !== undefined)
+            config.target = credentials.target;
+        return new Daytona(config);
+    }
+}

package/dist/providers/destroy.js

@@ -0,0 +1,11 @@
+export const destroyOrFalse = async (isNotFound, run) => {
+    try {
+        await run();
+        return true;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return false;
+        throw error;
+    }
+};

package/dist/providers/e2b/index.js

@@ -0,0 +1,93 @@
+import { CommandExitError, Sandbox as E2bSandbox } from "e2b";
+import { toArrayBuffer } from "../encode.js";
+import { requireCred } from "../index.js";
+const UPLOAD_TIMEOUT_MS = 600000;
+const PATH_UPLOAD_TIMEOUT_MS = 3_600_000;
+class E2bSandboxAdapter {
+    id;
+    sandbox;
+    host;
+    constructor(sandbox, host) {
+        this.sandbox = sandbox;
+        this.host = host;
+        this.id = sandbox.sandboxId;
+    }
+    async uploadFile(path, data) {
+        await this.sandbox.files.write(path, toArrayBuffer(data), {
+            requestTimeoutMs: UPLOAD_TIMEOUT_MS,
+            useOctetStream: true,
+        });
+    }
+    async uploadPath(remotePath, localPath) {
+        await this.sandbox.files.write(remotePath, await this.host.openBlob(localPath), {
+            requestTimeoutMs: PATH_UPLOAD_TIMEOUT_MS,
+            useOctetStream: true,
+        });
+    }
+    async exec(cmd) {
+        try {
+            const result = await this.sandbox.commands.run(cmd, {
+                timeoutMs: UPLOAD_TIMEOUT_MS,
+                requestTimeoutMs: UPLOAD_TIMEOUT_MS,
+            });
+            return {
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            };
+        }
+        catch (error) {
+            if (error instanceof CommandExitError)
+                return {
+                    exitCode: error.exitCode,
+                    stdout: error.stdout,
+                    stderr: error.stderr,
+                };
+            throw error;
+        }
+    }
+    async spawn(cmd) {
+        await this.sandbox.commands.run(cmd, { background: true, timeoutMs: 0 });
+    }
+    async exposePort(port) {
+        return { url: `https://${this.sandbox.getHost(port)}` };
+    }
+    async destroy() {
+        await E2bSandbox.kill(this.id);
+    }
+}
+export class E2bSandboxProvider {
+    name = "e2b";
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    async create(opts) {
+        const credentials = this.credentials();
+        const sandbox = await E2bSandbox.create("base", {
+            ...credentials,
+            envs: opts.envs,
+            timeoutMs: opts.timeoutMs,
+        });
+        return new E2bSandboxAdapter(sandbox, this.host);
+    }
+    async connect(id) {
+        return new E2bSandboxAdapter(await E2bSandbox.connect(id, this.credentials()), this.host);
+    }
+    async list() {
+        const sandboxes = [];
+        const paginator = E2bSandbox.list(this.credentials());
+        while (paginator.hasNext) {
+            for (const sandbox of await paginator.nextItems()) {
+                sandboxes.push({ id: sandbox.sandboxId, startedAt: sandbox.startedAt });
+            }
+        }
+        return sandboxes;
+    }
+    async destroy(id) {
+        return E2bSandbox.kill(id, this.credentials());
+    }
+    credentials() {
+        return { apiKey: requireCred(this.host, "e2b", "E2B_API_KEY") };
+    }
+}

package/dist/providers/encode.js

@@ -0,0 +1,10 @@
+import { Buffer } from "node:buffer";
+const encoder = new TextEncoder();
+export const toBytes = (data) => typeof data === "string" ? encoder.encode(data) : new Uint8Array(data);
+export const toBuffer = (data) => Buffer.from(toBytes(data));
+export const toArrayBuffer = (data) => {
+    const bytes = toBytes(data);
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    return buffer;
+};

package/dist/providers/index.js

@@ -0,0 +1,119 @@
+import { CredentialError } from "../core/errors.js";
+import { DaytonaSandboxProvider } from "./daytona/index.js";
+import { E2bSandboxProvider } from "./e2b/index.js";
+import { ModalSandboxProvider } from "./modal/index.js";
+import { VercelSandboxProvider } from "./vercel/index.js";
+export const PROVIDER_IDS = ["e2b", "modal", "daytona", "vercel"];
+export const PROVIDER_INFO = {
+    e2b: {
+        id: "e2b",
+        label: "E2B",
+        docsUrl: "https://e2b.dev/dashboard?tab=keys",
+        credentials: [
+            {
+                env: "E2B_API_KEY",
+                label: "E2B API key",
+                secret: true,
+                required: true,
+            },
+        ],
+    },
+    modal: {
+        id: "modal",
+        label: "Modal",
+        docsUrl: "https://modal.com/settings/tokens",
+        credentials: [
+            {
+                env: "MODAL_TOKEN_ID",
+                label: "Modal token id",
+                secret: false,
+                required: true,
+            },
+            {
+                env: "MODAL_TOKEN_SECRET",
+                label: "Modal token secret",
+                secret: true,
+                required: true,
+            },
+        ],
+    },
+    daytona: {
+        id: "daytona",
+        label: "Daytona",
+        docsUrl: "https://app.daytona.io/dashboard/keys",
+        credentials: [
+            {
+                env: "DAYTONA_API_KEY",
+                label: "Daytona API key",
+                secret: true,
+                required: true,
+            },
+            {
+                env: "DAYTONA_API_URL",
+                label: "Daytona API URL (optional)",
+                secret: false,
+                required: false,
+            },
+            {
+                env: "DAYTONA_TARGET",
+                label: "Daytona target region (optional)",
+                secret: false,
+                required: false,
+            },
+        ],
+    },
+    vercel: {
+        id: "vercel",
+        label: "Vercel Sandbox",
+        docsUrl: "https://vercel.com/account/tokens",
+        credentials: [
+            {
+                env: "VERCEL_TOKEN",
+                label: "Vercel token",
+                secret: true,
+                required: true,
+            },
+            {
+                env: "VERCEL_TEAM_ID",
+                label: "Vercel team id (team_...)",
+                secret: false,
+                required: true,
+            },
+            {
+                env: "VERCEL_PROJECT_ID",
+                label: "Vercel project id (prj_...)",
+                secret: false,
+                required: true,
+            },
+        ],
+    },
+};
+export const buildProvider = (id, host) => {
+    if (id === "e2b")
+        return new E2bSandboxProvider(host);
+    if (id === "modal")
+        return new ModalSandboxProvider(host);
+    if (id === "daytona")
+        return new DaytonaSandboxProvider(host);
+    if (id === "vercel")
+        return new VercelSandboxProvider(host);
+    throw new Error(`Unknown provider ${id}`);
+};
+const readCredField = (id, env) => {
+    const field = PROVIDER_INFO[id].credentials.find((credential) => credential.env === env);
+    if (field === undefined)
+        throw new CredentialError(`${env} is not declared for ${id}`);
+    return field;
+};
+export const requireCred = (host, id, env) => {
+    const field = readCredField(id, env);
+    const value = host.env[field.env];
+    if (value === undefined || value === "")
+        throw new CredentialError(`${field.env} is required — set it or run \`sandhop setup\``);
+    return value;
+};
+export const optionalCred = (host, id, env) => {
+    const field = readCredField(id, env);
+    const value = host.env[field.env];
+    return value === "" ? undefined : value;
+};

package/dist/providers/lazy-import.js

@@ -0,0 +1,25 @@
+import { formatErrorText } from "../core/errors.js";
+const isModuleNotFound = (error, pkg) => {
+    const text = formatErrorText(error);
+    return (text.includes(`Cannot find package '${pkg}'`) ||
+        text.includes(`Cannot find package "${pkg}"`) ||
+        text.includes(`Cannot find module '${pkg}'`) ||
+        text.includes(`Cannot find module "${pkg}"`));
+};
+export const lazyImport = async (pkg, hint) => {
+    try {
+        return (await import(pkg));
+    }
+    catch (error) {
+        if (isModuleNotFound(error, pkg))
+            throw new Error(hint);
+        throw error;
+    }
+};
+export const lazyOnce = (factory) => {
+    let value;
+    return () => {
+        value ??= factory();
+        return value;
+    };
+};

package/dist/providers/modal/index.js

@@ -0,0 +1,110 @@
+import { destroyOrFalse } from "../destroy.js";
+import { toBytes } from "../encode.js";
+import { requireCred } from "../index.js";
+import { lazyImport, lazyOnce } from "../lazy-import.js";
+const COMMAND_TIMEOUT_MS = 600000;
+const TUNNEL_TIMEOUT_MS = 60000;
+const MODAL_INSTALL_HINT = "The 'modal' provider needs the 'modal' package. Run: npm i modal";
+const MODAL_PACKAGE = "modal";
+class ModalSandboxAdapter {
+    id;
+    sandbox;
+    host;
+    constructor(sandbox, host) {
+        this.sandbox = sandbox;
+        this.host = host;
+        this.id = sandbox.sandboxId;
+    }
+    async uploadFile(path, data) {
+        const file = await this.sandbox.open(path, "w");
+        try {
+            await file.write(toBytes(data));
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async uploadPath(remotePath, localPath) {
+        const file = await this.sandbox.open(remotePath, "w");
+        try {
+            for await (const chunk of (await this.host.openBlob(localPath)).stream())
+                await file.write(chunk);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async exec(cmd) {
+        const process = await this.sandbox.exec(["bash", "-lc", cmd], {
+            timeoutMs: COMMAND_TIMEOUT_MS,
+        });
+        const [stdout, stderr, exitCode] = await Promise.all([
+            process.stdout.readText(),
+            process.stderr.readText(),
+            process.wait(),
+        ]);
+        return { exitCode, stdout, stderr };
+    }
+    async spawn(cmd) {
+        await this.sandbox.exec(["bash", "-lc", cmd]);
+    }
+    async exposePort(port) {
+        const tunnels = await this.sandbox.tunnels(TUNNEL_TIMEOUT_MS);
+        const tunnel = tunnels[port];
+        if (tunnel === undefined)
+            throw new Error(`Modal tunnel ${port} not found`);
+        return { url: `https://${tunnel.host}` };
+    }
+    async destroy() {
+        await this.sandbox.terminate();
+    }
+}
+export class ModalSandboxProvider {
+    name = "modal";
+    host;
+    client;
+    constructor(host) {
+        this.host = host;
+        this.client = lazyOnce(() => this.createClient());
+    }
+    async create(opts) {
+        const client = await this.client();
+        const app = await client.apps.fromName("sandhop", {
+            createIfMissing: true,
+        });
+        const image = client.images.fromRegistry("node:22");
+        const sandbox = await client.sandboxes.create(app, image, {
+            command: ["sleep", "infinity"],
+            encryptedPorts: opts.ports ?? [7681],
+            env: opts.envs,
+            timeoutMs: opts.timeoutMs,
+        });
+        return new ModalSandboxAdapter(sandbox, this.host);
+    }
+    async connect(id) {
+        return new ModalSandboxAdapter(await (await this.client()).sandboxes.fromId(id), this.host);
+    }
+    async list() {
+        const sandboxes = [];
+        for await (const sandbox of (await this.client()).sandboxes.list())
+            sandboxes.push({ id: sandbox.sandboxId, startedAt: new Date(0) });
+        return sandboxes;
+    }
+    async destroy(id) {
+        return destroyOrFalse((error) => error instanceof Error && error.name === "NotFoundError", async () => {
+            const sandbox = await (await this.client()).sandboxes.fromId(id);
+            await sandbox.terminate();
+        });
+    }
+    async createClient() {
+        const { ModalClient } = await lazyImport(MODAL_PACKAGE, MODAL_INSTALL_HINT);
+        const credentials = {
+            tokenId: requireCred(this.host, "modal", "MODAL_TOKEN_ID"),
+            tokenSecret: requireCred(this.host, "modal", "MODAL_TOKEN_SECRET"),
+        };
+        return new ModalClient({
+            tokenId: credentials.tokenId,
+            tokenSecret: credentials.tokenSecret,
+        });
+    }
+}