Merge remote-tracking branch 'origin/main' into base-image

Author: ghostwriternr

.changeset/top-level-await.md

@@ -5,6 +5,10 @@ on:
     branches:
       - main
 
+permissions:
+  id-token: write # Required for OIDC
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -144,6 +148,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
+      id-token: write # Required for trusted publishing
       contents: write
       pull-requests: write
 
@@ -155,12 +160,16 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 24
+          registry-url: 'https://registry.npmjs.org'
           cache: 'npm'
 
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
 
+      - name: Upgrade npm for OIDC trusted publishing
+        run: npm install -g npm@latest
+
       - name: Install dependencies
         run: npm ci
 
@@ -220,8 +229,7 @@ jobs:
           publish: npx tsx .github/changeset-publish.ts
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
-          NPM_PUBLISH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
 
       - name: Upload standalone binary to GitHub release
         if: steps.changesets.outputs.published == 'true'

.github/workflows/claude-code-review.yml

@@ -64,7 +64,7 @@ npm run build:clean        # Force rebuild without cache
 # Unit tests (runs in Workers runtime with vitest-pool-workers)
 npm test
 
-# E2E tests (requires Docker, runs sequentially due to container provisioning)
+# E2E tests (requires Docker)
 npm run test:e2e
 
 # Run a single E2E test file
@@ -74,7 +74,7 @@ npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts
 npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'test name'
 ```
 
-**Important**: E2E tests (`tests/e2e/`) run sequentially (not in parallel) to avoid container resource contention. Each test spawns its own wrangler dev instance.
+**Important**: E2E tests share a single sandbox container for performance. Tests run in parallel using unique sessions for isolation.
 
 ### Code Quality
 
@@ -211,11 +211,12 @@ npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'should handle cl
 **Architecture:**
 
 - Tests in `tests/e2e/` run against real Cloudflare Workers + Docker containers
-- **In CI**: Tests deploy to actual Cloudflare infrastructure and run against deployed workers
-- **Locally**: Each test file spawns its own `wrangler dev` instance
+- **Shared sandbox**: All tests share ONE container, using sessions for isolation
+- **In CI**: Tests deploy to actual Cloudflare infrastructure
+- **Locally**: Global setup spawns wrangler dev once, all tests share it
 - Config: `vitest.e2e.config.ts` (root level)
-- Sequential execution (`singleFork: true`) to prevent container resource contention
-- Longer timeouts (2min per test) for container operations
+- Parallel execution via thread pool (~30s for full suite)
+- See `docs/E2E_TESTING.md` for writing tests
 
 **Build system trust:** The monorepo build system (turbo + npm workspaces) is robust and handles all package dependencies automatically. E2E tests always run against the latest built code - there's no need to manually rebuild or worry about stale builds unless explicitly working on the build setup itself.
 

.github/workflows/release.yml

@@ -165,12 +165,11 @@ Located in `tests/e2e/`:
 
 - Test full workflows against real Workers and containers
 - Require Docker
-- Slower but comprehensive
+- Share a single sandbox container for performance (~30s for full suite)
+- Use sessions for test isolation
 
 Run with: `npm run test:e2e`
 
-You can also run specific test files or individual tests:
-
 ```bash
 # Run a single E2E test file
 npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts
@@ -179,12 +178,15 @@ npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts
 npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'should handle cloning to default directory'
 ```
 
+**See `docs/E2E_TESTING.md` for the complete guide on writing E2E tests.**
+
 ### Writing Tests
 
 - Write tests for new features
 - Add regression tests for bug fixes
 - Ensure tests are deterministic (no flaky tests)
 - Use descriptive test names
+- For E2E tests: use `getSharedSandbox()` and `createUniqueSession()` for isolation
 
 ## Documentation
 

CLAUDE.md

@@ -0,0 +1,165 @@
+# E2E Testing Guide
+
+E2E tests validate full workflows against real Cloudflare Workers and Docker containers.
+
+## Architecture
+
+All E2E tests share a **single sandbox container** for performance. Test isolation is achieved through **sessions** - each test file gets a unique session that provides isolated shell state (env vars, working directory) within the shared container.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Shared Sandbox                     │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
+│  │  Session A  │ │  Session B  │ │  Session C  │    │
+│  │  (test 1)   │ │  (test 2)   │ │  (test 3)   │    │
+│  └─────────────┘ └─────────────┘ └─────────────┘    │
+│                                                     │
+│              Shared filesystem & processes          │
+└─────────────────────────────────────────────────────┘
+```
+
+**Key files:**
+
+- `tests/e2e/global-setup.ts` - Creates sandbox before tests, warms containers
+- `tests/e2e/helpers/global-sandbox.ts` - Provides `getSharedSandbox()` API
+- `vitest.e2e.config.ts` - Configures parallel execution with global setup
+
+## Writing Tests
+
+### Basic Template
+
+```typescript
+import { describe, test, expect, beforeAll } from 'vitest';
+import {
+  getSharedSandbox,
+  createUniqueSession
+} from './helpers/global-sandbox';
+
+describe('My Feature', () => {
+  let workerUrl: string;
+  let headers: Record<string, string>;
+
+  beforeAll(async () => {
+    const sandbox = await getSharedSandbox();
+    workerUrl = sandbox.workerUrl;
+    headers = sandbox.createHeaders(createUniqueSession());
+  }, 120000);
+
+  test('should do something', async () => {
+    const response = await fetch(`${workerUrl}/api/execute`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ command: 'echo hello' })
+    });
+    expect(response.status).toBe(200);
+  }, 60000);
+});
+```
+
+### Using Python Image
+
+For tests requiring Python (code interpreter, etc.):
+
+```typescript
+beforeAll(async () => {
+  const sandbox = await getSharedSandbox();
+  workerUrl = sandbox.workerUrl;
+  // Use createPythonHeaders instead of createHeaders
+  headers = sandbox.createPythonHeaders(createUniqueSession());
+}, 120000);
+```
+
+### File Isolation
+
+Since the filesystem is shared, use unique paths to avoid conflicts:
+
+```typescript
+const sandbox = await getSharedSandbox();
+const testDir = sandbox.uniquePath('my-feature'); // /workspace/test-abc123/my-feature
+
+await fetch(`${workerUrl}/api/file/write`, {
+  method: 'POST',
+  headers,
+  body: JSON.stringify({
+    path: `${testDir}/config.json`,
+    content: '{"key": "value"}'
+  })
+});
+```
+
+### Port Usage
+
+Ports must be exposed in the Dockerfile. Currently exposed:
+
+- `8080` - General testing
+- `9090`, `9091`, `9092` - Process readiness tests
+- `9998` - Process lifecycle tests
+- `9999` - WebSocket tests
+
+To use a new port:
+
+1. Add it to both `tests/e2e/test-worker/Dockerfile` and `Dockerfile.python`
+2. Document which test uses it
+
+### Process Cleanup
+
+Always clean up background processes:
+
+```typescript
+test('should start server', async () => {
+  const startRes = await fetch(`${workerUrl}/api/process/start`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ command: 'bun run server.js' })
+  });
+  const { id: processId } = await startRes.json();
+
+  // ... test logic ...
+
+  // Cleanup
+  await fetch(`${workerUrl}/api/process/${processId}`, {
+    method: 'DELETE',
+    headers
+  });
+}, 60000);
+```
+
+## Test Organization
+
+| File                                    | Purpose                      |
+| --------------------------------------- | ---------------------------- |
+| `comprehensive-workflow.test.ts`        | Happy path integration tests |
+| `process-lifecycle-workflow.test.ts`    | Error handling for processes |
+| `process-readiness-workflow.test.ts`    | waitForLog/waitForPort tests |
+| `code-interpreter-workflow.test.ts`     | Python/JS code execution     |
+| `file-operations-workflow.test.ts`      | File read/write/list         |
+| `streaming-operations-workflow.test.ts` | Streaming command output     |
+| `websocket-workflow.test.ts`            | WebSocket connections        |
+| `bucket-mounting.test.ts`               | R2 bucket mounting (CI only) |
+
+## Running Tests
+
+```bash
+# All E2E tests
+npm run test:e2e
+
+# Single file
+npm run test:e2e -- -- tests/e2e/process-lifecycle-workflow.test.ts
+
+# Single test by name
+npm run test:e2e -- -- tests/e2e/git-clone-workflow.test.ts -t 'should clone repo'
+```
+
+## Debugging
+
+- Tests auto-retry once on failure (`retry: 1` in config)
+- Global setup logs sandbox ID on startup - check for initialization errors
+- If tests fail on first run only, the container might not be warmed (check global-setup.ts initializes the right image type)
+- Port conflicts: check no other test uses the same port
+
+## What NOT to Do
+
+- **Don't create new sandboxes unless strictly necessary** - use `getSharedSandbox()`
+- **Don't skip cleanup** - leaked processes affect other tests
+- **Don't use hardcoded ports** without adding to Dockerfile
+- **Don't rely on filesystem state** from other tests - use unique paths

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-FROM docker.io/cloudflare/sandbox:0.6.0
+FROM docker.io/cloudflare/sandbox:0.6.3
 RUN npm install -g @anthropic-ai/claude-code
 ENV COMMAND_TIMEOUT_MS=300000
 EXPOSE 3000

docs/E2E_TESTING.md

@@ -1 +1 @@
-FROM docker.io/cloudflare/sandbox:0.6.0
+FROM docker.io/cloudflare/sandbox:0.6.3-python

examples/claude-code/Dockerfile

@@ -43,7 +43,7 @@ async function callCloudflareAPI(
 
 async function executePythonCode(env: Env, code: string): Promise<string> {
   const sandboxId = env.Sandbox.idFromName('default');
-  const sandbox = getSandbox(env.Sandbox, sandboxId.toString());
+  const sandbox = getSandbox(env.Sandbox, sandboxId.toString().slice(0, 63));
   const pythonCtx = await sandbox.createCodeContext({ language: 'python' });
   const result = await sandbox.runCode(code, {
     context: pythonCtx

examples/code-interpreter/Dockerfile

@@ -1,4 +1,4 @@
-FROM docker.io/cloudflare/sandbox:0.6.0
+FROM docker.io/cloudflare/sandbox:0.6.3
 
 # Required during local development to access exposed ports
 EXPOSE 8080