@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/realtimekit/patterns.md

@@ -0,0 +1,223 @@
+# RealtimeKit Patterns
+
+## UI Kit (Minimal Code)
+
+```tsx
+// React
+import { RtkMeeting } from '@cloudflare/realtimekit-react-ui';
+<RtkMeeting authToken="<token>" onLeave={() => console.log('Left')} />
+
+// Angular
+@Component({ template: `<rtk-meeting [authToken]="authToken" (rtkLeave)="onLeave($event)"></rtk-meeting>` })
+export class AppComponent { authToken = '<token>'; onLeave(event: unknown) {} }
+
+// HTML/Web Components
+<script type="module" src="https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui/dist/realtimekit-ui/realtimekit-ui.esm.js"></script>
+<rtk-meeting id="meeting"></rtk-meeting>
+<script>document.getElementById('meeting').authToken = '<token>';</script>
+```
+
+## UI Components
+
+RealtimeKit provides 133+ pre-built Stencil.js Web Components with framework wrappers:
+
+### Layout Components
+- `<RtkMeeting>` - Full meeting UI (all-in-one)
+- `<RtkHeader>`, `<RtkStage>`, `<RtkControlbar>` - Layout sections
+- `<RtkSidebar>` - Chat/participants sidebar
+- `<RtkGrid>` - Adaptive video grid
+
+### Control Components  
+- `<RtkMicToggle>`, `<RtkCameraToggle>` - Media controls
+- `<RtkScreenShareToggle>` - Screen sharing
+- `<RtkLeaveButton>` - Leave meeting
+- `<RtkSettingsModal>` - Device settings
+
+### Grid Variants
+- `<RtkSpotlightGrid>` - Active speaker focus
+- `<RtkAudioGrid>` - Audio-only mode
+- `<RtkPaginatedGrid>` - Paginated layout
+
+**See full catalog**: https://docs.realtime.cloudflare.com/ui-kit
+
+## Core SDK Patterns
+
+### Basic Setup
+```typescript
+import RealtimeKitClient from '@cloudflare/realtimekit';
+
+const meeting = new RealtimeKitClient({ authToken, video: true, audio: true });
+meeting.self.on('roomJoined', () => console.log('Joined:', meeting.meta.meetingTitle));
+meeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined`));
+await meeting.join();
+```
+
+### Video Grid & Device Selection
+```typescript
+// Video grid
+function VideoGrid({ meeting }) {
+  const [participants, setParticipants] = useState([]);
+  useEffect(() => {
+    const update = () => setParticipants(meeting.participants.joined.toArray());
+    meeting.participants.joined.on('participantJoined', update);
+    meeting.participants.joined.on('participantLeft', update);
+    update();
+    return () => { meeting.participants.joined.off('participantJoined', update); meeting.participants.joined.off('participantLeft', update); };
+  }, [meeting]);
+  return <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))' }}>
+    {participants.map(p => <VideoTile key={p.id} participant={p} />)}
+  </div>;
+}
+
+function VideoTile({ participant }) {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  useEffect(() => {
+    if (videoRef.current && participant.videoTrack) videoRef.current.srcObject = new MediaStream([participant.videoTrack]);
+  }, [participant.videoTrack]);
+  return <div><video ref={videoRef} autoPlay playsInline muted /><div>{participant.name}</div></div>;
+}
+
+// Device selection
+const devices = await meeting.self.getAllDevices();
+const switchCamera = (deviceId: string) => {
+  const device = devices.find(d => d.deviceId === deviceId);
+  if (device) await meeting.self.setDevice(device);
+};
+```
+
+## React Hooks (Official)
+
+```typescript
+import { useRealtimeKitClient, useRealtimeKitSelector } from '@cloudflare/realtimekit-react-ui';
+
+function MyComponent() {
+  const [meeting, initMeeting] = useRealtimeKitClient();
+  const audioEnabled = useRealtimeKitSelector(m => m.self.audioEnabled);
+  const participantCount = useRealtimeKitSelector(m => m.participants.joined.size());
+  
+  useEffect(() => { initMeeting({ authToken: '<token>' }); }, []);
+  
+  return <div>
+    <button onClick={() => meeting?.self.enableAudio()}>{audioEnabled ? 'Mute' : 'Unmute'}</button>
+    <span>{participantCount} participants</span>
+  </div>;
+}
+```
+
+**Benefits:** Automatic re-renders, memoized selectors, type-safe
+
+## Waitlist Handling
+
+```typescript
+// Monitor waitlist
+meeting.participants.waitlisted.on('participantJoined', (participant) => {
+  console.log(`${participant.name} is waiting`);
+  // Show admin UI to approve/reject
+});
+
+// Approve from waitlist (backend only)
+await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${accountId}/realtime/kit/${appId}/meetings/${meetingId}/active-session/waitlist/approve`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${apiToken}` },
+    body: JSON.stringify({ user_ids: [participant.userId] })
+  }
+);
+
+// Client receives automatic transition when approved
+meeting.self.on('roomJoined', () => console.log('Approved and joined'));
+```
+
+## Audio-Only Mode
+
+```typescript
+const meeting = new RealtimeKitClient({
+  authToken: '<token>',
+  video: false,  // Disable video
+  audio: true,
+  mediaConfiguration: {
+    audio: {
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true
+    }
+  }
+});
+
+// Use audio grid component
+import { RtkAudioGrid } from '@cloudflare/realtimekit-react-ui';
+<RtkAudioGrid meeting={meeting} />
+```
+
+## Addon System
+
+```typescript
+// List available addons
+meeting.plugins.all.forEach(plugin => {
+  console.log(plugin.id, plugin.name, plugin.active);
+});
+
+// Activate collaborative app
+await meeting.plugins.activate('whiteboard-addon-id');
+
+// Listen for activations
+meeting.plugins.on('pluginActivated', ({ plugin }) => {
+  console.log(`${plugin.name} activated`);
+});
+
+// Deactivate
+await meeting.plugins.deactivate();
+```
+
+## Backend Integration
+
+### Token Generation (Workers)
+```typescript
+export interface Env { CLOUDFLARE_API_TOKEN: string; CLOUDFLARE_ACCOUNT_ID: string; REALTIMEKIT_APP_ID: string; }
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    
+    if (url.pathname === '/api/join-meeting') {
+      const { meetingId, userName, presetName } = await request.json();
+      const response = await fetch(
+        `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/realtime/kit/${env.REALTIMEKIT_APP_ID}/meetings/${meetingId}/participants`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${env.CLOUDFLARE_API_TOKEN}` },
+          body: JSON.stringify({ name: userName, preset_name: presetName })
+        }
+      );
+      const data = await response.json();
+      return Response.json({ authToken: data.result.authToken });
+    }
+    
+    return new Response('Not found', { status: 404 });
+  }
+};
+```
+
+## Best Practices
+
+### Security
+1. **Never expose API tokens client-side** - Generate participant tokens server-side only
+2. **Don't reuse participant tokens** - Generate fresh token per session, use refresh endpoint if expired
+3. **Use custom participant IDs** - Map to your user system for cross-session tracking
+
+### Performance
+1. **Event-driven updates** - Listen to events, don't poll. Use `toArray()` only when needed
+2. **Media quality constraints** - Set appropriate resolution/bitrate limits based on network conditions
+3. **Device management** - Enable `autoSwitchAudioDevice` for better UX, handle device list updates
+
+### Architecture
+1. **Separate Apps for environments** - staging vs production to prevent data mixing
+2. **Preset strategy** - Create presets at App level, reuse across meetings
+3. **Token management** - Backend generates tokens, frontend receives via authenticated endpoint
+
+## In This Reference
+- [README.md](README.md) - Overview, core concepts, quick start
+- [configuration.md](configuration.md) - SDK config, presets, wrangler setup
+- [api.md](api.md) - Client SDK APIs, REST endpoints
+- [gotchas.md](gotchas.md) - Common issues, troubleshooting, limits

package/skills/cloudflare-deploy/references/sandbox/README.md

@@ -0,0 +1,96 @@
+# Cloudflare Sandbox SDK
+
+Secure isolated code execution in containers on Cloudflare's edge. Run untrusted code, manage files, expose services, integrate with AI agents.
+
+**Use cases**: AI code execution, interactive dev environments, data analysis, CI/CD, code interpreters, multi-tenant execution.
+
+## Architecture
+
+- Each sandbox = Durable Object + Container
+- Persistent across requests (same ID = same sandbox)
+- Isolated filesystem/processes/network
+- Configurable sleep/wake for cost optimization
+
+## Quick Start
+
+```typescript
+import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
+export { Sandbox } from '@cloudflare/sandbox';
+
+type Env = { Sandbox: DurableObjectNamespace<Sandbox>; };
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // CRITICAL: proxyToSandbox MUST be called first for preview URLs
+    const proxyResponse = await proxyToSandbox(request, env);
+    if (proxyResponse) return proxyResponse;
+
+    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
+    const result = await sandbox.exec('python3 -c "print(2 + 2)"');
+    return Response.json({ output: result.stdout });
+  }
+};
+```
+
+**wrangler.jsonc**:
+```jsonc
+{
+  "name": "my-sandbox-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  
+  "containers": [{
+    "class_name": "Sandbox",
+    "image": "./Dockerfile",
+    "instance_type": "lite",        // lite | standard | heavy
+    "max_instances": 5
+  }],
+  
+  "durable_objects": {
+    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
+  },
+  
+  "migrations": [{
+    "tag": "v1",
+    "new_sqlite_classes": ["Sandbox"]
+  }]
+}
+```
+
+**Dockerfile**:
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+RUN pip3 install --no-cache-dir pandas numpy matplotlib
+EXPOSE 8080 3000  # Required for wrangler dev
+```
+
+## Core APIs
+
+- `getSandbox(namespace, id, options?)` → Get/create sandbox
+- `sandbox.exec(command, options?)` → Execute command
+- `sandbox.readFile(path)` / `writeFile(path, content)` → File ops
+- `sandbox.startProcess(command, options)` → Background process
+- `sandbox.exposePort(port, options)` → Get preview URL
+- `sandbox.createSession(options)` → Isolated session
+- `sandbox.wsConnect(request, port)` → WebSocket proxy
+- `sandbox.destroy()` → Terminate container
+- `sandbox.mountBucket(bucket, path, options)` → Mount S3 storage
+
+## Critical Rules
+
+- ALWAYS call `proxyToSandbox()` first
+- Same ID = reuse sandbox
+- Use `/workspace` for persistent files
+- `normalizeId: true` for preview URLs
+- Retry on `CONTAINER_NOT_READY`
+
+## In This Reference
+- [configuration.md](./configuration.md) - Config, CLI, environment setup
+- [api.md](./api.md) - Programmatic API, testing patterns
+- [patterns.md](./patterns.md) - Common workflows, CI/CD integration
+- [gotchas.md](./gotchas.md) - Issues, limits, best practices
+
+## See Also
+- [durable-objects](../durable-objects/) - Sandbox runs on DO infrastructure
+- [containers](../containers/) - Container runtime fundamentals
+- [workers](../workers/) - Entry point for sandbox requests

package/skills/cloudflare-deploy/references/sandbox/api.md

@@ -0,0 +1,198 @@
+# API Reference
+
+## Command Execution
+
+```typescript
+// Basic
+const result = await sandbox.exec('python3 script.py');
+// Returns: { stdout, stderr, exitCode, success, duration }
+
+// With options
+await sandbox.exec('python3 test.py', {
+  cwd: '/workspace/project',
+  env: { API_KEY: 'secret' },
+  stream: true,
+  onOutput: (stream, data) => console.log(data)
+});
+```
+
+## File Operations
+
+```typescript
+// Read/Write
+const { content } = await sandbox.readFile('/workspace/data.txt');
+await sandbox.writeFile('/workspace/file.txt', 'content');  // Auto-creates dirs
+
+// List/Delete
+const files = await sandbox.listFiles('/workspace');
+await sandbox.deleteFile('/workspace/temp.txt');
+await sandbox.deleteFile('/workspace/dir', { recursive: true });
+
+// Utils
+await sandbox.mkdir('/workspace/dir', { recursive: true });
+await sandbox.pathExists('/workspace/file.txt');
+```
+
+## Background Processes
+
+```typescript
+// Start
+const process = await sandbox.startProcess('python3 -m http.server 8080', {
+  processId: 'web-server',
+  cwd: '/workspace/public',
+  env: { PORT: '8080' }
+});
+// Returns: { id, pid, command }
+
+// Wait for readiness
+await process.waitForPort(8080);  // Wait for port to listen
+await process.waitForLog(/Server running/);  // Wait for log pattern
+await process.waitForExit();  // Wait for completion
+
+// Management
+const processes = await sandbox.listProcesses();
+const info = await sandbox.getProcess('web-server');
+await sandbox.stopProcess('web-server');
+const logs = await sandbox.getProcessLogs('web-server');
+```
+
+## Port Exposure
+
+```typescript
+// Expose port
+const { url } = await sandbox.exposePort(8080, {
+  name: 'web-app',
+  hostname: request.hostname
+});
+
+// Management
+await sandbox.isPortExposed(8080);
+await sandbox.getExposedPorts(request.hostname);
+await sandbox.unexposePort(8080);
+```
+
+## Sessions (Isolated Contexts)
+
+Each session maintains own shell state, env vars, cwd, process namespace.
+
+```typescript
+// Create with context
+const session = await sandbox.createSession({
+  id: 'user-123',
+  cwd: '/workspace/user123',
+  env: { USER_ID: '123' }
+});
+
+// Use (full sandbox API)
+await session.exec('echo $USER_ID');
+await session.writeFile('config.txt', 'data');
+
+// Manage
+await sandbox.getSession('user-123');
+await sandbox.deleteSession('user-123');
+```
+
+## Code Interpreter
+
+```typescript
+// Create context with variables
+const ctx = await sandbox.createCodeContext({
+  language: 'python',
+  variables: {
+    data: [1, 2, 3, 4, 5],
+    config: { verbose: true }
+  }
+});
+
+// Execute code with rich outputs
+const result = await ctx.runCode(`
+import matplotlib.pyplot as plt
+plt.plot(data, [x**2 for x in data])
+plt.savefig('plot.png')
+print(f"Processed {len(data)} points")
+`);
+// Returns: { outputs: [{ type: 'text'|'image'|'html', content }], error }
+
+// Context persists variables across runs
+const result2 = await ctx.runCode('print(data[0])');  // Still has 'data'
+```
+
+## WebSocket Connections
+
+```typescript
+// Proxy WebSocket to sandbox service
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const proxyResponse = await proxyToSandbox(request, env);
+    if (proxyResponse) return proxyResponse;
+
+    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
+      const sandbox = getSandbox(env.Sandbox, 'realtime');
+      return await sandbox.wsConnect(request, 8080);
+    }
+    
+    return new Response('Not a WebSocket request', { status: 400 });
+  }
+};
+```
+
+## Bucket Mounting (S3 Storage)
+
+```typescript
+// Mount R2 bucket (production only, not wrangler dev)
+await sandbox.mountBucket(env.DATA_BUCKET, '/data', {
+  readOnly: false
+});
+
+// Access files in mounted bucket
+await sandbox.exec('ls /data');
+await sandbox.writeFile('/data/output.txt', 'result');
+
+// Unmount
+await sandbox.unmountBucket('/data');
+```
+
+**Note**: Bucket mounting only works in production. Mounted buckets are sandbox-scoped (visible to all sessions in that sandbox).
+
+## Lifecycle Management
+
+```typescript
+// Terminate container immediately
+await sandbox.destroy();
+
+// REQUIRED when using keepAlive: true
+const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true });
+try {
+  await sandbox.writeFile('/tmp/code.py', code);
+  const result = await sandbox.exec('python /tmp/code.py');
+  return result.stdout;
+} finally {
+  await sandbox.destroy();  // Free resources
+}
+```
+
+Deletes: files, processes, sessions, network connections, exposed ports.
+
+## Error Handling
+
+```typescript
+// Command errors
+const result = await sandbox.exec('python3 invalid.py');
+if (!result.success) {
+  console.error('Exit code:', result.exitCode);
+  console.error('Stderr:', result.stderr);
+}
+
+// SDK errors
+try {
+  await sandbox.readFile('/nonexistent');
+} catch (error) {
+  if (error.code === 'FILE_NOT_FOUND') { /* ... */ }
+  else if (error.code === 'CONTAINER_NOT_READY') { /* retry */ }
+  else if (error.code === 'TIMEOUT') { /* ... */ }
+}
+
+// Retry pattern (see gotchas.md for full implementation)
+```
+
+

package/skills/cloudflare-deploy/references/sandbox/configuration.md

@@ -0,0 +1,143 @@
+# Configuration
+
+## getSandbox Options
+
+```typescript
+const sandbox = getSandbox(env.Sandbox, 'sandbox-id', {
+  normalizeId: true,         // lowercase ID (required for preview URLs)
+  sleepAfter: '10m',         // sleep after inactivity: '5m', '1h', '2d' (default: '10m')
+  keepAlive: false,          // false = auto-timeout, true = never sleep
+  
+  containerTimeouts: {
+    instanceGetTimeoutMS: 30000,  // 30s for provisioning (default: 30000)
+    portReadyTimeoutMS: 90000     // 90s for container startup (default: 90000)
+  }
+});
+```
+
+**Sleep Config**:
+- `sleepAfter`: Duration string (e.g., '5m', '10m', '1h') - default: '10m'
+- `keepAlive: false`: Auto-sleep (default, cost-optimized)
+- `keepAlive: true`: Never sleep (higher cost, requires explicit `destroy()`)
+- Sleeping sandboxes wake automatically (cold start)
+
+## Instance Types
+
+wrangler.jsonc `instance_type`:
+- `lite`: 256MB RAM, 0.5 vCPU (default)
+- `standard`: 512MB RAM, 1 vCPU
+- `heavy`: 1GB RAM, 2 vCPU
+
+## Dockerfile Patterns
+
+**Basic**:
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+RUN pip3 install --no-cache-dir pandas numpy
+EXPOSE 8080  # Required for wrangler dev
+```
+
+**Scientific**:
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+RUN pip3 install --no-cache-dir \
+    jupyter-server ipykernel matplotlib \
+    pandas seaborn plotly scipy scikit-learn
+```
+
+**Node.js**:
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+RUN npm install -g typescript ts-node
+```
+
+**CRITICAL**: `EXPOSE` required for `wrangler dev` port access. Production auto-exposes all ports.
+
+## CLI Commands
+
+```bash
+# Dev
+wrangler dev                    # Start local dev server
+wrangler deploy                 # Deploy to production
+wrangler tail                   # Monitor logs
+wrangler containers list        # Check container status
+wrangler secret put KEY         # Set secret
+```
+
+## Environment & Secrets
+
+**wrangler.jsonc**:
+```jsonc
+{
+  "vars": {
+    "ENVIRONMENT": "production",
+    "API_URL": "https://api.example.com"
+  },
+  "r2_buckets": [{
+    "binding": "DATA_BUCKET",
+    "bucket_name": "my-data-bucket"
+  }]
+}
+```
+
+**Usage**:
+```typescript
+const token = env.GITHUB_TOKEN;  // From wrangler secret
+await sandbox.exec('git clone ...', {
+  env: { GIT_TOKEN: token }
+});
+```
+
+## Preview URL Setup
+
+**Prerequisites**:
+- Custom domain with wildcard DNS: `*.yourdomain.com → worker.yourdomain.com`
+- `.workers.dev` domains NOT supported
+- `normalizeId: true` in getSandbox
+- `proxyToSandbox()` called first in fetch handler
+
+## Cron Triggers (Pre-warming)
+
+```jsonc
+{
+  "triggers": {
+    "crons": ["*/5 * * * *"]  // Every 5 minutes
+  }
+}
+```
+
+```typescript
+export default {
+  async scheduled(event: ScheduledEvent, env: Env) {
+    const sandbox = getSandbox(env.Sandbox, 'main');
+    await sandbox.exec('echo "keepalive"');  // Wake sandbox
+  }
+};
+```
+
+## Logging Configuration
+
+**wrangler.jsonc**:
+```jsonc
+{
+  "vars": {
+    "SANDBOX_LOG_LEVEL": "debug",  // debug | info | warn | error (default: info)
+    "SANDBOX_LOG_FORMAT": "pretty" // json | pretty (default: json)
+  }
+}
+```
+
+**Dev**: `debug` + `pretty`. **Production**: `info`/`warn` + `json`.
+
+## Timeout Environment Overrides
+
+Override default timeouts via environment variables:
+
+```jsonc
+{
+  "vars": {
+    "SANDBOX_INSTANCE_TIMEOUT_MS": "60000",  // Override instanceGetTimeoutMS
+    "SANDBOX_PORT_TIMEOUT_MS": "120000"      // Override portReadyTimeoutMS
+  }
+}
+```