@larkup/sandbox 0.1.1 → 0.1.3

package/src/providers/flyio.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const execMock = vi.fn();
+const deleteMock = vi.fn();
+const createSpriteMock = vi.fn();
+let listSpritesMock: ReturnType<typeof vi.fn> | undefined;
+
+vi.mock('@fly/sprites', () => ({
+  SpritesClient: vi.fn().mockImplementation(function () {
+    return { createSprite: createSpriteMock, listSprites: listSpritesMock };
+  }),
+}));
+
+const { flyioAdapter } = await import('./flyio.js');
+
+beforeEach(() => {
+  execMock.mockReset();
+  deleteMock.mockReset();
+  createSpriteMock.mockReset();
+  listSpritesMock = undefined;
+  createSpriteMock.mockResolvedValue({ exec: execMock, delete: deleteMock });
+});
+
+describe('flyioAdapter.verifyCredentials', () => {
+  it('requires a token', async () => {
+    await expect(flyioAdapter.verifyCredentials({})).rejects.toThrow('Fly Sprites token is required.');
+  });
+
+  it('falls back to a throwaway sprite when listSprites is not exposed', async () => {
+    await flyioAdapter.verifyCredentials({ token: 't' });
+    expect(createSpriteMock).toHaveBeenCalledTimes(1);
+    expect(deleteMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('flyioAdapter.execute — ExecError handling', () => {
+  it('reports exitCode 0 on a plain successful exec', async () => {
+    execMock.mockResolvedValue({ stdout: 'ok\n', stderr: '' });
+    const result = await flyioAdapter.execute({ code: 'print(1)', language: 'python' }, { token: 't' });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('ok\n');
+  });
+
+  it('extracts exitCode/stdout/stderr from a thrown ExecError', async () => {
+    const execError = Object.assign(new Error('non-zero exit'), {
+      exitCode: 7,
+      stdout: 'partial\n',
+      stderr: 'failure detail',
+    });
+    execMock.mockRejectedValue(execError);
+
+    const result = await flyioAdapter.execute({ code: 'exit(7)', language: 'python' }, { token: 't' });
+    expect(result.exitCode).toBe(7);
+    expect(result.stderr).toBe('failure detail');
+  });
+
+  it('rethrows and produces a failed result for errors without an exitCode', async () => {
+    execMock.mockRejectedValue(new Error('network down'));
+    const result = await flyioAdapter.execute({ code: 'x=1', language: 'python' }, { token: 't' });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('network down');
+  });
+
+  it('always deletes the sprite afterward', async () => {
+    execMock.mockResolvedValue({ stdout: '', stderr: '' });
+    await flyioAdapter.execute({ code: 'x=1', language: 'python' }, { token: 't' });
+    expect(deleteMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/providers/flyio.ts

@@ -0,0 +1,148 @@
+/**
+ * Fly.io Sprites adapter — https://fly.io/sprites/
+ *
+ * The `@fly/sprites` SDK is very early (0.2.x) and its docs don't confirm a
+ * dedicated whoami/list call. `verifyCredentials` falls back to creating and
+ * immediately deleting a throwaway sprite if no lighter check is exposed.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import {
+  DEFAULT_TIMEOUT_MS,
+  failedResult,
+  runScriptedExecution,
+  safeCleanup,
+  withTimeout,
+} from '../remote-exec.js';
+
+interface Sprite {
+  exec(script: string): Promise<{ stdout?: string; stderr?: string }>;
+  delete(): Promise<void>;
+}
+
+interface SpritesClientInstance {
+  createSprite(name: string): Promise<Sprite>;
+  listSprites?(): Promise<unknown[]>;
+}
+
+interface SpritesModule {
+  SpritesClient: new (token: string) => SpritesClientInstance;
+}
+
+interface SpriteExecError extends Error {
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+async function loadSdk(): Promise<SpritesModule> {
+  // @ts-ignore
+  return (await import(/* webpackIgnore: true */ '@fly/sprites')) as unknown as SpritesModule;
+}
+
+function requireToken(credentials: Record<string, string>): string {
+  const token = credentials.token?.trim();
+  if (!token) throw new Error('Fly Sprites token is required.');
+  return token;
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const token = requireToken(credentials);
+  const { SpritesClient } = await loadSdk();
+  const client = new SpritesClient(token);
+  if (typeof client.listSprites === 'function') {
+    await client.listSprites();
+    return;
+  }
+  const sprite = await client.createSprite(`larkup-verify-${randomUUID().slice(0, 8)}`);
+  await safeCleanup(() => sprite.delete());
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  if (!credentials.token?.trim()) {
+    return {
+      status: 'missing-credentials',
+      backend: 'flyio',
+      error: 'Fly Sprites token is required.',
+    };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'ready', backend: 'flyio' };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'flyio',
+      error: err instanceof Error ? err.message : 'Fly Sprites health check failed.',
+    };
+  }
+}
+
+async function execute(
+  request: ExecutionRequest,
+  credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  let token: string;
+  try {
+    token = requireToken(credentials);
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Missing Fly Sprites token.',
+      startTime,
+    );
+  }
+
+  const timeoutMs = request.timeout ?? DEFAULT_TIMEOUT_MS;
+  let sprite: Sprite | undefined;
+  try {
+    const { SpritesClient } = await loadSdk();
+    const client = new SpritesClient(token);
+    sprite = await withTimeout(
+      client.createSprite(`larkup-${randomUUID().slice(0, 8)}`),
+      timeoutMs + 30_000,
+      'Fly Sprite create',
+    );
+    const activeSprite = sprite;
+    return await withTimeout(
+      runScriptedExecution(async (script) => {
+        try {
+          const result = await activeSprite.exec(script);
+          return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', exitCode: 0 };
+        } catch (err) {
+          const execErr = err as SpriteExecError;
+          if (execErr && typeof execErr.exitCode === 'number') {
+            return {
+              stdout: execErr.stdout ?? '',
+              stderr: execErr.stderr ?? execErr.message,
+              exitCode: execErr.exitCode,
+            };
+          }
+          throw err;
+        }
+      }, request),
+      timeoutMs + 15_000,
+      'Fly Sprite execution',
+    );
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Fly Sprites execution failed.',
+      startTime,
+    );
+  } finally {
+    if (sprite) await safeCleanup(() => sprite!.delete());
+  }
+}
+
+export const flyioAdapter: SandboxProviderAdapter = {
+  id: 'flyio',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/index.ts

@@ -0,0 +1,42 @@
+import type { SandboxBackend, SandboxProviderAdapter } from '../types.js';
+import { e2bAdapter } from './e2b.js';
+import { vercelAdapter } from './vercel.js';
+import { modalAdapter } from './modal.js';
+import { daytonaAdapter } from './daytona.js';
+import { browserbaseAdapter } from './browserbase.js';
+import { flyioAdapter } from './flyio.js';
+import { northflankAdapter } from './northflank.js';
+import { cloudflareAdapter } from './cloudflare.js';
+import { webcontainersAdapter } from './webcontainers.js';
+
+export const SANDBOX_PROVIDER_ADAPTERS: Record<
+  Exclude<SandboxBackend, 'local' | 'docker' | 'custom'>,
+  SandboxProviderAdapter
+> = {
+  e2b: e2bAdapter,
+  vercel: vercelAdapter,
+  modal: modalAdapter,
+  daytona: daytonaAdapter,
+  browserbase: browserbaseAdapter,
+  flyio: flyioAdapter,
+  northflank: northflankAdapter,
+  cloudflare: cloudflareAdapter,
+  webcontainers: webcontainersAdapter,
+};
+
+export function getSandboxProviderAdapter(id: SandboxBackend): SandboxProviderAdapter | undefined {
+  if (id === 'local' || id === 'docker' || id === 'custom') return undefined;
+  return SANDBOX_PROVIDER_ADAPTERS[id];
+}
+
+export {
+  e2bAdapter,
+  vercelAdapter,
+  modalAdapter,
+  daytonaAdapter,
+  browserbaseAdapter,
+  flyioAdapter,
+  northflankAdapter,
+  cloudflareAdapter,
+  webcontainersAdapter,
+};

package/src/providers/modal.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const clientConstructorMock = vi.fn();
+const imageBuilderVersionMock = vi.fn();
+const appFromNameMock = vi.fn();
+const imageFromRegistryMock = vi.fn();
+const sandboxCreateMock = vi.fn();
+const execMock = vi.fn();
+const terminateMock = vi.fn();
+const closeMock = vi.fn();
+const stdoutReadMock = vi.fn();
+const stderrReadMock = vi.fn();
+const waitMock = vi.fn();
+
+vi.mock('modal', () => ({
+  ModalClient: class {
+    apps = { fromName: appFromNameMock };
+    images = { fromRegistry: imageFromRegistryMock };
+    sandboxes = { create: sandboxCreateMock };
+    getImageBuilderVersion = imageBuilderVersionMock;
+    close = closeMock;
+
+    constructor(options: unknown) {
+      clientConstructorMock(options);
+    }
+  },
+}));
+
+const { modalAdapter } = await import('./modal.js');
+
+const fields = { tokenId: 'ak-123', tokenSecret: 'as-456' };
+
+beforeEach(() => {
+  clientConstructorMock.mockReset();
+  imageBuilderVersionMock.mockReset();
+  appFromNameMock.mockReset();
+  imageFromRegistryMock.mockReset();
+  sandboxCreateMock.mockReset();
+  execMock.mockReset();
+  terminateMock.mockReset();
+  closeMock.mockReset();
+  stdoutReadMock.mockReset();
+  stderrReadMock.mockReset();
+  waitMock.mockReset();
+
+  imageBuilderVersionMock.mockResolvedValue('2026.1');
+  appFromNameMock.mockResolvedValue({ appId: 'ap-123' });
+  imageFromRegistryMock.mockReturnValue({ imageId: 'im-123' });
+  sandboxCreateMock.mockResolvedValue({ exec: execMock, terminate: terminateMock });
+  stdoutReadMock.mockResolvedValue('done\n');
+  stderrReadMock.mockResolvedValue('');
+  waitMock.mockResolvedValue(0);
+  execMock.mockResolvedValue({
+    stdout: { readText: stdoutReadMock },
+    stderr: { readText: stderrReadMock },
+    wait: waitMock,
+  });
+  terminateMock.mockResolvedValue(undefined);
+});
+
+describe('modalAdapter', () => {
+  it('rejects immediately when either token field is missing', async () => {
+    await expect(
+      modalAdapter.execute({ code: 'x=1', language: 'python' }, { tokenId: 'ak-1' }),
+    ).resolves.toMatchObject({ exitCode: 1 });
+    expect(clientConstructorMock).not.toHaveBeenCalled();
+  });
+
+  it('verifies credentials through the current Modal client API', async () => {
+    await expect(modalAdapter.healthCheck(fields)).resolves.toMatchObject({ status: 'ready' });
+    expect(clientConstructorMock).toHaveBeenCalledWith(fields);
+    expect(imageBuilderVersionMock).toHaveBeenCalledTimes(1);
+    expect(closeMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('creates a sandbox through the client with the runtime image for the request', async () => {
+    await modalAdapter.execute({ code: 'print(1)', language: 'python', timeout: 5_000 }, fields);
+
+    expect(appFromNameMock).toHaveBeenCalledWith('larkup-sandbox', { createIfMissing: true });
+    expect(imageFromRegistryMock).toHaveBeenCalledWith('python:3.13-slim');
+    expect(sandboxCreateMock).toHaveBeenCalledWith(
+      { appId: 'ap-123' },
+      { imageId: 'im-123' },
+      { timeoutMs: 65_000, idleTimeoutMs: 35_000 },
+    );
+    expect(execMock).toHaveBeenCalledWith(expect.arrayContaining(['bash', '-lc']), {
+      timeoutMs: 5_000,
+    });
+    expect(terminateMock).toHaveBeenCalledTimes(1);
+    expect(closeMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns the command process exit code and output', async () => {
+    stdoutReadMock.mockResolvedValue('result\n');
+    stderrReadMock.mockResolvedValue('warning\n');
+    waitMock.mockResolvedValue(2);
+
+    await expect(
+      modalAdapter.execute({ code: 'x=1', language: 'typescript' }, fields),
+    ).resolves.toMatchObject({
+      stdout: 'result\n',
+      stderr: 'warning\n',
+      exitCode: 2,
+    });
+    expect(imageFromRegistryMock).toHaveBeenCalledWith('node:22-bookworm-slim');
+  });
+});

package/src/providers/modal.ts

@@ -0,0 +1,167 @@
+/**
+ * Modal adapter — https://modal.com/docs/guide/sandboxes
+ *
+ * The Modal JavaScript SDK is client-based: create a ModalClient with the
+ * configured credentials, then create sandboxes through `modal.sandboxes`.
+ */
+
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import {
+  DEFAULT_TIMEOUT_MS,
+  failedResult,
+  runScriptedExecution,
+  safeCleanup,
+  withTimeout,
+} from '../remote-exec.js';
+
+interface ModalProcess {
+  stdout: { readText(): Promise<string> };
+  stderr: { readText(): Promise<string> };
+  wait(): Promise<number>;
+}
+
+interface ModalSandbox {
+  exec(command: string[], params?: { timeoutMs?: number }): Promise<ModalProcess>;
+  terminate(): Promise<void>;
+}
+
+interface ModalClient {
+  apps: {
+    fromName(name: string, options?: { createIfMissing?: boolean }): Promise<unknown>;
+  };
+  images: {
+    fromRegistry(name: string): unknown;
+  };
+  sandboxes: {
+    create(
+      app: unknown,
+      image: unknown,
+      options?: { timeoutMs?: number; idleTimeoutMs?: number },
+    ): Promise<ModalSandbox>;
+  };
+  getImageBuilderVersion(): Promise<string>;
+  close(): void;
+}
+
+interface ModalModule {
+  ModalClient: new (options: { tokenId: string; tokenSecret: string }) => ModalClient;
+}
+
+async function loadSdk(): Promise<ModalModule> {
+  return (await import('modal')) as unknown as ModalModule;
+}
+
+function requireFields(credentials: Record<string, string>): {
+  tokenId: string;
+  tokenSecret: string;
+} {
+  const tokenId = credentials.tokenId?.trim();
+  const tokenSecret = credentials.tokenSecret?.trim();
+  if (!tokenId || !tokenSecret)
+    throw new Error('Modal token ID and token secret are both required.');
+  return { tokenId, tokenSecret };
+}
+
+async function createClient(tokenId: string, tokenSecret: string): Promise<ModalClient> {
+  const { ModalClient } = await loadSdk();
+  return new ModalClient({ tokenId, tokenSecret });
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const { tokenId, tokenSecret } = requireFields(credentials);
+  const modal = await createClient(tokenId, tokenSecret);
+  try {
+    await withTimeout(modal.getImageBuilderVersion(), 20_000, 'Modal credential check');
+  } finally {
+    modal.close();
+  }
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  if (!credentials.tokenId?.trim() || !credentials.tokenSecret?.trim()) {
+    return {
+      status: 'missing-credentials',
+      backend: 'modal',
+      error: 'Modal token ID and secret are required.',
+    };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'ready', backend: 'modal' };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'modal',
+      error: err instanceof Error ? err.message : 'Modal health check failed.',
+    };
+  }
+}
+
+async function execute(
+  request: ExecutionRequest,
+  credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  let fields: { tokenId: string; tokenSecret: string };
+  try {
+    fields = requireFields(credentials);
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Missing Modal credentials.',
+      startTime,
+    );
+  }
+
+  const timeoutMs = request.timeout ?? DEFAULT_TIMEOUT_MS;
+  const modal = await createClient(fields.tokenId, fields.tokenSecret);
+  let sandbox: ModalSandbox | undefined;
+  try {
+    const app = await withTimeout(
+      modal.apps.fromName('larkup-sandbox', { createIfMissing: true }),
+      timeoutMs + 15_000,
+      'Modal app setup',
+    );
+    const image = modal.images.fromRegistry(
+      request.language === 'python' ? 'python:3.13-slim' : 'node:22-bookworm-slim',
+    );
+    sandbox = await withTimeout(
+      modal.sandboxes.create(app, image, {
+        timeoutMs: timeoutMs + 60_000,
+        idleTimeoutMs: timeoutMs + 30_000,
+      }),
+      timeoutMs + 30_000,
+      'Modal sandbox create',
+    );
+    const activeSandbox = sandbox;
+    return await withTimeout(
+      runScriptedExecution(async (script) => {
+        const process = await activeSandbox.exec(['bash', '-lc', script], { timeoutMs });
+        const [stdout, stderr, exitCode] = await Promise.all([
+          process.stdout.readText(),
+          process.stderr.readText(),
+          process.wait(),
+        ]);
+        return { stdout, stderr, exitCode };
+      }, request),
+      timeoutMs + 15_000,
+      'Modal execution',
+    );
+  } catch (err) {
+    return failedResult(err instanceof Error ? err.message : 'Modal execution failed.', startTime);
+  } finally {
+    if (sandbox) await safeCleanup(() => sandbox!.terminate());
+    modal.close();
+  }
+}
+
+export const modalAdapter: SandboxProviderAdapter = {
+  id: 'modal',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/northflank.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const deploymentMock = vi.fn();
+const getProjectMock = vi.fn();
+const getServiceMock = vi.fn();
+const deleteServiceMock = vi.fn();
+const execServiceSessionMock = vi.fn();
+const addContextMock = vi.fn();
+
+vi.mock('@northflank/js-client', () => ({
+  ApiClient: vi.fn().mockImplementation(function () {
+    return {
+      create: { service: { deployment: deploymentMock } },
+      get: { project: getProjectMock, service: getServiceMock },
+      delete: { service: deleteServiceMock },
+      exec: { execServiceSession: execServiceSessionMock },
+    };
+  }),
+  ApiClientInMemoryContextProvider: vi.fn().mockImplementation(function () {
+    return { addContext: addContextMock };
+  }),
+}));
+
+const { northflankAdapter } = await import('./northflank.js');
+
+const fields = { token: 'tok', projectId: 'proj_1' };
+
+function makeExecHandle(stdout: string, stderr: string, exitCode: number) {
+  return {
+    stdOut: { on: (_event: string, cb: (chunk: string) => void) => cb(stdout) },
+    stdErr: { on: (_event: string, cb: (chunk: string) => void) => cb(stderr) },
+    waitForCommandResult: vi.fn().mockResolvedValue({ exitCode }),
+  };
+}
+
+beforeEach(() => {
+  deploymentMock.mockReset();
+  getProjectMock.mockReset();
+  getServiceMock.mockReset();
+  deleteServiceMock.mockReset();
+  execServiceSessionMock.mockReset();
+  addContextMock.mockReset();
+  deploymentMock.mockResolvedValue({});
+  getProjectMock.mockResolvedValue({ data: { id: 'proj_1' } });
+  getServiceMock.mockResolvedValue({ data: { status: 'COMPLETED' } });
+  deleteServiceMock.mockResolvedValue({});
+});
+
+describe('northflankAdapter.verifyCredentials', () => {
+  it('requires both token and projectId', async () => {
+    await expect(northflankAdapter.verifyCredentials({ token: 'tok' })).rejects.toThrow(
+      'Northflank API token and project ID are both required.',
+    );
+  });
+
+  it('checks the project with the authenticated API client', async () => {
+    await northflankAdapter.verifyCredentials(fields);
+    expect(getProjectMock).toHaveBeenCalledWith({ parameters: { projectId: 'proj_1' } });
+  });
+
+  it('rejects a project ID that the token cannot access', async () => {
+    getProjectMock.mockRejectedValue(new Error('Northflank API returned 404.'));
+    await expect(
+      northflankAdapter.verifyCredentials({ token: 'tok', projectId: 'missing-project' }),
+    ).rejects.toThrow('404');
+  });
+});
+
+describe('northflankAdapter.execute', () => {
+  it('creates a service, waits for it to be ready, execs, and deletes it', async () => {
+    execServiceSessionMock.mockResolvedValue(makeExecHandle('out\n', '', 0));
+
+    const result = await northflankAdapter.execute(
+      { code: 'print(1)', language: 'python' },
+      fields,
+    );
+
+    expect(deploymentMock).toHaveBeenCalledTimes(1);
+    expect(getServiceMock).toHaveBeenCalled();
+    expect(execServiceSessionMock).toHaveBeenCalledTimes(1);
+    expect(result.stdout).toBe('out\n');
+    expect(result.exitCode).toBe(0);
+    expect(deleteServiceMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('aggregates stdErr stream chunks into ExecutionResult.stderr', async () => {
+    execServiceSessionMock.mockResolvedValue(makeExecHandle('', 'boom', 1));
+    const result = await northflankAdapter.execute({ code: 'x=1', language: 'python' }, fields);
+    expect(result.stderr).toBe('boom');
+    expect(result.exitCode).toBe(1);
+  });
+
+  it('throws when the service reports FAILED while waiting for readiness', async () => {
+    getServiceMock.mockResolvedValue({ data: { status: 'FAILED' } });
+    const result = await northflankAdapter.execute({ code: 'x=1', language: 'python' }, fields);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('failed to start');
+    // Cleanup still runs even though the service never became ready.
+    expect(deleteServiceMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns a failed result without calling the API when projectId is missing', async () => {
+    const result = await northflankAdapter.execute(
+      { code: 'x=1', language: 'python' },
+      { token: 'tok' },
+    );
+    expect(result.exitCode).toBe(1);
+    expect(deploymentMock).not.toHaveBeenCalled();
+  });
+});