pi-cloudflare 0.1.0

package/skills/cloudflare/references/observability/configuration.md

@@ -0,0 +1,169 @@
+## Configuration Patterns
+
+### Enable Workers Logs
+
+```jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1  // 100% sampling (default)
+  }
+}
+```
+
+**Best Practice**: Use structured JSON logging for better indexing
+
+```typescript
+// Good - structured logging
+console.log({ 
+  user_id: 123, 
+  action: "login", 
+  status: "success",
+  duration_ms: 45
+});
+
+// Avoid - unstructured string
+console.log("user_id: 123 logged in successfully in 45ms");
+```
+
+### Enable Workers Traces
+
+```jsonc
+{
+  "observability": {
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.05  // 5% sampling
+    }
+  }
+}
+```
+
+**Note**: Default sampling is 100%. For high-traffic Workers, use lower sampling (0.01-0.1).
+
+### Configure Analytics Engine
+
+**Bind to Worker**:
+```toml
+# wrangler.toml
+analytics_engine_datasets = [
+  { binding = "ANALYTICS", dataset = "api_metrics" }
+]
+```
+
+**Write Data Points**:
+```typescript
+export interface Env {
+  ANALYTICS: AnalyticsEngineDataset;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Track metrics
+    env.ANALYTICS.writeDataPoint({
+      blobs: ['customer_123', 'POST', '/api/v1/users'],
+      doubles: [1, 245.5], // request_count, response_time_ms
+      indexes: ['customer_123'] // for efficient filtering
+    });
+    
+    return new Response('OK');
+  }
+}
+```
+
+### Configure Tail Workers
+
+Tail Workers receive logs/traces from other Workers for filtering, transformation, or export.
+
+**Setup**:
+```toml
+# wrangler.toml
+name = "log-processor"
+main = "src/tail.ts"
+
+[[tail_consumers]]
+service = "my-worker" # Worker to tail
+```
+
+**Tail Worker Example**:
+```typescript
+export default {
+  async tail(events: TraceItem[], env: Env, ctx: ExecutionContext) {
+    // Filter errors only
+    const errors = events.filter(event => 
+      event.outcome === 'exception' || event.outcome === 'exceededCpu'
+    );
+    
+    if (errors.length > 0) {
+      // Send to external monitoring
+      ctx.waitUntil(
+        fetch('https://monitoring.example.com/errors', {
+          method: 'POST',
+          body: JSON.stringify(errors)
+        })
+      );
+    }
+  }
+}
+```
+
+### Configure Logpush
+
+Send logs to external storage (S3, R2, GCS, Azure, Datadog, etc.). Requires Business/Enterprise plan.
+
+**Via Dashboard**:
+1. Navigate to Analytics → Logs → Logpush
+2. Select destination type
+3. Provide credentials and bucket/endpoint
+4. Choose dataset (e.g., Workers Trace Events)
+5. Configure filters and fields
+
+**Via API**:
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/logpush/jobs" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "workers-logs-to-s3",
+    "destination_conf": "s3://my-bucket/logs?region=us-east-1",
+    "dataset": "workers_trace_events",
+    "enabled": true,
+    "frequency": "high",
+    "filter": "{\"where\":{\"and\":[{\"key\":\"ScriptName\",\"operator\":\"eq\",\"value\":\"my-worker\"}]}}"
+  }'
+```
+
+### Environment-Specific Configuration
+
+**Development** (verbose logs, full sampling):
+```jsonc
+// wrangler.dev.jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1.0,
+    "traces": {
+      "enabled": true
+    }
+  }
+}
+```
+
+**Production** (reduced sampling, structured logs):
+```jsonc
+// wrangler.prod.jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 0.1, // 10% sampling
+    "traces": {
+      "enabled": true
+    }
+  }
+}
+```
+
+Deploy with env-specific config:
+```bash
+wrangler deploy --config wrangler.prod.jsonc --env production
+```

package/skills/cloudflare/references/observability/gotchas.md

@@ -0,0 +1,115 @@
+## Common Errors
+
+### "Logs not appearing"
+
+**Cause:** Observability disabled, Worker not redeployed, no traffic, low sampling rate, or log size exceeds 256 KB
+**Solution:** 
+```bash
+# Verify config
+cat wrangler.jsonc | jq '.observability'
+
+# Check deployment
+wrangler deployments list <WORKER_NAME>
+
+# Test with curl
+curl https://your-worker.workers.dev
+```
+Ensure `observability.enabled = true`, redeploy Worker, check `head_sampling_rate`, verify traffic
+
+### "Traces not being captured"
+
+**Cause:** Traces not enabled, incorrect sampling rate, Worker not redeployed, or destination unavailable
+**Solution:**
+```jsonc
+// Temporarily set to 100% sampling for debugging
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1.0,
+    "traces": {
+      "enabled": true
+    }
+  }
+}
+```
+Ensure `observability.traces.enabled = true`, set `head_sampling_rate` to 1.0 for testing, redeploy, check destination status
+
+## Limits
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| Max log size | 256 KB | Logs exceeding this are truncated |
+| Default sampling rate | 1.0 (100%) | Reduce for high-traffic Workers |
+| Max destinations | Varies by plan | Check dashboard |
+| Trace context propagation | 100 spans max | Deep call chains may lose spans |
+| Analytics Engine write rate | 25 writes/request | Excess writes dropped silently |
+
+## Performance Gotchas
+
+### Spectre Mitigation Timing
+
+**Problem:** `Date.now()` and `performance.now()` have reduced precision (coarsened to 100μs)
+**Cause:** Spectre vulnerability mitigation in V8
+**Solution:** Accept reduced precision or use Workers Traces for accurate timing
+```typescript
+// Date.now() is coarsened - trace spans are accurate
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // For user-facing timing, Date.now() is fine
+    const start = Date.now();
+    const response = await processRequest(request);
+    const duration = Date.now() - start;
+    
+    // For detailed performance analysis, use Workers Traces instead
+    return response;
+  }
+}
+```
+
+### Analytics Engine _sample_interval Aggregation
+
+**Problem:** Queries return incorrect totals when not multiplying by `_sample_interval`
+**Cause:** Analytics Engine stores sampled data points, each representing multiple events
+**Solution:** Always multiply counts/sums by `_sample_interval` in aggregations
+```sql
+-- WRONG: Undercounts actual events
+SELECT blob1 AS customer_id, COUNT(*) AS total_calls
+FROM api_usage GROUP BY customer_id;
+
+-- CORRECT: Accounts for sampling
+SELECT blob1 AS customer_id, SUM(_sample_interval) AS total_calls
+FROM api_usage GROUP BY customer_id;
+```
+
+### Trace Context Propagation Limits
+
+**Problem:** Deep call chains lose trace context after 100 spans
+**Cause:** Cloudflare limits trace depth to prevent performance impact
+**Solution:** Design for flatter architectures or use custom correlation IDs for deep chains
+```typescript
+// For deep call chains, add custom correlation ID
+const correlationId = crypto.randomUUID();
+console.log({ correlationId, event: 'request_start' });
+
+// Pass correlationId through headers to downstream services
+await fetch('https://api.example.com', {
+  headers: { 'X-Correlation-ID': correlationId }
+});
+```
+
+## Pricing (2026)
+
+### Workers Traces
+- **GA Pricing (starts March 1, 2026):**
+  - $0.10 per 1M trace spans captured
+  - Retention: 14 days included
+- **Free tier:** 10M trace spans/month
+- **Note:** Beta usage (before March 1, 2026) is free
+
+### Workers Logs
+- **Included:** Free for all Workers
+- **Logpush:** Requires Business/Enterprise plan
+
+### Analytics Engine
+- **Included:** 10M writes/month on Paid Workers plan
+- **Additional:** $0.25 per 1M writes beyond included quota

package/skills/cloudflare/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/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/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.