@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/smart-placement/patterns.md

@@ -0,0 +1,183 @@
+# Smart Placement Patterns
+
+## Backend Worker with Database Access
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const user = await env.DATABASE.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+    const orders = await env.DATABASE.prepare('SELECT * FROM orders WHERE user_id = ?').bind(userId).all();
+    return Response.json({ user, orders });
+  }
+};
+```
+
+```jsonc
+{ "placement": { "mode": "smart" }, "d1_databases": [{ "binding": "DATABASE", "database_id": "xxx" }] }
+```
+
+## Frontend + Backend Split (Service Bindings)
+
+**Frontend:** Runs at edge for fast user response
+**Backend:** Smart Placement runs close to database
+
+```typescript
+// Frontend Worker - routes requests to backend
+interface Env {
+  BACKEND: Fetcher;  // Service Binding to backend Worker
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (new URL(request.url).pathname.startsWith('/api/')) {
+      return env.BACKEND.fetch(request);  // Forward to backend
+    }
+    return new Response('Frontend content');
+  }
+};
+
+// Backend Worker - database operations
+interface BackendEnv {
+  DATABASE: D1Database;
+}
+
+export default {
+  async fetch(request: Request, env: BackendEnv): Promise<Response> {
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
+    return Response.json(data);
+  }
+};
+```
+
+**CRITICAL:** Use fetch-based Service Bindings (shown above). If using RPC with `WorkerEntrypoint`, Smart Placement will NOT optimize those method calls - only `fetch` handlers are affected.
+
+**RPC vs Fetch - CRITICAL:** Smart Placement ONLY works with fetch-based bindings, NOT RPC.
+
+```typescript
+// ❌ RPC - Smart Placement has NO EFFECT on backend RPC methods
+export class BackendRPC extends WorkerEntrypoint {
+  async getData() {
+    // ALWAYS runs at edge, Smart Placement ignored
+    return await this.env.DATABASE.prepare('SELECT * FROM table').all();
+  }
+}
+
+// ✅ Fetch - Smart Placement WORKS
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Runs close to DATABASE when Smart Placement enabled
+    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
+    return Response.json(data);
+  }
+};
+```
+
+## External API Integration
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiUrl = 'https://api.partner.com';
+    const headers = { 'Authorization': `Bearer ${env.API_KEY}` };
+    
+    const [profile, transactions] = await Promise.all([
+      fetch(`${apiUrl}/profile`, { headers }),
+      fetch(`${apiUrl}/transactions`, { headers })
+    ]);
+    
+    return Response.json({ 
+      profile: await profile.json(), 
+      transactions: await transactions.json()
+    });
+  }
+};
+```
+
+## SSR / API Gateway Pattern
+
+```typescript
+// Frontend (edge) - auth/routing close to user
+export default {
+  async fetch(request: Request, env: Env) {
+    if (!request.headers.get('Authorization')) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    const data = await env.BACKEND.fetch(request);
+    return new Response(renderPage(await data.json()), { 
+      headers: { 'Content-Type': 'text/html' } 
+    });
+  }
+};
+
+// Backend (Smart Placement) - DB operations close to data
+export default {
+  async fetch(request: Request, env: Env) {
+    const data = await env.DATABASE.prepare('SELECT * FROM pages WHERE id = ?').bind(pageId).first();
+    return Response.json(data);
+  }
+};
+```
+
+## Durable Objects with Smart Placement
+
+**Key principle:** Smart Placement does NOT control WHERE Durable Objects run. DOs always run in their designated region (based on jurisdiction or smart location hints).
+
+**What Smart Placement DOES affect:** The location of the coordinator Worker's `fetch` handler that makes calls to multiple DOs.
+
+**Pattern:** Enable Smart Placement on coordinator Worker that aggregates data from multiple DOs:
+
+```typescript
+// Worker with Smart Placement - aggregates data from multiple DOs
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userId = new URL(request.url).searchParams.get('user');
+    
+    // Get DO stubs
+    const userDO = env.USER_DO.get(env.USER_DO.idFromName(userId));
+    const analyticsID = env.ANALYTICS_DO.idFromName(`analytics-${userId}`);
+    const analyticsDO = env.ANALYTICS_DO.get(analyticsID);
+    
+    // Fetch from multiple DOs
+    const [userData, analyticsData] = await Promise.all([
+      userDO.fetch(new Request('https://do/profile')),
+      analyticsDO.fetch(new Request('https://do/stats'))
+    ]);
+    
+    return Response.json({
+      user: await userData.json(),
+      analytics: await analyticsData.json()
+    });
+  }
+};
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "placement": { "mode": "smart" },
+  "durable_objects": {
+    "bindings": [
+      { "name": "USER_DO", "class_name": "UserDO" },
+      { "name": "ANALYTICS_DO", "class_name": "AnalyticsDO" }
+    ]
+  }
+}
+```
+
+**When this helps:** 
+- Worker's `fetch` handler runs closer to DO regions, reducing network latency for multiple DO calls
+- Most beneficial when DOs are geographically concentrated or in specific jurisdictions
+- Helps when coordinator makes many sequential or parallel DO calls
+
+**When this DOESN'T help:**
+- DOs are globally distributed (no single optimal Worker location)
+- Worker only calls a single DO
+- DO calls are infrequent or cached
+
+## Best Practices
+
+- Split full-stack apps: frontend at edge, backend with Smart Placement
+- Use fetch-based Service Bindings (not RPC)
+- Enable for backend logic: APIs, data aggregation, DB operations
+- Don't enable for: static content, edge logic, RPC methods, Pages with `run_worker_first`
+- Wait 15+ min for analysis, verify `placement_status = SUCCESS`

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

@@ -0,0 +1,68 @@
+# Cloudflare Snippets Skill Reference
+
+## Description
+Expert guidance for **Cloudflare Snippets ONLY** - a lightweight JavaScript-based edge logic platform for modifying HTTP requests and responses. Snippets run as part of the Ruleset Engine and are included at no additional cost on paid plans (Pro, Business, Enterprise).
+
+## What Are Snippets?
+Snippets are JavaScript functions executed at the edge as part of Cloudflare's Ruleset Engine. Key characteristics:
+- **Execution time**: 5ms CPU limit per request
+- **Size limit**: 32KB per snippet
+- **Runtime**: V8 isolate (subset of Workers APIs)
+- **Subrequests**: 2-5 fetch calls depending on plan
+- **Cost**: Included with Pro/Business/Enterprise plans
+
+## Snippets vs Workers Decision Matrix
+
+| Factor | Choose Snippets If... | Choose Workers If... |
+|--------|----------------------|---------------------|
+| **Complexity** | Simple request/response modifications | Complex business logic, routing, middleware |
+| **Execution time** | <5ms sufficient | Need >5ms or variable time |
+| **Subrequests** | 2-5 fetch calls sufficient | Need >5 subrequests or complex orchestration |
+| **Code size** | <32KB sufficient | Need >32KB or npm dependencies |
+| **Cost** | Want zero additional cost | Can afford $5/mo + usage |
+| **APIs** | Need basic fetch, headers, URL | Need KV, D1, R2, Durable Objects, cron triggers |
+| **Deployment** | Need rule-based triggers | Want custom routing logic |
+
+**Rule of thumb**: Use Snippets for modifications, Workers for applications.
+
+## Execution Model
+1. Request arrives at Cloudflare edge
+2. Ruleset Engine evaluates snippet rules (filter expressions)
+3. If rule matches, snippet executes within 5ms limit
+4. Modified request/response continues through pipeline
+5. Response returned to client
+
+Snippets execute synchronously in the request path - performance is critical.
+
+## Reading Order
+1. **[configuration.md](configuration.md)** - Start here: setup, deployment methods (Dashboard/API/Terraform)
+2. **[api.md](api.md)** - Core APIs: Request, Response, headers, `request.cf` properties
+3. **[patterns.md](patterns.md)** - Real-world examples: geo-routing, A/B tests, security headers
+4. **[gotchas.md](gotchas.md)** - Troubleshooting: common errors, performance tips, API limitations
+
+## 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
+
+## Quick Start
+```javascript
+// Snippet: Add security headers
+export default {
+  async fetch(request) {
+    const response = await fetch(request);
+    const newResponse = new Response(response.body, response);
+    newResponse.headers.set("X-Frame-Options", "DENY");
+    newResponse.headers.set("X-Content-Type-Options", "nosniff");
+    return newResponse;
+  }
+}
+```
+
+Deploy via Dashboard (Rules → Snippets) or API/Terraform. See configuration.md for details.
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/rules/snippets/)

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

@@ -0,0 +1,198 @@
+# Snippets API Reference
+
+## Request Object
+
+### HTTP Properties
+```javascript
+request.method    // GET, POST, PUT, DELETE, etc.
+request.url       // Full URL string
+request.headers   // Headers object
+request.body      // ReadableStream (for POST/PUT)
+request.cf        // Cloudflare properties (see below)
+```
+
+### URL Operations
+```javascript
+const url = new URL(request.url);
+url.hostname             // "example.com"
+url.pathname             // "/path/to/page"
+url.search               // "?query=value"
+url.searchParams.get("q") // "value"
+url.searchParams.set("q", "new")
+url.searchParams.delete("q")
+```
+
+### Header Operations
+```javascript
+// Read headers
+request.headers.get("User-Agent")
+request.headers.has("Authorization")
+request.headers.getSetCookie() // Get all Set-Cookie headers
+
+// Modify headers (create new request)
+const modifiedRequest = new Request(request);
+modifiedRequest.headers.set("X-Custom", "value")
+modifiedRequest.headers.delete("X-Remove")
+```
+
+### Cloudflare Properties (`request.cf`)
+Access Cloudflare-specific metadata about the request:
+
+```javascript
+// Geolocation
+request.cf.city            // "San Francisco"
+request.cf.continent       // "NA"
+request.cf.country         // "US"
+request.cf.region          // "California" or "CA"
+request.cf.regionCode      // "CA"
+request.cf.postalCode      // "94102"
+request.cf.latitude        // "37.7749"
+request.cf.longitude       // "-122.4194"
+request.cf.timezone        // "America/Los_Angeles"
+request.cf.metroCode       // "807" (DMA code)
+
+// Network
+request.cf.colo            // "SFO" (airport code of datacenter)
+request.cf.asn             // 13335 (ASN number)
+request.cf.asOrganization  // "Cloudflare, Inc."
+
+// Bot Management (if enabled)
+request.cf.botManagement.score        // 1-99 (1=bot, 99=human)
+request.cf.botManagement.verified_bot // true/false
+request.cf.botManagement.static_resource // true/false
+
+// TLS/HTTP version
+request.cf.tlsVersion      // "TLSv1.3"
+request.cf.tlsCipher       // "AEAD-AES128-GCM-SHA256"
+request.cf.httpProtocol    // "HTTP/2"
+
+// Request metadata
+request.cf.requestPriority // "weight=192;exclusive=0"
+```
+
+**Use cases**: Geo-routing, bot detection, security decisions, analytics.
+
+## Response Object
+
+### Response Constructors
+```javascript
+// Plain text
+new Response("Hello", { status: 200 })
+
+// JSON
+Response.json({ key: "value" }, { status: 200 })
+
+// HTML
+new Response("<h1>Hi</h1>", { 
+  status: 200,
+  headers: { "Content-Type": "text/html" }
+})
+
+// Redirect
+Response.redirect("https://example.com", 301) // or 302
+
+// Stream (pass through)
+new Response(response.body, response)
+```
+
+### Response Headers
+```javascript
+// Create modified response
+const newResponse = new Response(response.body, response);
+
+// Set/modify headers
+newResponse.headers.set("X-Custom", "value")
+newResponse.headers.append("Set-Cookie", "session=abc; Path=/")
+newResponse.headers.delete("Server")
+
+// Common headers
+newResponse.headers.set("Cache-Control", "public, max-age=3600")
+newResponse.headers.set("Content-Type", "application/json")
+```
+
+### Response Properties
+```javascript
+response.status       // 200, 404, 500, etc.
+response.statusText   // "OK", "Not Found", etc.
+response.headers      // Headers object
+response.body         // ReadableStream
+response.ok           // true if status 200-299
+response.redirected   // true if redirected
+```
+
+## REST API Operations
+
+### List Snippets
+```bash
+GET /zones/{zone_id}/snippets
+```
+
+### Get Snippet
+```bash
+GET /zones/{zone_id}/snippets/{snippet_name}
+```
+
+### Create/Update Snippet
+```bash
+PUT /zones/{zone_id}/snippets/{snippet_name}
+Content-Type: multipart/form-data
+
+files=@snippet.js
+metadata={"main_module":"snippet.js"}
+```
+
+### Delete Snippet
+```bash
+DELETE /zones/{zone_id}/snippets/{snippet_name}
+```
+
+### List Snippet Rules
+```bash
+GET /zones/{zone_id}/rulesets/phases/http_request_snippets/entrypoint
+```
+
+### Update Snippet Rules
+```bash
+PUT /zones/{zone_id}/snippets/snippet_rules
+Content-Type: application/json
+
+{
+  "rules": [{
+    "description": "Apply snippet",
+    "enabled": true,
+    "expression": "http.host eq \"example.com\"",
+    "snippet_name": "my_snippet"
+  }]
+}
+```
+
+## Available APIs in Snippets
+
+### ✅ Supported
+- `fetch()` - HTTP requests (2-5 subrequests per plan)
+- `Request` / `Response` - Standard Web APIs
+- `URL` / `URLSearchParams` - URL manipulation
+- `Headers` - Header manipulation
+- `TextEncoder` / `TextDecoder` - Text encoding
+- `crypto.subtle` - Web Crypto API (hashing, signing)
+- `crypto.randomUUID()` - UUID generation
+
+### ❌ Not Supported in Snippets
+- `caches` API - Not available (use Workers)
+- `KV`, `D1`, `R2` - Storage APIs (use Workers)
+- `Durable Objects` - Stateful objects (use Workers)
+- `WebSocket` - WebSocket upgrades (use Workers)
+- `HTMLRewriter` - HTML parsing (use Workers)
+- `import` statements - No module imports
+- `addEventListener` - Use `export default { async fetch() {}` pattern
+
+## Snippet Structure
+```javascript
+export default {
+  async fetch(request) {
+    // Your logic here
+    const response = await fetch(request);
+    return response; // or modified response
+  }
+}
+```

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

@@ -0,0 +1,227 @@
+# Snippets Configuration Guide
+
+## Configuration Methods
+
+### 1. Dashboard (GUI)
+**Best for**: Quick tests, single snippets, visual rule building
+
+```
+1. Go to zone → Rules → Snippets
+2. Click "Create Snippet" or select template
+3. Enter snippet name (a-z, 0-9, _ only, cannot change later)
+4. Write JavaScript code (32KB max)
+5. Configure snippet rule:
+   - Expression Builder (visual) or Expression Editor (text)
+   - Use Ruleset Engine filter expressions
+6. Test with Preview/HTTP tabs
+7. Deploy or Save as Draft
+```
+
+### 2. REST API
+**Best for**: CI/CD, automation, programmatic management
+
+```bash
+# Create/update snippet
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
+  --request PUT \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --form "files=@example.js" \
+  --form "metadata={\"main_module\": \"example.js\"}"
+
+# Create snippet rule
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/snippet_rules" \
+  --request PUT \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "rules": [
+      {
+        "description": "Trigger snippet on /api paths",
+        "enabled": true,
+        "expression": "starts_with(http.request.uri.path, \"/api/\")",
+        "snippet_name": "api_snippet"
+      }
+    ]
+  }'
+
+# List snippets
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets" \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+
+# Delete snippet
+curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME" \
+  --request DELETE \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+### 3. Terraform
+**Best for**: Infrastructure-as-code, multi-zone deployments
+
+```hcl
+# Configure Terraform provider
+terraform {
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 4.0"
+    }
+  }
+}
+
+provider "cloudflare" {
+  api_token = var.cloudflare_api_token
+}
+
+# Create snippet
+resource "cloudflare_snippet" "security_headers" {
+  zone_id = var.zone_id
+  name    = "security_headers"
+  
+  main_module = "security_headers.js"
+  files {
+    name    = "security_headers.js"
+    content = file("${path.module}/snippets/security_headers.js")
+  }
+}
+
+# Create snippet rule
+resource "cloudflare_snippet_rules" "security_rules" {
+  zone_id = var.zone_id
+  
+  rules {
+    description  = "Apply security headers to all requests"
+    enabled      = true
+    expression   = "true"
+    snippet_name = cloudflare_snippet.security_headers.name
+  }
+}
+```
+
+### 4. Pulumi
+**Best for**: Multi-cloud IaC, TypeScript/Python/Go workflows
+
+```typescript
+import * as cloudflare from "@pulumi/cloudflare";
+import * as fs from "fs";
+
+// Create snippet
+const securitySnippet = new cloudflare.Snippet("security-headers", {
+  zoneId: zoneId,
+  name: "security_headers",
+  mainModule: "security_headers.js",
+  files: [{
+    name: "security_headers.js",
+    content: fs.readFileSync("./snippets/security_headers.js", "utf8"),
+  }],
+});
+
+// Create snippet rule
+const snippetRule = new cloudflare.SnippetRules("security-rules", {
+  zoneId: zoneId,
+  rules: [{
+    description: "Apply security headers",
+    enabled: true,
+    expression: "true",
+    snippetName: securitySnippet.name,
+  }],
+});
+```
+
+## Filter Expressions
+
+Snippets use Cloudflare's Ruleset Engine expression language to determine when to execute.
+
+### Common Expression Patterns
+
+```javascript
+// Host matching
+http.host eq "example.com"
+http.host in {"example.com" "www.example.com"}
+http.host contains "example"
+
+// Path matching
+http.request.uri.path eq "/api/users"
+starts_with(http.request.uri.path, "/api/")
+ends_with(http.request.uri.path, ".json")
+matches(http.request.uri.path, "^/api/v[0-9]+/")
+
+// Query parameters
+http.request.uri.query contains "debug=true"
+
+// Headers
+http.headers["user-agent"] contains "Mobile"
+http.headers["accept-language"] eq "en-US"
+
+// Cookies
+http.cookie contains "session="
+
+// Geolocation
+ip.geoip.country eq "US"
+ip.geoip.continent eq "EU"
+
+// Bot detection (requires Bot Management)
+cf.bot_management.score lt 30
+
+// Method
+http.request.method eq "POST"
+http.request.method in {"POST" "PUT" "PATCH"}
+
+// Combine with logical operators
+http.host eq "example.com" and starts_with(http.request.uri.path, "/api/")
+ip.geoip.country eq "US" or ip.geoip.country eq "CA"
+not http.headers["user-agent"] contains "bot"
+```
+
+### Expression Functions
+
+| Function | Example | Description |
+|----------|---------|-------------|
+| `starts_with()` | `starts_with(http.request.uri.path, "/api/")` | Check prefix |
+| `ends_with()` | `ends_with(http.request.uri.path, ".json")` | Check suffix |
+| `contains()` | `contains(http.headers["user-agent"], "Mobile")` | Check substring |
+| `matches()` | `matches(http.request.uri.path, "^/api/")` | Regex match |
+| `lower()` | `lower(http.host) eq "example.com"` | Convert to lowercase |
+| `upper()` | `upper(http.headers["x-api-key"])` | Convert to uppercase |
+| `len()` | `len(http.request.uri.path) gt 100` | String length |
+
+## Deployment Workflow
+
+### Development
+1. Write snippet code locally
+2. Test syntax with `node snippet.js` or TypeScript compiler
+3. Deploy to Dashboard or use API with `Save as Draft`
+4. Test with Preview/HTTP tabs in Dashboard
+5. Enable rule when ready
+
+### Production
+1. Store snippet code in version control
+2. Use Terraform/Pulumi for reproducible deployments
+3. Deploy to staging zone first
+4. Test with real traffic (use low-traffic subdomain)
+5. Apply to production zone
+6. Monitor with Analytics/Logpush
+
+## Limits & Requirements
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| Snippet size | 32 KB | Per snippet, compressed |
+| Snippet name | 64 chars | `a-z`, `0-9`, `_` only, immutable |
+| Snippets per zone | 20 | Soft limit, contact support for more |
+| Rules per zone | 20 | One rule per snippet typical |
+| Expression length | 4096 chars | Per rule expression |
+
+## Authentication
+
+### API Token (Recommended)
+```bash
+# Create token at: https://dash.cloudflare.com/profile/api-tokens
+# Required permissions: Zone.Snippets:Edit, Zone.Rules:Edit
+export CLOUDFLARE_API_TOKEN="your_token_here"
+```
+
+### API Key (Legacy)
+```bash
+export CLOUDFLARE_EMAIL="your@email.com"
+export CLOUDFLARE_API_KEY="your_global_api_key"
+```