@ngxtm/devkit 1.0.0

package/skills/cloudflare-expert/references/cron-triggers/api.md

@@ -0,0 +1,198 @@
+# Cron Triggers API
+
+## Basic Handler
+
+```typescript
+interface Env {
+  // Bindings (KV, R2, D1, secrets, etc.)
+}
+
+export default {
+  async scheduled(
+    controller: ScheduledController,
+    env: Env,
+    ctx: ExecutionContext,
+  ): Promise<void> {
+    console.log("Cron executed:", new Date(controller.scheduledTime));
+  },
+};
+```
+
+```javascript
+export default {
+  async scheduled(controller, env, ctx) {
+    console.log("Cron executed:", new Date(controller.scheduledTime));
+  },
+};
+```
+
+```python
+from workers import WorkerEntrypoint
+
+class Default(WorkerEntrypoint):
+    async def scheduled(self, controller, env, ctx):
+        print(f"Cron executed: {controller.scheduledTime}")
+```
+
+## ScheduledController
+
+```typescript
+interface ScheduledController {
+  scheduledTime: number;  // Unix ms when scheduled to run
+  cron: string;           // Expression that triggered (e.g., "*/5 * * * *")
+  type: string;           // Always "scheduled"
+}
+```
+
+**Parse time:**
+```typescript
+const date = new Date(controller.scheduledTime);
+console.log(date.toISOString());
+```
+
+## Handler Parameters
+
+**`controller: ScheduledController`**
+- Access cron expression and scheduled time
+
+**`env: Env`**
+- All bindings: KV, R2, D1, secrets, service bindings
+
+**`ctx: ExecutionContext`**
+- `ctx.waitUntil(promise)` - Extend execution for async tasks (logging, cleanup, external APIs)
+- First `waitUntil` failure recorded in Cron Events
+
+## Multiple Schedules Pattern
+
+```typescript
+import { Hono } from "hono";
+
+interface Env {
+  MY_KV: KVNamespace;
+}
+
+const app = new Hono<{ Bindings: Env }>();
+app.get("/", (c) => c.text("API Running"));
+
+export default {
+  fetch: app.fetch,
+
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
+    switch (controller.cron) {
+      case "*/3 * * * *":
+        ctx.waitUntil(updateRecentData(env));
+        break;
+      
+      case "0 * * * *":
+        ctx.waitUntil(processHourlyAggregation(env));
+        break;
+      
+      case "0 2 * * *":
+        ctx.waitUntil(performDailyMaintenance(env));
+        break;
+      
+      default:
+        console.warn(`Unhandled cron: ${controller.cron}`);
+    }
+  },
+};
+```
+
+## ctx.waitUntil Usage
+
+Non-blocking async tasks:
+
+```typescript
+export default {
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
+    // Critical path - runs immediately
+    const data = await fetchCriticalData();
+    
+    // Non-blocking background tasks
+    ctx.waitUntil(
+      Promise.all([
+        logToAnalytics(data),
+        cleanupOldRecords(env.DB),
+        notifyWebhook(env.WEBHOOK_URL, data),
+      ])
+    );
+    
+    // Handler returns while waitUntil tasks complete
+  },
+};
+```
+
+## Workflow Integration
+
+Trigger long-running workflows on schedule:
+
+```typescript
+import { WorkflowEntrypoint } from "cloudflare:workers";
+
+interface Env {
+  MY_WORKFLOW: Workflow;
+}
+
+export class DataProcessingWorkflow extends WorkflowEntrypoint {
+  async run(event: any, step: any) {
+    const data = await step.do("fetch-data", async () => {
+      return await fetchLargeDataset();
+    });
+    
+    const processed = await step.do("process-data", async () => {
+      return await processDataset(data);
+    });
+    
+    await step.do("store-results", async () => {
+      return await storeResults(processed);
+    });
+  }
+}
+
+export default {
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
+    const instance = await env.MY_WORKFLOW.create({
+      params: {
+        scheduledTime: controller.scheduledTime,
+        cron: controller.cron,
+      },
+    });
+    
+    console.log(`Started workflow: ${instance.id}`);
+  },
+};
+```
+
+## Testing Handler
+
+```typescript
+// test/scheduled.test.ts
+import { describe, it, expect } from "vitest";
+import worker from "../src/index";
+
+describe("Scheduled Handler", () => {
+  it("processes scheduled event", async () => {
+    const env = getMiniflareBindings();
+    const ctx = {
+      waitUntil: (promise: Promise<any>) => promise,
+      passThroughOnException: () => {},
+    };
+    
+    const controller = {
+      scheduledTime: Date.now(),
+      cron: "*/5 * * * *",
+      type: "scheduled" as const,
+    };
+    
+    await worker.scheduled(controller, env, ctx);
+    
+    const result = await env.MY_KV.get("last_run");
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview
+- [patterns.md](./patterns.md) - Use cases, examples

package/skills/cloudflare-expert/references/cron-triggers/configuration.md

@@ -0,0 +1,151 @@
+# Cron Triggers Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-cron-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-01-01",
+  
+  "triggers": {
+    "crons": [
+      "*/5 * * * *",     // Every 5 minutes
+      "0 */2 * * *",     // Every 2 hours
+      "0 9 * * MON-FRI", // Weekdays at 9am UTC
+      "0 2 1 * *"        // Monthly on 1st at 2am UTC
+    ]
+  }
+}
+```
+
+## wrangler.toml
+
+```toml
+name = "my-cron-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[triggers]
+crons = [
+  "*/5 * * * *",     # Every 5 minutes
+  "0 */2 * * *",     # Every 2 hours
+  "0 9 * * MON-FRI", # Weekdays at 9am UTC
+  "0 2 1 * *"        # Monthly on 1st at 2am UTC
+]
+```
+
+## Environment-Specific Schedules
+
+```jsonc
+{
+  "name": "my-cron-worker",
+  "triggers": {
+    "crons": ["0 */6 * * *"]  // Prod: every 6 hours
+  },
+  "env": {
+    "staging": {
+      "triggers": {
+        "crons": ["*/15 * * * *"]  // Staging: every 15min
+      }
+    },
+    "dev": {
+      "triggers": {
+        "crons": ["*/5 * * * *"]  // Dev: every 5min
+      }
+    }
+  }
+}
+```
+
+```toml
+name = "my-cron-worker"
+
+[triggers]
+crons = ["0 */6 * * *"]  # Prod: every 6 hours
+
+[env.staging.triggers]
+crons = ["*/15 * * * *"]  # Staging: every 15min
+
+[env.dev.triggers]
+crons = ["*/5 * * * *"]  # Dev: every 5min
+```
+
+## Schedule Format
+
+**5-field structure:**
+```
+minute hour day-of-month month day-of-week
+```
+
+**Special characters:**
+- `*` - Any value
+- `,` - List: `1,15,30 * * * *` (minutes 1, 15, 30)
+- `-` - Range: `0 9-17 * * *` (9am-5pm)
+- `/` - Step: `*/10 * * * *` (every 10 minutes)
+- `L` - Last: `0 0 L * *` (last day of month), `0 18 * * FRI-L` (last Friday)
+- `W` - Weekday: `0 9 15W * *` (weekday nearest 15th)
+- `#` - Nth: `0 10 * * MON#1` (1st Monday)
+
+## Managing Triggers
+
+**Remove all:**
+```jsonc
+{
+  "triggers": {
+    "crons": []  // Empty array removes all
+  }
+}
+```
+
+**Preserve existing:**
+```jsonc
+{
+  // Omit "triggers" entirely to keep existing crons
+}
+```
+
+## Deployment
+
+```bash
+# Deploy with config crons
+npx wrangler deploy
+
+# Deploy specific environment
+npx wrangler deploy --env production
+
+# View deployments
+npx wrangler deployments list
+```
+
+**⚠️ Changes take up to 15 minutes to propagate globally**
+
+## API Management
+
+**Get triggers:**
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}"
+```
+
+**Update triggers:**
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"crons": ["*/5 * * * *", "0 2 * * *"]}'
+```
+
+**Delete all:**
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{"crons": []}'
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview, quick start
+- [api.md](./api.md) - Handler implementation

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

@@ -0,0 +1,129 @@
+# Cron Triggers Gotchas
+
+## Timezone Issues
+
+**⚠️ UTC ONLY** - No timezone configuration
+
+```typescript
+// ❌ Wrong: "0 9 * * *" // 9am UTC, not local
+// ✅ Right: "0 17 * * *" // 9am PST (UTC-8) = 17:00 UTC
+// Calculate: utcHour = (localHour - utcOffset + 24) % 24
+```
+
+## Propagation Delay
+
+**Changes take up to 15 minutes**. Verify: Dashboard → Workers → Select Worker → Settings → Triggers
+
+## Limits
+
+| Plan | Triggers/Worker | CPU Time | Execution |
+|------|----------------|----------|-----------|
+| Free | 3 | 10ms | At-least-once |
+| Paid | Unlimited | 50ms | At-least-once |
+
+```typescript
+// ❌ BAD: await processLargeDataset(); // May exceed CPU
+// ✅ GOOD: ctx.waitUntil(processLargeDataset(env));
+// ✅ OR: await env.WORKFLOW.create({});
+```
+
+## Duplicate Executions
+
+**At-least-once delivery** - duplicates possible. Make idempotent:
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const execId = `${controller.scheduledTime}-${controller.cron}`;
+    if (await env.KV.get(`exec:${execId}`)) return;
+    await env.KV.put(`exec:${execId}`, "processing", { expirationTtl: 3600 });
+    await performTask(env);
+    await env.KV.put(`exec:${execId}`, "complete", { expirationTtl: 86400 });
+  },
+};
+```
+
+## Debugging Not Executing
+
+**Check:** `scheduled()` exported, recent deploy, 15min wait, valid cron ([crontab.guru](https://crontab.guru/)), plan limits
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    console.log("EXECUTED", {time: new Date().toISOString(), scheduledTime: new Date(controller.scheduledTime).toISOString(), cron: controller.cron});
+    ctx.waitUntil(env.KV.put("last_execution", Date.now().toString()));
+  },
+};
+```
+
+## Execution Failures
+
+**Common:** CPU exceeded, unhandled exceptions, network timeouts, binding misconfiguration
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    try {
+      const abortCtrl = new AbortController();
+      const timeout = setTimeout(() => abortCtrl.abort(), 5000);
+      const response = await fetch("https://api.example.com/data", {signal: abortCtrl.signal});
+      clearTimeout(timeout);
+      if (!response.ok) throw new Error(`API: ${response.status}`);
+      await processData(await response.json(), env);
+    } catch (error) {
+      console.error("Failed", {error: error.message, cron: controller.cron});
+      // Don't re-throw to mark success despite errors
+    }
+  },
+};
+```
+
+## Local Testing Issues
+
+Ensure `wrangler dev` runs, `scheduled()` exists, update Wrangler: `npm i -g wrangler@latest`
+
+```bash
+curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*" # URL encode spaces
+curl "http://localhost:8787/__scheduled" # No params = default
+# Python: curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*/5+*+*+*+*"
+```
+
+## Security
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    if (url.pathname === "/__scheduled") {
+      if (env.ENVIRONMENT === "production") return new Response("Not found", { status: 404 });
+      await this.scheduled({scheduledTime: Date.now(), cron: url.searchParams.get("cron") || "* * * * *", type: "scheduled"}, env, ctx);
+      return new Response("OK");
+    }
+    return new Response("Hello");
+  },
+  async scheduled(controller, env, ctx) {},
+};
+```
+
+## Secrets Management
+
+```typescript
+// ❌ BAD: headers: { "Authorization": "Bearer sk_live_abc123..." }
+// ✅ GOOD: headers: { "Authorization": `Bearer ${env.API_KEY}` }
+```
+
+```bash
+npx wrangler secret put API_KEY
+```
+
+## Green Compute
+
+Dashboard: Workers & Pages → Account details → Compute Setting → Green Compute. Tradeoffs: fewer locations, higher latency, ideal for non-time-critical jobs
+
+## 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

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

@@ -0,0 +1,122 @@
+# 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))));
+  },
+};
+```
+
+## Monitoring & Logging
+
+```typescript
+export default {
+  async scheduled(controller, env, ctx) {
+    const startTime = Date.now();
+    console.log(`[START] Cron ${controller.cron} at ${new Date(controller.scheduledTime).toISOString()}`);
+    try {
+      const result = await performTask(env);
+      const duration = Date.now() - startTime;
+      console.log(`[SUCCESS] Completed in ${duration}ms`, {cron: controller.cron, recordsProcessed: result.count});
+      ctx.waitUntil(logToExternal(env.ANALYTICS_ENDPOINT, {event: "cron_success", duration, cron: controller.cron}));
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      console.error(`[ERROR] Failed after ${duration}ms`, {cron: controller.cron, error: error.message});
+      ctx.waitUntil(notifyFailure(env.ALERT_WEBHOOK, {cron: controller.cron, error: error.message}));
+      throw error;
+    }
+  },
+};
+```
+
+## View Past Events
+
+**Dashboard:** Workers & Pages → Select Worker → Settings → Triggers → Cron Events
+
+**Wrangler:**
+```bash
+npx wrangler tail
+npx wrangler tail --format json | jq 'select(.event.cron != null)'
+```
+
+**GraphQL:**
+```graphql
+query CronMetrics($accountTag: string!, $workerName: string!) {
+  viewer { accounts(filter: { accountTag: $accountTag }) { workersInvocationsAdaptive(filter: {scriptName: $workerName, eventType: "scheduled"}, limit: 100) { dimensions { datetime, status }, sum { requests, errors } } } }
+}
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview
+- [api.md](./api.md) - Handler implementation
+- [gotchas.md](./gotchas.md) - Troubleshooting

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

@@ -0,0 +1,92 @@
+# 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 execute <db-name> --remote --file=./migrations/0001_schema.sql
+
+# 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)
+]);
+```
+
+## Platform Limits
+
+| Limit | Value |
+|-------|-------|
+| Database size | 10 GB per database |
+| Row size | 1 MB maximum |
+| Query timeout | 30 seconds |
+| Batch size | 10,000 statements |
+| Time Travel retention | 30 days |
+
+## CLI Commands
+
+```bash
+# Database management
+wrangler d1 create <db-name>
+wrangler d1 list
+wrangler d1 delete <db-name>
+
+# Execute queries
+wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"
+wrangler d1 execute <db-name> --local --file=./migrations/0001_schema.sql
+
+# Backups
+wrangler d1 export <db-name> --remote --output=./backup.sql
+wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"
+
+# Development
+wrangler dev --persist-to=./.wrangler/state
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.toml setup, TypeScript types, binding configuration
+- [api.md](./api.md) - D1Database API, prepared statements, batch operations, testing
+- [patterns.md](./patterns.md) - Pagination, bulk operations, caching, multi-tenant patterns
+- [gotchas.md](./gotchas.md) - SQL injection prevention, error handling, performance pitfalls
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handler patterns
+- [kv](../kv/) - Workers KV for caching D1 results
+- [r2](../r2/) - R2 for storing binary data instead of D1 BLOBs
+- [queues](../queues/) - Queue writes to D1 for high-throughput scenarios
+- [durable-objects](../durable-objects/) - Coordinate D1 writes with strong consistency