Document process readiness feature

Add documentation for new waitForLog() and waitForPort() methods added
to the Process interface. These methods allow users to wait for
processes to become ready before continuing execution.

Changes:
- Add Process method reference documentation in commands.mdx
- Update background-processes guide with readiness checking examples
- Show error handling for ProcessReadyTimeoutError
- Demonstrate regex pattern matching for log analysis
- Include timeout configuration examples

Related to cloudflare/sandbox-sdk#273

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: github-actions[bot]

src/content/docs/sandbox/api/commands.mdx

@@ -87,7 +87,7 @@ for await (const event of parseSSEStream<ExecEvent>(stream)) {
 Start a long-running background process.
 
 ```ts
-const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<ProcessInfo>
+const process = await sandbox.startProcess(command: string, options?: ProcessOptions): Promise<Process>
 ```
 
 **Parameters**:
@@ -96,7 +96,7 @@ const process = await sandbox.startProcess(command: string, options?: ProcessOpt
   - `cwd` - Working directory
   - `env` - Environment variables
 
-**Returns**: `Promise<ProcessInfo>` with `id`, `pid`, `command`, `status`
+**Returns**: `Promise<Process>` with `id`, `pid`, `command`, `status`, and methods for process management
 
 <TypeScriptExample>
 ```
@@ -111,6 +111,143 @@ const app = await sandbox.startProcess('node app.js', {
 ```
 </TypeScriptExample>
 
+## Process methods
+
+The `Process` object returned by `startProcess()` provides methods for managing the process lifecycle and checking readiness.
+
+### `process.waitForLog()`
+
+Wait for a log pattern to appear in process output. Useful for detecting when a service is ready.
+
+```ts
+const result = await process.waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>
+```
+
+**Parameters**:
+- `pattern` - String to match or RegExp pattern
+- `timeout` (optional) - Maximum wait time in milliseconds
+
+**Returns**: `Promise<WaitForLogResult>` with `line` (matching line) and `match` (regex captures if using RegExp)
+
+**Throws**:
+- `ProcessReadyTimeoutError` - Pattern not found within timeout
+- `ProcessExitedBeforeReadyError` - Process exited before pattern appeared
+
+<TypeScriptExample>
+```
+// String pattern matching
+const server = await sandbox.startProcess('npm run dev');
+await server.waitForLog('Server listening on port 3000');
+console.log('Server is ready!');
+
+// Regex pattern with timeout
+const result = await server.waitForLog(/listening on port (\d+)/, 30000);
+console.log('Port:', result.match[1]); // Extract port from regex capture
+
+// Error handling
+import { ProcessReadyTimeoutError } from '@cloudflare/sandbox';
+
+try {
+  await server.waitForLog('Ready', 5000);
+} catch (error) {
+  if (error instanceof ProcessReadyTimeoutError) {
+    console.error('Server did not start within 5 seconds');
+    const logs = await server.getLogs();
+    console.error('Logs:', logs.stdout);
+  }
+}
+```
+</TypeScriptExample>
+
+### `process.waitForPort()`
+
+Wait for a port to accept TCP connections. Useful for ensuring network services are ready.
+
+```ts
+await process.waitForPort(port: number, timeout?: number): Promise<void>
+```
+
+**Parameters**:
+- `port` - Port number to check
+- `timeout` (optional) - Maximum wait time in milliseconds
+
+**Throws**:
+- `ProcessReadyTimeoutError` - Port did not become ready within timeout
+- `ProcessExitedBeforeReadyError` - Process exited before port opened
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js');
+
+// Wait for port to be ready
+await server.waitForPort(8080, 10000);
+console.log('Server is accepting connections on port 8080');
+
+// Make requests to the service
+const response = await fetch('http://localhost:8080/health');
+```
+</TypeScriptExample>
+
+### `process.getLogs()`
+
+Get accumulated logs from the process.
+
+```ts
+const logs = await process.getLogs(): Promise<{ stdout: string; stderr: string }>
+```
+
+**Returns**: `Promise` with `stdout` and `stderr` strings
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js');
+const logs = await server.getLogs();
+console.log('Output:', logs.stdout);
+console.log('Errors:', logs.stderr);
+```
+</TypeScriptExample>
+
+### `process.getStatus()`
+
+Get refreshed process status.
+
+```ts
+const status = await process.getStatus(): Promise<ProcessStatus>
+```
+
+**Returns**: `Promise<ProcessStatus>` - One of: `'starting'`, `'running'`, `'completed'`, `'failed'`, `'killed'`, `'error'`
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js');
+const status = await server.getStatus();
+
+if (status === 'running') {
+  console.log('Process is still running');
+}
+```
+</TypeScriptExample>
+
+### `process.kill()`
+
+Terminate the process.
+
+```ts
+await process.kill(signal?: string): Promise<void>
+```
+
+**Parameters**:
+- `signal` (optional) - Signal to send (default: `'SIGTERM'`)
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js');
+await server.kill(); // Graceful shutdown
+// or
+await server.kill('SIGKILL'); // Force kill
+```
+</TypeScriptExample>
+
 ### `listProcesses()`
 
 List all running processes.

src/content/docs/sandbox/guides/background-processes.mdx

@@ -83,24 +83,76 @@ const isRunning = processes.some(p => p.id === processId && p.status === 'runnin
 ```
 </TypeScriptExample>
 
-## Monitor process logs
+## Wait for process readiness
 
-Stream logs in real-time to detect when a service is ready:
+Use `waitForLog()` to detect when a service is ready by matching log output:
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js');
+
+// Wait for specific log message
+await server.waitForLog('Server listening on port 3000');
+console.log('Server is ready!');
+
+// Or use regex to extract information
+const result = await server.waitForLog(/listening on port (\d+)/);
+console.log('Server started on port', result.match[1]);
+```
+</TypeScriptExample>
+
+For network services, use `waitForPort()` to wait for a port to accept connections:
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('python -m http.server 8000');
+
+// Wait for port to be ready
+await server.waitForPort(8000);
+console.log('Server is accepting connections');
+
+// Now safe to make requests
+const response = await fetch('http://localhost:8000');
+```
+</TypeScriptExample>
+
+### Set timeouts for readiness checks
+
+Specify a timeout to avoid waiting indefinitely:
+
+<TypeScriptExample>
+```
+import { ProcessReadyTimeoutError } from '@cloudflare/sandbox';
+
+try {
+  // Wait up to 30 seconds
+  await server.waitForLog('Ready', 30000);
+} catch (error) {
+  if (error instanceof ProcessReadyTimeoutError) {
+    console.error('Server did not start in time');
+    const logs = await server.getLogs();
+    console.error('Last output:', logs.stdout);
+  }
+}
+```
+</TypeScriptExample>
+
+### Manual log monitoring
+
+For advanced scenarios, stream logs directly:
 
 <TypeScriptExample>
 ```
 import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
 
 const server = await sandbox.startProcess('node server.js');
-
-// Stream logs
 const logStream = await sandbox.streamProcessLogs(server.id);
 
 for await (const log of parseSSEStream<LogEvent>(logStream)) {
   console.log(log.data);
 
+  // Custom readiness logic
   if (log.data.includes('Server listening')) {
-    console.log('Server is ready!');
     break;
   }
 }
@@ -111,8 +163,9 @@ Or get accumulated logs:
 
 <TypeScriptExample>
 ```
-const logs = await sandbox.getProcessLogs(server.id);
-console.log('Logs:', logs);
+const logs = await server.getLogs();
+console.log('Output:', logs.stdout);
+console.log('Errors:', logs.stderr);
 ```
 </TypeScriptExample>
 
@@ -137,25 +190,21 @@ Start services in sequence, waiting for dependencies:
 
 <TypeScriptExample>
 ```
-import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
-
 // Start database first
 const db = await sandbox.startProcess('redis-server');
 
 // Wait for database to be ready
-const dbLogs = await sandbox.streamProcessLogs(db.id);
-for await (const log of parseSSEStream<LogEvent>(dbLogs)) {
-  if (log.data.includes('Ready to accept connections')) {
-    break;
-  }
-}
+await db.waitForLog('Ready to accept connections');
+console.log('Database is ready');
 
 // Now start API server (depends on database)
 const api = await sandbox.startProcess('node api-server.js', {
   env: { DATABASE_URL: 'redis://localhost:6379' }
 });
 
-console.log('All services running');
+// Wait for API to be ready
+await api.waitForPort(3000);
+console.log('API server is accepting connections');
 ```
 </TypeScriptExample>