@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/cloudflare/references/realtimekit/gotchas.md

@@ -0,0 +1,172 @@
+# RealtimeKit Gotchas & Troubleshooting
+
+## Common Issues
+
+### Issue: Cannot connect to meeting
+**Causes**:
+- Auth token invalid or expired
+- API credentials lack correct permissions
+- Network blocks WebRTC traffic (firewall/proxy)
+
+**Solutions**:
+- Verify token validity
+- Check API token has **Realtime / Realtime Admin** permissions
+- Enable TURN service for restrictive networks
+
+### Issue: No video/audio tracks
+**Causes**:
+- Browser permissions not granted
+- `video: true, audio: true` not set in initialization
+- Device in use by another app
+- Device not available
+
+**Solutions**:
+- Request browser permissions explicitly
+- Verify initialization config
+- Use `meeting.self.getAllDevices()` to debug device availability
+- Close other apps using the device
+
+### Issue: Participant count mismatched
+**Cause**: `meeting.participants` doesn't include `meeting.self`
+
+**Solution**: Total count = `meeting.participants.joined.size() + 1`
+
+### Issue: Events not firing
+**Causes**:
+- Event listeners registered after actions occur
+- Incorrect event name spelling
+- Wrong namespace (e.g., `meeting.self` vs `meeting.participants`)
+
+**Solutions**:
+- Register listeners before calling `meeting.join()`
+- Check event names against API documentation
+- Verify correct namespace for events
+
+### Issue: CORS errors in API calls
+**Cause**: Making REST API calls from client-side
+
+**Solution**: All REST API calls **must** be server-side (Workers, backend). Never expose API tokens to clients.
+
+### Issue: Preset not applying
+**Causes**:
+- Preset doesn't exist in App
+- `preset_name` doesn't match exactly (case-sensitive)
+- Participant created before preset
+
+**Solutions**:
+- Verify preset exists via Dashboard or API
+- Check exact spelling and case
+- Create preset before adding participants
+
+### Issue: Token reuse errors
+**Cause**: Reusing participant tokens across sessions
+
+**Solution**: Generate fresh token per session. Use refresh endpoint if token expires during session.
+
+### Issue: Video quality poor
+**Causes**:
+- Network bandwidth insufficient
+- Resolution/bitrate too high for connection
+- CPU overload
+
+**Solutions**:
+- Lower `mediaConfiguration.video` resolution/frameRate
+- Monitor network conditions
+- Reduce participant count or grid size
+
+### Issue: Echo or audio feedback
+**Cause**: Multiple devices picking up same audio source
+
+**Solutions**:
+- Enable `echoCancellation: true` in `mediaConfiguration.audio`
+- Use headphones
+- Mute when not speaking
+
+### Issue: Screen share not working
+**Causes**:
+- Browser doesn't support screen sharing API
+- Permission denied by user
+- Wrong `displaySurface` configuration
+
+**Solutions**:
+- Use Chrome/Edge/Firefox (Safari limited support)
+- Check browser permissions
+- Try different `displaySurface` values ('window', 'monitor', 'browser')
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Max participants per session | 100 |
+| Max concurrent sessions per App | 1000 |
+| Max recording duration | 6 hours |
+| Max meeting duration | 24 hours |
+| Max chat message length | 4000 characters |
+| Max preset name length | 64 characters |
+| Max meeting title length | 256 characters |
+| Max participant name length | 256 characters |
+| Token expiration | 24 hours (default) |
+| WebRTC ports required | UDP 1024-65535 |
+
+## Network Requirements
+
+### Firewall Rules
+Allow outbound UDP/TCP to:
+- `*.cloudflare.com` ports 443, 80
+- UDP ports 1024-65535 (WebRTC media)
+
+### TURN Service
+Enable for users behind restrictive firewalls/proxies:
+```jsonc
+// wrangler.jsonc
+{
+  "vars": {
+    "TURN_SERVICE_ID": "your_turn_service_id"
+  }
+  // Set secret: wrangler secret put TURN_SERVICE_TOKEN
+}
+```
+
+TURN automatically configured in SDK when enabled in account.
+
+## Debugging Tips
+
+```typescript
+// Check devices
+const devices = await meeting.self.getAllDevices();
+meeting.self.on('deviceListUpdate', ({ added, removed, devices }) => console.log('Devices:', { added, removed, devices }));
+
+// Monitor participants
+meeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined:`, { id: p.id, userId: p.userId, audioEnabled: p.audioEnabled, videoEnabled: p.videoEnabled }));
+
+// Check room state
+meeting.self.on('roomJoined', () => console.log('Room:', { meetingId: meeting.meta.meetingId, meetingTitle: meeting.meta.meetingTitle, participantCount: meeting.participants.joined.size() + 1, audioEnabled: meeting.self.audioEnabled, videoEnabled: meeting.self.videoEnabled }));
+
+// Log all events
+['roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'].forEach(event => meeting.self.on(event, (data) => console.log(`[self] ${event}:`, data)));
+['participantJoined', 'participantLeft'].forEach(event => meeting.participants.joined.on(event, (data) => console.log(`[participants] ${event}:`, data)));
+meeting.chat.on('chatUpdate', (data) => console.log('[chat] chatUpdate:', data));
+```
+
+## Security & Performance
+
+### Security: Do NOT
+- Expose `CLOUDFLARE_API_TOKEN` in client code, hardcode credentials in frontend
+- Reuse participant tokens, store tokens in localStorage without encryption
+- Allow client-side meeting creation
+
+### Security: DO
+- Generate tokens server-side only, use HTTPS, implement rate limiting
+- Validate user auth before generating tokens, use `custom_participant_id` to map to your user system
+- Set appropriate preset permissions per user role, rotate API tokens regularly
+
+### Performance
+- **CPU**: Lower video resolution/frameRate, disable video for audio-only, use `meeting.participants.active` for large meetings, implement virtual scrolling
+- **Bandwidth**: Set max resolution in `mediaConfiguration`, disable screenshare audio if unneeded, use audio-only mode, implement adaptive bitrate
+- **Memory**: Clean up event listeners on unmount, call `meeting.leave()` when done, don't store large participant arrays
+
+## 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
+- [patterns.md](./patterns.md) - Common patterns, React hooks, backend integration

package/dist/template/.opencode/skill/cloudflare/references/realtimekit/patterns.md

@@ -0,0 +1,155 @@
+# 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>
+```
+
+## 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 (React)
+```typescript
+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 & Chat
+```typescript
+// Device selection
+const devices = await meeting.self.getAllDevices();
+const audioInputs = devices.filter(d => d.kind === 'audioinput');
+const videoInputs = devices.filter(d => d.kind === 'videoinput');
+meeting.self.on('deviceListUpdate', ({ added, removed }) => console.log('Devices:', { added, removed }));
+const switchCamera = (deviceId: string) => { const d = devices.find(x => x.deviceId === deviceId); if (d) await meeting.self.setDevice(d); };
+
+// Chat component
+function ChatComponent({ meeting }) {
+  const [messages, setMessages] = useState(meeting.chat.messages);
+  const [input, setInput] = useState('');
+  useEffect(() => {
+    const handleUpdate = ({ messages }) => setMessages(messages);
+    meeting.chat.on('chatUpdate', handleUpdate);
+    return () => meeting.chat.off('chatUpdate', handleUpdate);
+  }, [meeting]);
+  const send = async () => { if (input.trim()) { await meeting.chat.sendTextMessage(input); setInput(''); } };
+  return <div><div>{messages.map((msg, i) => <div key={i}><strong>{msg.senderName}:</strong> {msg.text}</div>)}</div><input value={input} onChange={e => setInput(e.target.value)} onKeyPress={e => e.key === 'Enter' && send()} /><button onClick={send}>Send</button></div>;
+}
+
+// Custom hook
+export function useMeeting(authToken: string) {
+  const [meeting, setMeeting] = useState<RealtimeKitClient | null>(null);
+  const [joined, setJoined] = useState(false);
+  const [participants, setParticipants] = useState([]);
+  useEffect(() => {
+    const client = new RealtimeKitClient({ authToken });
+    client.self.on('roomJoined', () => setJoined(true));
+    const update = () => setParticipants(client.participants.joined.toArray());
+    client.participants.joined.on('participantJoined', update);
+    client.participants.joined.on('participantLeft', update);
+    setMeeting(client);
+    return () => { client.leave(); };
+  }, [authToken]);
+  return { meeting, joined, participants, join: async () => meeting?.join(), leave: async () => meeting?.leave() };
+}
+```
+
+## Backend Integration
+
+### Token Generation (Express)
+```typescript
+app.post('/api/join-meeting', async (req, res) => {
+  const { meetingId, userName, presetName } = req.body;
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${process.env.ACCOUNT_ID}/realtime/kit/${process.env.APP_ID}/meetings/${meetingId}/participants`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.CLOUDFLARE_API_TOKEN}` },
+      body: JSON.stringify({ name: userName, preset_name: presetName, custom_participant_id: req.user.id })
+    }
+  );
+  const data = await response.json();
+  res.json({ authToken: data.result.authToken });
+});
+```
+
+### Workers Integration
+```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> {
+    if (new URL(request.url).pathname === '/api/create-meeting') {
+      return fetch(`https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/realtime/kit/${env.REALTIMEKIT_APP_ID}/meetings`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${env.CLOUDFLARE_API_TOKEN}` },
+        body: JSON.stringify({ title: 'Team Meeting' })
+      });
+    }
+    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/dist/template/.opencode/skill/cloudflare/references/sandbox/README.md

@@ -0,0 +1,90 @@
+# 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": "2024-01-01",
+  
+  "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
+
+## 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`
+
+## Resources
+
+- [Configuration](./configuration.md) - Config, CLI, environment
+- [API Reference](./api.md) - Programmatic API, testing
+- [Patterns](./patterns.md) - Common workflows, CI/CD
+- [Gotchas](./gotchas.md) - Issues, limits, best practices
+- [Official Docs](https://developers.cloudflare.com/sandbox/)

package/dist/template/.opencode/skill/cloudflare/references/sandbox/api.md

@@ -0,0 +1,178 @@
+# API Reference
+
+## Command Execution
+
+```typescript
+// Basic
+const result = await sandbox.exec('python3 script.py');
+// Returns: { stdout, stderr, exitCode, success, duration }
+
+// Streaming
+await sandbox.exec('npm install', {
+  stream: true,
+  onOutput: (stream, data) => console.log(`[${stream}]`, data),
+  onComplete: (result) => console.log('Exit:', result.exitCode),
+  onError: (error) => console.error(error)
+});
+
+// With env & cwd
+await sandbox.exec('python3 test.py', {
+  cwd: '/workspace/project',
+  env: { API_KEY: 'secret', DEBUG: 'true' }
+});
+```
+
+## File Operations
+
+```typescript
+// Read
+const file = await sandbox.readFile('/workspace/data.txt');
+// Returns: { content, path }
+
+// Write (creates dirs automatically)
+await sandbox.writeFile('/workspace/deep/nested/file.txt', 'content');
+
+// List
+const files = await sandbox.listFiles('/workspace');
+// Returns: [{ name, path, type: 'file'|'directory', size, modified }]
+
+// Delete
+await sandbox.deleteFile('/workspace/temp.txt');
+await sandbox.deleteFile('/workspace/temp-dir', { recursive: true });
+
+// Directory ops
+await sandbox.mkdir('/workspace/new-dir', { recursive: true });
+const exists = 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 }
+
+// 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
+const exposed = await sandbox.exposePort(8080, {
+  name: 'web-app',
+  hostname: request.hostname
+});
+// Returns: { url, port, name, status }
+
+// Check
+const isExposed = await sandbox.isPortExposed(8080);
+const portInfo = await sandbox.getExposedPort(8080);
+const allPorts = await sandbox.getExposedPorts(request.hostname);
+
+// Unexpose
+await sandbox.unexposePort(8080);
+```
+
+## Sessions (Isolated Contexts)
+
+Each session maintains own shell state, env vars, cwd, process namespace.
+
+```typescript
+// Create
+const session = await sandbox.createSession({
+  id: 'user-123',
+  name: 'User Workspace',
+  cwd: '/workspace/user123',
+  env: { USER_ID: '123', API_KEY: 'secret' }
+});
+
+// Use (full sandbox API bound to session context)
+await session.exec('echo $USER_ID');
+await session.writeFile('config.txt', 'data');
+await session.startProcess('python3 worker.py', { processId: 'worker-1' });
+
+// Retrieve
+const session = await sandbox.getSession('user-123');
+const sessions = await sandbox.listSessions();
+
+// Delete
+await sandbox.deleteSession('user-123');
+```
+
+## Code Interpreter
+
+```typescript
+const result = await sandbox.interpret('python', {
+  code: `
+import matplotlib.pyplot as plt
+plt.plot([1, 2, 3], [4, 5, 6])
+plt.savefig('plot.png')
+print("Chart created")
+  `,
+  files: {
+    'data.csv': 'name,value\nalice,10\nbob,20'
+  }
+});
+// Returns: { outputs: [{ type, content }], files, error }
+```
+
+## 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
+async function execWithRetry(sandbox, cmd, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await sandbox.exec(cmd);
+    } catch (error) {
+      if (error.code === 'CONTAINER_NOT_READY' && i < maxRetries - 1) {
+        await new Promise(r => setTimeout(r, 2000));
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+```
+
+## Client Architecture
+
+```
+SandboxClient (aggregator)
+├── CommandClient     → exec(), streaming
+├── FileClient        → read/write/list/delete
+├── ProcessClient     → background processes
+├── PortClient        → expose services, preview URLs
+├── GitClient         → clone repos
+├── UtilityClient     → health, sessions
+└── InterpreterClient → code execution (Python/JS)
+```
+
+**Execution Modes**:
+1. **Foreground** (exec): Blocking, captures output
+2. **Background** (execStream/startProcess): Non-blocking, uses FIFOs, concurrent