@mohanscodex/spectra-code 0.4.9 → 0.5.0

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

@@ -0,0 +1,105 @@
+# Observability Patterns
+
+## Usage-Based Billing
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [customerId, request.url, request.method],
+  doubles: [1], // request_count
+  indexes: [customerId]
+});
+```
+
+```sql
+SELECT blob1 AS customer_id, SUM(_sample_interval * double1) AS total_calls
+FROM api_usage WHERE timestamp >= DATE_TRUNC('month', NOW())
+GROUP BY customer_id
+```
+
+## Performance Monitoring
+
+```typescript
+const start = Date.now();
+const response = await fetch(url);
+env.ANALYTICS.writeDataPoint({
+  blobs: [url, response.status.toString()],
+  doubles: [Date.now() - start, response.status]
+});
+```
+
+```sql
+SELECT blob1 AS url, AVG(double1) AS avg_ms, percentile(double1, 0.95) AS p95_ms
+FROM fetch_metrics WHERE timestamp >= NOW() - INTERVAL '1' HOUR
+GROUP BY url
+```
+
+## Error Tracking
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [error.name, request.url, request.method],
+  doubles: [1],
+  indexes: [error.name]
+});
+```
+
+## Multi-Tenant Tracking
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  indexes: [tenantId], // efficient filtering
+  blobs: [tenantId, url.pathname, method, status],
+  doubles: [1, duration, bytesSize]
+});
+```
+
+## Tail Worker Log Filtering
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const critical = events.filter(e => 
+      e.exceptions.length > 0 || e.event.wallTime > 1000000
+    );
+    if (critical.length === 0) return;
+    
+    ctx.waitUntil(
+      fetch('https://logging.example.com/ingest', {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${env.API_KEY}` },
+        body: JSON.stringify(critical.map(e => ({
+          outcome: e.event.outcome,
+          cpu_ms: e.event.cpuTime / 1000,
+          errors: e.exceptions
+        })))
+      })
+    );
+  }
+};
+```
+
+## OpenTelemetry Export
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const otelSpans = events.map(e => ({
+      traceId: generateId(32),
+      spanId: generateId(16),
+      name: e.scriptName || 'worker.request',
+      attributes: [
+        { key: 'worker.outcome', value: { stringValue: e.event.outcome } },
+        { key: 'worker.cpu_time_us', value: { intValue: String(e.event.cpuTime) } }
+      ]
+    }));
+    
+    ctx.waitUntil(
+      fetch('https://api.honeycomb.io/v1/traces', {
+        method: 'POST',
+        headers: { 'X-Honeycomb-Team': env.HONEYCOMB_KEY },
+        body: JSON.stringify({ resourceSpans: [{ scopeSpans: [{ spans: otelSpans }] }] })
+      })
+    );
+  }
+};
+```

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

@@ -0,0 +1,88 @@
+# Cloudflare Pages
+
+JAMstack platform for full-stack apps on Cloudflare's global network.
+
+## Key Features
+
+- **Git-based deploys**: Auto-deploy from GitHub/GitLab
+- **Preview deployments**: Unique URL per branch/PR
+- **Pages Functions**: File-based serverless routing (Workers runtime)
+- **Static + dynamic**: Smart asset caching + edge compute
+- **Smart Placement**: Automatic function optimization based on traffic patterns
+- **Framework optimized**: SvelteKit, Astro, Nuxt, Qwik, Solid Start
+
+## Deployment Methods
+
+### 1. Git Integration (Production)
+Dashboard → Workers & Pages → Create → Connect to Git → Configure build
+
+### 2. Direct Upload
+```bash
+npx wrangler pages deploy ./dist --project-name=my-project
+npx wrangler pages deploy ./dist --project-name=my-project --branch=staging
+```
+
+### 3. C3 CLI
+```bash
+npm create cloudflare@latest my-app
+# Select framework → auto-setup + deploy
+```
+
+## vs Workers
+
+- **Pages**: Static sites, JAMstack, frameworks, git workflow, file-based routing
+- **Workers**: Pure APIs, complex routing, WebSockets, scheduled tasks, email handlers
+- **Combine**: Pages Functions use Workers runtime, can bind to Workers
+
+## Quick Start
+
+```bash
+# Create
+npm create cloudflare@latest
+
+# Local dev
+npx wrangler pages dev ./dist
+
+# Deploy
+npx wrangler pages deploy ./dist --project-name=my-project
+
+# Types
+npx wrangler types --path='./functions/types.d.ts'
+
+# Secrets
+echo "value" | npx wrangler pages secret put KEY --project-name=my-project
+
+# Logs
+npx wrangler pages deployment tail --project-name=my-project
+```
+
+## Resources
+
+- [Pages Docs](https://developers.cloudflare.com/pages/)
+- [Functions API](https://developers.cloudflare.com/pages/functions/api-reference/)
+- [Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)
+- [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)
+
+## Reading Order
+
+**New to Pages?** Start here:
+1. README.md (you are here) - Overview & quick start
+2. [configuration.md](./configuration.md) - Project setup, wrangler.jsonc, bindings
+3. [api.md](./api.md) - Functions API, routing, context
+4. [patterns.md](./patterns.md) - Common implementations
+5. [gotchas.md](./gotchas.md) - Troubleshooting & pitfalls
+
+**Quick reference?** Jump to relevant file above.
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc, build, env vars, Smart Placement
+- [api.md](./api.md) - Functions API, bindings, context, advanced mode
+- [patterns.md](./patterns.md) - Full-stack patterns, framework integration
+- [gotchas.md](./gotchas.md) - Build issues, limits, debugging, framework warnings
+
+## See Also
+
+- [pages-functions](../pages-functions/) - File-based routing, middleware
+- [d1](../d1/) - SQL database for Pages Functions
+- [kv](../kv/) - Key-value storage for caching/state

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

@@ -0,0 +1,204 @@
+# Functions API
+
+## File-Based Routing
+
+```
+/functions/index.ts              → example.com/
+/functions/api/users.ts          → example.com/api/users
+/functions/api/users/[id].ts     → example.com/api/users/:id
+/functions/api/users/[[path]].ts → example.com/api/users/* (catchall)
+/functions/_middleware.ts        → Runs before all routes
+```
+
+**Rules**: `[param]` = single segment, `[[param]]` = multi-segment catchall, more specific wins.
+
+## Request Handlers
+
+```typescript
+import type { PagesFunction } from '@cloudflare/workers-types';
+
+interface Env {
+  DB: D1Database;
+  KV: KVNamespace;
+}
+
+// All methods
+export const onRequest: PagesFunction<Env> = async (context) => {
+  return new Response('All methods');
+};
+
+// Method-specific
+export const onRequestGet: PagesFunction<Env> = async (context) => {
+  const { request, env, params, data } = context;
+  
+  const user = await env.DB.prepare(
+    'SELECT * FROM users WHERE id = ?'
+  ).bind(params.id).first();
+  
+  return Response.json(user);
+};
+
+export const onRequestPost: PagesFunction<Env> = async (context) => {
+  const body = await context.request.json();
+  return Response.json({ success: true });
+};
+
+// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions
+```
+
+## Context Object
+
+```typescript
+interface EventContext<Env, Params, Data> {
+  request: Request;              // HTTP request
+  env: Env;                      // Bindings (KV, D1, R2, etc.)
+  params: Params;                // Route parameters
+  data: Data;                    // Middleware-shared data
+  waitUntil: (promise: Promise<any>) => void;  // Background tasks
+  next: () => Promise<Response>; // Next handler
+  passThroughOnException: () => void;  // Error fallback (not in advanced mode)
+}
+```
+
+## Dynamic Routes
+
+```typescript
+// Single segment: functions/users/[id].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /users/123 → params.id = "123"
+  return Response.json({ userId: params.id });
+};
+
+// Multi-segment: functions/files/[[path]].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /files/docs/api/v1.md → params.path = ["docs", "api", "v1.md"]
+  const filePath = (params.path as string[]).join('/');
+  return new Response(filePath);
+};
+```
+
+## Middleware
+
+```typescript
+// functions/_middleware.ts
+// Single
+export const onRequest: PagesFunction = async (context) => {
+  const response = await context.next();
+  response.headers.set('X-Custom-Header', 'value');
+  return response;
+};
+
+// Chained (runs in order)
+const errorHandler: PagesFunction = async (context) => {
+  try {
+    return await context.next();
+  } catch (err) {
+    return new Response(err.message, { status: 500 });
+  }
+};
+
+const auth: PagesFunction = async (context) => {
+  const token = context.request.headers.get('Authorization');
+  if (!token) return new Response('Unauthorized', { status: 401 });
+  context.data.userId = await verifyToken(token);
+  return context.next();
+};
+
+export const onRequest = [errorHandler, auth];
+```
+
+**Scope**: `functions/_middleware.ts` → all; `functions/api/_middleware.ts` → `/api/*` only
+
+## Bindings Usage
+
+```typescript
+export const onRequestGet: PagesFunction<Env> = async ({ env }) => {
+  // KV
+  const cached = await env.KV.get('key', 'json');
+  await env.KV.put('key', JSON.stringify({data: 'value'}), {expirationTtl: 3600});
+  
+  // D1
+  const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+  
+  // R2, Queue, AI - see respective reference docs
+  
+  return Response.json({success: true});
+};
+```
+
+## Advanced Mode
+
+Full Workers API, bypasses file-based routing:
+
+```javascript
+// functions/_worker.js
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    
+    // Custom routing
+    if (url.pathname.startsWith('/api/')) {
+      return new Response('API response');
+    }
+    
+    // REQUIRED: Serve static assets
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**When to use**: WebSockets, complex routing, scheduled handlers, email handlers.
+
+## Smart Placement
+
+Automatically optimizes function execution location based on traffic patterns.
+
+**Configuration** (in wrangler.jsonc):
+```jsonc
+{
+  "placement": {
+    "mode": "smart"  // Enables optimization (default: off)
+  }
+}
+```
+
+**How it works**: Analyzes traffic patterns over time and places functions closer to users or data sources (e.g., D1 databases). Requires no code changes.
+
+**Trade-offs**: Initial requests may see slightly higher latency during learning period (hours-days). Performance improves as system optimizes.
+
+**When to use**: Global apps with centralized databases or geographically concentrated traffic sources.
+
+## getRequestContext (Framework SSR)
+
+Access bindings in framework code:
+
+```typescript
+// SvelteKit
+import type { RequestEvent } from '@sveltejs/kit';
+export async function load({ platform }: RequestEvent) {
+  const data = await platform.env.DB.prepare('SELECT * FROM users').all();
+  return { users: data.results };
+}
+
+// Astro
+const { DB } = Astro.locals.runtime.env;
+const data = await DB.prepare('SELECT * FROM users').all();
+
+// Solid Start (server function)
+import { getRequestEvent } from 'solid-js/web';
+const event = getRequestEvent();
+const data = await event.locals.runtime.env.DB.prepare('SELECT * FROM users').all();
+```
+
+**✅ Supported adapters** (2026):
+- **SvelteKit**: `@sveltejs/adapter-cloudflare`
+- **Astro**: Built-in Cloudflare adapter
+- **Nuxt**: Set `nitro.preset: 'cloudflare-pages'` in `nuxt.config.ts`
+- **Qwik**: Built-in Cloudflare adapter
+- **Solid Start**: `@solidjs/start-cloudflare-pages`
+
+**❌ Deprecated/Unsupported**:
+- **Next.js**: Official adapter (`@cloudflare/next-on-pages`) deprecated. Use Vercel or self-host on Workers.
+- **Remix**: Official adapter (`@remix-run/cloudflare-pages`) deprecated. Migrate to supported frameworks.
+
+See [gotchas.md](./gotchas.md#framework-specific) for migration guidance.

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

@@ -0,0 +1,201 @@
+# Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "name": "my-pages-project",
+  "pages_build_output_dir": "./dist",
+  "compatibility_date": "2026-01-01", // Use current date for new projects
+  "compatibility_flags": ["nodejs_compat"],
+  "placement": {
+    "mode": "smart"  // Optional: Enable Smart Placement
+  },
+  "kv_namespaces": [{"binding": "KV", "id": "abcd1234..."}],
+  "d1_databases": [{"binding": "DB", "database_id": "xxxx-xxxx", "database_name": "production-db"}],
+  "r2_buckets": [{"binding": "BUCKET", "bucket_name": "my-bucket"}],
+  "durable_objects": {"bindings": [{"name": "COUNTER", "class_name": "Counter", "script_name": "counter-worker"}]},
+  "services": [{"binding": "API", "service": "api-worker"}],
+  "queues": {"producers": [{"binding": "QUEUE", "queue": "my-queue"}]},
+  "vectorize": [{"binding": "VECTORIZE", "index_name": "my-index"}],
+  "ai": {"binding": "AI"},
+  "analytics_engine_datasets": [{"binding": "ANALYTICS"}],
+  "vars": {"API_URL": "https://api.example.com", "ENVIRONMENT": "production"},
+  "env": {
+    "preview": {
+      "vars": {"API_URL": "https://staging-api.example.com"},
+      "kv_namespaces": [{"binding": "KV", "id": "preview-namespace-id"}]
+    }
+  }
+}
+```
+
+## Build Config
+
+**Git deployment**: Dashboard → Project → Settings → Build settings  
+Set build command, output dir, env vars. Framework auto-detection configures automatically.
+
+## Environment Variables
+
+### Local (.dev.vars)
+```bash
+# .dev.vars (never commit)
+SECRET_KEY="local-secret-key"
+API_TOKEN="dev-token-123"
+```
+
+### Production
+```bash
+echo "secret-value" | npx wrangler pages secret put SECRET_KEY --project-name=my-project
+npx wrangler pages secret list --project-name=my-project
+npx wrangler pages secret delete SECRET_KEY --project-name=my-project
+```
+
+Access: `env.SECRET_KEY`
+
+## Static Config Files
+
+### _redirects
+Place in build output (e.g., `dist/_redirects`):
+
+```txt
+/old-page /new-page 301          # 301 redirect
+/blog/* /news/:splat 301         # Splat wildcard
+/users/:id /members/:id 301      # Placeholders
+/api/* /api-v2/:splat 200        # Proxy (no redirect)
+```
+
+**Limits**: 2,100 total (2,000 static + 100 dynamic), 1,000 char/line  
+**Note**: Functions take precedence
+
+### _headers
+```txt
+/secure/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+
+/api/*
+  Access-Control-Allow-Origin: *
+
+/static/*
+  Cache-Control: public, max-age=31536000, immutable
+```
+
+**Limits**: 100 rules, 2,000 char/line  
+**Note**: Only static assets; Functions set headers in Response
+
+### _routes.json
+Controls which requests invoke Functions (auto-generated for most frameworks):
+
+```json
+{
+  "version": 1,
+  "include": ["/*"],
+  "exclude": ["/build/*", "/static/*", "/assets/*", "/*.{ico,png,jpg,css,js}"]
+}
+```
+
+**Purpose**: Functions are metered; static requests are free. `exclude` takes precedence. Max 100 rules, 100 char/rule.
+
+## TypeScript
+
+```bash
+npx wrangler types --path='./functions/types.d.ts'
+```
+
+Point `types` in `functions/tsconfig.json` to generated file.
+
+## Smart Placement
+
+Automatically optimizes function execution location based on request patterns.
+
+```jsonc
+{
+  "placement": {
+    "mode": "smart"  // Enable optimization (default: off)
+  }
+}
+```
+
+**How it works**: System analyzes traffic over hours/days and places function execution closer to:
+- User clusters (e.g., regional traffic)
+- Data sources (e.g., D1 database primary location)
+
+**Benefits**: 
+- Lower latency for read-heavy apps with centralized databases
+- Better performance for apps with regional traffic patterns
+
+**Trade-offs**:
+- Initial learning period: First requests may be slower while system optimizes
+- Optimization time: Performance improves over 24-48 hours
+
+**When to enable**: Global apps with D1/Durable Objects in specific regions, or apps with concentrated geographic traffic.
+
+**When to skip**: Evenly distributed global traffic with no data locality constraints.
+
+## Remote Bindings (Local Dev)
+
+Connect local dev server to production bindings instead of local mocks:
+
+```bash
+# All bindings remote
+npx wrangler pages dev ./dist --remote
+
+# Specific bindings remote (others local)
+npx wrangler pages dev ./dist --remote --kv=KV --d1=DB
+```
+
+**Use cases**:
+- Test against production data (read-only operations)
+- Debug binding-specific behavior
+- Validate changes before deployment
+
+**⚠️ Warning**: 
+- Writes affect **real production data**
+- Use only for read-heavy debugging or with non-production accounts
+- Consider creating separate preview environments instead
+
+**Requirements**: Must be logged in (`npx wrangler login`) with access to bindings.
+
+## Local Dev
+
+```bash
+# Basic
+npx wrangler pages dev ./dist
+
+# With bindings
+npx wrangler pages dev ./dist --kv KV --d1 DB=local-db-id
+
+# Remote bindings (production data)
+npx wrangler pages dev ./dist --remote
+
+# Persistence
+npx wrangler pages dev ./dist --persist-to=./.wrangler/state/v3
+
+# Proxy mode (SSR frameworks)
+npx wrangler pages dev -- npm run dev
+```
+
+## Limits (as of Jan 2026)
+
+| Resource | Free | Paid |
+|----------|------|------|
+| **Functions Requests** | 100k/day | Unlimited (metered) |
+| **Function CPU Time** | 10ms/req | 30ms/req (Workers Paid) |
+| **Function Memory** | 128MB | 128MB |
+| **Script Size** | 1MB compressed | 10MB compressed |
+| **Deployments** | 500/month | 5,000/month |
+| **Files per Deploy** | 20,000 | 20,000 |
+| **File Size** | 25MB | 25MB |
+| **Build Time** | 20min | 20min |
+| **Redirects** | 2,100 (2k static + 100 dynamic) | Same |
+| **Header Rules** | 100 | 100 |
+| **Route Rules** | 100 | 100 |
+| **Subrequests** | 50/request | 1,000/request (Workers Paid) |
+
+**Notes**:
+- Functions use Workers runtime; Workers Paid plan increases limits
+- Free plan sufficient for most projects
+- Static requests always free (not counted toward limits)
+
+[Full limits](https://developers.cloudflare.com/pages/platform/limits/)