computesdk 2.6.0 → 4.0.0

package/README.md

@@ -28,8 +28,8 @@ compute.setConfig({
 const sandbox = await compute.sandbox.create();
 
 // Execute code
-const result = await sandbox.runCode('print("Hello World!")');
-console.log(result.output); // "Hello World!"
+const result = await sandbox.runCommand('python -c "print(\"Hello World!\")"');
+console.log(result.stdout); // "Hello World!"
 
 // Clean up
 await sandbox.destroy();
@@ -179,9 +179,9 @@ const sandbox = await compute.sandbox.create({
 - `metadata?: Record<string, any>` - Custom metadata
 - `envs?: Record<string, string>` - Environment variables
 - `namespace?: string` - Namespace for organizing sandboxes
-- `name?: string` - Name for the sandbox (enables findOrCreate)
-- `overlays?: SetupOverlayConfig[]` - Template overlays to apply
-- `servers?: ServerStartOptions[]` - Servers to start automatically
+- `name?: string` - Human-readable name for the sandbox
+
+> **Note:** Not every provider honors every option. Support for fields like `name`, `metadata`, and `envs` depends on the underlying provider SDK — some pass them through, some map them to a different field, and some ignore them silently. Check your provider package's README for the exact set of options it respects.
 
 #### `compute.sandbox.getById(sandboxId)`
 
@@ -191,40 +191,8 @@ Get an existing sandbox by ID.
 const sandbox = await compute.sandbox.getById('sandbox-id');
 ```
 
-#### `compute.sandbox.findOrCreate(options)`
-
-Find an existing sandbox by namespace and name, or create a new one.
-
-```typescript
-const sandbox = await compute.sandbox.findOrCreate({
-  namespace: 'my-org',
-  name: 'my-project',
-});
-```
-
-#### `compute.sandbox.find(options)`
-
-Find an existing sandbox by namespace and name (returns null if not found).
-
-```typescript
-const sandbox = await compute.sandbox.find({
-  namespace: 'my-org',
-  name: 'my-project',
-});
-```
-
 ### Sandbox Operations
 
-#### `sandbox.runCode(code, language?)`
-
-Execute code in the sandbox.
-
-```typescript
-const result = await sandbox.runCode('print("Hello")', 'python');
-console.log(result.output); // "Hello"
-console.log(result.exitCode);
-```
-
 #### `sandbox.runCommand(command, options?)`
 
 Run a shell command.
@@ -305,209 +273,6 @@ Remove a file or directory.
 await sandbox.filesystem.remove('/tmp/hello.py');
 ```
 
-### Terminal Operations
-
-The sandbox provides terminal access in two modes: **PTY mode** (interactive shell) and **Exec mode** (command tracking).
-
-#### `sandbox.terminal.create(options?)`
-
-Create a new terminal session.
-
-```typescript
-// PTY mode - Interactive shell
-const pty = await sandbox.terminal.create({ pty: true, shell: '/bin/bash' });
-
-// Exec mode - Command tracking (default)
-const exec = await sandbox.terminal.create({ pty: false });
-```
-
-**Options:**
-- `pty?: boolean` - Terminal mode: `true` = PTY (interactive), `false` = exec (command tracking). Default: `false`
-- `shell?: string` - Shell to use (e.g., '/bin/bash'). PTY mode only
-- `encoding?: 'raw' | 'base64'` - Output encoding. Default: `'raw'`
-
-**Returns:** `TerminalInstance`
-
-#### `sandbox.terminal.list()`
-
-List all active terminals.
-
-```typescript
-const terminals = await sandbox.terminal.list();
-console.log(terminals); // [{ id: 'term-1', pty: true, status: 'running', ... }]
-```
-
-#### `sandbox.terminal.retrieve(id)`
-
-Retrieve a specific terminal by ID.
-
-```typescript
-const terminal = await sandbox.terminal.retrieve('term-123');
-console.log(terminal.id, terminal.status);
-```
-
-#### `sandbox.terminal.destroy(id)`
-
-Destroy a terminal by ID.
-
-```typescript
-await sandbox.terminal.destroy('term-123');
-```
-
-### PTY Mode (Interactive Shell)
-
-PTY mode creates an interactive shell session with real-time input/output over WebSocket.
-
-#### `terminal.write(input)`
-
-Send input to the terminal shell.
-
-```typescript
-const pty = await sandbox.terminal.create({ pty: true });
-pty.on('output', (data) => console.log(data));
-pty.write('ls -la\n');
-pty.write('pwd\n');
-await pty.destroy();
-```
-
-#### `terminal.resize(cols, rows)`
-
-Resize the terminal window.
-
-```typescript
-pty.resize(120, 40);
-```
-
-#### `terminal.on(event, handler)`
-
-Register an event handler. Events: `'output'`, `'error'`, `'destroyed'`.
-
-```typescript
-pty.on('output', (data) => console.log('Output:', data));
-pty.on('error', (error) => console.error('Error:', error));
-pty.on('destroyed', () => console.log('Terminal destroyed'));
-```
-
-#### `terminal.off(event, handler)`
-
-Unregister an event handler.
-
-```typescript
-const handler = (data) => console.log(data);
-pty.on('output', handler);
-pty.off('output', handler);
-```
-
-#### Terminal Properties
-
-```typescript
-console.log(pty.id);       // Terminal ID
-console.log(pty.status);   // 'running' | 'stopped' | 'active' | 'ready'
-console.log(pty.channel);  // WebSocket channel (PTY only)
-console.log(pty.pty);      // true for PTY mode
-```
-
-### Exec Mode (Command Tracking)
-
-Exec mode executes commands with structured result tracking, suitable for automation.
-
-#### `terminal.command.run(command, options?)`
-
-Execute a command in the terminal.
-
-```typescript
-const exec = await sandbox.terminal.create({ pty: false });
-
-// Foreground execution (waits for completion)
-const cmd = await exec.command.run('npm test');
-console.log(cmd.stdout);
-console.log(cmd.stderr);
-console.log(cmd.exitCode);
-
-// Background execution (returns immediately)
-const bgCmd = await exec.command.run('npm install', { background: true });
-console.log(bgCmd.status); // 'running'
-await bgCmd.wait(); // Wait for completion
-console.log(bgCmd.exitCode);
-```
-
-**Parameters:**
-- `command: string` - The command to execute
-- `options?: { background?: boolean }` - Execution options
-
-**Returns:** `Command` object
-
-#### `terminal.command.list()`
-
-List all commands executed in this terminal.
-
-```typescript
-const commands = await exec.command.list();
-commands.forEach(cmd => {
-  console.log(cmd.id, cmd.command, cmd.status, cmd.exitCode);
-});
-```
-
-#### `terminal.command.retrieve(cmdId)`
-
-Retrieve a specific command by ID.
-
-```typescript
-const cmd = await exec.command.retrieve('cmd-123');
-console.log(cmd.stdout);
-```
-
-### Command Object
-
-The `Command` object represents a command execution result.
-
-#### Command Properties
-
-```typescript
-console.log(cmd.id);          // Command ID
-console.log(cmd.terminalId);  // Parent terminal ID
-console.log(cmd.command);     // Executed command
-console.log(cmd.status);      // 'running' | 'completed' | 'failed'
-console.log(cmd.stdout);      // Standard output
-console.log(cmd.stderr);      // Standard error
-console.log(cmd.exitCode);    // Exit code (undefined if running)
-console.log(cmd.durationMs);  // Execution time in milliseconds
-console.log(cmd.startedAt);   // Start timestamp
-console.log(cmd.finishedAt);  // Finish timestamp (undefined if running)
-```
-
-#### `command.wait(timeout?)`
-
-Wait for a background command to complete.
-
-```typescript
-const cmd = await exec.command.run('sleep 5', { background: true });
-await cmd.wait(); // Waits up to default timeout
-console.log(cmd.exitCode);
-
-// With custom timeout (in seconds, 0 = no timeout)
-await cmd.wait(10);
-```
-
-#### `command.refresh()`
-
-Refresh the command status from the server.
-
-```typescript
-const cmd = await exec.command.run('npm build', { background: true });
-// ... later ...
-await cmd.refresh();
-console.log(cmd.status, cmd.exitCode);
-```
-
-#### `terminal.destroy()`
-
-Destroy the terminal and clean up resources.
-
-```typescript
-await exec.destroy();
-```
-
 ## Examples
 
 ### Multi-Step Build Process
@@ -547,93 +312,13 @@ const installResult = await sandbox.runCommand('npm install', { cwd: '/app' });
 console.log('Install:', installResult.stdout);
 
 // Run the app
-const runResult = await sandbox.runCode(`
-const { spawn } = require('child_process');
-const proc = spawn('node', ['src/index.js'], { cwd: '/app' });
-proc.stdout.on('data', (data) => console.log(data.toString()));
-`);
+const runResult = await sandbox.runCommand('node src/index.js', { cwd: '/app' });
 
-console.log(runResult.output);
+console.log(runResult.stdout);
 
 await sandbox.destroy();
 ```
 
-### Terminal Command Execution
-
-```typescript
-import { compute } from 'computesdk';
-
-const sandbox = await compute.sandbox.create();
-
-// Create exec mode terminal for command tracking
-const terminal = await sandbox.terminal.create({ pty: false });
-
-// Run build commands with tracking
-const install = await terminal.command.run('npm install');
-console.log('Install exit code:', install.exitCode);
-
-const build = await terminal.command.run('npm run build');
-console.log('Build output:', build.stdout);
-
-// Run tests in background
-const tests = await terminal.command.run('npm test', { background: true });
-console.log('Tests started:', tests.status);
-
-// Wait for tests to complete
-await tests.wait(60); // 60 second timeout
-console.log('Tests completed:', tests.exitCode === 0 ? 'PASSED' : 'FAILED');
-console.log('Test output:', tests.stdout);
-
-// List all commands
-const commands = await terminal.command.list();
-console.log(`Executed ${commands.length} commands`);
-
-await terminal.destroy();
-await sandbox.destroy();
-```
-
-### Interactive Terminal Session
-
-```typescript
-import { compute } from 'computesdk';
-
-const sandbox = await compute.sandbox.create();
-
-// Create PTY terminal for interactive shell
-const pty = await sandbox.terminal.create({ 
-  pty: true, 
-  shell: '/bin/bash' 
-});
-
-// Collect all output
-let output = '';
-pty.on('output', (data) => {
-  output += data;
-  console.log(data);
-});
-
-pty.on('error', (error) => {
-  console.error('Terminal error:', error);
-});
-
-// Execute interactive commands
-pty.write('echo "Starting project setup"\n');
-pty.write('mkdir -p /workspace/myproject\n');
-pty.write('cd /workspace/myproject\n');
-pty.write('npm init -y\n');
-pty.write('npm install express\n');
-pty.write('echo "Setup complete"\n');
-
-// Wait for operations to complete
-await new Promise(resolve => setTimeout(resolve, 5000));
-
-// Clean up
-await pty.destroy();
-await sandbox.destroy();
-
-console.log('Complete output:', output);
-```
-
 ### Using Different Providers
 
 ```typescript
@@ -647,7 +332,7 @@ compute.setConfig({
 });
 
 const e2bSandbox = await compute.sandbox.create();
-await e2bSandbox.runCode('import pandas as pd; print(pd.__version__)');
+await e2bSandbox.runCommand('python -c "import pandas as pd; print(pd.__version__)"');
 await e2bSandbox.destroy();
 
 // Switch to Modal for GPU workloads
@@ -659,7 +344,7 @@ compute.setConfig({
 });
 
 const modalSandbox = await compute.sandbox.create();
-await modalSandbox.runCode('import torch; print(torch.cuda.is_available())');
+await modalSandbox.runCommand('python -c "import torch; print(torch.cuda.is_available())"');
 await modalSandbox.destroy();
 ```
 
@@ -668,7 +353,7 @@ await modalSandbox.destroy();
 ```typescript
 try {
   const sandbox = await compute.sandbox.create();
-  const result = await sandbox.runCode('invalid python code');
+  const result = await sandbox.runCommand('invalid python code');
 } catch (error) {
   console.error('Execution failed:', error.message);