@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/cron-triggers/gotchas.md

@@ -0,0 +1,199 @@
+# Cron Triggers Gotchas
+
+## Common Errors
+
+### "Timezone Issues"
+
+**Problem:** Cron runs at wrong time relative to local timezone  
+**Cause:** All crons execute in UTC, no local timezone support  
+**Solution:** Convert local time to UTC manually
+
+**Conversion formula:** `utcHour = (localHour - utcOffset + 24) % 24`
+
+**Examples:**
+- 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *`
+- 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *`
+- 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *`
+
+**Daylight Saving Time:** Adjust manually when DST changes, or schedule at times unaffected by DST (e.g., 2am-4am local time usually safe)
+
+### "Cron Not Executing"
+
+**Cause:** Missing `scheduled()` export, invalid syntax, propagation delay (<15min), or plan limits  
+**Solution:** Verify export exists, validate at crontab.guru, wait 15+ min after deploy, check plan limits
+
+### "Duplicate Executions"
+
+**Cause:** At-least-once delivery  
+**Solution:** Track execution IDs in KV - see idempotency pattern below
+
+### "Execution Failures"
+
+**Cause:** CPU exceeded, unhandled exceptions, network timeouts, binding errors  
+**Solution:** Use try-catch, AbortController timeouts, `ctx.waitUntil()` for long ops, or Workflows for heavy tasks
+
+### "Local Testing Not Working"
+
+**Problem:** `/__scheduled` endpoint returns 404 or doesn't trigger handler  
+**Cause:** Missing `scheduled()` export, wrangler not running, or incorrect endpoint format  
+**Solution:**
+
+1. Verify `scheduled()` is exported:
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    console.log("Cron triggered");
+  },
+};
+```
+
+2. Start dev server:
+```bash
+npx wrangler dev
+```
+
+3. Use correct endpoint format (URL-encode spaces as `+`):
+```bash
+# Correct
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+
+# Wrong (will fail)
+curl "http://localhost:8787/__scheduled?cron=*/5 * * * *"
+```
+
+4. Update Wrangler if outdated:
+```bash
+npm install -g wrangler@latest
+```
+
+### "waitUntil() Tasks Not Completing"
+
+**Problem:** Background tasks in `ctx.waitUntil()` fail silently or don't execute  
+**Cause:** Promises rejected without error handling, or handler returns before promise settles  
+**Solution:** Always await or handle errors in waitUntil promises:
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    // BAD: Silent failures
+    ctx.waitUntil(riskyOperation());
+    
+    // GOOD: Explicit error handling
+    ctx.waitUntil(
+      riskyOperation().catch(err => {
+        console.error("Background task failed:", err);
+        return logError(err, env);
+      })
+    );
+  },
+};
+```
+
+### "Idempotency Issues"
+
+**Problem:** At-least-once delivery causes duplicate side effects (double charges, duplicate emails)  
+**Cause:** No deduplication mechanism  
+**Solution:** Use KV to track execution IDs:
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const executionId = `${controller.cron}-${controller.scheduledTime}`;
+    const existing = await env.EXECUTIONS.get(executionId);
+    
+    if (existing) {
+      console.log("Already executed, skipping");
+      controller.noRetry();
+      return;
+    }
+    
+    await env.EXECUTIONS.put(executionId, "1", { expirationTtl: 86400 }); // 24h TTL
+    await performIdempotentOperation(env);
+  },
+};
+```
+
+### "Security Concerns"
+
+**Problem:** `__scheduled` endpoint exposed in production allows unauthorized cron triggering  
+**Cause:** Testing endpoint available in deployed Workers  
+**Solution:** Block `__scheduled` in production:
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    
+    // Block __scheduled in production
+    if (url.pathname === "/__scheduled" && env.ENVIRONMENT === "production") {
+      return new Response("Not Found", { status: 404 });
+    }
+    
+    return handleRequest(request, env, ctx);
+  },
+  
+  async scheduled(controller, env, ctx) {
+    // Your cron logic
+  },
+};
+```
+
+**Also:** Use `env.API_KEY` for secrets (never hardcode)
+
+**Alternative:** Add middleware to verify request origin:
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    
+    if (url.pathname === "/__scheduled") {
+      // Check Cloudflare headers to verify internal request
+      const cfRay = request.headers.get("cf-ray");
+      if (!cfRay && env.ENVIRONMENT === "production") {
+        return new Response("Not Found", { status: 404 });
+      }
+    }
+    
+    return handleRequest(request, env, ctx);
+  },
+  
+  async scheduled(controller, env, ctx) {
+    // Your cron logic
+  },
+};
+```
+
+## Limits & Quotas
+
+| Limit | Free | Paid | Notes |
+|-------|------|------|-------|
+| Triggers per Worker | 3 | Unlimited | Maximum cron schedules per Worker |
+| CPU time | 10ms | 50ms | May need `ctx.waitUntil()` or Workflows |
+| Execution guarantee | At-least-once | At-least-once | Duplicates possible - use idempotency |
+| Propagation delay | Up to 15 minutes | Up to 15 minutes | Time for changes to take effect globally |
+| Min interval | 1 minute | 1 minute | Cannot schedule more frequently |
+| Cron accuracy | ±1 minute | ±1 minute | Execution may drift slightly |
+
+## Testing Best Practices
+
+**Unit tests:**
+- Mock `ScheduledController`, `ExecutionContext`, and bindings
+- Test each cron expression separately
+- Verify `noRetry()` is called when expected
+- Use Vitest with `@cloudflare/vitest-pool-workers` for realistic env
+
+**Integration tests:**
+- Test via `/__scheduled` endpoint in dev environment
+- Verify idempotency logic with duplicate `scheduledTime` values
+- Test error handling and retry behavior
+
+**Production:** Start with long intervals (`*/30 * * * *`), monitor Cron Events for 24h, set up alerts before reducing interval
+
+## Resources
+
+- [Cron Triggers Docs](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
+- [Scheduled Handler API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
+- [Cloudflare Workflows](https://developers.cloudflare.com/workflows/)
+- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
+- [Crontab Guru](https://crontab.guru/) - Validator
+- [Vitest Pool Workers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples)

package/skills/cloudflare-deploy/references/cron-triggers/patterns.md

@@ -0,0 +1,190 @@
+# Cron Triggers Patterns
+
+## API Data Sync
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const response = await fetch("https://api.example.com/data", {headers: { "Authorization": `Bearer ${env.API_KEY}` }});
+    if (!response.ok) throw new Error(`API error: ${response.status}`);
+    ctx.waitUntil(env.MY_KV.put("cached_data", JSON.stringify(await response.json()), {expirationTtl: 3600}));
+  },
+};
+```
+
+## Database Cleanup
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const result = await env.DB.prepare(`DELETE FROM sessions WHERE expires_at < datetime('now')`).run();
+    console.log(`Deleted ${result.meta.changes} expired sessions`);
+    ctx.waitUntil(env.DB.prepare("VACUUM").run());
+  },
+};
+```
+
+## Report Generation
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const startOfWeek = new Date(); startOfWeek.setDate(startOfWeek.getDate() - 7);
+    const { results } = await env.DB.prepare(`SELECT date, revenue, orders FROM daily_stats WHERE date >= ? ORDER BY date`).bind(startOfWeek.toISOString()).all();
+    const report = {period: "weekly", totalRevenue: results.reduce((sum, d) => sum + d.revenue, 0), totalOrders: results.reduce((sum, d) => sum + d.orders, 0), dailyBreakdown: results};
+    const reportKey = `reports/weekly-${Date.now()}.json`;
+    await env.REPORTS_BUCKET.put(reportKey, JSON.stringify(report));
+    ctx.waitUntil(env.SEND_EMAIL.fetch("https://example.com/send", {method: "POST", body: JSON.stringify({to: "team@example.com", subject: "Weekly Report", reportUrl: `https://reports.example.com/${reportKey}`})}));
+  },
+};
+```
+
+## Health Checks
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const services = [{name: "API", url: "https://api.example.com/health"}, {name: "CDN", url: "https://cdn.example.com/health"}];
+    const checks = await Promise.all(services.map(async (service) => {
+      const start = Date.now();
+      try {
+        const response = await fetch(service.url, { signal: AbortSignal.timeout(5000) });
+        return {name: service.name, status: response.ok ? "up" : "down", responseTime: Date.now() - start};
+      } catch (error) {
+        return {name: service.name, status: "down", responseTime: Date.now() - start, error: error.message};
+      }
+    }));
+    ctx.waitUntil(env.STATUS_KV.put("health_status", JSON.stringify(checks)));
+    const failures = checks.filter(c => c.status === "down");
+    if (failures.length > 0) ctx.waitUntil(fetch(env.ALERT_WEBHOOK, {method: "POST", body: JSON.stringify({text: `${failures.length} service(s) down: ${failures.map(f => f.name).join(", ")}`})}));
+  },
+};
+```
+
+## Batch Processing (Rate-Limited)
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const queueData = await env.QUEUE_KV.get("pending_items", "json");
+    if (!queueData || queueData.length === 0) return;
+    const batch = queueData.slice(0, 100);
+    const results = await Promise.allSettled(batch.map(item => fetch("https://api.example.com/process", {method: "POST", headers: {"Authorization": `Bearer ${env.API_KEY}`, "Content-Type": "application/json"}, body: JSON.stringify(item)})));
+    console.log(`Processed ${results.filter(r => r.status === "fulfilled").length}/${batch.length} items`);
+    ctx.waitUntil(env.QUEUE_KV.put("pending_items", JSON.stringify(queueData.slice(100))));
+  },
+};
+```
+
+## Queue Integration
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const batch = await env.MY_QUEUE.receive({ batchSize: 100 });
+    const results = await Promise.allSettled(batch.messages.map(async (msg) => {
+      await processMessage(msg.body, env);
+      await msg.ack();
+    }));
+    console.log(`Processed ${results.filter(r => r.status === "fulfilled").length}/${batch.messages.length}`);
+  },
+};
+```
+
+## Monitoring & Observability
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const startTime = Date.now();
+    const meta = { cron: controller.cron, scheduledTime: controller.scheduledTime };
+    console.log("[START]", meta);
+    try {
+      const result = await performTask(env);
+      console.log("[SUCCESS]", { ...meta, duration: Date.now() - startTime, count: result.count });
+      ctx.waitUntil(env.METRICS.put(`cron:${controller.scheduledTime}`, JSON.stringify({ ...meta, status: "success" }), { expirationTtl: 2592000 }));
+    } catch (error) {
+      console.error("[ERROR]", { ...meta, duration: Date.now() - startTime, error: error.message });
+      ctx.waitUntil(fetch(env.ALERT_WEBHOOK, { method: "POST", body: JSON.stringify({ text: `Cron failed: ${controller.cron}`, error: error.message }) }));
+      throw error;
+    }
+  },
+};
+```
+
+**View logs:** `npx wrangler tail` or Dashboard → Workers & Pages → Worker → Logs
+
+## Durable Objects Coordination
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const stub = env.COORDINATOR.get(env.COORDINATOR.idFromName("cron-lock"));
+    const acquired = await stub.tryAcquireLock(controller.scheduledTime);
+    if (!acquired) {
+      controller.noRetry();
+      return;
+    }
+    try {
+      await performTask(env);
+    } finally {
+      await stub.releaseLock();
+    }
+  },
+};
+```
+
+## Python Handler
+
+```python
+from workers import WorkerEntrypoint
+
+class Default(WorkerEntrypoint):
+    async def scheduled(self, controller, env, ctx):
+        data = await env.MY_KV.get("key")
+        ctx.waitUntil(env.DB.execute("DELETE FROM logs WHERE created_at < datetime('now', '-7 days')"))
+```
+
+## Testing Patterns
+
+**Local testing with /__scheduled:**
+```bash
+# Start dev server
+npx wrangler dev
+
+# Test specific cron
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
+
+# Test with specific time
+curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"
+```
+
+**Unit tests:**
+```typescript
+// test/scheduled.test.ts
+import { describe, it, expect, vi } from "vitest";
+import { env } from "cloudflare:test";
+import worker from "../src/index";
+
+describe("Scheduled Handler", () => {
+  it("executes cron", async () => {
+    const controller = { scheduledTime: Date.now(), cron: "*/5 * * * *", type: "scheduled" as const, noRetry: vi.fn() };
+    const ctx = { waitUntil: vi.fn(), passThroughOnException: vi.fn() };
+    await worker.scheduled(controller, env, ctx);
+    expect(await env.MY_KV.get("last_run")).toBeDefined();
+  });
+  
+  it("calls noRetry on duplicate", async () => {
+    const controller = { scheduledTime: 1704067200000, cron: "0 2 * * *", type: "scheduled" as const, noRetry: vi.fn() };
+    await env.EXECUTIONS.put("0 2 * * *-1704067200000", "1");
+    await worker.scheduled(controller, env, { waitUntil: vi.fn(), passThroughOnException: vi.fn() });
+    expect(controller.noRetry).toHaveBeenCalled();
+  });
+});
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview
+- [api.md](./api.md) - Handler implementation
+- [gotchas.md](./gotchas.md) - Troubleshooting

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

@@ -0,0 +1,133 @@
+# Cloudflare D1 Database
+
+Expert guidance for Cloudflare D1, a serverless SQLite database designed for horizontal scale-out across multiple databases.
+
+## Overview
+
+D1 is Cloudflare's managed, serverless database with:
+- SQLite SQL semantics and compatibility
+- Built-in disaster recovery via Time Travel (30-day point-in-time recovery)
+- Horizontal scale-out architecture (10 GB per database)
+- Worker and HTTP API access
+- Pricing based on query and storage costs only
+
+**Architecture Philosophy**: D1 is optimized for per-user, per-tenant, or per-entity database patterns rather than single large databases.
+
+## Quick Start
+
+```bash
+# Create database
+wrangler d1 create <database-name>
+
+# Execute migration
+wrangler d1 migrations apply <db-name> --remote
+
+# Local development
+wrangler dev
+```
+
+## Core Query Methods
+
+```typescript
+// .all() - Returns all rows; .first() - First row or null; .first(col) - Single column value
+// .run() - INSERT/UPDATE/DELETE; .raw() - Array of arrays (efficient)
+const { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?').bind(true).all();
+const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+```
+
+## Batch Operations
+
+```typescript
+// Multiple queries in single round trip (atomic transaction)
+const results = await env.DB.batch([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),
+  env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),
+  env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1)
+]);
+```
+
+## Sessions API (Paid Plans)
+
+```typescript
+// Create long-running session for analytics/migrations (up to 15 minutes)
+const session = env.DB.withSession();
+try {
+  await session.prepare('CREATE INDEX idx_heavy ON large_table(column)').run();
+  await session.prepare('ANALYZE').run();
+} finally {
+  session.close(); // Always close to release resources
+}
+```
+
+## Read Replication (Paid Plans)
+
+```typescript
+// Read from nearest replica for lower latency (automatic failover)
+const user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+
+// Writes always go to primary
+await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();
+```
+
+## Platform Limits
+
+| Limit | Free Tier | Paid Plans |
+|-------|-----------|------------|
+| Database size | 500 MB | 10 GB per database |
+| Row size | 1 MB max | 1 MB max |
+| Query timeout | 30 seconds | 30 seconds |
+| Batch size | 1,000 statements | 10,000 statements |
+| Time Travel retention | 7 days | 30 days |
+| Read replicas | Not available | Yes (paid add-on) |
+
+**Pricing**: $5/month per database beyond free tier + $0.001 per 1K reads + $1 per 1M writes + $0.75/GB storage/month
+
+## CLI Commands
+
+```bash
+# Database management
+wrangler d1 create <db-name>
+wrangler d1 list
+wrangler d1 delete <db-name>
+
+# Migrations
+wrangler d1 migrations create <db-name> <migration-name>    # Create new migration file
+wrangler d1 migrations apply <db-name> --remote             # Apply pending migrations
+wrangler d1 migrations apply <db-name> --local              # Apply locally
+wrangler d1 migrations list <db-name> --remote              # Show applied migrations
+
+# Direct SQL execution
+wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"
+wrangler d1 execute <db-name> --local --file=./schema.sql
+
+# Backups & Import/Export
+wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export with schema
+wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
+wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time recovery
+
+# Development
+wrangler dev --persist-to=./.wrangler/state
+```
+
+## Reading Order
+
+**Start here**: Quick Start above → configuration.md (setup) → api.md (queries)
+
+**Common tasks**:
+- First time setup: configuration.md → Run migrations
+- Adding queries: api.md → Prepared statements
+- Pagination/caching: patterns.md
+- Production optimization: Read Replication + Sessions API (this file)
+- Debugging: gotchas.md
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, migrations, TypeScript types, ORMs, local dev
+- [api.md](./api.md) - Query methods (.all/.first/.run/.raw), batch, sessions, read replicas, error handling
+- [patterns.md](./patterns.md) - Pagination, bulk operations, caching, multi-tenant, sessions, analytics
+- [gotchas.md](./gotchas.md) - SQL injection, limits by plan tier, performance, common errors
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handler patterns
+- [hyperdrive](../hyperdrive/) - Connection pooling for external databases