sbox-sdk 0.0.2

package/dist/codesandbox/index.js

@@ -0,0 +1,227 @@
+/**
+ * `sbox-sdk/codesandbox` — adapter for the CodeSandbox SDK (`@codesandbox/sdk`).
+ * A "sandbox" is a CodeSandbox microVM. The SDK has two halves: a control object
+ * (`sdk.sandboxes.*` — create/resume/hibernate/shutdown/list) and a per-sandbox
+ * `client` you get from `sandbox.connect()` for commands/fs/ports. This adapter
+ * holds both.
+ *
+ * exec is the buffered `client.commands.run` (native cwd/env), which THROWS a
+ * `CommandError` on non-zero exit — the adapter catches it and emits a normal
+ * `exit` event so the core never sees a throw. Filesystem is native
+ * (`client.fs.*`). Ports are public hosts (`client.hosts.getUrl`). `pause()` =
+ * hibernate (memory snapshotted), `resume()` wakes it, `shutdown()` destroys.
+ * `setTimeout()` maps to the hibernation timeout. Requires the optional peer
+ * dependency `@codesandbox/sdk`.
+ */
+import { AsyncQueue, defineProvider, SandboxError } from "../adapter/index.js";
+export const CODESANDBOX_CAPS = {
+    background: "unsupported",
+    codeInterpreter: "unsupported",
+    egressControl: "unsupported",
+    exposePort: "native",
+    filesUpload: "native",
+    filesWatch: "unsupported",
+    fork: "unsupported",
+    gpu: "unsupported",
+    killProcess: "unsupported",
+    list: "native",
+    metrics: "unsupported",
+    pause: "native",
+    privatePreview: "native",
+    proxiedFetch: "unsupported",
+    pty: "unsupported",
+    region: "unsupported",
+    secretsVault: "unsupported",
+    setTimeout: "native",
+    snapshot: "unsupported",
+    ssh: "unsupported",
+    statefulKernel: "unsupported",
+    stdin: "unsupported",
+    stop: "unsupported",
+    streaming: "emulated",
+    volumes: "unsupported",
+};
+const CODESANDBOX_FLAGS = {
+    exitCodeNative: true, // exit code recovered from CommandError
+    perCommandEnvCwd: true, // commands.run accepts { cwd, env }
+    preservesDiskOnStop: false,
+    preservesMemoryOnPause: true, // hibernate snapshots memory
+    previewModel: "subdomain",
+};
+let cached = null;
+async function loadCsb() {
+    if (!cached) {
+        cached = (await import("@codesandbox/sdk"));
+    }
+    return cached;
+}
+function mapState(state) {
+    switch ((state ?? "").toLowerCase()) {
+        case "running":
+        case "connected": {
+            return "running";
+        }
+        case "hibernated": {
+            return "paused";
+        }
+        case "shutdown": {
+            return "stopped";
+        }
+        default: {
+            return "unknown";
+        }
+    }
+}
+function mapFileType(type) {
+    if (type === "directory" || type === "dir") {
+        return "dir";
+    }
+    if (type === "symlink") {
+        return "symlink";
+    }
+    return "file";
+}
+export const codesandbox = defineProvider((opts) => {
+    let sdkP = null;
+    const getSdk = () => {
+        if (!sdkP) {
+            sdkP = loadCsb().then((mod) => new mod.CodeSandbox(opts.apiKey));
+        }
+        return sdkP;
+    };
+    const makeHandle = (sb, client) => ({
+        id: sb.id,
+        raw: sb,
+        getInfo() {
+            return {
+                id: sb.id,
+                state: "running",
+                provider: "codesandbox",
+                metadata: {},
+                raw: sb,
+            };
+        },
+        async destroy() {
+            const sdk = await getSdk();
+            await sdk.sandboxes.shutdown(sb.id);
+        },
+        async pause() {
+            const sdk = await getSdk();
+            await sdk.sandboxes.hibernate(sb.id);
+        },
+        async resume() {
+            const sdk = await getSdk();
+            await sdk.sandboxes.resume(sb.id);
+        },
+        async setTimeout(ttlMs) {
+            await sb.updateHibernationTimeout(Math.max(1, Math.ceil(ttlMs / 1000)));
+        },
+        exec(cmd, options) {
+            const queue = new AsyncQueue();
+            void client.commands
+                .run(cmd, { cwd: options.cwd, env: options.env })
+                .then((stdout) => {
+                if (stdout) {
+                    queue.push({ type: "stdout", data: stdout });
+                }
+                queue.push({ type: "exit", exitCode: 0 });
+                queue.close();
+            })
+                .catch((error) => {
+                // CommandError carries the non-zero exit code + buffered output; turn
+                // it into a normal exit event rather than a thrown error.
+                const ce = error;
+                if (typeof ce?.exitCode === "number") {
+                    if (ce.output) {
+                        queue.push({ type: "stderr", data: ce.output });
+                    }
+                    queue.push({ type: "exit", exitCode: ce.exitCode });
+                    queue.close();
+                    return;
+                }
+                queue.fail(error instanceof SandboxError
+                    ? error
+                    : SandboxError.wrap(error, "codesandbox"));
+            });
+            return {
+                pid: Promise.resolve(""),
+                async kill() {
+                    /* commands.run is buffered; use runBackground for control (not wired) */
+                },
+                [Symbol.asyncIterator]: () => queue.iterator(),
+            };
+        },
+        async readFile(path) {
+            return new Uint8Array(await client.fs.readFile(path));
+        },
+        async writeFile(path, data) {
+            await client.fs.writeFile(path, data, { create: true, overwrite: true });
+        },
+        async listDir(path) {
+            const entries = await client.fs.readdir(path);
+            const base = path.replace(/\/$/, "");
+            return entries.map((e) => ({
+                name: e.name,
+                path: `${base}/${e.name}`,
+                type: mapFileType(e.type),
+            }));
+        },
+        async remove(path, recursive) {
+            await client.fs.remove(path, recursive);
+        },
+        async rename(from, to) {
+            await client.fs.rename(from, to);
+        },
+        async stat(path) {
+            const s = await client.fs.stat(path);
+            return {
+                path,
+                type: mapFileType(s.type),
+                size: s.size ?? 0,
+                mtime: s.mtime ? new Date(s.mtime) : undefined,
+            };
+        },
+        exposePort(port) {
+            return { url: client.hosts.getUrl(port), port };
+        },
+    });
+    const provider = {
+        name: "codesandbox",
+        capabilities: CODESANDBOX_CAPS,
+        flags: CODESANDBOX_FLAGS,
+        async create(spec) {
+            const sdk = await getSdk();
+            const id = spec.template ?? opts.templateId;
+            const sb = await sdk.sandboxes.create({
+                id,
+                title: spec.name,
+                tags: spec.metadata ? Object.values(spec.metadata) : undefined,
+                hibernationTimeoutSeconds: spec.ttlMs
+                    ? Math.ceil(spec.ttlMs / 1000)
+                    : undefined,
+            });
+            const client = await sb.connect();
+            return makeHandle(sb, client);
+        },
+        async connect(id) {
+            const sdk = await getSdk();
+            const sb = await sdk.sandboxes.resume(id);
+            const client = await sb.connect();
+            return makeHandle(sb, client);
+        },
+        async *list() {
+            const sdk = await getSdk();
+            const res = await sdk.sandboxes.list();
+            for (const s of res.sandboxes ?? []) {
+                yield {
+                    id: s.id,
+                    state: mapState(s.status),
+                    provider: "codesandbox",
+                    metadata: {},
+                    raw: s,
+                };
+            }
+        },
+    };
+    return provider;
+});

package/dist/conformance/index.d.ts

@@ -0,0 +1,20 @@
+import type { CapabilityMap } from "../internal/capabilities.js";
+import type { SandboxProvider } from "../internal/types.js";
+export interface ConformanceCheck {
+    name: string;
+    ok: boolean;
+    error?: string;
+}
+export interface ConformanceReport {
+    provider: string;
+    checks: ConformanceCheck[];
+    passed: boolean;
+}
+export interface ConformanceOptions {
+    /** Assert the provider declares these exact capability levels. */
+    expectedCaps?: Partial<CapabilityMap>;
+    /** Skip checks by name (for genuinely-not-applicable providers). */
+    skip?: string[];
+}
+export declare function runConformance(provider: SandboxProvider, options?: ConformanceOptions): Promise<ConformanceReport>;
+//# sourceMappingURL=index.d.ts.map

package/dist/conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conformance/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAQjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,YAAY,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACtC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAQD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CA0N5B"}

package/dist/conformance/index.js

@@ -0,0 +1,189 @@
+/**
+ * `sbox-sdk/conformance` — one identical battery every adapter must pass, so all
+ * providers behave the same. Runner-agnostic: returns a report you assert on
+ * inside your own test framework (vitest, node:test, ...).
+ */
+import { createSandboxClient } from "../internal/client.js";
+import { NotSupportedError } from "../internal/errors.js";
+function assert(cond, msg) {
+    if (!cond) {
+        throw new Error(msg);
+    }
+}
+export async function runConformance(provider, options = {}) {
+    const client = createSandboxClient({ provider });
+    const checks = [];
+    const skip = new Set(options.skip ?? []);
+    const caps = provider.capabilities;
+    const check = async (name, fn) => {
+        if (skip.has(name)) {
+            return;
+        }
+        try {
+            await fn();
+            checks.push({ name, ok: true });
+        }
+        catch (error) {
+            checks.push({
+                error: error instanceof Error ? error.message : String(error),
+                name,
+                ok: false,
+            });
+        }
+    };
+    if (options.expectedCaps) {
+        const expected = options.expectedCaps;
+        await check("caps: declared levels match expected", async () => {
+            for (const key of Object.keys(expected)) {
+                const actual = caps[key];
+                assert(actual === expected[key], `cap '${key}' expected '${expected[key]}' got '${actual}'`);
+            }
+        });
+    }
+    const sb = await client.create({});
+    await check("lifecycle: getInfo", async () => {
+        const info = await sb.getInfo();
+        assert(!!info.id, "info.id present");
+        assert(info.provider === provider.name, "info.provider matches");
+    });
+    await check("exec: echo buffered", async () => {
+        const r = await sb.commands.run("echo hi");
+        assert(r.exitCode === 0, `exit 0 (got ${r.exitCode})`);
+        assert(r.stdout.trim() === "hi", `stdout 'hi' (got ${JSON.stringify(r.stdout)})`);
+    });
+    await check("exec: non-zero exit is data, not throw", async () => {
+        const r = await sb.commands.run("false");
+        assert(r.exitCode !== 0, `non-zero exit (got ${r.exitCode})`);
+    });
+    if (caps.streaming !== "unsupported") {
+        await check("exec: streaming events", async () => {
+            let out = "";
+            let exited = false;
+            for await (const ev of sb.commands.run("echo streamed")) {
+                if (ev.type === "stdout") {
+                    out += ev.data;
+                }
+                if (ev.type === "exit") {
+                    exited = true;
+                }
+            }
+            assert(out.trim() === "streamed", `streamed stdout (got ${JSON.stringify(out)})`);
+            assert(exited, "saw exit event");
+        });
+    }
+    await check("exec: cwd applied", async () => {
+        const r = await sb.commands.run("pwd", { cwd: "/tmp" });
+        assert(r.stdout.includes("/tmp"), `pwd in /tmp (got ${JSON.stringify(r.stdout)})`);
+    });
+    await check("exec: env applied", async () => {
+        const r = await sb.commands.run("echo $SBOX_CONF", {
+            env: { SBOX_CONF: "xyz" },
+        });
+        assert(r.stdout.trim() === "xyz", `env expand (got ${JSON.stringify(r.stdout)})`);
+    });
+    await check("files: write/read text round-trip", async () => {
+        await sb.files.write("/tmp/conf.txt", "hello world");
+        const f = await sb.files.read("/tmp/conf.txt");
+        const text = await f.text();
+        assert(text === "hello world", `text round-trip (got ${JSON.stringify(text)})`);
+    });
+    await check("files: write/read binary round-trip", async () => {
+        const bytes = new Uint8Array([0, 1, 2, 250, 255]);
+        await sb.files.write("/tmp/conf.bin", bytes);
+        const got = await (await sb.files.read("/tmp/conf.bin")).bytes();
+        assert(got.length === bytes.length, `binary length (got ${got.length})`);
+        assert(got[0] === 0 && got[4] === 255, "binary content preserved");
+    });
+    await check("files: list shows written file", async () => {
+        await sb.files.write("/tmp/listed.txt", "x");
+        const entries = await sb.files.list("/tmp");
+        assert(entries.some((e) => e.name === "listed.txt"), "file listed");
+    });
+    await check("files: mkdir/exists/remove", async () => {
+        await sb.files.mkdir("/tmp/confdir", { recursive: true });
+        assert(await sb.files.exists("/tmp/confdir"), "exists after mkdir");
+        await sb.files.remove("/tmp/confdir", { recursive: true });
+        assert(!(await sb.files.exists("/tmp/confdir")), "gone after remove");
+    });
+    await check("files: exists() is false (not throw) on missing", async () => {
+        const e = await sb.files.exists("/tmp/definitely-missing-xyz");
+        assert(e === false, "missing => false");
+    });
+    await check("caps: code gating matches declaration", async () => {
+        if (caps.codeInterpreter === "unsupported") {
+            assert(sb.code === undefined, "code undefined");
+        }
+        else {
+            assert(sb.code !== undefined, "code present");
+        }
+    });
+    await check("caps: snapshots gating matches declaration", async () => {
+        if (caps.snapshot === "unsupported") {
+            assert(sb.snapshots === undefined, "snapshots undefined");
+        }
+        else {
+            assert(sb.snapshots !== undefined, "snapshots present");
+        }
+    });
+    await check("caps: ports gating matches declaration", async () => {
+        if (caps.exposePort === "unsupported") {
+            assert(sb.ports === undefined, "ports undefined");
+        }
+        else {
+            assert(sb.ports !== undefined, "ports present");
+        }
+    });
+    await check("caps: network gating matches declaration", async () => {
+        if (caps.egressControl === "unsupported") {
+            assert(sb.network === undefined, "network undefined");
+        }
+        else {
+            assert(sb.network !== undefined, "network present");
+        }
+    });
+    if (caps.snapshot !== "unsupported") {
+        await check("snapshots: create returns a ref", async () => {
+            const snap = await sb.snapshots.create({ name: "conf-ck" });
+            assert(!!snap.id, "snapshot id");
+        });
+    }
+    if (caps.pause !== "unsupported") {
+        await check("lifecycle: pause/resume", async () => {
+            await sb.pause();
+            await sb.resume();
+        });
+    }
+    await check("client: list honors capability", async () => {
+        if (caps.list === "unsupported") {
+            let threw = false;
+            try {
+                for await (const _info of client.list()) {
+                    break;
+                }
+            }
+            catch (error) {
+                threw = error instanceof NotSupportedError;
+            }
+            assert(threw, "list throws NotSupportedError when unsupported");
+        }
+        else {
+            for await (const _info of client.list()) {
+                break;
+            }
+        }
+    });
+    await check("lifecycle: destroy", async () => {
+        await sb.destroy();
+    });
+    await check("lifecycle: create + destroy a fresh sandbox", async () => {
+        const s2 = await client.create({});
+        assert(!!s2.id, "fresh id");
+        await s2.destroy();
+    });
+    await client.dispose();
+    return {
+        checks,
+        passed: checks.every((c) => c.ok),
+        provider: provider.name,
+    };
+}

package/dist/daytona/index.d.ts

@@ -0,0 +1,64 @@
+import type { Sandbox as DaytonaSandbox } from "@daytonaio/sdk";
+import type { SandboxProvider } from "../adapter/index.js";
+export interface DaytonaOptions {
+    apiKey: string;
+    apiUrl?: string;
+    /** Target region, e.g. "us" or "eu". */
+    target?: string;
+}
+export declare const DAYTONA_CAPS: {
+    readonly background: "unsupported";
+    readonly codeInterpreter: "native";
+    readonly egressControl: "unsupported";
+    readonly exposePort: "native";
+    readonly filesUpload: "native";
+    readonly filesWatch: "unsupported";
+    readonly fork: "unsupported";
+    readonly gpu: "unsupported";
+    readonly killProcess: "unsupported";
+    readonly list: "native";
+    readonly metrics: "unsupported";
+    readonly pause: "native";
+    readonly privatePreview: "native";
+    readonly proxiedFetch: "unsupported";
+    readonly pty: "unsupported";
+    readonly region: "native";
+    readonly secretsVault: "unsupported";
+    readonly setTimeout: "native";
+    readonly snapshot: "unsupported";
+    readonly ssh: "unsupported";
+    readonly statefulKernel: "unsupported";
+    readonly stdin: "unsupported";
+    readonly stop: "native";
+    readonly streaming: "emulated";
+    readonly volumes: "unsupported";
+};
+export type DaytonaCaps = typeof DAYTONA_CAPS;
+export declare const daytona: (opts: DaytonaOptions) => SandboxProvider<{
+    readonly background: "unsupported";
+    readonly codeInterpreter: "native";
+    readonly egressControl: "unsupported";
+    readonly exposePort: "native";
+    readonly filesUpload: "native";
+    readonly filesWatch: "unsupported";
+    readonly fork: "unsupported";
+    readonly gpu: "unsupported";
+    readonly killProcess: "unsupported";
+    readonly list: "native";
+    readonly metrics: "unsupported";
+    readonly pause: "native";
+    readonly privatePreview: "native";
+    readonly proxiedFetch: "unsupported";
+    readonly pty: "unsupported";
+    readonly region: "native";
+    readonly secretsVault: "unsupported";
+    readonly setTimeout: "native";
+    readonly snapshot: "unsupported";
+    readonly ssh: "unsupported";
+    readonly statefulKernel: "unsupported";
+    readonly stdin: "unsupported";
+    readonly stop: "native";
+    readonly streaming: "emulated";
+    readonly volumes: "unsupported";
+}, DaytonaSandbox>;
+//# sourceMappingURL=index.d.ts.map

package/dist/daytona/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/daytona/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAWzE,OAAO,KAAK,EAaV,eAAe,EAGhB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BS,CAAC;AAEnC,MAAM,MAAM,WAAW,GAAG,OAAO,YAAY,CAAC;AA4G9C,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;kBAgNlB,CAAC"}