feat(packages/sandbox): sandbox sdk poc

Author: jamie-at-bunny

.changeset/sandbox-sdk.md

@@ -0,0 +1,6 @@
+---
+"@bunny.net/sandbox": minor
+"@bunny.net/cli": minor
+---
+
+Add @bunny.net/sandbox SDK for programmatic sandbox create, file buffering, command execution, and port exposure; wire sandbox CLI commands onto it

AGENTS.md

@@ -74,7 +74,8 @@ This is a Bun workspace monorepo with four packages:
 - **`@bunny.net/openapi-client`** (`packages/openapi-client/`) — Standalone, type-safe OpenAPI client for bunny.net, generated from OpenAPI specs. Zero CLI dependencies. Publishable to npm.
 - **`@bunny.net/app-config`** (`packages/app-config/`) — Shared app configuration schemas (Zod), inferred types, JSON Schema generation, and API conversion functions. Used by the CLI and potentially other tools.
 - **`@bunny.net/database-shell`** (`packages/database-shell/`) — Standalone interactive SQL shell for libSQL databases. Framework-agnostic REPL, dot-commands, formatting, masking, and history. Also usable as a standalone CLI (binary: `bsql`).
-- **`@bunny.net/cli`** (`packages/cli/`) — The CLI. Depends on `@bunny.net/openapi-client`, `@bunny.net/app-config`, and `@bunny.net/database-shell`.
+- **`@bunny.net/sandbox`** (`packages/sandbox/`) — Standalone sandbox SDK. Code-first DX (`Sandbox.create`, `writeFiles`, `runCommand`, `exposePort`) over Magic Containers provisioning plus an `ssh2` SSH/SFTP transport. Zero CLI dependencies.
+- **`@bunny.net/cli`** (`packages/cli/`) — The CLI. Depends on `@bunny.net/openapi-client`, `@bunny.net/app-config`, `@bunny.net/database-shell`, and `@bunny.net/sandbox`.
 
 ```
 bunny-cli/
@@ -144,6 +145,19 @@ bunny-cli/
 │   │       ├── types.ts                  # ShellLogger, ShellOptions, PrintMode
 │   │       └── shell.test.ts            # Tests for shell utilities
 │   │
+│   ├── sandbox/                          # @bunny.net/sandbox package
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── src/
+│   │       ├── index.ts                  # Barrel export: Sandbox, Command, types
+│   │       ├── sandbox.ts                # Sandbox class: create/get/fromHandle, runCommand, writeFiles, readFile, mkDir, exposePort, domain, delete
+│   │       ├── provision.ts              # Magic Containers app create/poll/endpoints + auth helpers
+│   │       ├── transport.ts              # ssh2 SSH/SFTP transport (exec, file IO, reachability)
+│   │       ├── command.ts                # Command (detached, logs()) and CommandFinished
+│   │       ├── types.ts                  # Option and handle types
+│   │       ├── errors.ts                 # SandboxError
+│   │       └── sandbox.test.ts           # Tests for pure logic (command building, app extraction)
+│   │
 │   └── cli/                              # @bunny.net/cli package
 │       ├── package.json
 │       ├── tsconfig.json
@@ -349,7 +363,7 @@ bunny-cli/
 
 ### Conventions
 
-- **Monorepo with Bun workspaces.** `packages/openapi-client/` is the standalone API client SDK; `packages/app-config/` provides shared Zod schemas, types, and API conversion functions for `bunny.jsonc`; `packages/database-shell/` is the standalone SQL shell engine; `packages/cli/` is the CLI.
+- **Monorepo with Bun workspaces.** `packages/openapi-client/` is the standalone API client SDK; `packages/app-config/` provides shared Zod schemas, types, and API conversion functions for `bunny.jsonc`; `packages/database-shell/` is the standalone SQL shell engine; `packages/sandbox/` is the standalone sandbox SDK (provisioning + SSH transport); `packages/cli/` is the CLI.
 - **API clients use `ClientOptions`** — an options object with `apiKey`, `baseUrl`, `verbose`, `userAgent`, and `onDebug`. The CLI provides a `clientOptions(config, verbose)` helper to build this from `ResolvedConfig`.
 - **One command per file.** Each file in `commands/` exports a single command or namespace.
 - **Commands are grouped by domain** in subdirectories (`config/`, `db/`, `scripts/`).

CLAUDE.md

@@ -26,12 +26,13 @@ test("example", () => {
 
 ## Monorepo structure
 
-This is a Bun workspace monorepo with four packages:
+This is a Bun workspace monorepo with five packages:
 
 - `packages/openapi-client/` (`@bunny.net/openapi-client`) — standalone, type-safe OpenAPI client, zero CLI deps
 - `packages/app-config/` (`@bunny.net/app-config`) — shared Zod schemas, types, and JSON Schema for `bunny.jsonc`
 - `packages/database-shell/` (`@bunny.net/database-shell`) — standalone SQL shell engine (REPL, formatting, masking)
-- `packages/cli/` (`@bunny.net/cli`) — the CLI, depends on all three
+- `packages/sandbox/` (`@bunny.net/sandbox`) — standalone sandbox SDK (create, file buffering, command exec, port exposure) over Magic Containers + SSH
+- `packages/cli/` (`@bunny.net/cli`) — the CLI, depends on the other four
 
 ## Project conventions
 

bun.lock

@@ -13,6 +13,7 @@
     "@bunny.net/openapi-client": "workspace:*",
     "@bunny.net/app-config": "workspace:*",
     "@bunny.net/database-shell": "workspace:*",
+    "@bunny.net/sandbox": "workspace:*",
     "@bunny.net/database-studio": "workspace:*",
     "@libsql/client": "^0.17.0",
     "@types/prompts": "^2.4.9",