Add e2e tests for compatibility tests

.codesandbox/ci.json

@@ -0,0 +1 @@
+{}

.github/workflows/release-please.yml

@@ -0,0 +1,42 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: node
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          bump-minor-pre-major: true
+          bump-patch-for-minor-pre-major: true
+
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to NPM
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --no-git-checks

.gitignore

@@ -2,7 +2,7 @@
 
 # Generated stuff
 dist
-tests
+test-template
 
 ### macOS ###
 *.DS_Store
@@ -99,8 +99,4 @@ typings/
 !.vscode/launch.json
 !.vscode/extensions.json
 
-# Lock files
-package-lock.json
-yarn.lock
-
 # End of https://www.gitignore.io/api/node,visualstudiocode,macos

.prettierrc

@@ -0,0 +1 @@
+{}

CLAUDE.md

@@ -0,0 +1,134 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Build Commands
+
+- `npm run build` - Full production build (clean, esbuild, generate types for both CJS and ESM)
+- `npm run build:esbuild` - Run esbuild bundling only
+- `npm run clean` - Remove dist directory
+- `npm run dev:cli` - Development mode with file watching for CLI (watches src/bin)
+
+### Type Checking and Linting
+
+- `npm run typecheck` - Run TypeScript type checking without emitting files
+- `npm run format` - Format code using Prettier
+
+### CLI Development
+
+- `npm run dev:cli` - Start development mode with file watching specifically for CLI changes
+- The CLI binary is built to `dist/bin/codesandbox.mjs` and made executable
+- CLI can be run with `./dist/bin/codesandbox.mjs` or just `csb` if installed globally
+
+### API Client Generation
+
+- `npm run build-openapi` - Generate API clients from production OpenAPI spec
+- `npm run build-openapi:staging` - Generate API clients from staging OpenAPI spec
+- Generated clients are placed in `src/api-clients/` directory
+
+## Architecture
+
+### Core Components
+
+**SDK Entry Points:**
+
+- `src/index.ts` - Main SDK export with `CodeSandbox` class
+- `src/browser/index.ts` - Browser-specific SDK build
+- `src/node/index.ts` - Node.js-specific SDK build
+
+**Key Classes:**
+
+- `CodeSandbox` - Main SDK class providing `sandboxes` and `hosts` properties
+- `Sandboxes` (src/Sandboxes.ts) - Manages sandbox operations (create, list, get, fork)
+- `Sandbox` (src/Sandbox.ts) - Individual sandbox instance with connection and session management
+- `SandboxClient` (src/SandboxClient/index.ts) - High-level client for sandbox interactions
+- `API` (src/API.ts) - Low-level API wrapper for all CodeSandbox REST endpoints
+
+**Communication Layer:**
+
+- `src/pitcher-protocol/` - WebSocket protocol definitions and message types for real-time sandbox communication
+- `src/AgentClient/` - WebSocket client implementation for connecting to sandbox agents
+
+**CLI:**
+
+- `src/bin/main.tsx` - CLI entry point using Ink (React for CLI)
+- `src/bin/commands/` - Individual CLI commands (build, sandbox, previewHosts, hostTokens)
+- `src/bin/ui/` - Ink-based UI components for the interactive CLI
+
+### Build System
+
+**Multi-Format Output:**
+
+- ESM build: `dist/esm/` (primary format, "type": "module")
+- CommonJS build: `dist/cjs/` (compatibility)
+- Browser build: Separate bundles with browser polyfills
+- CLI build: Standalone executable with shebang
+
+**Key Build Features:**
+
+- esbuild for bundling with custom plugins for module replacement
+- Separate TypeScript compilation for type definitions
+- Browser polyfills for Node.js modules (os, path, crypto, etc.)
+- External dependencies preserved except for CLI build which bundles React/Ink
+
+### Type System
+
+**Configuration:**
+
+- Main tsconfig.json excludes `src/bin` and `src/api-clients`
+- Separate build configs for CJS (`tsconfig.build-cjs.json`) and ESM (`tsconfig.build-esm.json`)
+- Strict TypeScript configuration with comprehensive type checking
+
+**Generated Types:**
+
+- `src/api-clients/` contains auto-generated API clients and types from OpenAPI specs
+- Multiple API client modules for different sandbox services (fs, git, shell, etc.)
+
+### Authentication & Configuration
+
+**API Authentication:**
+
+- Requires CodeSandbox API token (CSB_API_KEY environment variable)
+- Token creation: https://codesandbox.io/t/api
+- Automatic User-Agent header injection with SDK version
+
+**Environment Detection:**
+
+- Automatic base URL inference based on API key format
+- Support for different CodeSandbox environments (production, staging)
+
+### Testing
+
+The codebase includes a `test-template/` directory with a Vite + React + TypeScript template for SDK testing.
+
+## Documentation
+
+**SDK Documentation:** https://codesandbox.io/docs/sdk
+
+**Contributing to Documentation:**
+
+- Documentation source is located at https://github.com/codesandbox/docs
+- SDK-specific docs are in `packages/projects-docs/pages/sdk/` folder
+- Update documentation there when making changes to SDK functionality
+
+## Key Patterns
+
+**Error Handling:**
+
+- `handleResponse` utility for consistent API error handling
+- Retry logic with exponential backoff for critical operations
+- OpenTelemetry tracing integration for observability
+
+**Session Management:**
+
+- Support for custom sessions with git credentials and environment variables
+- Browser session creation for web-based sandbox interactions
+- Automatic session cleanup and disposal
+
+**Resource Management:**
+
+- VM tier scaling and hibernation timeout management
+- Cluster and bootup type tracking
+- Agent version management and update detection

README.md

@@ -6,10 +6,9 @@ CodeSandbox SDK enables you to programmatically spin up development environments
 
 Under the hood, the SDK uses the microVM infrastructure of CodeSandbox to spin up sandboxes. It supports:
 
-- Starting fresh VMs within 4 seconds
 - Snapshotting/restoring VMs (checkpointing) at any point in time
-  - With snapshot restore times of less than 2 seconds
-- Cloning VMs within 3 seconds
+  - With snapshot restore times within 1 second
+- Cloning VMs & Snapshots within 2 seconds
 - Source control (git, GitHub, CodeSandbox SCM)
 - Running any Dockerfile
 
@@ -23,58 +22,45 @@ To get started, install the SDK:
 npm install @codesandbox/sdk
 ```
 
-Then, create an API token by going to https://codesandbox.io/t/api, and clicking on the "Create API Token" button. You can then use this token to authenticate with the SDK:
+Create an API token by going to https://codesandbox.io/t/api, and clicking on the "Create API Token" button. You can then use this token to authenticate with the SDK:
 
 ```javascript
 import { CodeSandbox } from "@codesandbox/sdk";
 
-// Create the client with your token
-const sdk = new CodeSandbox(token);
+const sdk = new CodeSandbox(process.env.CSB_API_KEY);
+const sandbox = await sdk.sandboxes.create();
+const client = await sandbox.connect();
 
-// This creates a new sandbox by forking our default template sandbox.
-// You can also pass in other template ids, or create your own template to fork from.
-const sandbox = await sdk.sandbox.create();
+const output = await client.commands.run("echo 'Hello World'");
 
-// You can run JS code directly
-await sandbox.shells.js.run("console.log(1+1)");
-// Or Python code (if it's installed in the template)
-await sandbox.shells.python.run("print(1+1)");
+console.log(output); // Hello World
+```
 
-// Or anything else
-await sandbox.shells.run("echo 'Hello, world!'");
+## Efficient Sandbox Retrieval
 
-// We have a FS API to interact with the filesystem
-await sandbox.fs.writeTextFile("./hello.txt", "world");
+When you need to retrieve metadata for specific sandboxes by their IDs, you can use the efficient retrieval methods instead of listing and filtering all sandboxes:
 
-// And you can clone sandboxes! This does not only clone the filesystem, processes that are running in the original sandbox will also be cloned!
-const sandbox2 = await sandbox.fork();
+### Get Single Sandbox
 
-// Check that the file is still there
-await sandbox2.fs.readTextFile("./hello.txt");
+```javascript
+// Efficient single sandbox retrieval
+const sandbox = await sdk.sandboxes.get("sandbox-id");
+console.log(sandbox.title, sandbox.tags);
+```
 
-// You can also get the opened ports, with the URL to access those
-console.log(sandbox2.ports.getOpenedPorts());
+This method is significantly more efficient than using `list()` and filtering, especially for large organizations with thousands of sandboxes.
 
-// Getting metrics...
-const metrics = await sandbox2.getMetrics();
-console.log(
-  `Memory: ${metrics.memory.usedKiB} KiB / ${metrics.memory.totalKiB} KiB`
-);
-console.log(`CPU: ${(metrics.cpu.used / metrics.cpu.cores) * 100}%`);
+## Configuration
 
-// Finally, you can hibernate a sandbox. This will snapshot the sandbox and stop it. Next time you start the sandbox, it will continue where it left off, as we created a memory snapshot.
-await sandbox.hibernate();
-await sandbox2.hibernate();
+The SDK supports the following environment variables for configuration:
 
-// Open the sandbox again
-const resumedSandbox = await sdk.sandbox.open(sandbox.id);
-```
+- `CSB_API_KEY`: Your CodeSandbox API token for authentication
 
 ## CodeSandbox Integration
 
 This SDK uses the API token from your workspace in CodeSandbox to authenticate and create sandboxes. Because of this, the sandboxes will be created inside your workspace, and the resources will be billed to your workspace.
 
-You could, for example, create a private template in your workspace that has all the dependencies you need (even running servers), and then use that template to fork sandboxes from. This way, you can control the environment that the sandboxes run in.
+Build your own template that has all the dependencies you need (even running servers), and then use that template to create sandboxes from. This way, you can control the environment that the sandboxes run in.
 
 ## Example Use Cases
 
@@ -84,6 +70,6 @@ Code interpretation: Run code in a sandbox to interpret it. This way, you can ru
 
 Development environments: Create a sandbox for each developer, and run their code in the sandbox. This way, you can run multiple development environments in parallel without them interfering with each other.
 
-AI Agents: Create a sandbox for each AI agent, and run the agent in the sandbox. This way, you can run multiple agents in parallel without them interfering with each other. Using the forking mechanism, you can also A/B test different agents.
+AI Agents: Create a sandbox for each AI agent, and run the agent in the sandbox. This way, you can run multiple agents in parallel without them interfering with each other.
 
 CI/CD: Run tests inside a sandbox, and hibernate the sandbox when the tests are done. This way, you can quickly start the sandbox again when you need to run the tests again or evaluate the results.