@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

@@ -0,0 +1,188 @@
+# Binding Configuration Reference
+
+## Storage Bindings
+
+```jsonc
+{
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "..." }],
+  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "..." }],
+  "durable_objects": { "bindings": [{ "name": "MY_DO", "class_name": "MyDO" }] },
+  "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }],
+  "queues": { "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }] }
+}
+```
+
+**Create commands:**
+```bash
+npx wrangler kv namespace create MY_KV
+npx wrangler r2 bucket create my-bucket
+npx wrangler d1 create my-db
+npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
+npx wrangler queues create my-queue
+
+# List existing resources
+npx wrangler kv namespace list
+npx wrangler r2 bucket list
+npx wrangler d1 list
+npx wrangler vectorize list
+npx wrangler queues list
+```
+
+## Compute Bindings
+
+```jsonc
+{
+  "services": [{ 
+    "binding": "MY_SERVICE", 
+    "service": "other-worker",
+    "environment": "production"  // Optional: target specific env
+  }],
+  "ai": { "binding": "AI" },
+  "browser": { "binding": "BROWSER" },
+  "workflows": [{ "binding": "MY_WORKFLOW", "name": "my-workflow" }]
+}
+```
+
+**Create workflows:**
+```bash
+npx wrangler workflows create my-workflow
+```
+
+## Platform Bindings
+
+```jsonc
+{
+  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }],
+  "mtls_certificates": [{ "binding": "MY_CERT", "certificate_id": "..." }],
+  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "..." }],
+  "unsafe": {
+    "bindings": [{ "name": "RATE_LIMITER", "type": "ratelimit", "namespace_id": "..." }]
+  }
+}
+```
+
+## Configuration Bindings
+
+```jsonc
+{
+  "vars": {
+    "API_URL": "https://api.example.com",
+    "MAX_RETRIES": "3"
+  },
+  "text_blobs": { "MY_TEXT": "./data/template.html" },
+  "data_blobs": { "MY_DATA": "./data/config.bin" },
+  "wasm_modules": { "MY_WASM": "./build/module.wasm" }
+}
+```
+
+**Secrets (never in config):**
+```bash
+npx wrangler secret put API_KEY
+```
+
+## Environment-Specific Configuration
+
+```jsonc
+{
+  "name": "my-worker",
+  "vars": { "ENV": "production" },
+  "kv_namespaces": [{ "binding": "CACHE", "id": "prod-kv-id" }],
+  
+  "env": {
+    "staging": {
+      "vars": { "ENV": "staging" },
+      "kv_namespaces": [{ "binding": "CACHE", "id": "staging-kv-id" }]
+    }
+  }
+}
+```
+
+**Deploy:**
+```bash
+npx wrangler deploy              # Production
+npx wrangler deploy --env staging
+```
+
+## Local Development
+
+```jsonc
+{
+  "kv_namespaces": [{
+    "binding": "MY_KV",
+    "id": "prod-id",
+    "preview_id": "dev-id"  // Used in wrangler dev
+  }]
+}
+```
+
+**Or use remote:**
+```bash
+npx wrangler dev --remote  # Uses production bindings
+```
+
+## Complete Example
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  
+  "vars": { "API_URL": "https://api.example.com" },
+  "kv_namespaces": [{ "binding": "CACHE", "id": "abc123" }],
+  "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-assets" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
+  "services": [{ "binding": "AUTH", "service": "auth-worker" }],
+  "ai": { "binding": "AI" }
+}
+```
+
+## Binding-Specific Configuration
+
+### Durable Objects with Class Export
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "COUNTER", "class_name": "Counter", "script_name": "my-worker" }
+    ]
+  }
+}
+```
+
+```typescript
+// In same Worker or script_name Worker
+export class Counter {
+  constructor(private state: DurableObjectState, private env: Env) {}
+  async fetch(request: Request) { /* ... */ }
+}
+```
+
+### Queue Consumers
+
+```jsonc
+{
+  "queues": {
+    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
+    "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }]
+  }
+}
+```
+
+Queue consumer handler: `export default { async queue(batch, env) { /* process batch.messages */ } }`
+
+## Key Points
+
+- **64 binding limit** (all types combined)
+- **Secrets**: Always use `wrangler secret put`, never commit
+- **Types**: Run `npx wrangler types` after config changes
+- **Environments**: Use `env` field for staging/production variants
+- **Development**: Use `preview_id` or `--remote` flag
+- **IDs vs Names**: Some bindings use `id` (KV, D1), others use `name` (R2, Queues)
+
+## See Also
+
+- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)

package/skills/cloudflare-deploy/references/bindings/gotchas.md

@@ -0,0 +1,208 @@
+# Binding Gotchas and Troubleshooting
+
+## Critical: Global Scope Mutation
+
+### ❌ THE #1 GOTCHA: Caching env in Global Scope
+
+```typescript
+// ❌ DANGEROUS - env cached at deploy time
+const apiKey = env.API_KEY;  // ERROR: env not available in global scope
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // Uses undefined or stale value!
+  }
+}
+```
+
+**Why it breaks:**
+- `env` not available in global scope
+- If using workarounds, secrets may not update without redeployment
+- Leads to "Cannot read property 'X' of undefined" errors
+
+**✅ Always access env per-request:**
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const apiKey = env.API_KEY;  // Fresh every request
+  }
+}
+```
+
+## Common Errors
+
+### "env.MY_KV is undefined"
+
+**Cause:** Name mismatch or not configured  
+**Solution:** Check wrangler.jsonc (case-sensitive), run `npx wrangler types`, verify `npx wrangler kv namespace list`
+
+### "Property 'MY_KV' does not exist on type 'Env'"
+
+**Cause:** Types not generated  
+**Solution:** `npx wrangler types`
+
+### "preview_id is required for --remote"
+
+**Cause:** Missing preview binding  
+**Solution:** Add `"preview_id": "dev-id"` or use `npx wrangler dev` (local mode)
+
+### "Secret updated but Worker still uses old value"
+
+**Cause:** Cached in global scope or not redeployed  
+**Solution:** Avoid global caching, redeploy after secret change
+
+### "KV get() returns null for existing key"
+
+**Cause:** Eventual consistency (60s), wrong namespace, wrong environment  
+**Solution:**
+```bash
+# Check key exists
+npx wrangler kv key get --binding=MY_KV "your-key"
+
+# Verify namespace ID
+npx wrangler kv namespace list
+
+# Check environment
+npx wrangler deployments list
+```
+
+### "D1 database not found"
+
+**Solution:** `npx wrangler d1 list`, verify ID in wrangler.jsonc
+
+### "Service binding returns 'No such service'"
+
+**Cause:** Target Worker not deployed, name mismatch, environment mismatch  
+**Solution:**
+```bash
+# List deployed Workers
+npx wrangler deployments list --name=target-worker
+
+# Check service binding config
+cat wrangler.jsonc | grep -A2 services
+
+# Deploy target first
+cd ../target-worker && npx wrangler deploy
+```
+
+### "Rate limit exceeded" on KV writes
+
+**Cause:** >1 write/second per key  
+**Solution:** Use different keys, Durable Objects, or Queues
+
+## Type Safety Gotchas
+
+### Missing @cloudflare/workers-types
+
+**Error:** `Cannot find name 'Request'`  
+**Solution:** `npm install -D @cloudflare/workers-types`, add to tsconfig.json `"types"`
+
+### Binding Type Mismatches
+
+```typescript
+// ❌ Wrong - KV returns string | null
+const value: string = await env.MY_KV.get('key');
+
+// ✅ Handle null
+const value = await env.MY_KV.get('key');
+if (!value) return new Response('Not found', { status: 404 });
+```
+
+## Environment Gotchas
+
+### Wrong Environment Deployed
+
+**Solution:** Check `npx wrangler deployments list`, use `--env` flag
+
+### Secrets Not Per-Environment
+
+**Solution:** Set per environment: `npx wrangler secret put API_KEY --env staging`
+
+## Development Gotchas
+
+**wrangler dev vs deploy:**
+- dev: Uses `preview_id` or local bindings, secrets not available
+- deploy: Uses production `id`, secrets available
+
+**Access secrets in dev:** `npx wrangler dev --remote`  
+**Persist local data:** `npx wrangler dev --persist`
+
+## Performance Gotchas
+
+### Sequential Binding Calls
+
+```typescript
+// ❌ Slow
+const user = await env.DB.prepare('...').first();
+const config = await env.MY_KV.get('config');
+
+// ✅ Parallel
+const [user, config] = await Promise.all([
+  env.DB.prepare('...').first(),
+  env.MY_KV.get('config')
+]);
+```
+
+## Security Gotchas
+
+**❌ Secrets in logs:** `console.log('Key:', env.API_KEY)` - visible in dashboard  
+**✅** `console.log('Key:', env.API_KEY ? '***' : 'missing')`
+
+**❌ Exposing env:** `return Response.json(env)` - exposes all bindings  
+**✅** Never return env object in responses
+
+## Limits Reference
+
+| Resource | Limit | Impact | Plan |
+|----------|-------|--------|------|
+| **Bindings per Worker** | 64 total | All binding types combined | All |
+| **Environment variables** | 64 max, 5KB each | Per Worker | All |
+| **Secret size** | 1KB | Per secret | All |
+| **KV key size** | 512 bytes | UTF-8 encoded | All |
+| **KV value size** | 25 MB | Per value | All |
+| **KV writes per key** | 1/second | Per key; exceeding = 429 error | All |
+| **KV list() results** | 1000 keys | Per call; use cursor for more | All |
+| **KV operations** | 1000 reads/day | Free tier only | Free |
+| **R2 object size** | 5 TB | Per object | All |
+| **R2 operations** | 1M Class A/month free | Writes | All |
+| **D1 database size** | 10 GB | Per database | All |
+| **D1 rows per query** | 100,000 | Result set limit | All |
+| **D1 databases** | 10 | Free tier | Free |
+| **Queue batch size** | 100 messages | Per consumer batch | All |
+| **Queue message size** | 128 KB | Per message | All |
+| **Service binding calls** | Unlimited | Counts toward CPU time | All |
+| **Durable Objects** | 1M requests/month free | First 1M | Free |
+
+## Debugging Tips
+
+```bash
+# Check configuration
+npx wrangler deploy --dry-run       # Validate config without deploying
+npx wrangler kv namespace list      # List KV namespaces
+npx wrangler secret list            # List secrets (not values)
+npx wrangler deployments list       # Recent deployments
+
+# Inspect bindings
+npx wrangler kv key list --binding=MY_KV
+npx wrangler kv key get --binding=MY_KV "key-name"
+npx wrangler r2 object get my-bucket/file.txt
+npx wrangler d1 execute my-db --command="SELECT * FROM sqlite_master"
+
+# Test locally
+npx wrangler dev                  # Local mode
+npx wrangler dev --remote         # Production bindings
+npx wrangler dev --persist        # Persist data across restarts
+
+# Verify types
+npx wrangler types
+cat .wrangler/types/runtime.d.ts | grep "interface Env"
+
+# Debug specific binding issues
+npx wrangler tail                 # Stream logs in real-time
+npx wrangler tail --format=pretty # Formatted logs
+```
+
+## See Also
+
+- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
+- [Wrangler Commands](https://developers.cloudflare.com/workers/wrangler/commands/)

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

@@ -0,0 +1,200 @@
+# Binding Patterns and Best Practices
+
+## Service Binding Patterns
+
+### RPC via Service Bindings
+
+```typescript
+// auth-worker
+export default {
+  async fetch(request: Request, env: Env) {
+    const token = request.headers.get('Authorization');
+    return new Response(JSON.stringify({ valid: await validateToken(token) }));
+  }
+}
+
+// api-worker
+const response = await env.AUTH_SERVICE.fetch(
+  new Request('https://fake-host/validate', {
+    headers: { 'Authorization': token }
+  })
+);
+```
+
+**Why RPC?** Zero latency (same datacenter), no DNS, free, type-safe.
+
+**HTTP vs Service:**
+```typescript
+// ❌ HTTP (slow, paid, cross-region latency)
+await fetch('https://auth-worker.example.com/validate');
+
+// ✅ Service binding (fast, free, same isolate)
+await env.AUTH_SERVICE.fetch(new Request('https://fake-host/validate'));
+```
+
+**URL doesn't matter:** Service bindings ignore hostname/protocol, routing happens via binding name.
+
+### Typed Service RPC
+
+```typescript
+// shared-types.ts
+export interface AuthRequest { token: string; }
+export interface AuthResponse { valid: boolean; userId?: string; }
+
+// auth-worker
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const body: AuthRequest = await request.json();
+    const response: AuthResponse = { valid: true, userId: '123' };
+    return Response.json(response);
+  }
+}
+
+// api-worker
+const response = await env.AUTH_SERVICE.fetch(
+  new Request('https://fake/validate', {
+    method: 'POST',
+    body: JSON.stringify({ token } satisfies AuthRequest)
+  })
+);
+const data: AuthResponse = await response.json();
+```
+
+## Secrets Management
+
+```bash
+# Set secret
+npx wrangler secret put API_KEY
+cat api-key.txt | npx wrangler secret put API_KEY
+npx wrangler secret put API_KEY --env staging
+```
+
+```typescript
+// Use secret
+const response = await fetch('https://api.example.com', {
+  headers: { 'Authorization': `Bearer ${env.API_KEY}` }
+});
+```
+
+**Never commit secrets:**
+```jsonc
+// ❌ NEVER
+{ "vars": { "API_KEY": "sk_live_abc123" } }
+```
+
+## Testing with Mock Bindings
+
+### Vitest Mock
+
+```typescript
+import { vi } from 'vitest';
+
+const mockKV: KVNamespace = {
+  get: vi.fn(async (key) => key === 'test' ? 'value' : null),
+  put: vi.fn(async () => {}),
+  delete: vi.fn(async () => {}),
+  list: vi.fn(async () => ({ keys: [], list_complete: true, cursor: '' })),
+  getWithMetadata: vi.fn(),
+} as unknown as KVNamespace;
+
+const mockEnv: Env = { MY_KV: mockKV };
+const mockCtx: ExecutionContext = {
+  waitUntil: vi.fn(),
+  passThroughOnException: vi.fn(),
+};
+
+const response = await worker.fetch(
+  new Request('http://localhost/test'),
+  mockEnv,
+  mockCtx
+);
+```
+
+## Binding Access Patterns
+
+### Lazy Access
+
+```typescript
+// ✅ Access only when needed
+if (url.pathname === '/cached') {
+  const cached = await env.MY_KV.get('data');
+  if (cached) return new Response(cached);
+}
+```
+
+### Parallel Access
+
+```typescript
+// ✅ Parallelize independent calls
+const [user, config, cache] = await Promise.all([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first(),
+  env.MY_KV.get('config'),
+  env.CACHE.get('data')
+]);
+```
+
+## Storage Selection
+
+### KV: CDN-Backed Reads
+
+```typescript
+const config = await env.MY_KV.get('app-config', { type: 'json' });
+```
+
+**Use when:** Read-heavy, <25MB, global distribution, eventual consistency OK  
+**Latency:** <10ms reads (cached), writes eventually consistent (60s)
+
+### D1: Relational Queries
+
+```typescript
+const results = await env.DB.prepare(`
+  SELECT u.name, COUNT(o.id) FROM users u
+  LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id
+`).all();
+```
+
+**Use when:** Relational data, JOINs, ACID transactions  
+**Limits:** 10GB database size, 100k rows per query
+
+### R2: Large Objects
+
+```typescript
+const object = await env.MY_BUCKET.get('large-file.zip');
+return new Response(object.body);
+```
+
+**Use when:** Files >25MB, S3-compatible API needed  
+**Limits:** 5TB per object, unlimited storage
+
+### Durable Objects: Coordination
+
+```typescript
+const id = env.COUNTER.idFromName('global');
+const stub = env.COUNTER.get(id);
+await stub.fetch(new Request('https://fake/increment'));
+```
+
+**Use when:** Strong consistency, real-time coordination, WebSocket state  
+**Guarantees:** Single-threaded execution, transactional storage
+
+## Anti-Patterns
+
+**❌ Hardcoding credentials:** `const apiKey = 'sk_live_abc123'`  
+**✅** `npx wrangler secret put API_KEY`
+
+**❌ Using REST API:** `fetch('https://api.cloudflare.com/.../kv/...')`  
+**✅** `env.MY_KV.get('key')`
+
+**❌ Polling storage:** `setInterval(() => env.KV.get('config'), 1000)`  
+**✅** Use Durable Objects for real-time state
+
+**❌ Large data in vars:** `{ "vars": { "HUGE_CONFIG": "..." } }` (5KB max)  
+**✅** `env.MY_KV.put('config', data)`
+
+**❌ Caching env globally:** `const apiKey = env.API_KEY` outside fetch()  
+**✅** Access `env.API_KEY` per-request inside fetch()
+
+## See Also
+
+- [Service Bindings Docs](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/)
+- [Miniflare Testing](https://miniflare.dev/)

package/skills/cloudflare-deploy/references/bot-management/README.md

@@ -0,0 +1,94 @@
+# Cloudflare Bot Management
+
+Enterprise-grade bot detection, protection, and mitigation using ML/heuristics, bot scores, JavaScript detections, and verified bot handling.
+
+## Overview
+
+Bot Management provides multi-tier protection:
+- **Free (Bot Fight Mode)**: Auto-blocks definite bots, no config
+- **Pro/Business (Super Bot Fight Mode)**: Configurable actions, static resource protection, analytics groupings
+- **Enterprise (Bot Management)**: Granular 1-99 scores, WAF integration, JA3/JA4 fingerprinting, Workers API, Advanced Analytics
+
+## Quick Start
+
+```txt
+# Dashboard: Security > Bots
+# Enterprise: Deploy rule template
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block
+(cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge
+```
+
+## What Do You Need?
+
+```txt
+├─ Initial setup → configuration.md
+│   ├─ Free tier → "Bot Fight Mode"
+│   ├─ Pro/Business → "Super Bot Fight Mode"
+│   └─ Enterprise → "Bot Management for Enterprise"
+├─ Workers API integration → api.md
+├─ WAF rules → patterns.md
+├─ Debugging → gotchas.md
+└─ Analytics → api.md#bot-analytics
+```
+
+## Reading Order
+
+| Task | Files to Read |
+|------|---------------|
+| Enable bot protection | README → configuration.md |
+| Workers bot detection | README → api.md |
+| WAF rule templates | README → patterns.md |
+| Debug bot issues | gotchas.md |
+| Advanced analytics | api.md#bot-analytics |
+
+## Core Concepts
+
+**Bot Scores**: 1-99 (1 = definitely automated, 99 = definitely human). Threshold: <30 indicates bot traffic. Enterprise gets granular 1-99; Pro/Business get groupings only.
+
+**Detection Engines**: Heuristics (known fingerprints, assigns score=1), ML (majority of detections, supervised learning on billions of requests), Anomaly Detection (optional, baseline traffic analysis), JavaScript Detections (headless browser detection).
+
+**Verified Bots**: Allowlisted good bots (search engines, AI crawlers) verified via reverse DNS or Web Bot Auth. Access via `cf.bot_management.verified_bot` or `cf.verified_bot_category`.
+
+## Platform Limits
+
+| Plan | Bot Scores | JA3/JA4 | Custom Rules | Analytics Retention |
+|------|------------|---------|--------------|---------------------|
+| Free | No (auto-block only) | No | 5 | N/A (no analytics) |
+| Pro/Business | Groupings only | No | 20/100 | 30 days (72h at a time) |
+| Enterprise | 1-99 granular | Yes | 1,000+ | 30 days (1 week at a time) |
+
+## Basic Patterns
+
+```typescript
+// Workers: Check bot score
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const botScore = request.cf?.botManagement?.score;
+    if (botScore && botScore < 30 && !request.cf?.botManagement?.verifiedBot) {
+      return new Response('Bot detected', { status: 403 });
+    }
+    return fetch(request);
+  }
+};
+```
+
+```txt
+# WAF: Block definite bots
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot)
+
+# WAF: Protect sensitive endpoints
+(cf.bot_management.score lt 50 and http.request.uri.path in {"/login" "/checkout"} and not cf.bot_management.verified_bot)
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Product tiers, WAF rule setup, JavaScript Detections, ML auto-updates
+- [api.md](./api.md) - Workers BotManagement interface, WAF fields, JA4 Signals
+- [patterns.md](./patterns.md) - E-commerce, API protection, mobile app allowlisting, SEO-friendly handling
+- [gotchas.md](./gotchas.md) - False positives/negatives, score=0 issues, JSD limitations, CSP requirements
+
+## See Also
+
+- [waf](../waf/) - WAF custom rules for bot enforcement
+- [workers](../workers/) - Workers request.cf.botManagement API
+- [api-shield](../api-shield/) - API-specific bot protection