@larkup/sandbox 0.1.1 → 0.1.3

package/src/providers/northflank.ts

@@ -0,0 +1,199 @@
+/**
+ * Northflank adapter — https://northflank.com/docs/v1/application/sandboxes/sandboxes-on-northflank
+ *
+ * Northflank has no dedicated "Sandbox" primitive — a sandbox here is a
+ * short-lived service deployment (`sleep infinity` container) we exec
+ * commands into over a session, then tear down.
+ */
+
+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 NorthflankExecHandle {
+  stdOut: { on(event: 'data', cb: (chunk: Buffer | string) => void): void };
+  stdErr: { on(event: 'data', cb: (chunk: Buffer | string) => void): void };
+  waitForCommandResult(): Promise<{ exitCode?: number }>;
+}
+
+interface NorthflankApiClient {
+  create: { service: { deployment(args: unknown): Promise<unknown> } };
+  get: {
+    project(args: { parameters: { projectId: string } }): Promise<unknown>;
+    service(args: unknown): Promise<{ data?: { status?: string } }>;
+  };
+  delete: { service(args: unknown): Promise<unknown> };
+  exec: {
+    execServiceSession(
+      target: { projectId: string; serviceId: string },
+      opts: { shell: string; command: string },
+    ): Promise<NorthflankExecHandle>;
+  };
+}
+
+interface NorthflankModule {
+  ApiClient: new (
+    ctx: unknown,
+    opts?: { throwErrorOnHttpErrorCode?: boolean },
+  ) => NorthflankApiClient;
+  ApiClientInMemoryContextProvider: new () => {
+    addContext(opts: { name: string; token: string }): Promise<void>;
+  };
+}
+
+async function loadSdk(): Promise<NorthflankModule> {
+  return (await import('@northflank/js-client')) as unknown as NorthflankModule;
+}
+
+function requireFields(credentials: Record<string, string>): { token: string; projectId: string } {
+  const token = credentials.token?.trim();
+  const projectId = credentials.projectId?.trim();
+  if (!token || !projectId)
+    throw new Error('Northflank API token and project ID are both required.');
+  return { token, projectId };
+}
+
+async function buildClient(token: string): Promise<NorthflankApiClient> {
+  const { ApiClient, ApiClientInMemoryContextProvider } = await loadSdk();
+  const ctx = new ApiClientInMemoryContextProvider();
+  await ctx.addContext({ name: 'larkup', token });
+  return new ApiClient(ctx, { throwErrorOnHttpErrorCode: true });
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const { token, projectId } = requireFields(credentials);
+  const client = await buildClient(token);
+  await withTimeout(
+    client.get.project({ parameters: { projectId } }),
+    20_000,
+    'Northflank credential check',
+  );
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  if (!credentials.token?.trim() || !credentials.projectId?.trim()) {
+    return {
+      status: 'missing-credentials',
+      backend: 'northflank',
+      error: 'Northflank API token and project ID are required.',
+    };
+  }
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'ready', backend: 'northflank' };
+  } catch (err) {
+    return {
+      status: 'error',
+      backend: 'northflank',
+      error: err instanceof Error ? err.message : 'Northflank health check failed.',
+    };
+  }
+}
+
+async function waitForServiceReady(
+  client: NorthflankApiClient,
+  projectId: string,
+  serviceId: string,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const service = await client.get.service({ parameters: { projectId, serviceId } });
+    const status = service.data?.status;
+    if (status === 'COMPLETED' || status === undefined) return; // running, or status field not modeled — proceed
+    if (status === 'FAILED') throw new Error('Northflank sandbox service failed to start.');
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+  }
+  throw new Error('Timed out waiting for the Northflank sandbox service to become ready.');
+}
+
+async function execute(
+  request: ExecutionRequest,
+  credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  let fields: { token: string; projectId: string };
+  try {
+    fields = requireFields(credentials);
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Missing Northflank credentials.',
+      startTime,
+    );
+  }
+
+  const timeoutMs = request.timeout ?? DEFAULT_TIMEOUT_MS;
+  const serviceId = `larkup-${randomUUID().slice(0, 8)}`;
+  const { projectId } = fields;
+  let client: NorthflankApiClient | undefined;
+  try {
+    client = await buildClient(fields.token);
+    await withTimeout(
+      client.create.service.deployment({
+        parameters: { projectId },
+        data: {
+          name: serviceId,
+          billing: { deploymentPlan: 'nf-compute-200' },
+          deployment: {
+            instances: 1,
+            docker: { configType: 'customCommand', customCommand: 'sleep infinity' },
+            external: { imagePath: 'ubuntu:22.04' },
+            storage: { ephemeralStorage: { storageSize: 2048 } },
+          },
+        },
+      }),
+      30_000,
+      'Northflank service create',
+    );
+    await waitForServiceReady(client, projectId, serviceId, 60_000);
+
+    return await withTimeout(
+      runScriptedExecution(async (script) => {
+        const activeClient = client!;
+        const handle = await activeClient.exec.execServiceSession(
+          { projectId, serviceId },
+          { shell: 'bash -c', command: script },
+        );
+        const stdoutChunks: string[] = [];
+        const stderrChunks: string[] = [];
+        handle.stdOut.on('data', (chunk) => stdoutChunks.push(chunk.toString()));
+        handle.stdErr.on('data', (chunk) => stderrChunks.push(chunk.toString()));
+        const result = await handle.waitForCommandResult();
+        return {
+          stdout: stdoutChunks.join(''),
+          stderr: stderrChunks.join(''),
+          exitCode: result.exitCode ?? 0,
+        };
+      }, request),
+      timeoutMs + 15_000,
+      'Northflank execution',
+    );
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Northflank execution failed.',
+      startTime,
+    );
+  } finally {
+    if (client) {
+      await safeCleanup(() => client!.delete.service({ parameters: { projectId, serviceId } }));
+    }
+  }
+}
+
+export const northflankAdapter: SandboxProviderAdapter = {
+  id: 'northflank',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/vercel.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const runCommandMock = vi.fn();
+const stopMock = vi.fn();
+const createMock = vi.fn();
+const listMock = vi.fn();
+
+vi.mock('@vercel/sandbox', () => ({
+  Sandbox: { create: createMock, list: listMock },
+}));
+
+const { vercelAdapter } = await import('./vercel.js');
+
+const fields = { token: 'tok', teamId: 'team_1', projectId: 'prj_1' };
+
+beforeEach(() => {
+  runCommandMock.mockReset();
+  stopMock.mockReset();
+  createMock.mockReset();
+  listMock.mockReset();
+  createMock.mockResolvedValue({ runCommand: runCommandMock, stop: stopMock });
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+describe('vercelAdapter.verifyCredentials', () => {
+  it('requires token, teamId, and projectId', async () => {
+    await expect(vercelAdapter.verifyCredentials({ token: 'tok' })).rejects.toThrow(
+      'Vercel access token, team ID, and project ID are all required.',
+    );
+  });
+
+  it('lists sandboxes with the submitted project credentials', async () => {
+    const toArray = vi.fn().mockResolvedValue([]);
+    listMock.mockResolvedValue({ toArray });
+    await vercelAdapter.verifyCredentials(fields);
+    expect(listMock).toHaveBeenCalledWith(fields);
+    expect(toArray).toHaveBeenCalledTimes(1);
+  });
+
+  it('surfaces a Vercel Sandbox authorization failure', async () => {
+    listMock.mockRejectedValue(new Error('Forbidden'));
+    await expect(vercelAdapter.verifyCredentials(fields)).rejects.toThrow('Forbidden');
+  });
+});
+
+describe('vercelAdapter.execute', () => {
+  it('runs the script through bash -c and reads stdout/stderr as functions', async () => {
+    runCommandMock.mockResolvedValue({
+      exitCode: 0,
+      stdout: async () => 'result\n',
+      stderr: async () => '',
+    });
+
+    const result = await vercelAdapter.execute({ code: 'print(1)', language: 'python' }, fields);
+
+    expect(createMock).toHaveBeenCalledWith(expect.objectContaining(fields));
+    expect(runCommandMock).toHaveBeenCalledWith('bash', ['-c', expect.stringContaining('run.py')]);
+    expect(result.stdout).toBe('result\n');
+    expect(stopMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('restores a configured snapshot for each execution', async () => {
+    runCommandMock.mockResolvedValue({
+      exitCode: 0,
+      stdout: async () => '',
+      stderr: async () => '',
+    });
+
+    await vercelAdapter.execute(
+      { code: 'print(1)', language: 'python' },
+      { ...fields, snapshotId: 'snap_1' },
+    );
+
+    expect(createMock).toHaveBeenCalledWith(
+      expect.objectContaining({ source: { type: 'snapshot', snapshotId: 'snap_1' } }),
+    );
+  });
+
+  it('returns a failed result without creating a sandbox when credentials are incomplete', async () => {
+    const result = await vercelAdapter.execute({ code: 'x=1', language: 'python' }, { token: 'tok' });
+    expect(result.exitCode).toBe(1);
+    expect(createMock).not.toHaveBeenCalled();
+  });
+});

package/src/providers/vercel.ts

@@ -0,0 +1,143 @@
+/**
+ * Vercel Sandbox adapter — https://vercel.com/docs/sandbox
+ *
+ * Uses the access-token auth path (token + team + project) rather than the
+ * OIDC path, since credentials here come from the Settings UI, not a
+ * Vercel-managed environment.
+ */
+
+import type {
+  SandboxHealthCheck,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxProviderAdapter,
+} from '../types.js';
+import {
+  DEFAULT_TIMEOUT_MS,
+  failedResult,
+  runScriptedExecution,
+  safeCleanup,
+  withTimeout,
+} from '../remote-exec.js';
+
+interface VercelCommandResult {
+  exitCode: number;
+  stdout(): Promise<string>;
+  stderr(): Promise<string>;
+}
+
+interface VercelSandbox {
+  runCommand(cmd: string, args: string[]): Promise<VercelCommandResult>;
+  stop(): Promise<unknown>;
+}
+
+interface VercelSandboxModule {
+  Sandbox: {
+    create(opts: {
+      token: string;
+      teamId: string;
+      projectId: string;
+      timeout?: number;
+      source?: { type: 'snapshot'; snapshotId: string };
+    }): Promise<VercelSandbox>;
+    list(opts: {
+      token: string;
+      teamId: string;
+      projectId: string;
+    }): Promise<{ toArray(): Promise<unknown[]> }>;
+  };
+}
+
+async function loadSdk(): Promise<VercelSandboxModule> {
+  return (await import('@vercel/sandbox')) as unknown as VercelSandboxModule;
+}
+
+function requireFields(credentials: Record<string, string>): {
+  token: string;
+  teamId: string;
+  projectId: string;
+} {
+  const token = credentials.token?.trim();
+  const teamId = credentials.teamId?.trim();
+  const projectId = credentials.projectId?.trim();
+  if (!token || !teamId || !projectId) {
+    throw new Error('Vercel access token, team ID, and project ID are all required.');
+  }
+  return { token, teamId, projectId };
+}
+
+async function verifyCredentials(credentials: Record<string, string>): Promise<void> {
+  const { token, teamId, projectId } = requireFields(credentials);
+  const { Sandbox } = await loadSdk();
+  await (await Sandbox.list({ token, teamId, projectId })).toArray();
+}
+
+async function healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  try {
+    await verifyCredentials(credentials);
+    return { status: 'ready', backend: 'vercel' };
+  } catch (err) {
+    const missing = !credentials.token || !credentials.teamId || !credentials.projectId;
+    return {
+      status: missing ? 'missing-credentials' : 'error',
+      backend: 'vercel',
+      error: err instanceof Error ? err.message : 'Vercel Sandbox health check failed.',
+    };
+  }
+}
+
+async function execute(
+  request: ExecutionRequest,
+  credentials: Record<string, string>,
+): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  let fields: { token: string; teamId: string; projectId: string };
+  try {
+    fields = requireFields(credentials);
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Missing Vercel credentials.',
+      startTime,
+    );
+  }
+
+  const timeoutMs = request.timeout ?? DEFAULT_TIMEOUT_MS;
+  let sandbox: VercelSandbox | undefined;
+  try {
+    const { Sandbox } = await loadSdk();
+    const snapshotId = credentials.snapshotId?.trim();
+    sandbox = await withTimeout(
+      Sandbox.create({
+        ...fields,
+        timeout: timeoutMs + 60_000,
+        ...(snapshotId ? { source: { type: 'snapshot' as const, snapshotId } } : {}),
+      }),
+      timeoutMs + 30_000,
+      'Vercel sandbox create',
+    );
+    const activeSandbox = sandbox;
+    return await withTimeout(
+      runScriptedExecution(async (script) => {
+        const result = await activeSandbox.runCommand('bash', ['-c', script]);
+        const [stdout, stderr] = await Promise.all([result.stdout(), result.stderr()]);
+        return { stdout, stderr, exitCode: result.exitCode };
+      }, request),
+      timeoutMs + 15_000,
+      'Vercel Sandbox execution',
+    );
+  } catch (err) {
+    return failedResult(
+      err instanceof Error ? err.message : 'Vercel Sandbox execution failed.',
+      startTime,
+    );
+  } finally {
+    if (sandbox) await safeCleanup(() => sandbox!.stop());
+  }
+}
+
+export const vercelAdapter: SandboxProviderAdapter = {
+  id: 'vercel',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/providers/webcontainers.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { webcontainersAdapter } from './webcontainers.js';
+
+describe('webcontainersAdapter', () => {
+  it('execute() always fails — WebContainers is browser-only, no Node.js entry point', async () => {
+    const result = await webcontainersAdapter.execute({ code: 'console.log(1)', language: 'javascript' }, {});
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('cross-origin-isolated browser tab');
+  });
+
+  it('verifyCredentials always throws, since nothing here is server-checkable', async () => {
+    await expect(webcontainersAdapter.verifyCredentials({})).rejects.toThrow('no server-side credential check');
+    await expect(webcontainersAdapter.verifyCredentials({ apiKey: 'wc_live_key' })).rejects.toThrow();
+  });
+
+  it('healthCheck reports status "unsupported"', async () => {
+    const result = await webcontainersAdapter.healthCheck({});
+    expect(result.status).toBe('unsupported');
+    expect(result.error).toContain('SharedArrayBuffer');
+  });
+});

package/src/providers/webcontainers.ts

@@ -0,0 +1,36 @@
+/**
+ * WebContainers adapter — https://webcontainers.io/
+ *
+ * `@webcontainer/api` boots a WebAssembly Node.js runtime that only runs
+ * inside a cross-origin-isolated browser tab (it needs SharedArrayBuffer) —
+ * there is no Node.js/server-side entry point at all, so `execute()` fails
+ * fast. The optional "license key" field is a StackBlitz-issued commercial
+ * key consumed by `WebContainer.configureAPIKey()` in the browser; there is
+ * no server-reachable endpoint to validate it against, so `verifyCredentials`
+ * says so honestly rather than reporting a false positive.
+ */
+
+import type { SandboxHealthCheck, ExecutionRequest, ExecutionResult, SandboxProviderAdapter } from '../types.js';
+import { failedResult } from '../remote-exec.js';
+import { SANDBOX_PROVIDERS } from '../registry.js';
+
+async function verifyCredentials(_credentials: Record<string, string>): Promise<void> {
+  throw new Error(
+    'WebContainers has no server-side credential check — the license key is only validated by StackBlitz when WebContainer.boot() runs in the browser.',
+  );
+}
+
+async function healthCheck(_credentials: Record<string, string>): Promise<SandboxHealthCheck> {
+  return { status: 'unsupported', backend: 'webcontainers', error: SANDBOX_PROVIDERS.webcontainers.executionCaveat };
+}
+
+async function execute(_request: ExecutionRequest, _credentials: Record<string, string>): Promise<ExecutionResult> {
+  return failedResult(SANDBOX_PROVIDERS.webcontainers.executionCaveat!, Date.now());
+}
+
+export const webcontainersAdapter: SandboxProviderAdapter = {
+  id: 'webcontainers',
+  verifyCredentials,
+  healthCheck,
+  execute,
+};

package/src/registry.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import {
+  SANDBOX_PROVIDER_LIST,
+  getSandboxProvider,
+  validateSandboxCredentials,
+} from './registry.js';
+
+const EXPECTED_PROVIDER_IDS = [
+  'e2b',
+  'vercel',
+  'modal',
+  'daytona',
+  'browserbase',
+  'flyio',
+  'northflank',
+  'cloudflare',
+  'webcontainers',
+];
+
+describe('SANDBOX_PROVIDER_LIST', () => {
+  it('registers exactly the nine remote providers', () => {
+    expect(SANDBOX_PROVIDER_LIST.map((p) => p.id).sort()).toEqual(
+      [...EXPECTED_PROVIDER_IDS].sort(),
+    );
+  });
+
+  it('gives every provider a label, docs link, and public icon path', () => {
+    for (const provider of SANDBOX_PROVIDER_LIST) {
+      expect(provider.label.length).toBeGreaterThan(0);
+      expect(provider.docsUrl).toMatch(/^https:\/\//);
+      expect(provider.icon.startsWith('/')).toBe(true);
+    }
+  });
+
+  it('requires an executionCaveat exactly when executionSupport is unsupported', () => {
+    for (const provider of SANDBOX_PROVIDER_LIST) {
+      if (provider.executionSupport === 'unsupported') {
+        expect(
+          provider.executionCaveat,
+          `${provider.id} should explain its limitation`,
+        ).toBeTruthy();
+      }
+    }
+  });
+
+  it('flags browserbase, cloudflare, and webcontainers as not general code-execution backends', () => {
+    const unsupported = SANDBOX_PROVIDER_LIST.filter(
+      (p) => p.executionSupport === 'unsupported',
+    ).map((p) => p.id);
+    expect(unsupported.sort()).toEqual(['browserbase', 'cloudflare', 'webcontainers']);
+  });
+});
+
+describe('getSandboxProvider', () => {
+  it('returns undefined for local, docker, and custom, which are not registry-backed', () => {
+    expect(getSandboxProvider('local')).toBeUndefined();
+    expect(getSandboxProvider('docker')).toBeUndefined();
+    expect(getSandboxProvider('custom')).toBeUndefined();
+  });
+
+  it('returns the matching descriptor for a registered provider', () => {
+    expect(getSandboxProvider('e2b')?.label).toBe('E2B');
+  });
+});
+
+describe('validateSandboxCredentials', () => {
+  it('flags every missing required field', () => {
+    const vercel = getSandboxProvider('vercel')!;
+    const errors = validateSandboxCredentials(vercel, {});
+    expect(Object.keys(errors).sort()).toEqual(['projectId', 'teamId', 'token']);
+  });
+
+  it('passes once all required fields are present, ignoring optional ones', () => {
+    const daytona = getSandboxProvider('daytona')!;
+    const errors = validateSandboxCredentials(daytona, { apiKey: 'dtn_123' });
+    expect(errors).toEqual({});
+  });
+
+  it('treats whitespace-only values as missing', () => {
+    const e2b = getSandboxProvider('e2b')!;
+    const errors = validateSandboxCredentials(e2b, { apiKey: '   ' });
+    expect(errors.apiKey).toBeTruthy();
+  });
+});