Add process readiness documentation

Documents new waitForLog() and waitForPort() methods for detecting
process readiness. Updates Commands API reference and Background
Processes guide with practical 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,16 @@ 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>` object with properties and methods:
+- `id` - Unique process identifier
+- `pid` - System process ID
+- `command` - Command that was executed
+- `status` - Current process status
+- `kill(signal?: string)` - Terminate the process
+- `getStatus()` - Get current process status
+- `getLogs()` - Get accumulated logs
+- `waitForLog(pattern, timeout?)` - Wait for log pattern (see [process.waitForLog()](#processwaitforlog))
+- `waitForPort(port, options?)` - Wait for port readiness (see [process.waitForPort()](#processwaitforport))
 
 <TypeScriptExample>
 ```
@@ -213,6 +222,95 @@ console.log('Server logs:', logs);
 ```
 </TypeScriptExample>
 
+### `process.waitForLog()`
+
+Wait for a log pattern to appear in process output. This method checks existing logs first, then streams new output until the pattern is found.
+
+```ts
+const result = await process.waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>
+```
+
+**Parameters**:
+- `pattern` - String to search for or RegExp pattern to match
+- `timeout` (optional) - Maximum time to wait in milliseconds (no timeout by default)
+
+**Returns**: `Promise<WaitForLogResult>` with:
+- `line` - The log line that matched the pattern
+- `match` (optional) - RegExp capture groups if pattern was a RegExp
+
+**Errors**:
+- `ProcessReadyTimeoutError` - Pattern not found within timeout period
+- `ProcessExitedBeforeReadyError` - Process exited before pattern appeared
+
+<TypeScriptExample>
+```
+// Wait for simple string pattern
+const server = await sandbox.startProcess('python -m http.server 8000');
+await server.waitForLog('Serving HTTP');
+console.log('Server is ready');
+
+// Wait with timeout
+const app = await sandbox.startProcess('npm run dev');
+await app.waitForLog('Local: http://localhost:3000', 30000); // 30s timeout
+
+// Use RegExp for pattern matching
+const build = await sandbox.startProcess('npm run build');
+const result = await build.waitForLog(/Built in (\d+)ms/);
+console.log('Matched line:', result.line);
+console.log('Build time:', result.match?.[1]);
+```
+</TypeScriptExample>
+
+### `process.waitForPort()`
+
+Wait for a process to start listening on a port. Supports both HTTP health checks and TCP connection checks.
+
+```ts
+await process.waitForPort(port: number, options?: WaitForPortOptions): Promise<void>
+```
+
+**Parameters**:
+- `port` - Port number to check
+- `options` (optional):
+  - `mode` - Check mode: `'http'` (default) or `'tcp'`
+  - `path` - HTTP path to check (default: `'/'`, only for HTTP mode)
+  - `status` - Expected HTTP status code or range (default: `{ min: 200, max: 399 }`)
+    - Single number: exact match (e.g., `200`)
+    - Object with min/max: range match (e.g., `{ min: 200, max: 299 }`)
+  - `timeout` - Maximum time to wait in milliseconds (no timeout by default)
+  - `interval` - Interval between checks in milliseconds (default: `500`)
+
+**Errors**:
+- `ProcessReadyTimeoutError` - Port not ready within timeout period
+- `ProcessExitedBeforeReadyError` - Process exited before port became ready
+
+<TypeScriptExample>
+```
+// Wait for HTTP endpoint with default settings (200-399 status on /)
+const web = await sandbox.startProcess('npm run dev');
+await web.waitForPort(3000);
+console.log('Web server ready at http://localhost:3000');
+
+// Check specific health endpoint
+const api = await sandbox.startProcess('node api.js');
+await api.waitForPort(8080, {
+  path: '/health',
+  status: 200,
+  timeout: 30000 // 30 second timeout
+});
+
+// TCP-only check (just verify port accepts connections)
+const db = await sandbox.startProcess('redis-server');
+await db.waitForPort(6379, { mode: 'tcp' });
+
+// Wait for specific status code range
+const app = await sandbox.startProcess('python app.py');
+await app.waitForPort(5000, {
+  status: { min: 200, max: 299 } // Only 2xx status codes
+});
+```
+</TypeScriptExample>
+
 ## Related resources
 
 - [Background processes guide](/sandbox/guides/background-processes/) - Managing long-running processes

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

@@ -83,36 +83,55 @@ 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 `waitForPort()` or `waitForLog()` to wait for a process to become ready before proceeding:
 
 <TypeScriptExample>
 ```
-import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
-
+// Wait for HTTP server to be ready
 const server = await sandbox.startProcess('node server.js');
+await server.waitForPort(3000);
+console.log('Server is ready at http://localhost:3000');
+
+// Wait for log pattern
+const app = await sandbox.startProcess('npm run dev');
+await app.waitForLog('Server listening');
+console.log('App is ready');
+
+// Wait with timeout and custom health check
+const api = await sandbox.startProcess('python api.py');
+await api.waitForPort(8080, {
+  path: '/health',
+  timeout: 30000 // 30 seconds
+});
+```
+</TypeScriptExample>
 
-// Stream logs
-const logStream = await sandbox.streamProcessLogs(server.id);
+## Monitor process logs
 
-for await (const log of parseSSEStream<LogEvent>(logStream)) {
-  console.log(log.data);
+Get accumulated logs from a running or completed process:
 
-  if (log.data.includes('Server listening')) {
-    console.log('Server is ready!');
-    break;
-  }
-}
+<TypeScriptExample>
+```
+const logs = await server.getLogs();
+console.log('stdout:', logs.stdout);
+console.log('stderr:', logs.stderr);
 ```
 </TypeScriptExample>
 
-Or get accumulated logs:
+Or stream logs in real-time:
 
 <TypeScriptExample>
 ```
-const logs = await sandbox.getProcessLogs(server.id);
-console.log('Logs:', logs);
+import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
+
+const server = await sandbox.startProcess('node server.js');
+const logStream = await sandbox.streamProcessLogs(server.id);
+
+for await (const log of parseSSEStream<LogEvent>(logStream)) {
+  console.log(log.data);
+}
 ```
 </TypeScriptExample>
 
@@ -137,24 +156,20 @@ 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.waitForPort(6379, { mode: 'tcp' });
 
 // Now start API server (depends on database)
 const api = await sandbox.startProcess('node api-server.js', {
   env: { DATABASE_URL: 'redis://localhost:6379' }
 });
 
+// Wait for API to be ready
+await api.waitForPort(8080, { path: '/health' });
+
 console.log('All services running');
 ```
 </TypeScriptExample>
@@ -165,7 +180,7 @@ By default, containers automatically shut down after 10 minutes of inactivity. F
 
 <TypeScriptExample>
 ```ts
-import { getSandbox, parseSSEStream, type LogEvent } from '@cloudflare/sandbox';
+import { getSandbox } from '@cloudflare/sandbox';
 
 export { Sandbox } from '@cloudflare/sandbox';
 
@@ -180,16 +195,8 @@ export default {
       // Start a long-running build process
       const build = await sandbox.startProcess('npm run build:production');
 
-      // Monitor progress
-      const logs = await sandbox.streamProcessLogs(build.id);
-
-      // Process can run indefinitely without container shutdown
-      for await (const log of parseSSEStream<LogEvent>(logs)) {
-        console.log(log.data);
-        if (log.data.includes('Build complete')) {
-          break;
-        }
-      }
+      // Wait for completion
+      await build.waitForLog('Build complete', 600000); // 10 minute timeout
 
       return new Response('Build completed');
     } finally {
@@ -207,7 +214,8 @@ When using `keepAlive: true`, containers will not automatically timeout. You **m
 
 ## Best practices
 
-- **Wait for readiness** - Stream logs to detect when services are ready
+- **Wait for readiness** - Use `waitForPort()` or `waitForLog()` to detect when services are ready
+- **Set timeouts** - Always specify timeout values to prevent indefinite waiting
 - **Clean up** - Always stop processes when done
 - **Handle failures** - Monitor logs for errors and restart if needed
 - **Use try/finally** - Ensure cleanup happens even on errors