@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/workers-for-platforms/patterns.md

@@ -0,0 +1,188 @@
+# Multi-Tenant Patterns
+
+## Billing by Plan
+
+```typescript
+interface Env {
+  DISPATCHER: DispatchNamespace;
+  CUSTOMERS_KV: KVNamespace;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userWorkerName = new URL(request.url).hostname.split(".")[0];
+    const customerPlan = await env.CUSTOMERS_KV.get(userWorkerName);
+    
+    const plans = {
+      enterprise: { cpuMs: 50, subRequests: 50 },
+      pro: { cpuMs: 20, subRequests: 20 },
+      free: { cpuMs: 10, subRequests: 5 },
+    };
+    const limits = plans[customerPlan as keyof typeof plans] || plans.free;
+    
+    const userWorker = env.DISPATCHER.get(userWorkerName, {}, { limits });
+    return await userWorker.fetch(request);
+  },
+};
+```
+
+## Resource Isolation
+
+**Complete isolation:** Create unique resources per customer
+- KV namespace per customer
+- D1 database per customer
+- R2 bucket per customer
+
+```typescript
+const bindings = [{
+  type: "kv_namespace",
+  name: "USER_KV",
+  namespace_id: `customer-${customerId}-kv`
+}];
+```
+
+## Hostname Routing
+
+### Wildcard Route (Recommended)
+Configure `*/*` route on SaaS domain → dispatch Worker
+
+**Benefits:**
+- Supports subdomains + custom vanity domains
+- No per-route limits (regular Workers limited to 100 routes)
+- Programmatic control
+- Works with any DNS proxy settings
+
+**Setup:**
+1. Cloudflare for SaaS custom hostnames
+2. Fallback origin (dummy `A 192.0.2.0` if Worker is origin)
+3. DNS CNAME to SaaS domain
+4. `*/*` route → dispatch Worker
+5. Routing logic in dispatch Worker
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const hostname = new URL(request.url).hostname;
+    const hostnameData = await env.ROUTING_KV.get(`hostname:${hostname}`, { type: "json" });
+    
+    if (!hostnameData?.workerName) {
+      return new Response("Hostname not configured", { status: 404 });
+    }
+    
+    const userWorker = env.DISPATCHER.get(hostnameData.workerName);
+    return await userWorker.fetch(request);
+  },
+};
+```
+
+### Subdomain-Only
+1. Wildcard DNS: `*.saas.com` → origin
+2. Route: `*.saas.com/*` → dispatch Worker
+3. Extract subdomain for routing
+
+### Orange-to-Orange (O2O) Behavior
+
+When customers use Cloudflare and CNAME to your Workers domain:
+
+| Scenario | Behavior | Route Pattern |
+|----------|----------|---------------|
+| Customer not on Cloudflare | Standard routing | `*/*` or `*.domain.com/*` |
+| Customer on Cloudflare (proxied CNAME) | Invokes Worker at edge | `*/*` required |
+| Customer on Cloudflare (DNS-only CNAME) | Standard routing | Any route works |
+
+**Recommendation:** Always use `*/*` wildcard for consistent O2O behavior.
+
+### Custom Metadata Routing
+
+For Cloudflare for SaaS: Store worker name in custom hostname `custom_metadata`, retrieve in dispatch worker to route requests. Requires custom hostnames as subdomains of your domain.
+
+## Observability
+
+### Logpush
+- Enable on dispatch Worker → captures all user Worker logs
+- Filter by `Outcome` or `Script Name`
+
+### Tail Workers
+- Real-time logs with custom formatting
+- Receives HTTP status, `console.log()`, exceptions, diagnostics
+
+### Analytics Engine
+```typescript
+// Track violations
+env.ANALYTICS.writeDataPoint({
+  indexes: [customerName],
+  blobs: ["cpu_limit_exceeded"],
+});
+```
+
+### GraphQL
+```graphql
+query {
+  viewer {
+    accounts(filter: {accountTag: $accountId}) {
+      workersInvocationsAdaptive(filter: {dispatchNamespaceName: "production"}) {
+        sum { requests errors cpuTime }
+      }
+    }
+  }
+}
+```
+
+## Use Case Implementations
+
+### AI Code Execution
+```typescript
+async function deployGeneratedCode(name: string, code: string) {
+  const file = new File([code], `${name}.mjs`, { type: "application/javascript+module" });
+  await client.workersForPlatforms.dispatch.namespaces.scripts.update("production", name, {
+    account_id: accountId,
+    metadata: { main_module: `${name}.mjs`, tags: [name, "ai-generated"] },
+    files: [file],
+  });
+}
+
+// Short limits for untrusted code
+const userWorker = env.DISPATCHER.get(sessionId, {}, { limits: { cpuMs: 5, subRequests: 3 } });
+```
+
+**VibeSDK:** For AI-powered code generation + deployment platforms, see [VibeSDK](https://github.com/cloudflare/vibesdk) - handles AI generation, sandbox execution, live preview, and deployment.
+
+Reference: [AI Vibe Coding Platform Architecture](https://developers.cloudflare.com/reference-architecture/diagrams/ai/ai-vibe-coding-platform/)
+
+### Edge Functions Platform
+```typescript
+// Route: /customer-id/function-name
+const [customerId, functionName] = new URL(request.url).pathname.split("/").filter(Boolean);
+const workerName = `${customerId}-${functionName}`;
+const userWorker = env.DISPATCHER.get(workerName);
+```
+
+### Website Builder
+- Deploy static assets + Worker code
+- See [api.md](./api.md#static-assets) for full implementation
+- Salt hashes for asset isolation
+
+## Best Practices
+
+### Architecture
+- One namespace per environment (production, staging)
+- Platform logic in dispatch Worker (auth, rate limiting, validation)
+- Isolation automatic (no shared cache, untrusted mode)
+
+### Routing
+- Use `*/*` wildcard routes
+- Store mappings in KV
+- Handle missing Workers gracefully
+
+### Limits & Security
+- Set custom limits by plan
+- Track violations with Analytics Engine
+- Use outbound Workers for egress control
+- Sanitize responses
+
+### Tags
+- Tag all Workers: customer ID, plan, environment
+- Enable bulk operations
+- Filter efficiently
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)

package/skills/cloudflare-deploy/references/workers-playground/README.md

@@ -0,0 +1,127 @@
+# Cloudflare Workers Playground Skill Reference
+
+## Overview
+
+Cloudflare Workers Playground is a browser-based sandbox for instantly experimenting with, testing, and deploying Cloudflare Workers without authentication or setup. This skill provides patterns, APIs, and best practices specifically for Workers Playground development.
+
+**URL:** [workers.cloudflare.com/playground](https://workers.cloudflare.com/playground)
+
+## ⚠️ Playground Constraints
+
+**Playground is NOT production-equivalent:**
+- ✅ Real Workers runtime, instant testing, shareable URLs
+- ❌ No TypeScript (JavaScript only)
+- ❌ No bindings (KV, D1, R2, Durable Objects)
+- ❌ No environment variables or secrets
+- ❌ ES modules only (no Service Worker format)
+- ⚠️ Safari broken (use Chrome/Firefox)
+
+**For production:** Use `wrangler` CLI. Playground is for rapid prototyping.
+
+## Quick Start
+
+Minimal Worker:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    return new Response('Hello World');
+  }
+};
+```
+
+JSON API:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const data = { message: 'Hello', timestamp: Date.now() };
+    return Response.json(data);
+  }
+};
+```
+
+Proxy with modification:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const response = await fetch('https://example.com');
+    const modified = new Response(response.body, response);
+    modified.headers.set('X-Custom-Header', 'added-by-worker');
+    return modified;
+  }
+};
+```
+
+Import from CDN:
+
+```javascript
+import { Hono } from 'https://esm.sh/hono@3';
+
+export default {
+  async fetch(request) {
+    const app = new Hono();
+    app.get('/', (c) => c.text('Hello Hono!'));
+    return app.fetch(request);
+  }
+};
+```
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Start here: playground setup, constraints, deployment
+2. **[api.md](api.md)** - Core APIs: Request, Response, ExecutionContext, fetch, Cache
+3. **[patterns.md](patterns.md)** - Common use cases: routing, proxying, A/B testing, multi-module code
+4. **[gotchas.md](gotchas.md)** - Troubleshooting: errors, browser issues, limits, best practices
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, deployment, configuration
+- **[api.md](api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations
+
+## Key Features
+
+**No Setup Required:**
+- Open URL and start coding
+- No CLI, no account, no config files
+- Code executes in real Cloudflare Workers runtime
+
+**Instant Preview:**
+- Live preview pane with browser tab or HTTP tester
+- Auto-reload on code changes
+- DevTools integration (right-click → Inspect)
+
+**Share & Deploy:**
+- Copy Link generates permanent shareable URL
+- Deploy button publishes to production in ~30 seconds
+- Get `*.workers.dev` subdomain immediately
+
+## Common Use Cases
+
+- **API development:** Test endpoints before wrangler setup
+- **Learning Workers:** Experiment with APIs without local environment
+- **Prototyping:** Quick POCs for edge logic
+- **Sharing examples:** Generate shareable links for bug reports or demos
+- **Framework testing:** Import from CDN (Hono, itty-router, etc.)
+
+## Limitations vs Production
+
+| Feature | Playground | Production (wrangler) |
+|---------|------------|----------------------|
+| Language | JavaScript only | JS + TypeScript |
+| Bindings | None | KV, D1, R2, DO, AI, etc. |
+| Environment vars | None | Full support |
+| Module format | ES only | ES + Service Worker |
+| CPU time | 10ms (Free plan) | 10ms Free / 50ms Paid |
+| Custom domains | No | Yes |
+| Analytics | No | Yes |
+
+## See Also
+
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
+- [Workers Examples](https://developers.cloudflare.com/workers/examples/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
+- [Workers API Reference](https://developers.cloudflare.com/workers/runtime-apis/)

package/skills/cloudflare-deploy/references/workers-playground/api.md

@@ -0,0 +1,101 @@
+# Workers Playground API
+
+## Handler
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    // request: Request, env: {} (empty in playground), ctx: ExecutionContext
+    return new Response('Hello');
+  }
+};
+```
+
+## Request
+
+```javascript
+const method = request.method;       // "GET", "POST"
+const url = new URL(request.url);    // Parse URL
+const headers = request.headers;     // Headers object
+const body = await request.json();   // Read body (consumes stream)
+const clone = request.clone();       // Clone before reading body
+
+// Query params
+url.searchParams.get('page');        // Single value
+url.searchParams.getAll('tag');      // Array
+
+// Cloudflare metadata
+request.cf.country;                  // "US"
+request.cf.colo;                     // "SFO"
+```
+
+## Response
+
+```javascript
+// Text
+return new Response('Hello', { status: 200 });
+
+// JSON
+return Response.json({ data }, { status: 200, headers: {...} });
+
+// Redirect
+return Response.redirect('/new-path', 301);
+
+// Modify existing
+const modified = new Response(response.body, response);
+modified.headers.set('X-Custom', 'value');
+```
+
+## ExecutionContext
+
+```javascript
+// Background work (after response sent)
+ctx.waitUntil(fetch('https://logs.example.com', { method: 'POST', body: '...' }));
+return new Response('OK'); // Returns immediately
+```
+
+## Fetch
+
+```javascript
+const response = await fetch('https://api.example.com');
+const data = await response.json();
+
+// With options
+await fetch(url, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'Alice' })
+});
+```
+
+## Cache
+
+```javascript
+const cache = caches.default;
+
+// Check cache
+let response = await cache.match(request);
+if (!response) {
+  response = await fetch(origin);
+  await cache.put(request, response.clone()); // Clone before put!
+}
+return response;
+```
+
+## Crypto
+
+```javascript
+crypto.randomUUID();                 // UUID v4
+crypto.getRandomValues(new Uint8Array(16));
+
+// SHA-256 hash
+const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(data));
+```
+
+## Limits (Playground = Free Plan)
+
+| Resource | Limit |
+|----------|-------|
+| CPU time | 10ms |
+| Subrequests | 50 |
+| Memory | 128 MB |

package/skills/cloudflare-deploy/references/workers-playground/configuration.md

@@ -0,0 +1,163 @@
+# Configuration
+
+## Getting Started
+
+Navigate to [workers.cloudflare.com/playground](https://workers.cloudflare.com/playground)
+
+- **No account required** for testing
+- **No CLI or local setup** needed
+- Code executes in real Cloudflare Workers runtime
+- Share code via URL (never expires)
+
+## Playground Constraints
+
+⚠️ **Important Limitations**
+
+| Constraint | Playground | Production Workers |
+|------------|------------|-------------------|
+| **Module Format** | ES modules only | ES modules or Service Worker |
+| **TypeScript** | Not supported (JS only) | Supported via build step |
+| **Bindings** | Not available | KV, D1, R2, Durable Objects, etc. |
+| **wrangler.toml** | Not used | Required for config |
+| **Environment Variables** | Not available | Full support |
+| **Secrets** | Not available | Full support |
+| **Custom Domains** | Not available | Full support |
+
+**Playground is for rapid prototyping only.** For production apps, use `wrangler` CLI.
+
+## Code Editor
+
+### Syntax Requirements
+
+Must export default object with `fetch` handler:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    return new Response('Hello World');
+  }
+};
+```
+
+**Key Points:**
+- Must use ES modules (`export default`)
+- `fetch` method receives `(request, env, ctx)`
+- Must return `Response` object
+- TypeScript not supported (use plain JavaScript)
+
+### Multi-Module Code
+
+Import from external URLs or inline modules:
+
+```javascript
+// Import from CDN
+import { Hono } from 'https://esm.sh/hono@3';
+
+// Or paste library code and import relatively
+// (See patterns.md for multi-module examples)
+
+export default {
+  async fetch(request) {
+    const app = new Hono();
+    app.get('/', (c) => c.text('Hello'));
+    return app.fetch(request);
+  }
+};
+```
+
+## Preview Panel
+
+### Browser Tab
+
+Default interactive preview with address bar:
+- Enter custom URL paths
+- Automatic reload on code changes
+- DevTools available (right-click → Inspect)
+
+### HTTP Test Panel
+
+Switch to **HTTP** tab for raw HTTP testing:
+- Change HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
+- Add/edit request headers
+- Modify request body (JSON, form data, text)
+- View response headers and body
+- Test different content types
+
+Example HTTP test:
+```
+Method: POST
+URL: /api/users
+Headers:
+  Content-Type: application/json
+  Authorization: Bearer token123
+Body:
+{
+  "name": "Alice",
+  "email": "alice@example.com"
+}
+```
+
+## Sharing Code
+
+**Copy Link** button generates shareable URL:
+- Code embedded in URL fragment
+- Links never expire
+- No account required
+- Can be bookmarked for later
+
+Example: `https://workers.cloudflare.com/playground#abc123...`
+
+## Deploying from Playground
+
+Click **Deploy** button to move code to production:
+
+1. **Log in** to Cloudflare account (creates free account if needed)
+2. **Review** Worker name and code
+3. **Deploy** to global network (takes ~30 seconds)
+4. **Get URL**: Deployed to `<name>.workers.dev` subdomain
+5. **Manage** from dashboard: add bindings, custom domains, analytics
+
+**After deploy:**
+- Code runs on Cloudflare's global network (300+ cities)
+- Can add KV, D1, R2, Durable Objects bindings
+- Configure custom domains and routes
+- View analytics and logs
+- Set environment variables and secrets
+
+**Note:** Deployed Workers are production-ready but start on Free plan (100k requests/day).
+
+## Browser Compatibility
+
+| Browser | Status | Notes |
+|---------|--------|-------|
+| Chrome/Edge | ✅ Full support | Recommended |
+| Firefox | ✅ Full support | Works well |
+| Safari | ⚠️ Broken | Preview fails with "PreviewRequestFailed" |
+
+**Safari users:** Use Chrome, Firefox, or Edge for Workers Playground.
+
+## DevTools Integration
+
+1. **Open preview** in browser tab
+2. **Right-click** → Inspect Element
+3. **Console tab** shows Worker logs:
+   - `console.log()` output
+   - Uncaught errors
+   - Network requests (subrequests)
+
+**Note:** DevTools show client-side console, not Worker execution logs. For production logging, use Logpush or Tail Workers.
+
+## Limits in Playground
+
+Same as production Free plan:
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| CPU time | 10ms | Per request |
+| Memory | 128 MB | Per request |
+| Script size | 1 MB | After compression |
+| Subrequests | 50 | Outbound fetch calls |
+| Request size | 100 MB | Incoming |
+| Response size | Unlimited | Outgoing (streamed) |
+
+**Exceeding CPU time** throws error immediately. Optimize hot paths or upgrade to Paid plan (50ms CPU).

package/skills/cloudflare-deploy/references/workers-playground/gotchas.md

@@ -0,0 +1,88 @@
+# Workers Playground Gotchas
+
+## Platform Limitations
+
+| Limitation | Impact | Workaround |
+|------------|--------|------------|
+| Safari broken | Preview fails | Use Chrome/Firefox/Edge |
+| TypeScript unsupported | TS syntax errors | Write plain JS or use JSDoc |
+| No bindings | `env` always `{}` | Mock data or use external APIs |
+| No env vars | Can't access secrets | Hardcode for testing |
+
+## Common Runtime Errors
+
+### "Response body already read"
+
+```javascript
+// ❌ Body consumed twice
+const body = await request.text();
+await fetch(url, { body: request.body }); // Error!
+
+// ✅ Clone first
+const clone = request.clone();
+const body = await request.text();
+await fetch(url, { body: clone.body });
+```
+
+### "Worker exceeded CPU time"
+
+**Limit:** 10ms (free), 50ms (paid)
+
+```javascript
+// ✅ Move slow work to background
+ctx.waitUntil(fetch('https://analytics.example.com', {...}));
+return new Response('OK'); // Return immediately
+```
+
+### "Too many subrequests"
+
+**Limit:** 50 (free), 1000 (paid)
+
+```javascript
+// ❌ 100 individual fetches
+// ✅ Batch into single API call
+await fetch('https://api.example.com/batch', {
+  body: JSON.stringify({ ids: [...] })
+});
+```
+
+## Best Practices
+
+```javascript
+// Clone before caching
+await cache.put(request, response.clone());
+return response;
+
+// Validate input early
+if (request.method !== 'POST') return new Response('', { status: 405 });
+
+// Handle errors
+try { ... } catch (e) {
+  return Response.json({ error: e.message }, { status: 500 });
+}
+```
+
+## Limits
+
+| Resource | Free | Paid |
+|----------|------|------|
+| CPU time | 10ms | 50ms |
+| Memory | 128 MB | 128 MB |
+| Subrequests | 50 | 1000 |
+
+## Browser Support
+
+| Browser | Status |
+|---------|--------|
+| Chrome | ✅ Recommended |
+| Firefox | ✅ Works |
+| Edge | ✅ Works |
+| Safari | ❌ Broken |
+
+## Debugging
+
+```javascript
+console.log('URL:', request.url); // View in browser DevTools Console
+```
+
+**Note:** `console.log` works in playground. For production, use Logpush or Tail Workers.