@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/static-assets/configuration.md

@@ -0,0 +1,186 @@
+## Configuration
+
+### Basic Setup
+
+Minimal configuration requires only `assets.directory`:
+
+```jsonc
+{
+  "name": "my-worker",
+  "compatibility_date": "2025-01-01",  // Use current date for new projects
+  "assets": {
+    "directory": "./dist"
+  }
+}
+```
+
+### Full Configuration Options
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "not_found_handling": "single-page-application",
+    "html_handling": "auto-trailing-slash",
+    "run_worker_first": ["/api/*", "!/api/docs/*"]
+  }
+}
+```
+
+**Configuration keys:**
+
+- `directory` (string, required): Path to assets folder (e.g. `./dist`, `./public`, `./build`)
+- `binding` (string, optional): Name to access assets in Worker code (e.g. `env.ASSETS`). Default: `"ASSETS"`
+- `not_found_handling` (string, optional): Behavior when asset not found
+  - `"single-page-application"`: Serve `/index.html` for non-asset paths (default for SPAs)
+  - `"404-page"`: Serve `/404.html` if present, otherwise 404
+  - `"none"`: Return 404 for missing assets
+- `html_handling` (string, optional): URL trailing slash behavior
+- `run_worker_first` (boolean | string[], optional): Routes that invoke Worker before checking assets
+
+### not_found_handling Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `"single-page-application"` | Serve `/index.html` for non-asset requests | React, Vue, Angular SPAs |
+| `"404-page"` | Serve `/404.html` if exists, else 404 | Static sites with custom error page |
+| `"none"` | Return 404 for missing assets | API-first or custom routing |
+
+### html_handling Modes
+
+Controls trailing slash behavior for HTML files:
+
+| Mode | `/page` | `/page/` | Use Case |
+|------|---------|----------|----------|
+| `"auto-trailing-slash"` | Redirect to `/page/` if `/page/index.html` exists | Serve `/page/index.html` | Default, SEO-friendly |
+| `"force-trailing-slash"` | Always redirect to `/page/` | Serve if exists | Consistent trailing slashes |
+| `"drop-trailing-slash"` | Serve if exists | Redirect to `/page` | Cleaner URLs |
+| `"none"` | No modification | No modification | Custom routing logic |
+
+**Default:** `"auto-trailing-slash"`
+
+### run_worker_first Configuration
+
+Controls which requests invoke Worker before checking assets.
+
+**Boolean syntax:**
+
+```jsonc
+{
+  "assets": {
+    "run_worker_first": true  // ALL requests invoke Worker
+  }
+}
+```
+
+**Array syntax (recommended):**
+
+```jsonc
+{
+  "assets": {
+    "run_worker_first": [
+      "/api/*",           // Positive pattern: match API routes
+      "/admin/*",         // Match admin routes
+      "!/admin/assets/*"  // Negative pattern: exclude admin assets
+    ]
+  }
+}
+```
+
+**Pattern rules:**
+
+- Glob patterns: `*` (any chars), `**` (any path segments)
+- Negative patterns: Prefix with `!` to exclude
+- Precedence: Negative patterns override positive patterns
+- Default: `false` (assets served directly)
+
+**Decision guidance:**
+
+- Use `true` for API-first apps (few static assets)
+- Use array patterns for hybrid apps (APIs + static assets)
+- Use `false` for static-first sites (minimal dynamic routes)
+
+### .assetsignore File
+
+Exclude files from upload using `.assetsignore` (same syntax as `.gitignore`):
+
+```
+# .assetsignore
+_worker.js
+*.map
+*.md
+node_modules/
+.git/
+```
+
+**Common patterns:**
+
+- `_worker.js` - Exclude Worker code from assets
+- `*.map` - Exclude source maps
+- `*.md` - Exclude markdown files
+- Development artifacts
+
+### Vite Plugin Integration
+
+For Vite-based projects, use `@cloudflare/vite-plugin`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { cloudflare } from '@cloudflare/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    cloudflare({
+      assets: {
+        directory: './dist',
+        binding: 'ASSETS'
+      }
+    })
+  ]
+});
+```
+
+**Features:**
+
+- Automatic asset detection during dev
+- Hot module replacement for assets
+- Production build integration
+- Requires: Wrangler 4.0.0+, `@cloudflare/vite-plugin` 1.0.0+
+
+### Key Compatibility Dates
+
+| Date | Feature | Impact |
+|------|---------|--------|
+| `2025-04-01` | Navigation request optimization | SPAs skip Worker for navigation, reducing costs |
+
+Use current date for new projects. See [Compatibility Dates](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) for full list.
+
+### Environment-Specific Configuration
+
+Use `wrangler.jsonc` environments for different configs:
+
+```jsonc
+{
+  "name": "my-worker",
+  "assets": { "directory": "./dist" },
+  "env": {
+    "staging": {
+      "assets": {
+        "not_found_handling": "404-page"
+      }
+    },
+    "production": {
+      "assets": {
+        "not_found_handling": "single-page-application"
+      }
+    }
+  }
+}
+```
+
+Deploy with: `wrangler deploy --env staging`

package/skills/cloudflare-deploy/references/static-assets/gotchas.md

@@ -0,0 +1,162 @@
+## Best Practices
+
+### 1. Use Selective Worker-First Routing
+
+Instead of `run_worker_first = true`, use array patterns:
+
+```jsonc
+{
+  "assets": {
+    "run_worker_first": [
+      "/api/*",           // API routes
+      "/admin/*",         // Admin area
+      "!/admin/assets/*"  // Except admin assets
+    ]
+  }
+}
+```
+
+**Benefits:**
+- Reduces Worker invocations
+- Lowers costs
+- Improves asset delivery performance
+
+### 2. Leverage Navigation Request Optimization
+
+For SPAs, use `compatibility_date = "2025-04-01"` or later:
+
+```jsonc
+{
+  "compatibility_date": "2025-04-01",
+  "assets": {
+    "not_found_handling": "single-page-application"
+  }
+}
+```
+
+Navigation requests skip Worker invocation, reducing costs.
+
+### 3. Type Safety with Bindings
+
+Always type your environment:
+
+```typescript
+interface Env {
+  ASSETS: Fetcher;
+}
+```
+
+## Common Errors
+
+### "Asset not found"
+
+**Cause:** Asset not in assets directory, wrong path, or assets not deployed  
+**Solution:** Verify asset exists, check path case-sensitivity, redeploy if needed
+
+### "Worker not invoked for asset"
+
+**Cause:** Asset served directly, `run_worker_first` not configured  
+**Solution:** Configure `run_worker_first` patterns to include asset routes (see configuration.md:66-106)
+
+### "429 Too Many Requests on free tier"
+
+**Cause:** `run_worker_first` patterns invoke Worker for many requests, hitting free tier limits (100k req/day)  
+**Solution:** Use more selective patterns with negative exclusions, or upgrade to paid plan
+
+### "Smart Placement increases latency"
+
+**Cause:** `run_worker_first=true` + Smart Placement routes all requests through single smart-placed location  
+**Solution:** Use selective patterns (array syntax) or disable Smart Placement for asset-heavy apps
+
+### "CF-Cache-Status header unreliable"
+
+**Cause:** Header is probabilistically added for privacy reasons  
+**Solution:** Don't rely on `CF-Cache-Status` for critical routing logic. Use other signals (ETag, age).
+
+### "JWT expired during deployment"
+
+**Cause:** Large asset deployments exceed JWT token lifetime  
+**Solution:** Update to Wrangler 4.34.0+ (automatic token refresh), or reduce asset count
+
+### "Cannot use 'assets' with 'site'"
+
+**Cause:** Legacy `site` config conflicts with new `assets` config  
+**Solution:** Migrate from `site` to `assets` (see configuration.md). Remove `site` key from wrangler.jsonc.
+
+### "Assets not updating after deployment"
+
+**Cause:** Browser or CDN cache serving old assets  
+**Solution:** 
+- Hard refresh browser (Cmd+Shift+R / Ctrl+F5)
+- Use cache-busting (hashed filenames)
+- Verify deployment completed: `wrangler tail`
+
+## Limits
+
+| Resource/Limit | Free | Paid | Notes |
+|----------------|------|------|-------|
+| Max asset size | 25 MiB | 25 MiB | Per file |
+| Total assets | 20,000 | **100,000** | Requires Wrangler 4.34.0+ (Sep 2025) |
+| Worker invocations | 100k/day | 10M/month | Optimize with `run_worker_first` patterns |
+| Asset storage | Unlimited | Unlimited | Included |
+
+### Version Requirements
+
+| Feature | Minimum Wrangler Version |
+|---------|--------------------------|
+| 100k file limit (paid) | 4.34.0 |
+| Vite plugin | 4.0.0 + @cloudflare/vite-plugin 1.0.0 |
+| Navigation optimization | 4.0.0 + compatibility_date: "2025-04-01" |
+
+## Performance Tips
+
+### 1. Use Hashed Filenames
+
+Enable long-term caching with content-hashed filenames:
+
+```
+app.a3b2c1d4.js
+styles.e5f6g7h8.css
+```
+
+Most bundlers (Vite, Webpack, Parcel) do this automatically.
+
+### 2. Minimize Worker Invocations
+
+Serve assets directly when possible:
+
+```jsonc
+{
+  "assets": {
+    // Only invoke Worker for dynamic routes
+    "run_worker_first": ["/api/*", "/auth/*"]
+  }
+}
+```
+
+### 3. Leverage Browser Cache
+
+Set appropriate `Cache-Control` headers:
+
+```typescript
+// Versioned assets
+'Cache-Control': 'public, max-age=31536000, immutable'
+
+// HTML (revalidate often)
+'Cache-Control': 'public, max-age=0, must-revalidate'
+```
+
+See patterns.md:169-189 for implementation.
+
+### 4. Use .assetsignore
+
+Reduce upload time by excluding unnecessary files:
+
+```
+*.map
+*.md
+.DS_Store
+node_modules/
+```
+
+See configuration.md:107-126 for details.

package/skills/cloudflare-deploy/references/static-assets/patterns.md

@@ -0,0 +1,189 @@
+### Common Patterns
+
+**1. Forward request to assets:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**2. Fetch specific asset by path:**
+
+```typescript
+const response = await env.ASSETS.fetch("https://assets.local/logo.png");
+```
+
+**3. Modify request before fetching asset:**
+
+```typescript
+const url = new URL(request.url);
+url.pathname = "/index.html";
+return env.ASSETS.fetch(new Request(url, request));
+```
+
+**4. Transform asset response:**
+
+```typescript
+const response = await env.ASSETS.fetch(request);
+const modifiedResponse = new Response(response.body, response);
+modifiedResponse.headers.set("X-Custom-Header", "value");
+modifiedResponse.headers.set("Cache-Control", "public, max-age=3600");
+return modifiedResponse;
+```
+
+**5. Conditional asset serving:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === '/') {
+      return env.ASSETS.fetch('/index.html');
+    }
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**6. SPA with API routes:**
+
+Most common full-stack pattern - static SPA with backend API:
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith('/api/')) {
+      return handleAPI(request, env);
+    }
+    return env.ASSETS.fetch(request);
+  }
+};
+
+async function handleAPI(request: Request, env: Env): Promise<Response> {
+  return new Response(JSON.stringify({ status: 'ok' }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+```
+
+**Config:** Set `run_worker_first: ["/api/*"]` (see configuration.md:66-106)
+
+**7. Auth gating for protected assets:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith('/admin/')) {
+      const session = await validateSession(request, env);
+      if (!session) {
+        return Response.redirect('/login', 302);
+      }
+    }
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**Config:** Set `run_worker_first: ["/admin/*"]`
+
+**8. Custom headers for security:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await env.ASSETS.fetch(request);
+    const secureResponse = new Response(response.body, response);
+    secureResponse.headers.set('X-Frame-Options', 'DENY');
+    secureResponse.headers.set('X-Content-Type-Options', 'nosniff');
+    secureResponse.headers.set('Content-Security-Policy', "default-src 'self'");
+    return secureResponse;
+  }
+};
+```
+
+**9. A/B testing via cookies:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const cookies = request.headers.get('Cookie') || '';
+    const variant = cookies.includes('variant=b') ? 'b' : 'a';
+    const url = new URL(request.url);
+    if (url.pathname === '/') {
+      return env.ASSETS.fetch(`/index-${variant}.html`);
+    }
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**10. Locale-based routing:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const locale = request.headers.get('Accept-Language')?.split(',')[0] || 'en';
+    const url = new URL(request.url);
+    if (url.pathname === '/') {
+      return env.ASSETS.fetch(`/${locale}/index.html`);
+    }
+    if (!url.pathname.startsWith(`/${locale}/`)) {
+      url.pathname = `/${locale}${url.pathname}`;
+    }
+    return env.ASSETS.fetch(url);
+  }
+};
+```
+
+**11. OAuth callback handling:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === '/auth/callback') {
+      const code = url.searchParams.get('code');
+      if (code) {
+        const session = await exchangeCode(code, env);
+        return new Response(null, {
+          status: 302,
+          headers: {
+            'Location': '/',
+            'Set-Cookie': `session=${session}; HttpOnly; Secure; SameSite=Lax`
+          }
+        });
+      }
+    }
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**Config:** Set `run_worker_first: ["/auth/*"]`
+
+**12. Cache control override:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await env.ASSETS.fetch(request);
+    const url = new URL(request.url);
+    // Immutable assets (hashed filenames)
+    if (/\.[a-f0-9]{8,}\.(js|css|png|jpg)$/.test(url.pathname)) {
+      return new Response(response.body, {
+        ...response,
+        headers: {
+          ...Object.fromEntries(response.headers),
+          'Cache-Control': 'public, max-age=31536000, immutable'
+        }
+      });
+    }
+    return response;
+  }
+};
+```

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

@@ -0,0 +1,114 @@
+# Cloudflare Stream
+
+Serverless live and on-demand video streaming platform with one API.
+
+## Overview
+
+Cloudflare Stream provides video upload, storage, encoding, and delivery without managing infrastructure. Runs on Cloudflare's global network.
+
+### Key Features
+- **On-demand video**: Upload, encode, store, deliver
+- **Live streaming**: RTMPS/SRT ingestion with ABR
+- **Direct creator uploads**: End users upload without API keys
+- **Signed URLs**: Token-based access control
+- **Analytics**: Server-side metrics via GraphQL
+- **Webhooks**: Processing notifications
+- **Captions**: Upload or AI-generate subtitles
+- **Watermarks**: Apply branding to videos
+- **Downloads**: Enable MP4 offline viewing
+
+## Core Concepts
+
+### Video Upload Methods
+1. **API Upload (TUS protocol)**: Direct server upload
+2. **Upload from URL**: Import from external source
+3. **Direct Creator Uploads**: User-generated content (recommended)
+
+### Playback Options
+1. **Stream Player (iframe)**: Built-in, optimized player
+2. **Custom Player (HLS/DASH)**: Video.js, HLS.js integration
+3. **Thumbnails**: Static or animated previews
+
+### Access Control
+- **Public**: No restrictions
+- **requireSignedURLs**: Token-based access
+- **allowedOrigins**: Domain restrictions
+- **Access Rules**: Geo/IP restrictions in tokens
+
+### Live Streaming
+- RTMPS/SRT ingest from OBS, FFmpeg
+- Automatic recording to on-demand
+- Simulcast to YouTube, Twitch, etc.
+- WebRTC support for browser streaming
+
+## Quick Start
+
+**Upload video via API**
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/video.mp4"}'
+```
+
+**Embed player**
+```html
+<iframe
+  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/iframe"
+  style="border: none;"
+  height="720" width="1280"
+  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
+  allowfullscreen="true"
+></iframe>
+```
+
+**Create live input**
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"recording": {"mode": "automatic"}}'
+```
+
+## Limits
+
+- Max file size: 30 GB
+- Max frame rate: 60 fps (recommended)
+- Supported formats: MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime
+
+## Pricing
+
+- $5/1000 min stored
+- $1/1000 min delivered
+
+## Resources
+
+- Dashboard: https://dash.cloudflare.com/?to=/:account/stream
+- API Docs: https://developers.cloudflare.com/api/resources/stream/
+- Stream Docs: https://developers.cloudflare.com/stream/
+
+## Reading Order
+
+| Order | File | Purpose | When to Use |
+|-------|------|---------|-------------|
+| 1 | [configuration.md](./configuration.md) | Setup SDKs, env vars, signing keys | Starting new project |
+| 2 | [api.md](./api.md) | On-demand video APIs | Implementing uploads/playback |
+| 3 | [api-live.md](./api-live.md) | Live streaming APIs | Building live streaming |
+| 4 | [patterns.md](./patterns.md) | Full-stack flows, TUS, JWT signing | Implementing workflows |
+| 5 | [gotchas.md](./gotchas.md) | Errors, limits, troubleshooting | Debugging issues |
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Setup, environment variables, wrangler config
+- [api.md](./api.md) - On-demand video upload, playback, management APIs
+- [api-live.md](./api-live.md) - Live streaming (RTMPS/SRT/WebRTC), simulcast
+- [patterns.md](./patterns.md) - Full-stack flows, state management, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting, limits
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs in Workers
+- [pages](../pages/) - Integrate Stream with Pages
+- [workers-ai](../workers-ai/) - AI-generate captions