@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

@@ -0,0 +1,81 @@
+# C3 Generated Configuration
+
+## Output Structure
+
+```
+my-app/
+├── src/index.ts          # Worker entry point
+├── wrangler.jsonc        # Cloudflare config
+├── package.json          # Scripts
+├── tsconfig.json
+└── .gitignore
+```
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json",
+  "name": "my-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-01-27"
+}
+```
+
+## Binding Placeholders
+
+C3 generates **placeholder IDs** that must be replaced before deploy:
+
+```jsonc
+{
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "placeholder_kv_id" }],
+  "d1_databases": [{ "binding": "DB", "database_id": "00000000-..." }]
+}
+```
+
+**Replace with real IDs:**
+```bash
+npx wrangler kv namespace create MY_KV   # Returns real ID
+npx wrangler d1 create my-database       # Returns real database_id
+```
+
+**Deployment error if not replaced:**
+```
+Error: Invalid KV namespace ID "placeholder_kv_id"
+```
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "cf-typegen": "wrangler types"
+  }
+}
+```
+
+## Type Generation
+
+Run after adding bindings:
+```bash
+npm run cf-typegen
+```
+
+Generates `.wrangler/types/runtime.d.ts`:
+```typescript
+interface Env {
+  MY_KV: KVNamespace;
+  DB: D1Database;
+}
+```
+
+## Post-Creation Checklist
+
+1. Review `wrangler.jsonc` - check name, compatibility_date
+2. Replace placeholder binding IDs with real resource IDs
+3. Run `npm run cf-typegen`
+4. Test: `npm run dev`
+5. Deploy: `npm run deploy`
+6. Add secrets: `npx wrangler secret put SECRET_NAME`

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

@@ -0,0 +1,92 @@
+# C3 Troubleshooting
+
+## Deployment Issues
+
+### Placeholder IDs
+
+**Error:** "Invalid namespace ID"  
+**Fix:** Replace placeholders in wrangler.jsonc with real IDs:
+```bash
+npx wrangler kv namespace create MY_KV  # Get real ID
+```
+
+### Authentication
+
+**Error:** "Not authenticated"  
+**Fix:** `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`
+
+### Name Conflict
+
+**Error:** "Worker already exists"  
+**Fix:** Change `name` in wrangler.jsonc
+
+## Platform Selection
+
+| Need | Platform |
+|------|----------|
+| Git integration, branch previews | `--platform=pages` |
+| Durable Objects, D1, Queues | Workers (default) |
+
+Wrong platform? Recreate with correct `--platform` flag.
+
+## TypeScript Issues
+
+**"Cannot find name 'KVNamespace'"**
+```bash
+npm run cf-typegen  # Regenerate types
+# Restart TS server in editor
+```
+
+**Missing types after config change:** Re-run `npm run cf-typegen`
+
+## Package Manager
+
+**Multiple lockfiles causing issues:**
+```bash
+rm pnpm-lock.yaml  # If using npm
+rm package-lock.json  # If using pnpm
+```
+
+## CI/CD
+
+**CI hangs on prompts:**
+```bash
+npm create cloudflare@latest my-app -- \
+  --type=hello-world --lang=ts --no-git --no-deploy
+```
+
+**Auth in CI:**
+```yaml
+env:
+  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+## Framework-Specific
+
+| Framework | Issue | Fix |
+|-----------|-------|-----|
+| Next.js | create-next-app failed | `npm cache clean --force`, retry |
+| Astro | Adapter missing | Install `@astrojs/cloudflare` |
+| Remix | Module errors | Update `@remix-run/cloudflare*` |
+
+## Compatibility Date
+
+**"Feature X requires compatibility_date >= ..."**  
+**Fix:** Update `compatibility_date` in wrangler.jsonc to today's date
+
+## Node.js Version
+
+**"Node.js version not supported"**  
+**Fix:** Install Node.js 18+ (`nvm install 20`)
+
+## Quick Reference
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Invalid namespace ID | Placeholder binding | Create resource, update config |
+| Not authenticated | No login | `npx wrangler login` |
+| Cannot find KVNamespace | Missing types | `npm run cf-typegen` |
+| Worker already exists | Name conflict | Change `name` |
+| CI hangs | Missing flags | Add --type, --lang, --no-deploy |
+| Template not found | Bad name | Check cloudflare/templates |

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

@@ -0,0 +1,82 @@
+# C3 Usage Patterns
+
+## Quick Workflows
+
+```bash
+# TypeScript API Worker
+npm create cloudflare@latest my-api -- --type=hello-world --lang=ts --deploy
+
+# Next.js on Pages
+npm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts --deploy
+
+# Astro static site  
+npm create cloudflare@latest my-blog -- --type=web-app --framework=astro --platform=pages --ts
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+- name: Deploy
+  run: npm run deploy
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+**Non-interactive requires:**
+```bash
+--type=<value>       # Required
+--no-git             # Recommended (CI already in git)
+--no-deploy          # Deploy separately with secrets
+--framework=<value>  # For web-app
+--ts / --no-ts       # Required
+```
+
+## Monorepo
+
+C3 detects workspace config (`package.json` workspaces or `pnpm-workspace.yaml`).
+
+```bash
+cd packages/
+npm create cloudflare@latest my-worker -- --type=hello-world --lang=ts --no-deploy
+```
+
+## Custom Templates
+
+```bash
+# GitHub repo
+npm create cloudflare@latest -- --template=username/repo
+npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi
+
+# Local path
+npm create cloudflare@latest my-app -- --template=../my-template
+```
+
+**Template requires `c3.config.json`:**
+```json
+{
+  "name": "my-template",
+  "category": "hello-world",
+  "copies": [{ "path": "src/" }, { "path": "wrangler.jsonc" }],
+  "transforms": [{ "path": "package.json", "jsonc": { "name": "{{projectName}}" }}]
+}
+```
+
+## Existing Projects
+
+```bash
+# Add Cloudflare to existing Worker
+npm create cloudflare@latest . -- --type=pre-existing --existing-script=./dist/index.js
+
+# Add to existing framework app
+npm create cloudflare@latest . -- --type=web-app --framework=next --platform=pages --ts
+```
+
+## Post-Creation Checklist
+
+1. Review `wrangler.jsonc` - set `compatibility_date`, verify `name`
+2. Create bindings: `wrangler kv namespace create`, `wrangler d1 create`, `wrangler r2 bucket create`
+3. Generate types: `npm run cf-typegen`
+4. Test: `npm run dev`
+5. Deploy: `npm run deploy`
+6. Set secrets: `wrangler secret put SECRET_NAME`

package/skills/cloudflare-deploy/references/cache-reserve/README.md

@@ -0,0 +1,147 @@
+# Cloudflare Cache Reserve
+
+**Persistent cache storage built on R2 for long-term content retention**
+
+## Smart Shield Integration
+
+Cache Reserve is part of **Smart Shield**, Cloudflare's comprehensive security and performance suite:
+
+- **Smart Shield Advanced tier**: Includes 2TB Cache Reserve storage
+- **Standalone purchase**: Available separately if not using Smart Shield
+- **Migration**: Existing standalone customers can migrate to Smart Shield bundles
+
+**Decision**: Already on Smart Shield Advanced? Cache Reserve is included. Otherwise evaluate standalone purchase vs Smart Shield upgrade.
+
+## Overview
+
+Cache Reserve is Cloudflare's persistent, large-scale cache storage layer built on R2. It acts as the ultimate upper-tier cache, storing cacheable content for extended periods (30+ days) to maximize cache hits, reduce origin egress fees, and shield origins from repeated requests for long-tail content.
+
+## Core Concepts
+
+### What is Cache Reserve?
+
+- **Persistent storage layer**: Built on R2, sits above tiered cache hierarchy
+- **Long-term retention**: 30-day default retention, extended on each access
+- **Automatic operation**: Works seamlessly with existing CDN, no code changes required
+- **Origin shielding**: Dramatically reduces origin egress by serving cached content longer
+- **Usage-based pricing**: Pay only for storage + read/write operations
+
+### Cache Hierarchy
+
+```
+Visitor Request
+    ↓
+Lower-Tier Cache (closest to visitor)
+    ↓ (on miss)
+Upper-Tier Cache (closest to origin)
+    ↓ (on miss)
+Cache Reserve (R2 persistent storage)
+    ↓ (on miss)
+Origin Server
+```
+
+### How It Works
+
+1. **On cache miss**: Content fetched from origin �� written to Cache Reserve + edge caches simultaneously
+2. **On edge eviction**: Content may be evicted from edge cache but remains in Cache Reserve
+3. **On subsequent request**: If edge cache misses but Cache Reserve hits → content restored to edge caches
+4. **Retention**: Assets remain in Cache Reserve for 30 days since last access (configurable via TTL)
+
+## When to Use Cache Reserve
+
+```
+Need persistent caching?
+├─ High origin egress costs → Cache Reserve ✓
+├─ Long-tail content (archives, media libraries) → Cache Reserve ✓
+├─ Already using Smart Shield Advanced → Included! ✓
+├─ Video streaming with seeking (range requests) → ✗ Not supported
+├─ Dynamic/personalized content → ✗ Use edge cache only
+├─ Need per-request cache control from Workers → ✗ Use R2 directly
+└─ Frequently updated content (< 10hr lifetime) → ✗ Not eligible
+```
+
+## Asset Eligibility
+
+Cache Reserve only stores assets meeting **ALL** criteria:
+
+- Cacheable per Cloudflare's standard rules
+- Minimum 10-hour TTL (36000 seconds)
+- `Content-Length` header present
+- Original files only (not transformed images)
+
+### Eligibility Checklist
+
+Use this checklist to verify if an asset is eligible:
+
+- [ ] Zone has Cache Reserve enabled
+- [ ] Zone has Tiered Cache enabled (required)
+- [ ] Asset TTL ≥ 10 hours (36,000 seconds)
+- [ ] `Content-Length` header present on origin response
+- [ ] No `Set-Cookie` header (or uses private directive)
+- [ ] `Vary` header is NOT `*` (can be `Accept-Encoding`)
+- [ ] Not an image transformation variant (original images OK)
+- [ ] Not a range request (no HTTP 206 support)
+- [ ] Not O2O (Orange-to-Orange) proxied request
+
+**All boxes must be checked for Cache Reserve eligibility.**
+
+### Not Eligible
+
+- Assets with TTL < 10 hours
+- Responses without `Content-Length` header
+- Image transformation variants (original images are eligible)
+- Responses with `Set-Cookie` headers
+- Responses with `Vary: *` header
+- Assets from R2 public buckets on same zone
+- O2O (Orange-to-Orange) setup requests
+- **Range requests** (video seeking, partial content downloads)
+
+## Quick Start
+
+```bash
+# Enable via Dashboard
+https://dash.cloudflare.com/caching/cache-reserve
+# Click "Enable Storage Sync" or "Purchase" button
+```
+
+**Prerequisites:**
+- Paid Cache Reserve plan or Smart Shield Advanced required
+- Tiered Cache required for optimal performance
+
+## Essential Commands
+
+```bash
+# Check Cache Reserve status
+curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# Enable Cache Reserve
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+
+# Check asset cache status
+curl -I https://example.com/asset.jpg | grep -i cache
+```
+
+## In This Reference
+
+| Task | Files |
+|------|-------|
+| Evaluate if Cache Reserve fits your use case | README.md (this file) |
+| Enable Cache Reserve for your zone | README.md + [configuration.md](./configuration.md) |
+| Use with Workers (understand limitations) | [api.md](./api.md) |
+| Setup via SDKs or IaC (TypeScript, Python, Terraform) | [configuration.md](./configuration.md) |
+| Optimize costs and debug issues | [patterns.md](./patterns.md) + [gotchas.md](./gotchas.md) |
+| Understand eligibility and troubleshoot | [gotchas.md](./gotchas.md) → [patterns.md](./patterns.md) |
+
+**Files:**
+- [configuration.md](./configuration.md) - Setup, API, SDKs, and Cache Rules
+- [api.md](./api.md) - Purging, monitoring, Workers integration
+- [patterns.md](./patterns.md) - Best practices, cost optimization, debugging
+- [gotchas.md](./gotchas.md) - Common issues, limitations, troubleshooting
+
+## See Also
+- [r2](../r2/) - Cache Reserve built on R2 storage
+- [workers](../workers/) - Workers integration with Cache API

package/skills/cloudflare-deploy/references/cache-reserve/api.md

@@ -0,0 +1,194 @@
+# Cache Reserve API
+
+## Workers Integration
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ CRITICAL: Workers Cache API ≠ Cache Reserve                   │
+│                                                                │
+│ • Workers caches.default / cache.put() → edge cache ONLY      │
+│ • Cache Reserve → zone-level setting, automatic, no per-req   │
+│ • You CANNOT selectively write to Cache Reserve from Workers  │
+│ • Cache Reserve works with standard fetch(), not cache.put()  │
+└────────────────────────────────────────────────────────────────┘
+```
+
+Cache Reserve is a **zone-level configuration**, not a per-request API. It works automatically when enabled for the zone:
+
+### Standard Fetch (Recommended)
+
+```typescript
+// Cache Reserve works automatically via standard fetch
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Standard fetch uses Cache Reserve automatically
+    return await fetch(request);
+  }
+};
+```
+
+### Cache API Limitations
+
+**IMPORTANT**: `cache.put()` is **NOT compatible** with Cache Reserve or Tiered Cache.
+
+```typescript
+// ❌ WRONG: cache.put() bypasses Cache Reserve
+const cache = caches.default;
+let response = await cache.match(request);
+if (!response) {
+  response = await fetch(request);
+  await cache.put(request, response.clone()); // Bypasses Cache Reserve!
+}
+
+// ✅ CORRECT: Use standard fetch for Cache Reserve compatibility
+return await fetch(request);
+
+// ✅ CORRECT: Use Cache API only for custom cache namespaces
+const customCache = await caches.open('my-custom-cache');
+let response = await customCache.match(request);
+if (!response) {
+  response = await fetch(request);
+  await customCache.put(request, response.clone()); // Custom cache OK
+}
+```
+
+## Purging and Cache Management
+
+### Purge by URL (Instant)
+
+```typescript
+// Purge specific URL from Cache Reserve immediately
+const purgeCacheReserveByURL = async (
+  zoneId: string,
+  apiToken: string,
+  urls: string[]
+) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ files: urls })
+    }
+  );
+  return await response.json();
+};
+
+// Example usage
+await purgeCacheReserveByURL('zone123', 'token456', [
+  'https://example.com/image.jpg',
+  'https://example.com/video.mp4'
+]);
+```
+
+### Purge by Tag/Host/Prefix (Revalidation)
+
+```typescript
+// Purge by cache tag - forces revalidation, not immediate removal
+await fetch(
+  `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ tags: ['tag1', 'tag2'] })
+  }
+);
+```
+
+**Purge behavior:**
+- **By URL**: Immediate removal from Cache Reserve + edge cache
+- **By tag/host/prefix**: Revalidation only, assets remain in storage (costs continue)
+
+### Clear All Cache Reserve Data
+
+```typescript
+// Requires Cache Reserve OFF first
+await fetch(
+  `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve_clear`,
+  { method: 'POST', headers: { 'Authorization': `Bearer ${apiToken}` } }
+);
+
+// Check status: GET same endpoint returns { state: "In-progress" | "Completed" }
+```
+
+**Process**: Disable Cache Reserve → Call clear endpoint → Wait up to 24hr → Re-enable
+
+## Monitoring and Analytics
+
+### Dashboard Analytics
+
+Navigate to **Caching > Cache Reserve** to view:
+
+- **Egress Savings**: Total bytes served from Cache Reserve vs origin egress cost saved
+- **Requests Served**: Cache Reserve hits vs misses breakdown
+- **Storage Used**: Current GB stored in Cache Reserve (billed monthly)
+- **Operations**: Class A (writes) and Class B (reads) operation counts
+- **Cost Tracking**: Estimated monthly costs based on current usage
+
+### Logpush Integration
+
+```typescript
+// Logpush field: CacheReserveUsed (boolean) - filter for Cache Reserve hits
+// Query Cache Reserve hits in analytics
+const logpushQuery = `
+  SELECT 
+    ClientRequestHost, 
+    COUNT(*) as requests, 
+    SUM(EdgeResponseBytes) as bytes_served,
+    COUNT(CASE WHEN CacheReserveUsed = true THEN 1 END) as cache_reserve_hits,
+    COUNT(CASE WHEN CacheReserveUsed = false THEN 1 END) as cache_reserve_misses
+  FROM http_requests 
+  WHERE Timestamp >= NOW() - INTERVAL '24 hours'
+  GROUP BY ClientRequestHost 
+  ORDER BY requests DESC
+`;
+
+// Filter only Cache Reserve hits
+const crHitsQuery = `
+  SELECT ClientRequestHost, COUNT(*) as requests, SUM(EdgeResponseBytes) as bytes
+  FROM http_requests 
+  WHERE CacheReserveUsed = true AND Timestamp >= NOW() - INTERVAL '7 days'
+  GROUP BY ClientRequestHost 
+  ORDER BY bytes DESC
+`;
+```
+
+### GraphQL Analytics
+
+```graphql
+query CacheReserveAnalytics($zoneTag: string, $since: string, $until: string) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpRequests1dGroups(
+        filter: { datetime_geq: $since, datetime_leq: $until }
+        limit: 1000
+      ) {
+        dimensions { date }
+        sum {
+          cachedBytes
+          cachedRequests
+          bytes
+          requests
+        }
+      }
+    }
+  }
+}
+```
+
+## Pricing
+
+```typescript
+// Storage: $0.015/GB-month | Class A (writes): $4.50/M | Class B (reads): $0.36/M
+// Cache miss: 1A + 1B | Cache hit: 1B | Assets >1GB: proportionally more ops
+```
+
+## See Also
+
+- [README](./README.md) - Overview and core concepts
+- [Configuration](./configuration.md) - Setup and Cache Rules
+- [Patterns](./patterns.md) - Best practices and optimization
+- [Gotchas](./gotchas.md) - Common issues and troubleshooting