Add Devbox product SDK

[hugosantos]

Summary

Adds a TypeScript-native Devbox client for creating and managing devboxes, blueprints, and images, and for interacting with running devboxes through commands, terminals, and filesystem operations.

Motivation

TypeScript users need a product-level API for Devboxes without depending on generated RPC messages or manually managing activation, authentication, and connection reuse.

Key features

• Creates and manages devboxes directly or from reusable blueprints.
• Runs structured commands or shell scripts, opens explicit PTY sessions, and transfers files.
• Registers, inspects, lists, optimizes, and deletes images.
• Handles devbox activation and authenticated connection reuse transparently.
• Supports AbortSignal and operation timeouts throughout the API.

API examples

Create a blueprint and a devbox from it:

import { loadUserToken } from "@namespacelabs/sdk/auth";
import { createDevboxClient } from "@namespacelabs/sdk/devbox";

const client = createDevboxClient({
  tokenSource: await loadUserToken(),
});

const blueprint = await client.blueprints.create("typescript", {
  image: "node:22",
  size: "m",
  environment: { NODE_ENV: "development" },
});

const devbox = await client.devboxes.create({
  name: "my-devbox",
  blueprint: blueprint.name,
});

Or create a devbox directly from an image:

const devbox = await client.devboxes.create({
  name: "my-devbox",
  image: "node:22",
  size: "s",
  environment: { NODE_ENV: "development" },
});

Execute commands and consume their output:

const result = await devbox.exec(["node", "--version"]);
process.stdout.write(result.stdout);

await devbox.shell("npm install && npm test", {
  cwd: "/workspace",
});

await devbox.fs.upload("./package.json", "/workspace/package.json");
await devbox.fs.download("/workspace/results.json", "./results.json");

Open an interactive terminal:

const terminal = await devbox.terminal.open({ columns: 120, rows: 40 });
terminal.onData((data) => process.stdout.write(data));
terminal.write("pwd\n");
terminal.resize(160, 50);
terminal.close();

Register and optimize an image:

const image = await client.images.register({
  name: "node-22",
  ref: "node:22",
});

await client.images.optimize(image.name);
client.close();

API design

• Uses product-facing blueprints terminology while keeping backend template types private.
• Uses the product's s, m, l, and xl machine sizes for direct devboxes and blueprints.
• Makes direct configuration and blueprint-based creation mutually exclusive in CreateDevboxInput.
• Accepts site names as strings and defaults direct creation, blueprint creation, and image optimization to iad.
• Keeps generated Devbox protobuf services and messages out of the public SDK surface.

Validation

• npm ci
• npm test
• npm run build
• npm pack --dry-run --json
• Verified ESM and CommonJS imports of @namespacelabs/sdk/devbox.