codexkit 1.0.0

package/.codex/skills/cloudflare/references/pulumi/gotchas.md

@@ -0,0 +1,223 @@
+# Troubleshooting & Best Practices
+
+## Common Errors
+
+**1. Account ID Missing**
+```
+error: Missing required property 'accountId'
+```
+Solution: Add to config or pass explicitly.
+
+**2. Binding Name Mismatch**
+Worker expects `MY_KV` but binding uses different name.
+Solution: Match binding names in Pulumi and worker code.
+
+**3. Resource Not Found**
+```
+error: resource 'abc123' not found
+```
+Solution: Ensure resources exist in correct account/zone.
+
+**4. API Token Permissions**
+Solution: Verify token has required permissions (Workers, KV, R2, etc.).
+
+## Debugging
+
+**Enable verbose logging:**
+```bash
+pulumi up --logtostderr -v=9
+```
+
+**Preview changes:**
+```bash
+pulumi preview
+```
+
+**View resource state:**
+```bash
+pulumi stack export
+```
+
+**Inspect specific resource:**
+```bash
+pulumi stack --show-urns
+pulumi state delete <urn> # Use with caution
+```
+
+## Best Practices
+
+### 1. Use Stack Configuration
+```yaml
+# Pulumi.<stack>.yaml
+config:
+  cloudflare:accountId: "abc123"
+  cloudflare:apiToken:
+    secure: "encrypted-value"
+  app:domain: "example.com"
+  app:zoneId: "xyz789"
+```
+
+### 2. Explicit Provider Configuration
+```typescript
+const devProvider = new cloudflare.Provider("dev", {apiToken: devToken});
+const prodProvider = new cloudflare.Provider("prod", {apiToken: prodToken});
+
+const devWorker = new cloudflare.WorkerScript("dev-worker", {
+    accountId: devAccountId, name: "worker", content: code,
+}, {provider: devProvider});
+
+const prodWorker = new cloudflare.WorkerScript("prod-worker", {
+    accountId: prodAccountId, name: "worker", content: code,
+}, {provider: prodProvider});
+```
+
+### 3. Resource Naming Conventions
+```typescript
+const stack = pulumi.getStack();
+const kv = new cloudflare.WorkersKvNamespace(`${stack}-kv`, {accountId, title: `${stack}-my-kv`});
+```
+
+### 4. Protect Production Resources
+```typescript
+const prodDb = new cloudflare.D1Database("prod-db", {accountId, name: "production-database"}, 
+    {protect: true}); // Cannot delete without removing protect
+```
+
+### 5. Use dependsOn for Ordering
+```typescript
+const migration = new command.local.Command("migration", {
+    create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,
+}, {dependsOn: [db]});
+
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId, name: "worker", content: code,
+    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
+}, {dependsOn: [migration]}); // Ensure migrations run first
+```
+
+### 6. Resource Tagging Pattern
+```typescript
+function createResource(name: string, type: string) {
+    const stack = pulumi.getStack();
+    const fullName = `${stack}-${type}-${name}`;
+    return new cloudflare.WorkersKvNamespace(fullName, {accountId, title: fullName});
+}
+
+const userCache = createResource("user-cache", "kv");
+const sessionCache = createResource("session-cache", "kv");
+```
+
+## Security
+
+### Secrets Management
+```typescript
+const config = new pulumi.Config();
+const apiKey = config.requireSecret("apiKey"); // Encrypted in state
+
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId, name: "my-worker", content: code,
+    secretTextBindings: [{name: "API_KEY", text: apiKey}],
+});
+```
+
+**Store secrets:**
+```bash
+pulumi config set --secret apiKey "secret-value"
+```
+
+**Use environment variables:**
+```bash
+export CLOUDFLARE_API_TOKEN="..."
+pulumi up
+```
+
+### API Token Scopes
+Create tokens with minimal permissions:
+- Workers: `Workers Routes:Edit`, `Workers Scripts:Edit`
+- KV: `Workers KV Storage:Edit`
+- R2: `R2:Edit`
+- D1: `D1:Edit`
+- DNS: `Zone:Edit`, `DNS:Edit`
+- Pages: `Pages:Edit`
+
+### State Security
+- Use Pulumi Cloud or S3 backend with encryption
+- Never commit state files to VCS
+- Use RBAC to control stack access
+
+## Performance
+
+### Reduce State Size
+- Avoid storing large files in state
+- Use `ignoreChanges` for frequently changing properties
+- Use external build processes
+
+### Parallel Updates
+Pulumi automatically parallelizes independent resource updates.
+
+### Refresh Strategy
+```bash
+pulumi refresh --yes # Sync state with actual infrastructure
+```
+
+## Migration
+
+### Import Existing Resources
+```bash
+pulumi import cloudflare:index/workerScript:WorkerScript my-worker <account_id>/<worker_name>
+pulumi import cloudflare:index/workersKvNamespace:WorkersKvNamespace my-kv <namespace_id>
+pulumi import cloudflare:index/r2Bucket:R2Bucket my-bucket <account_id>/<bucket_name>
+```
+
+### From Terraform
+Use `pulumi import` and rewrite configs in Pulumi DSL.
+
+### From Wrangler
+1. Create Pulumi resources matching wrangler.toml
+2. Import existing resources
+3. Verify with `pulumi preview`
+4. Switch to Pulumi for deployments
+
+## CI/CD
+
+**GitHub Actions:**
+```yaml
+name: Deploy
+on: [push]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: pulumi/actions@v4
+        with:
+          command: up
+          stack-name: prod
+        env:
+          PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+```
+
+**GitLab CI:**
+```yaml
+deploy:
+  image: pulumi/pulumi:latest
+  script:
+    - pulumi stack select prod
+    - pulumi up --yes
+  only:
+    - main
+  variables:
+    CLOUDFLARE_API_TOKEN: $CLOUDFLARE_API_TOKEN
+```
+
+## Resources
+
+- **Pulumi Registry:** https://www.pulumi.com/registry/packages/cloudflare/
+- **API Docs:** https://www.pulumi.com/registry/packages/cloudflare/api-docs/
+- **GitHub:** https://github.com/pulumi/pulumi-cloudflare
+- **Cloudflare Docs:** https://developers.cloudflare.com/
+- **Workers Docs:** https://developers.cloudflare.com/workers/
+
+---
+See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)

package/.codex/skills/cloudflare/references/pulumi/patterns.md

@@ -0,0 +1,139 @@
+# Architecture Patterns
+
+## Component Resources
+
+```typescript
+class WorkerApp extends pulumi.ComponentResource {
+    constructor(name: string, args: WorkerAppArgs, opts?) {
+        super("custom:cloudflare:WorkerApp", name, {}, opts);
+        const defaultOpts = {parent: this};
+
+        this.kv = new cloudflare.WorkersKvNamespace(`${name}-kv`, {accountId: args.accountId, title: `${name}-kv`}, defaultOpts);
+        this.worker = new cloudflare.WorkerScript(`${name}-worker`, {
+            accountId: args.accountId, name: `${name}-worker`, content: args.workerCode,
+            module: true, kvNamespaceBindings: [{name: "KV", namespaceId: this.kv.id}],
+        }, defaultOpts);
+        this.domain = new cloudflare.WorkersDomain(`${name}-domain`, {
+            accountId: args.accountId, hostname: args.domain, service: this.worker.name,
+        }, defaultOpts);
+    }
+}
+```
+
+## Full-Stack Worker App
+
+```typescript
+const kv = new cloudflare.WorkersKvNamespace("cache", {accountId, title: "api-cache"});
+const db = new cloudflare.D1Database("db", {accountId, name: "app-database"});
+const bucket = new cloudflare.R2Bucket("assets", {accountId, name: "app-assets"});
+
+const apiWorker = new cloudflare.WorkerScript("api", {
+    accountId, name: "api-worker", content: fs.readFileSync("./dist/api.js", "utf8"),
+    module: true, kvNamespaceBindings: [{name: "CACHE", namespaceId: kv.id}],
+    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
+    r2BucketBindings: [{name: "ASSETS", bucketName: bucket.name}],
+});
+```
+
+## Multi-Environment Setup
+
+```typescript
+const stack = pulumi.getStack();
+const worker = new cloudflare.WorkerScript(`worker-${stack}`, {
+    accountId, name: `my-worker-${stack}`, content: code,
+    plainTextBindings: [{name: "ENVIRONMENT", text: stack}],
+});
+```
+
+## Queue-Based Processing
+
+```typescript
+const queue = new cloudflare.Queue("processing-queue", {accountId, name: "image-processing"});
+
+// Producer: API receives requests
+const apiWorker = new cloudflare.WorkerScript("api", {
+    accountId, name: "api-worker", content: apiCode,
+    queueBindings: [{name: "PROCESSING_QUEUE", queue: queue.id}],
+});
+
+// Consumer: Process async
+const processorWorker = new cloudflare.WorkerScript("processor", {
+    accountId, name: "processor-worker", content: processorCode,
+    queueConsumers: [{queue: queue.name, maxBatchSize: 10, maxRetries: 3, maxWaitTimeMs: 5000}],
+    r2BucketBindings: [{name: "OUTPUT_BUCKET", bucketName: outputBucket.name}],
+});
+```
+
+## Microservices with Service Bindings
+
+```typescript
+const authWorker = new cloudflare.WorkerScript("auth", {accountId, name: "auth-service", content: authCode});
+const apiWorker = new cloudflare.WorkerScript("api", {
+    accountId, name: "api-service", content: apiCode,
+    serviceBindings: [{name: "AUTH", service: authWorker.name}],
+});
+// In worker: await env.AUTH.fetch("/verify", {...});
+```
+
+## Event-Driven Architecture
+
+```typescript
+const eventQueue = new cloudflare.Queue("events", {accountId, name: "event-bus"});
+const producers = ["api", "webhook"].map(name =>
+    new cloudflare.WorkerScript(`${name}-producer`, {
+        accountId, name: `${name}-producer`, content: producerCode,
+        queueBindings: [{name: "EVENTS", queue: eventQueue.id}],
+    })
+);
+const consumers = ["email", "analytics"].map(name =>
+    new cloudflare.WorkerScript(`${name}-consumer`, {
+        accountId, name: `${name}-consumer`, content: consumerCode,
+        queueConsumers: [{queue: eventQueue.name, maxBatchSize: 10}],
+    })
+);
+```
+
+## CDN with Dynamic Content
+
+```typescript
+const staticBucket = new cloudflare.R2Bucket("static", {accountId, name: "static-assets"});
+const appWorker = new cloudflare.WorkerScript("app", {
+    accountId, name: "app-worker", content: appCode,
+    r2BucketBindings: [{name: "STATIC", bucketName: staticBucket.name}],
+});
+const route = new cloudflare.WorkerRoute("route", {zoneId, pattern: `${domain}/*`, scriptName: appWorker.name});
+```
+
+## Wrangler Integration
+
+```typescript
+// Match wrangler.toml bindings in Pulumi
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId, name: "my-worker", content: code,
+    compatibilityDate: "2024-01-01", compatibilityFlags: ["nodejs_compat"],
+    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}], // Must match wrangler.toml
+});
+```
+
+## Dynamic Worker Content
+
+```typescript
+import * as command from "@pulumi/command";
+const build = new command.local.Command("build-worker", {create: "npm run build", dir: "./worker"});
+const workerContent = build.stdout.apply(() => fs.readFileSync("./worker/dist/index.js", "utf8"));
+const worker = new cloudflare.WorkerScript("worker", {accountId, name: "my-worker", content: workerContent}, {dependsOn: [build]});
+```
+
+## Conditional Resources
+
+```typescript
+const isProd = pulumi.getStack() === "prod";
+const analytics = isProd ? new cloudflare.WorkersKvNamespace("analytics", {accountId, title: "analytics"}) : undefined;
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId, name: "worker", content: code,
+    kvNamespaceBindings: analytics ? [{name: "ANALYTICS", namespaceId: analytics.id}] : [],
+});
+```
+
+---
+See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)

package/.codex/skills/cloudflare/references/queues/README.md

@@ -0,0 +1,69 @@
+# Cloudflare Queues
+
+Flexible message queuing for async task processing with guaranteed at-least-once delivery and configurable batching.
+
+## Overview
+
+Queues provide:
+- At-least-once delivery guarantee
+- Push-based (Worker) and pull-based (HTTP) consumers
+- Configurable batching and retries
+- Dead Letter Queues (DLQ)
+- Delays up to 12 hours
+
+**Use cases:** Async processing, API buffering, rate limiting, event workflows, deferred jobs
+
+## Quick Start
+
+```bash
+wrangler queues create my-queue
+wrangler queues consumer add my-queue my-worker
+```
+
+```typescript
+// Producer
+await env.MY_QUEUE.send({ userId: 123, action: 'notify' });
+
+// Consumer
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      await process(msg.body);
+      msg.ack();
+    }
+  }
+};
+```
+
+## Core Operations
+
+| Operation | Purpose | Limit |
+|-----------|---------|-------|
+| `send(body, options?)` | Publish message | 128 KB |
+| `sendBatch(messages)` | Bulk publish | 100 msgs/256 KB |
+| `message.ack()` | Acknowledge success | - |
+| `message.retry(options?)` | Retry with delay | - |
+| `batch.ackAll()` | Ack entire batch | - |
+
+## Architecture
+
+```
+[Producer Worker] → [Queue] → [Consumer Worker/HTTP] → [Processing]
+```
+
+- Max 10,000 queues per account
+- 5,000 msgs/second per queue
+- 4-14 day retention (configurable)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, producer/consumer config, DLQ
+- [api.md](./api.md) - Send/batch methods, queue handler, ack/retry, pull API
+- [patterns.md](./patterns.md) - Async tasks, buffering, rate limiting, event workflows
+- [gotchas.md](./gotchas.md) - Idempotency, retry limits, content types, cost optimization
+
+## See Also
+
+- [workers](../workers/) - Worker runtime for producers/consumers
+- [r2](../r2/) - Process R2 event notifications via queues
+- [d1](../d1/) - Batch write to D1 from queue consumers

package/.codex/skills/cloudflare/references/queues/api.md

@@ -0,0 +1,138 @@
+# Queues API Reference
+
+## Producer: Send Messages
+
+```typescript
+// Basic send
+await env.MY_QUEUE.send({ url: request.url, timestamp: Date.now() });
+
+// Options: delay (max 43200s), contentType (json|text|bytes|v8)
+await env.MY_QUEUE.send(message, { delaySeconds: 600 });
+await env.MY_QUEUE.send(message, { delaySeconds: 0 }); // Override queue default
+
+// Batch (up to 100 msgs or 256 KB)
+await env.MY_QUEUE.sendBatch([
+  { body: 'msg1' },
+  { body: 'msg2' },
+  { body: 'msg3', options: { delaySeconds: 300 } }
+]);
+
+// Non-blocking
+ctx.waitUntil(env.MY_QUEUE.send({ data: 'async' }));
+```
+
+## Consumer: Push-based (Worker)
+
+```typescript
+export default {
+  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void> {
+    // batch.queue, batch.messages.length
+    for (const msg of batch.messages) {
+      // msg.id, msg.body, msg.timestamp, msg.attempts
+      try {
+        await processMessage(msg.body);
+        msg.ack();
+      } catch (error) {
+        msg.retry({ delaySeconds: 600 });
+      }
+    }
+  }
+};
+```
+
+## Batch Operations
+
+```typescript
+// Acknowledge entire batch
+try {
+  await bulkProcess(batch.messages);
+  batch.ackAll();
+} catch (error) {
+  batch.retryAll({ delaySeconds: 300 });
+}
+```
+
+## Exponential Backoff
+
+```typescript
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    try {
+      await processMessage(msg.body);
+      msg.ack();
+    } catch (error) {
+      const delay = Math.min(30 ** msg.attempts, 43200);
+      msg.retry({ delaySeconds: delay });
+    }
+  }
+}
+```
+
+## Multiple Queues, Single Consumer
+
+```typescript
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    switch (batch.queue) {
+      case 'high-priority': await processUrgent(batch.messages); break;
+      case 'low-priority': await processDeferred(batch.messages); break;
+      case 'email': await sendEmails(batch.messages); break;
+      default: batch.retryAll();
+    }
+  }
+};
+```
+
+## Consumer: Pull-based (HTTP)
+
+```typescript
+// Pull messages
+const response = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/queues/${QUEUE_ID}/messages/pull`,
+  {
+    method: 'POST',
+    headers: { 'authorization': `Bearer ${API_TOKEN}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ visibility_timeout_ms: 6000, batch_size: 50 })
+  }
+);
+
+const data = await response.json();
+
+// Acknowledge
+await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/queues/${QUEUE_ID}/messages/ack`,
+  {
+    method: 'POST',
+    headers: { 'authorization': `Bearer ${API_TOKEN}`, 'content-type': 'application/json' },
+    body: JSON.stringify({
+      acks: [{ lease_id: msg.lease_id }],
+      retries: [{ lease_id: msg2.lease_id, delay_seconds: 600 }]
+    })
+  }
+);
+```
+
+## Interfaces
+
+```typescript
+interface MessageBatch<Body = unknown> {
+  readonly queue: string;
+  readonly messages: Message<Body>[];
+  ackAll(): void;
+  retryAll(options?: QueueRetryOptions): void;
+}
+
+interface Message<Body = unknown> {
+  readonly id: string;
+  readonly timestamp: Date;
+  readonly body: Body;
+  readonly attempts: number;
+  ack(): void;
+  retry(options?: QueueRetryOptions): void;
+}
+
+interface QueueSendOptions {
+  contentType?: 'text' | 'bytes' | 'json' | 'v8';
+  delaySeconds?: number; // 0-43200
+}
+```

package/.codex/skills/cloudflare/references/queues/configuration.md

@@ -0,0 +1,125 @@
+# Queues Configuration
+
+## Create Queue
+
+```bash
+wrangler queues create my-queue
+wrangler queues create my-queue --retention-period-hours=336  # 14 days
+wrangler queues create my-queue --delivery-delay-secs=300
+```
+
+## Producer Binding
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "queues": {
+    "producers": [
+      {
+        "queue": "my-queue-name",
+        "binding": "MY_QUEUE",
+        "delivery_delay": 60  // Optional: default delay in seconds
+      }
+    ]
+  }
+}
+```
+
+**wrangler.toml:**
+```toml
+[[queues.producers]]
+queue = "my-queue-name"
+binding = "MY_QUEUE"
+delivery_delay = 60
+```
+
+## Consumer Configuration (Push-based)
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "queues": {
+    "consumers": [
+      {
+        "queue": "my-queue-name",
+        "max_batch_size": 10,           // 1-100, default 10
+        "max_batch_timeout": 5,         // 0-60s, default 5
+        "max_retries": 3,               // default 3, max 100
+        "dead_letter_queue": "my-dlq",  // optional
+        "retry_delay": 300              // optional: delay retries in seconds
+      }
+    ]
+  }
+}
+```
+
+**wrangler.toml:**
+```toml
+[[queues.consumers]]
+queue = "my-queue-name"
+max_batch_size = 10
+max_batch_timeout = 5
+max_retries = 3
+dead_letter_queue = "my-dlq"
+retry_delay = 300
+```
+
+## Consumer Configuration (Pull-based)
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "queues": {
+    "consumers": [
+      {
+        "queue": "my-queue-name",
+        "type": "http_pull",
+        "visibility_timeout_ms": 5000,  // default 30000, max 12h
+        "max_retries": 5,
+        "dead_letter_queue": "my-dlq"
+      }
+    ]
+  }
+}
+```
+
+## TypeScript Types
+
+```typescript
+interface Env {
+  MY_QUEUE: Queue<MessageBody>;
+  ANALYTICS_QUEUE: Queue<AnalyticsEvent>;
+}
+
+interface MessageBody {
+  id: string;
+  action: 'create' | 'update' | 'delete';
+  data: Record<string, any>;
+}
+
+export default {
+  async queue(batch: MessageBatch<MessageBody>, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      console.log(msg.body.action);
+      msg.ack();
+    }
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## CLI Commands
+
+```bash
+# Consumer management
+wrangler queues consumer add my-queue my-worker --batch-size=50 --max-retries=5
+wrangler queues consumer http add my-queue
+wrangler queues consumer worker remove my-queue my-worker
+wrangler queues consumer http remove my-queue
+
+# Queue operations
+wrangler queues list
+wrangler queues pause my-queue
+wrangler queues resume my-queue
+wrangler queues purge my-queue
+wrangler queues delete my-queue
+```