memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,205 @@
+# Troubleshooting & Best Practices
+
+## Common Errors
+
+### "No bundler/build step" - Pulumi uploads raw code
+
+**Problem:** Worker fails with "Cannot use import statement outside a module"  
+**Cause:** Pulumi doesn't bundle Worker code - uploads exactly what you provide  
+**Solution:** Build Worker BEFORE Pulumi deploy
+
+```typescript
+// WRONG: Pulumi won't bundle this
+const worker = new cloudflare.WorkerScript('worker', {
+  content: fs.readFileSync('./src/index.ts', 'utf8'), // Raw TS file
+})
+
+// RIGHT: Build first, then deploy
+import * as command from '@pulumi/command'
+const build = new command.local.Command('build', {
+  create: 'npm run build',
+  dir: './worker',
+})
+const worker = new cloudflare.WorkerScript(
+  'worker',
+  {
+    content: build.stdout.apply(() => fs.readFileSync('./worker/dist/index.js', 'utf8')),
+  },
+  { dependsOn: [build] }
+)
+```
+
+### "wrangler.toml not consumed" - Config drift
+
+**Problem:** Local wrangler dev works, Pulumi deploy fails  
+**Cause:** Pulumi ignores wrangler.toml - must duplicate config  
+**Solution:** Generate wrangler.toml from Pulumi or keep synced manually
+
+```typescript
+// Pattern: Export Pulumi config to wrangler.toml
+const workerConfig = {
+  name: 'my-worker',
+  compatibilityDate: '2025-01-01',
+  compatibilityFlags: ['nodejs_compat'],
+}
+
+new command.local.Command('generate-wrangler', {
+  create: pulumi.interpolate`cat > wrangler.toml <<EOF
+name = "${workerConfig.name}"
+compatibility_date = "${workerConfig.compatibilityDate}"
+compatibility_flags = ${JSON.stringify(workerConfig.compatibilityFlags)}
+EOF`,
+})
+```
+
+### "False no-changes detection" - Content SHA unchanged
+
+**Problem:** Worker code updated, Pulumi says "no changes"  
+**Cause:** Content hash identical (whitespace/comment-only change)  
+**Solution:** Add build timestamp or version to force update
+
+```typescript
+const version = Date.now().toString()
+const worker = new cloudflare.WorkerScript('worker', {
+  content: code,
+  plainTextBindings: [{ name: 'VERSION', text: version }], // Forces new deployment
+})
+```
+
+### "D1 migrations don't run on pulumi up"
+
+**Problem:** Database schema not applied after D1 database created  
+**Cause:** Pulumi creates database but doesn't run migrations  
+**Solution:** Use Command resource with dependsOn
+
+```typescript
+const db = new cloudflare.D1Database('db', { accountId, name: 'mydb' })
+
+// Run migrations after DB created
+const migration = new command.local.Command(
+  'migrate',
+  {
+    create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,
+  },
+  { dependsOn: [db] }
+)
+
+// Worker depends on migrations
+const worker = new cloudflare.WorkerScript(
+  'worker',
+  {
+    d1DatabaseBindings: [{ name: 'DB', databaseId: db.id }],
+  },
+  { dependsOn: [migration] }
+)
+```
+
+### "Missing required property 'accountId'"
+
+**Problem:** `Error: Missing required property 'accountId'`  
+**Cause:** Account ID not provided in resource configuration  
+**Solution:** Add to stack config
+
+```yaml
+# Pulumi.<stack>.yaml
+config:
+  cloudflare:accountId: 'abc123...'
+```
+
+### "Binding name mismatch"
+
+**Problem:** Worker fails with "env.MY_KV is undefined"  
+**Cause:** Binding name in Pulumi != name in Worker code  
+**Solution:** Match exactly (case-sensitive)
+
+```typescript
+// Pulumi
+kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }]
+
+// Worker code
+export default {
+  async fetch(request, env) {
+    await env.MY_KV.get('key')
+  },
+}
+```
+
+### "API token permissions insufficient"
+
+**Problem:** `Error: authentication error (10000)`  
+**Cause:** Token lacks required permissions  
+**Solution:** Grant token permissions: Account.Workers Scripts:Edit, Account.Account Settings:Read
+
+### "Resource not found after import"
+
+**Problem:** Imported resource shows as changed on next `pulumi up`  
+**Cause:** State mismatch between actual resource and Pulumi config  
+**Solution:** Check property names/types match exactly
+
+```bash
+pulumi import cloudflare:index/workerScript:WorkerScript my-worker <account_id>/<worker_name>
+pulumi preview # If shows changes, adjust Pulumi code to match actual resource
+```
+
+### "v6.x Worker versioning confusion"
+
+**Problem:** Worker deployed but not receiving traffic  
+**Cause:** v6.x requires Worker + WorkerVersion + WorkersDeployment (3 resources)  
+**Solution:** Use WorkerScript (auto-versioning) OR full versioning pattern
+
+```typescript
+// SIMPLE: WorkerScript auto-versions (default behavior)
+const worker = new cloudflare.WorkerScript('worker', {
+  accountId,
+  name: 'my-worker',
+  content: code,
+})
+
+// ADVANCED: Manual versioning for gradual rollouts (v6.x)
+const worker = new cloudflare.Worker('worker', { accountId, name: 'my-worker' })
+const version = new cloudflare.WorkerVersion('v1', {
+  accountId,
+  workerId: worker.id,
+  content: code,
+  compatibilityDate: '2025-01-01',
+})
+const deployment = new cloudflare.WorkersDeployment('prod', {
+  accountId,
+  workerId: worker.id,
+  versionId: version.id,
+})
+```
+
+## Best Practices
+
+1. **Always set compatibilityDate** - Locks Worker behavior, prevents breaking changes
+2. **Build before deploy** - Pulumi doesn't bundle; use Command resource or CI build step
+3. **Match binding names** - Case-sensitive, must match between Pulumi and Worker code
+4. **Use dependsOn for migrations** - Ensure D1 migrations run before Worker deploys
+5. **Version Worker content** - Add VERSION binding to force redeployment on content changes
+6. **Store secrets in stack config** - Use `pulumi config set --secret` for API keys
+
+## Limits
+
+| Resource              | Limit                   | Notes                                         |
+| --------------------- | ----------------------- | --------------------------------------------- |
+| Worker script size    | 10 MB                   | Includes all dependencies, after compression  |
+| Worker CPU time       | 50ms (free), 30s (paid) | Per request                                   |
+| KV keys per namespace | Unlimited               | 1000 ops/sec write, 100k ops/sec read         |
+| R2 storage            | Unlimited               | Class A ops: 1M/mo free, Class B: 10M/mo free |
+| D1 databases          | 50,000 per account      | Free: 10 per account, 5 GB each               |
+| Queues                | 10,000 per account      | Free: 1M ops/day                              |
+| Pages projects        | 500 per account         | Free: 100 projects                            |
+| API requests          | Varies by plan          | ~1200 req/5min on free                        |
+
+## 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/skills/cloudflare/references/pulumi/patterns.md

@@ -0,0 +1,260 @@
+# 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 }],
+})
+```
+
+## Event-Driven Architecture
+
+```typescript
+const eventQueue = new cloudflare.Queue('events', { accountId, name: 'event-bus' })
+const producer = new cloudflare.WorkerScript('producer', {
+  accountId,
+  name: 'api-producer',
+  content: producerCode,
+  queueBindings: [{ name: 'EVENTS', queue: eventQueue.id }],
+})
+const consumer = new cloudflare.WorkerScript('consumer', {
+  accountId,
+  name: 'email-consumer',
+  content: consumerCode,
+  queueConsumers: [{ queue: eventQueue.name, maxBatchSize: 10 }],
+})
+```
+
+## v6.x Versioned Deployments (Blue-Green/Canary)
+
+```typescript
+const worker = new cloudflare.Worker('api', { accountId, name: 'api-worker' })
+const v1 = new cloudflare.WorkerVersion('v1', {
+  accountId,
+  workerId: worker.id,
+  content: fs.readFileSync('./dist/v1.js', 'utf8'),
+  compatibilityDate: '2025-01-01',
+})
+const v2 = new cloudflare.WorkerVersion('v2', {
+  accountId,
+  workerId: worker.id,
+  content: fs.readFileSync('./dist/v2.js', 'utf8'),
+  compatibilityDate: '2025-01-01',
+})
+
+// Gradual rollout: 10% v2, 90% v1
+const deployment = new cloudflare.WorkersDeployment('canary', {
+  accountId,
+  workerId: worker.id,
+  versions: [
+    { versionId: v2.id, percentage: 10 },
+    { versionId: v1.id, percentage: 90 },
+  ],
+  kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }],
+})
+```
+
+**Use:** Canary releases, A/B testing, blue-green. Most apps use `WorkerScript` (auto-versioning).
+
+## Wrangler.toml Generation (Bridge IaC with Local Dev)
+
+Generate wrangler.toml from Pulumi config to keep local dev in sync:
+
+```typescript
+import * as command from '@pulumi/command'
+
+const workerConfig = {
+  name: 'my-worker',
+  compatibilityDate: '2025-01-01',
+  compatibilityFlags: ['nodejs_compat'],
+}
+
+// Create resources
+const kv = new cloudflare.WorkersKvNamespace('kv', { accountId, title: 'my-kv' })
+const db = new cloudflare.D1Database('db', { accountId, name: 'my-db' })
+const bucket = new cloudflare.R2Bucket('bucket', { accountId, name: 'my-bucket' })
+
+// Generate wrangler.toml after resources created
+const wranglerGen = new command.local.Command(
+  'gen-wrangler',
+  {
+    create: pulumi.interpolate`cat > wrangler.toml <<EOF
+name = "${workerConfig.name}"
+main = "src/index.ts"
+compatibility_date = "${workerConfig.compatibilityDate}"
+compatibility_flags = ${JSON.stringify(workerConfig.compatibilityFlags)}
+
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "${kv.id}"
+
+[[d1_databases]]
+binding = "DB"
+database_id = "${db.id}"
+database_name = "${db.name}"
+
+[[r2_buckets]]
+binding = "MY_BUCKET"
+bucket_name = "${bucket.name}"
+EOF`,
+  },
+  { dependsOn: [kv, db, bucket] }
+)
+
+// Deploy worker after wrangler.toml generated
+const worker = new cloudflare.WorkerScript(
+  'worker',
+  {
+    accountId,
+    name: workerConfig.name,
+    content: code,
+    compatibilityDate: workerConfig.compatibilityDate,
+    compatibilityFlags: workerConfig.compatibilityFlags,
+    kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }],
+    d1DatabaseBindings: [{ name: 'DB', databaseId: db.id }],
+    r2BucketBindings: [{ name: 'MY_BUCKET', bucketName: bucket.name }],
+  },
+  { dependsOn: [wranglerGen] }
+)
+```
+
+**Benefits:**
+
+- `wrangler dev` uses same bindings as production
+- No config drift between Pulumi and local dev
+- Single source of truth (Pulumi config)
+
+**Alternative:** Read wrangler.toml in Pulumi (reverse direction) if wrangler is source of truth
+
+## Build + Deploy Pattern
+
+```typescript
+import * as command from '@pulumi/command'
+const build = new command.local.Command('build', { create: 'npm run build', dir: './worker' })
+const worker = new cloudflare.WorkerScript(
+  'worker',
+  {
+    accountId,
+    name: 'my-worker',
+    content: build.stdout.apply(() => fs.readFileSync('./worker/dist/index.js', 'utf8')),
+  },
+  { dependsOn: [build] }
+)
+```
+
+## Content SHA Pattern (Force Updates)
+
+Prevent false "no changes" detections:
+
+```typescript
+const version = Date.now().toString()
+const worker = new cloudflare.WorkerScript('worker', {
+  accountId,
+  name: 'my-worker',
+  content: code,
+  plainTextBindings: [{ name: 'VERSION', text: version }], // Forces deployment
+})
+```
+
+---
+
+See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)

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

@@ -0,0 +1,99 @@
+# 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 (with proper error handling)
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      try {
+        await process(msg.body)
+        msg.ack()
+      } catch (error) {
+        msg.retry({ delaySeconds: 60 })
+      }
+    }
+  },
+}
+```
+
+## Critical Warnings
+
+**Before using Queues, understand these production mistakes:**
+
+1. **Uncaught errors retry ENTIRE batch** (not just failed message). Always use per-message try/catch.
+2. **Messages not ack'd/retry'd will auto-retry forever** until max_retries. Always explicitly handle each message.
+
+See [gotchas.md](./gotchas.md) for detailed solutions.
+
+## 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)
+
+## Reading Order
+
+**New to Queues?** Start here:
+
+1. [configuration.md](./configuration.md) - Set up queues, bindings, consumers
+2. [api.md](./api.md) - Send messages, handle batches, ack/retry patterns
+3. [patterns.md](./patterns.md) - Real-world examples and integrations
+4. [gotchas.md](./gotchas.md) - Critical warnings and troubleshooting
+
+**Task-based routing:**
+
+- Setup queue → [configuration.md](./configuration.md)
+- Send/receive messages → [api.md](./api.md)
+- Implement specific pattern → [patterns.md](./patterns.md)
+- Debug/troubleshoot → [gotchas.md](./gotchas.md)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, producer/consumer config, DLQ, content types
+- [api.md](./api.md) - Send/batch methods, queue handler, ack/retry rules, type-safe patterns
+- [patterns.md](./patterns.md) - Async tasks, buffering, rate limiting, D1/Workflows/DO integrations
+- [gotchas.md](./gotchas.md) - Critical batch error handling, idempotency, error classification
+
+## 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