memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,113 @@
+# Cloudflare Pulumi Provider
+
+Expert guidance for Cloudflare Pulumi Provider (@pulumi/cloudflare).
+
+## Overview
+
+Programmatic management of Cloudflare resources: Workers, Pages, D1, KV, R2, DNS, Queues, etc.
+
+**Packages:**
+
+- TypeScript/JS: `@pulumi/cloudflare`
+- Python: `pulumi-cloudflare`
+- Go: `github.com/pulumi/pulumi-cloudflare/sdk/v6/go/cloudflare`
+- .NET: `Pulumi.Cloudflare`
+
+**Version:** v6.x
+
+## Core Principles
+
+1. Use API tokens (not legacy API keys)
+2. Store accountId in stack config
+3. Match binding names across code/config
+4. Use `module: true` for ES modules
+5. Set `compatibilityDate` to lock behavior
+
+## Authentication
+
+```typescript
+import * as cloudflare from '@pulumi/cloudflare'
+
+// API Token (recommended): CLOUDFLARE_API_TOKEN env
+const provider = new cloudflare.Provider('cf', { apiToken: process.env.CLOUDFLARE_API_TOKEN })
+
+// API Key (legacy): CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL env
+const provider = new cloudflare.Provider('cf', {
+  apiKey: process.env.CLOUDFLARE_API_KEY,
+  email: process.env.CLOUDFLARE_EMAIL,
+})
+
+// API User Service Key: CLOUDFLARE_API_USER_SERVICE_KEY env
+const provider = new cloudflare.Provider('cf', {
+  apiUserServiceKey: process.env.CLOUDFLARE_API_USER_SERVICE_KEY,
+})
+```
+
+## Setup
+
+**Pulumi.yaml:**
+
+```yaml
+name: my-cloudflare-app
+runtime: nodejs
+config:
+  cloudflare:apiToken:
+    value: ${CLOUDFLARE_API_TOKEN}
+```
+
+**Pulumi.<stack>.yaml:**
+
+```yaml
+config:
+  cloudflare:accountId: 'abc123...'
+```
+
+**index.ts:**
+
+```typescript
+import * as pulumi from '@pulumi/pulumi'
+import * as cloudflare from '@pulumi/cloudflare'
+const accountId = new pulumi.Config('cloudflare').require('accountId')
+```
+
+## Common Resource Types
+
+- `Provider` - Provider config
+- `WorkerScript` - Worker
+- `WorkersKvNamespace` - KV
+- `R2Bucket` - R2
+- `D1Database` - D1
+- `Queue` - Queue
+- `PagesProject` - Pages
+- `DnsRecord` - DNS
+- `WorkerRoute` - Worker route
+- `WorkersDomain` - Custom domain
+
+## Key Properties
+
+- `accountId` - Required for most resources
+- `zoneId` - Required for DNS/domain
+- `name`/`title` - Resource identifier
+- `*Bindings` - Connect resources to Workers
+
+## Reading Order
+
+| Order | File                                   | What                                                  | When to Read                          |
+| ----- | -------------------------------------- | ----------------------------------------------------- | ------------------------------------- |
+| 1     | [configuration.md](./configuration.md) | Resource config for Workers/KV/D1/R2/Queues/Pages     | First time setup, resource reference  |
+| 2     | [patterns.md](./patterns.md)           | Architecture patterns, multi-env, component resources | Building complex apps, best practices |
+| 3     | [api.md](./api.md)                     | Outputs, dependencies, imports, dynamic providers     | Advanced features, integrations       |
+| 4     | [gotchas.md](./gotchas.md)             | Common errors, troubleshooting, limits                | Debugging, deployment issues          |
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Provider config, stack setup, Workers/bindings
+- [api.md](./api.md) - Resource types, Workers script, KV/D1/R2/queues/Pages
+- [patterns.md](./patterns.md) - Multi-env, secrets, CI/CD, stack management
+- [gotchas.md](./gotchas.md) - State issues, deployment failures, limits
+
+## See Also
+
+- [terraform](../terraform/) - Alternative IaC for Cloudflare
+- [wrangler](../wrangler/) - CLI deployment alternative
+- [workers](../workers/) - Worker runtime documentation

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

@@ -0,0 +1,230 @@
+# API & Data Sources
+
+## Outputs and Exports
+
+Export resource identifiers:
+
+```typescript
+export const kvId = kv.id
+export const bucketName = bucket.name
+export const workerUrl = worker.subdomain
+export const dbId = db.id
+```
+
+## Resource Dependencies
+
+Implicit dependencies via outputs:
+
+```typescript
+const kv = new cloudflare.WorkersKvNamespace('kv', {
+  accountId: accountId,
+  title: 'my-kv',
+})
+
+// Worker depends on KV (implicit via kv.id)
+const worker = new cloudflare.WorkerScript('worker', {
+  accountId: accountId,
+  name: 'my-worker',
+  content: code,
+  kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }], // Creates dependency
+})
+```
+
+Explicit dependencies:
+
+```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: accountId,
+    name: 'worker',
+    content: code,
+    d1DatabaseBindings: [{ name: 'DB', databaseId: db.id }],
+  },
+  { dependsOn: [migration] }
+) // Ensure migrations run first
+```
+
+## Using Outputs with API Calls
+
+```typescript
+const db = new cloudflare.D1Database('db', { accountId, name: 'my-db' })
+
+db.id.apply(async (dbId) => {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${dbId}/query`,
+    {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sql: 'CREATE TABLE users (id INT)' }),
+    }
+  )
+  return response.json()
+})
+```
+
+## Custom Dynamic Providers
+
+For resources not in provider:
+
+```typescript
+import * as pulumi from '@pulumi/pulumi'
+
+class D1MigrationProvider implements pulumi.dynamic.ResourceProvider {
+  async create(inputs: any): Promise<pulumi.dynamic.CreateResult> {
+    const response = await fetch(
+      `https://api.cloudflare.com/client/v4/accounts/${inputs.accountId}/d1/database/${inputs.databaseId}/query`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${inputs.apiToken}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sql: inputs.sql }),
+      }
+    )
+    return { id: `${inputs.databaseId}-${Date.now()}`, outs: await response.json() }
+  }
+  async update(id: string, olds: any, news: any): Promise<pulumi.dynamic.UpdateResult> {
+    if (olds.sql !== news.sql) await this.create(news)
+    return {}
+  }
+  async delete(id: string, props: any): Promise<void> {}
+}
+
+class D1Migration extends pulumi.dynamic.Resource {
+  constructor(name: string, args: any, opts?: pulumi.CustomResourceOptions) {
+    super(new D1MigrationProvider(), name, args, opts)
+  }
+}
+
+const migration = new D1Migration(
+  'migration',
+  {
+    accountId,
+    databaseId: db.id,
+    apiToken,
+    sql: 'CREATE TABLE users (id INT)',
+  },
+  { dependsOn: [db] }
+)
+```
+
+## Data Sources
+
+**Get Zone:**
+
+```typescript
+const zone = cloudflare.getZone({ name: 'example.com' })
+const zoneId = zone.then((z) => z.id)
+```
+
+**Get Accounts (via API):**
+Use Cloudflare API directly or custom dynamic resources.
+
+## Import Existing Resources
+
+```bash
+# Import worker
+pulumi import cloudflare:index/workerScript:WorkerScript my-worker <account_id>/<worker_name>
+
+# Import KV namespace
+pulumi import cloudflare:index/workersKvNamespace:WorkersKvNamespace my-kv <namespace_id>
+
+# Import R2 bucket
+pulumi import cloudflare:index/r2Bucket:R2Bucket my-bucket <account_id>/<bucket_name>
+
+# Import D1 database
+pulumi import cloudflare:index/d1Database:D1Database my-db <account_id>/<database_id>
+
+# Import DNS record
+pulumi import cloudflare:index/dnsRecord:DnsRecord my-record <zone_id>/<record_id>
+```
+
+## Secrets Management
+
+```typescript
+import * as pulumi from '@pulumi/pulumi'
+
+const config = new pulumi.Config()
+const apiKey = config.requireSecret('apiKey') // Encrypted in state
+
+const worker = new cloudflare.WorkerScript('worker', {
+  accountId: accountId,
+  name: 'my-worker',
+  content: code,
+  secretTextBindings: [{ name: 'API_KEY', text: apiKey }],
+})
+```
+
+Store secrets:
+
+```bash
+pulumi config set --secret apiKey "secret-value"
+```
+
+## Transform Pattern
+
+Modify resource args before creation:
+
+```typescript
+import { Transform } from '@pulumi/pulumi'
+
+interface BucketArgs {
+  accountId: pulumi.Input<string>
+  transform?: { bucket?: Transform<cloudflare.R2BucketArgs> }
+}
+
+function createBucket(name: string, args: BucketArgs) {
+  const bucketArgs: cloudflare.R2BucketArgs = {
+    accountId: args.accountId,
+    name: name,
+    location: 'auto',
+  }
+  const finalArgs = args.transform?.bucket?.(bucketArgs) ?? bucketArgs
+  return new cloudflare.R2Bucket(name, finalArgs)
+}
+```
+
+## v6.x Worker Versioning Resources
+
+**Worker** - Container for versions:
+
+```typescript
+const worker = new cloudflare.Worker('api', { accountId, name: 'api-worker' })
+export const workerId = worker.id
+```
+
+**WorkerVersion** - Immutable code + config:
+
+```typescript
+const version = new cloudflare.WorkerVersion('v1', {
+  accountId,
+  workerId: worker.id,
+  content: fs.readFileSync('./dist/worker.js', 'utf8'),
+  compatibilityDate: '2025-01-01',
+})
+export const versionId = version.id
+```
+
+**WorkersDeployment** - Active deployment with bindings:
+
+```typescript
+const deployment = new cloudflare.WorkersDeployment('prod', {
+  accountId,
+  workerId: worker.id,
+  versionId: version.id,
+  kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }],
+})
+```
+
+**Use:** Advanced deployments (canary, blue-green). Most apps should use `WorkerScript` (auto-versioning).
+
+---
+
+See: [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

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

@@ -0,0 +1,213 @@
+# Resource Configuration
+
+## Workers (cloudflare.WorkerScript)
+
+```typescript
+import * as cloudflare from '@pulumi/cloudflare'
+import * as fs from 'fs'
+
+const worker = new cloudflare.WorkerScript('my-worker', {
+  accountId: accountId,
+  name: 'my-worker',
+  content: fs.readFileSync('./dist/worker.js', 'utf8'),
+  module: true, // ES modules
+  compatibilityDate: '2025-01-01',
+  compatibilityFlags: ['nodejs_compat'],
+
+  // v6.x: Observability
+  logpush: true, // Enable Workers Logpush
+  tailConsumers: [{ service: 'log-consumer' }], // Stream logs to Worker
+
+  // v6.x: Placement
+  placement: { mode: 'smart' }, // Smart placement for latency optimization
+
+  // Bindings
+  kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }],
+  r2BucketBindings: [{ name: 'MY_BUCKET', bucketName: bucket.name }],
+  d1DatabaseBindings: [{ name: 'DB', databaseId: db.id }],
+  queueBindings: [{ name: 'MY_QUEUE', queue: queue.id }],
+  serviceBindings: [{ name: 'OTHER_SERVICE', service: other.name }],
+  plainTextBindings: [{ name: 'ENV_VAR', text: 'value' }],
+  secretTextBindings: [{ name: 'API_KEY', text: secret }],
+
+  // v6.x: Advanced bindings
+  analyticsEngineBindings: [{ name: 'ANALYTICS', dataset: 'my-dataset' }],
+  browserBinding: { name: 'BROWSER' }, // Browser Rendering
+  aiBinding: { name: 'AI' }, // Workers AI
+  hyperdriveBindings: [{ name: 'HYPERDRIVE', id: hyperdriveConfig.id }],
+})
+```
+
+## Workers KV (cloudflare.WorkersKvNamespace)
+
+```typescript
+const kv = new cloudflare.WorkersKvNamespace('my-kv', {
+  accountId: accountId,
+  title: 'my-kv-namespace',
+})
+
+// Write values
+const kvValue = new cloudflare.WorkersKvValue('config', {
+  accountId: accountId,
+  namespaceId: kv.id,
+  key: 'config',
+  value: JSON.stringify({ foo: 'bar' }),
+})
+```
+
+## R2 Buckets (cloudflare.R2Bucket)
+
+```typescript
+const bucket = new cloudflare.R2Bucket('my-bucket', {
+  accountId: accountId,
+  name: 'my-bucket',
+  location: 'auto', // or "wnam", etc.
+})
+```
+
+## D1 Databases (cloudflare.D1Database)
+
+```typescript
+const db = new cloudflare.D1Database('my-db', { accountId, name: 'my-database' })
+
+// Migrations via wrangler
+import * as command from '@pulumi/command'
+const migration = new command.local.Command(
+  'd1-migration',
+  {
+    create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,
+  },
+  { dependsOn: [db] }
+)
+```
+
+## Queues (cloudflare.Queue)
+
+```typescript
+const queue = new cloudflare.Queue('my-queue', { accountId, name: 'my-queue' })
+
+// Producer
+const producer = new cloudflare.WorkerScript('producer', {
+  accountId,
+  name: 'producer',
+  content: code,
+  queueBindings: [{ name: 'MY_QUEUE', queue: queue.id }],
+})
+
+// Consumer
+const consumer = new cloudflare.WorkerScript('consumer', {
+  accountId,
+  name: 'consumer',
+  content: code,
+  queueConsumers: [{ queue: queue.name, maxBatchSize: 10, maxRetries: 3 }],
+})
+```
+
+## Pages Projects (cloudflare.PagesProject)
+
+```typescript
+const pages = new cloudflare.PagesProject('my-site', {
+  accountId,
+  name: 'my-site',
+  productionBranch: 'main',
+  buildConfig: { buildCommand: 'npm run build', destinationDir: 'dist' },
+  source: {
+    type: 'github',
+    config: { owner: 'my-org', repoName: 'my-repo', productionBranch: 'main' },
+  },
+  deploymentConfigs: {
+    production: {
+      environmentVariables: { NODE_VERSION: '18' },
+      kvNamespaces: { MY_KV: kv.id },
+      d1Databases: { DB: db.id },
+    },
+  },
+})
+```
+
+## DNS Records (cloudflare.DnsRecord)
+
+```typescript
+const zone = cloudflare.getZone({ name: 'example.com' })
+const record = new cloudflare.DnsRecord('www', {
+  zoneId: zone.then((z) => z.id),
+  name: 'www',
+  type: 'A',
+  content: '192.0.2.1',
+  ttl: 3600,
+  proxied: true,
+})
+```
+
+## Workers Domains/Routes
+
+```typescript
+// Route (pattern-based)
+const route = new cloudflare.WorkerRoute('my-route', {
+  zoneId: zoneId,
+  pattern: 'example.com/api/*',
+  scriptName: worker.name,
+})
+
+// Domain (dedicated subdomain)
+const domain = new cloudflare.WorkersDomain('my-domain', {
+  accountId: accountId,
+  hostname: 'api.example.com',
+  service: worker.name,
+  zoneId: zoneId,
+})
+```
+
+## Assets Configuration (v6.x)
+
+Serve static assets from Workers:
+
+```typescript
+const worker = new cloudflare.WorkerScript('app', {
+  accountId: accountId,
+  name: 'my-app',
+  content: code,
+  assets: {
+    path: './public', // Local directory
+    // Assets uploaded and served from Workers
+  },
+})
+```
+
+## v6.x Versioned Deployments (Advanced)
+
+For gradual rollouts, use 3-resource pattern:
+
+```typescript
+// 1. Worker (container for versions)
+const worker = new cloudflare.Worker('api', {
+  accountId: accountId,
+  name: 'api-worker',
+})
+
+// 2. Version (immutable code + config)
+const version = new cloudflare.WorkerVersion('v1', {
+  accountId: accountId,
+  workerId: worker.id,
+  content: fs.readFileSync('./dist/worker.js', 'utf8'),
+  compatibilityDate: '2025-01-01',
+  compatibilityFlags: ['nodejs_compat'],
+  // Note: Bindings configured at deployment level
+})
+
+// 3. Deployment (version + bindings + traffic split)
+const deployment = new cloudflare.WorkersDeployment('prod', {
+  accountId: accountId,
+  workerId: worker.id,
+  versionId: version.id,
+  // Bindings applied to deployment
+  kvNamespaceBindings: [{ name: 'MY_KV', namespaceId: kv.id }],
+})
+```
+
+**When to use:** Blue-green deployments, canary releases, gradual rollouts  
+**When NOT to use:** Simple single-version deployments (use WorkerScript)
+
+---
+
+See: [README.md](./README.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)