memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,214 @@
+# Bindings API Reference
+
+## TypeScript Types
+
+Cloudflare generates binding types via `npx wrangler types`. This creates `.wrangler/types/runtime.d.ts` with your Env interface.
+
+### Generated Env Interface
+
+After running `wrangler types`, TypeScript knows your bindings:
+
+```typescript
+interface Env {
+  // From wrangler.jsonc bindings
+  MY_KV: KVNamespace
+  MY_BUCKET: R2Bucket
+  DB: D1Database
+  MY_SERVICE: Fetcher
+  AI: Ai
+
+  // From vars
+  API_URL: string
+
+  // From secrets (set via wrangler secret put)
+  API_KEY: string
+}
+```
+
+### Binding Types
+
+| Config                                                     | TypeScript Type          | Package                     |
+| ---------------------------------------------------------- | ------------------------ | --------------------------- |
+| `kv_namespaces`                                            | `KVNamespace`            | `@cloudflare/workers-types` |
+| `r2_buckets`                                               | `R2Bucket`               | `@cloudflare/workers-types` |
+| `d1_databases`                                             | `D1Database`             | `@cloudflare/workers-types` |
+| `durable_objects.bindings`                                 | `DurableObjectNamespace` | `@cloudflare/workers-types` |
+| `vectorize`                                                | `VectorizeIndex`         | `@cloudflare/workers-types` |
+| `queues.producers`                                         | `Queue`                  | `@cloudflare/workers-types` |
+| `services`                                                 | `Fetcher`                | `@cloudflare/workers-types` |
+| `ai`                                                       | `Ai`                     | `@cloudflare/workers-types` |
+| `browser`                                                  | `Fetcher`                | `@cloudflare/workers-types` |
+| `analytics_engine_datasets`                                | `AnalyticsEngineDataset` | `@cloudflare/workers-types` |
+| `hyperdrive`                                               | `Hyperdrive`             | `@cloudflare/workers-types` |
+| `rate_limiting`                                            | `RateLimit`              | `@cloudflare/workers-types` |
+| `workflows`                                                | `Workflow`               | `@cloudflare/workers-types` |
+| `mtls_certificates` / `vars` / `text_blobs` / `data_blobs` | `string`                 | Built-in                    |
+| `wasm_modules`                                             | `WebAssembly.Module`     | Built-in                    |
+
+## Accessing Bindings
+
+### Method 1: fetch() Handler (Recommended)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const value = await env.MY_KV.get('key')
+    return new Response(value)
+  },
+}
+```
+
+**Why:** Type-safe, aligns with Workers API, supports ctx for waitUntil/passThroughOnException.
+
+### Method 2: Hono Framework
+
+```typescript
+import { Hono } from 'hono'
+
+const app = new Hono<{ Bindings: Env }>()
+
+app.get('/', async (c) => {
+  const value = await c.env.MY_KV.get('key')
+  return c.json({ value })
+})
+
+export default app
+```
+
+**Why:** c.env auto-typed, ergonomic for routing-heavy apps.
+
+### Method 3: Module Workers (Legacy)
+
+```typescript
+export async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const value = await env.MY_KV.get('key')
+  return new Response(value)
+}
+
+addEventListener('fetch', (event) => {
+  // env not directly available - requires workarounds
+})
+```
+
+**Avoid:** Use fetch() handler instead (Method 1).
+
+## Type Generation Workflow
+
+### Initial Setup
+
+```bash
+# Install wrangler
+npm install -D wrangler
+
+# Generate types from wrangler.jsonc
+npx wrangler types
+```
+
+### After Changing Bindings
+
+```bash
+# Added/modified binding in wrangler.jsonc
+npx wrangler types
+
+# TypeScript now sees updated Env interface
+```
+
+**Note:** `wrangler types` outputs to `.wrangler/types/runtime.d.ts`. TypeScript picks this up automatically if `@cloudflare/workers-types` is in `tsconfig.json` `"types"` array.
+
+## Key Binding Methods
+
+**KV:**
+
+```typescript
+await env.MY_KV.get(key, { type: 'json' }) // text|json|arrayBuffer|stream
+await env.MY_KV.put(key, value, { expirationTtl: 3600 })
+await env.MY_KV.delete(key)
+await env.MY_KV.list({ prefix: 'user:' })
+```
+
+**R2:**
+
+```typescript
+await env.BUCKET.get(key)
+await env.BUCKET.put(key, value)
+await env.BUCKET.delete(key)
+await env.BUCKET.list({ prefix: 'images/' })
+```
+
+**D1:**
+
+```typescript
+await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
+await env.DB.batch([stmt1, stmt2])
+```
+
+**Service:**
+
+```typescript
+await env.MY_SERVICE.fetch(new Request('https://fake/path'))
+```
+
+**Workers AI:**
+
+```typescript
+await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' })
+```
+
+**Queues:**
+
+```typescript
+await env.MY_QUEUE.send({ userId: 123, action: 'process' })
+```
+
+**Durable Objects:**
+
+```typescript
+const id = env.MY_DO.idFromName('user-123')
+const stub = env.MY_DO.get(id)
+await stub.fetch(new Request('https://fake/increment'))
+```
+
+## Runtime vs Build-Time Types
+
+| Type Source                 | When Generated      | Use Case                                    |
+| --------------------------- | ------------------- | ------------------------------------------- |
+| `@cloudflare/workers-types` | npm install         | Base Workers APIs (Request, Response, etc.) |
+| `wrangler types`            | After config change | Your specific bindings (Env interface)      |
+
+**Install both:**
+
+```bash
+npm install -D @cloudflare/workers-types
+npx wrangler types
+```
+
+## Type Safety Best Practices
+
+1. **Never use `any` for env:**
+
+```typescript
+// ❌ BAD
+async fetch(request: Request, env: any) { }
+
+// ✅ GOOD
+async fetch(request: Request, env: Env) { }
+```
+
+2. **Run wrangler types after config changes:**
+
+```bash
+# After editing wrangler.jsonc
+npx wrangler types
+```
+
+3. **Check generated types match config:**
+
+```bash
+# View generated Env interface
+cat .wrangler/types/runtime.d.ts
+```
+
+## See Also
+
+- [Workers Types Package](https://www.npmjs.com/package/@cloudflare/workers-types)
+- [Wrangler Types Command](https://developers.cloudflare.com/workers/wrangler/commands/#types)

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

@@ -0,0 +1,200 @@
+# Binding Configuration Reference
+
+## Storage Bindings
+
+```jsonc
+{
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "..." }],
+  "r2_buckets": [{ "binding": "MY_BUCKET", "bucket_name": "my-bucket" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "..." }],
+  "durable_objects": { "bindings": [{ "name": "MY_DO", "class_name": "MyDO" }] },
+  "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }],
+  "queues": { "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }] },
+}
+```
+
+**Create commands:**
+
+```bash
+npx wrangler kv namespace create MY_KV
+npx wrangler r2 bucket create my-bucket
+npx wrangler d1 create my-db
+npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
+npx wrangler queues create my-queue
+
+# List existing resources
+npx wrangler kv namespace list
+npx wrangler r2 bucket list
+npx wrangler d1 list
+npx wrangler vectorize list
+npx wrangler queues list
+```
+
+## Compute Bindings
+
+```jsonc
+{
+  "services": [
+    {
+      "binding": "MY_SERVICE",
+      "service": "other-worker",
+      "environment": "production", // Optional: target specific env
+    },
+  ],
+  "ai": { "binding": "AI" },
+  "browser": { "binding": "BROWSER" },
+  "workflows": [{ "binding": "MY_WORKFLOW", "name": "my-workflow" }],
+}
+```
+
+**Create workflows:**
+
+```bash
+npx wrangler workflows create my-workflow
+```
+
+## Platform Bindings
+
+```jsonc
+{
+  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }],
+  "mtls_certificates": [{ "binding": "MY_CERT", "certificate_id": "..." }],
+  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "..." }],
+  "unsafe": {
+    "bindings": [{ "name": "RATE_LIMITER", "type": "ratelimit", "namespace_id": "..." }],
+  },
+}
+```
+
+## Configuration Bindings
+
+```jsonc
+{
+  "vars": {
+    "API_URL": "https://api.example.com",
+    "MAX_RETRIES": "3",
+  },
+  "text_blobs": { "MY_TEXT": "./data/template.html" },
+  "data_blobs": { "MY_DATA": "./data/config.bin" },
+  "wasm_modules": { "MY_WASM": "./build/module.wasm" },
+}
+```
+
+**Secrets (never in config):**
+
+```bash
+npx wrangler secret put API_KEY
+```
+
+## Environment-Specific Configuration
+
+```jsonc
+{
+  "name": "my-worker",
+  "vars": { "ENV": "production" },
+  "kv_namespaces": [{ "binding": "CACHE", "id": "prod-kv-id" }],
+
+  "env": {
+    "staging": {
+      "vars": { "ENV": "staging" },
+      "kv_namespaces": [{ "binding": "CACHE", "id": "staging-kv-id" }],
+    },
+  },
+}
+```
+
+**Deploy:**
+
+```bash
+npx wrangler deploy              # Production
+npx wrangler deploy --env staging
+```
+
+## Local Development
+
+```jsonc
+{
+  "kv_namespaces": [
+    {
+      "binding": "MY_KV",
+      "id": "prod-id",
+      "preview_id": "dev-id", // Used in wrangler dev
+    },
+  ],
+}
+```
+
+**Or use remote:**
+
+```bash
+npx wrangler dev --remote  # Uses production bindings
+```
+
+## Complete Example
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+
+  "vars": { "API_URL": "https://api.example.com" },
+  "kv_namespaces": [{ "binding": "CACHE", "id": "abc123" }],
+  "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-assets" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "xyz789" }],
+  "services": [{ "binding": "AUTH", "service": "auth-worker" }],
+  "ai": { "binding": "AI" },
+}
+```
+
+## Binding-Specific Configuration
+
+### Durable Objects with Class Export
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "COUNTER", "class_name": "Counter", "script_name": "my-worker" }],
+  },
+}
+```
+
+```typescript
+// In same Worker or script_name Worker
+export class Counter {
+  constructor(
+    private state: DurableObjectState,
+    private env: Env
+  ) {}
+  async fetch(request: Request) {
+    /* ... */
+  }
+}
+```
+
+### Queue Consumers
+
+```jsonc
+{
+  "queues": {
+    "producers": [{ "binding": "MY_QUEUE", "queue": "my-queue" }],
+    "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }],
+  },
+}
+```
+
+Queue consumer handler: `export default { async queue(batch, env) { /* process batch.messages */ } }`
+
+## Key Points
+
+- **64 binding limit** (all types combined)
+- **Secrets**: Always use `wrangler secret put`, never commit
+- **Types**: Run `npx wrangler types` after config changes
+- **Environments**: Use `env` field for staging/production variants
+- **Development**: Use `preview_id` or `--remote` flag
+- **IDs vs Names**: Some bindings use `id` (KV, D1), others use `name` (R2, Queues)
+
+## See Also
+
+- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)

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

@@ -0,0 +1,210 @@
+# Binding Gotchas and Troubleshooting
+
+## Critical: Global Scope Mutation
+
+### ❌ THE #1 GOTCHA: Caching env in Global Scope
+
+```typescript
+// ❌ DANGEROUS - env cached at deploy time
+const apiKey = env.API_KEY // ERROR: env not available in global scope
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // Uses undefined or stale value!
+  },
+}
+```
+
+**Why it breaks:**
+
+- `env` not available in global scope
+- If using workarounds, secrets may not update without redeployment
+- Leads to "Cannot read property 'X' of undefined" errors
+
+**✅ Always access env per-request:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const apiKey = env.API_KEY // Fresh every request
+  },
+}
+```
+
+## Common Errors
+
+### "env.MY_KV is undefined"
+
+**Cause:** Name mismatch or not configured  
+**Solution:** Check wrangler.jsonc (case-sensitive), run `npx wrangler types`, verify `npx wrangler kv namespace list`
+
+### "Property 'MY_KV' does not exist on type 'Env'"
+
+**Cause:** Types not generated  
+**Solution:** `npx wrangler types`
+
+### "preview_id is required for --remote"
+
+**Cause:** Missing preview binding  
+**Solution:** Add `"preview_id": "dev-id"` or use `npx wrangler dev` (local mode)
+
+### "Secret updated but Worker still uses old value"
+
+**Cause:** Cached in global scope or not redeployed  
+**Solution:** Avoid global caching, redeploy after secret change
+
+### "KV get() returns null for existing key"
+
+**Cause:** Eventual consistency (60s), wrong namespace, wrong environment  
+**Solution:**
+
+```bash
+# Check key exists
+npx wrangler kv key get --binding=MY_KV "your-key"
+
+# Verify namespace ID
+npx wrangler kv namespace list
+
+# Check environment
+npx wrangler deployments list
+```
+
+### "D1 database not found"
+
+**Solution:** `npx wrangler d1 list`, verify ID in wrangler.jsonc
+
+### "Service binding returns 'No such service'"
+
+**Cause:** Target Worker not deployed, name mismatch, environment mismatch  
+**Solution:**
+
+```bash
+# List deployed Workers
+npx wrangler deployments list --name=target-worker
+
+# Check service binding config
+cat wrangler.jsonc | grep -A2 services
+
+# Deploy target first
+cd ../target-worker && npx wrangler deploy
+```
+
+### "Rate limit exceeded" on KV writes
+
+**Cause:** >1 write/second per key  
+**Solution:** Use different keys, Durable Objects, or Queues
+
+## Type Safety Gotchas
+
+### Missing @cloudflare/workers-types
+
+**Error:** `Cannot find name 'Request'`  
+**Solution:** `npm install -D @cloudflare/workers-types`, add to tsconfig.json `"types"`
+
+### Binding Type Mismatches
+
+```typescript
+// ❌ Wrong - KV returns string | null
+const value: string = await env.MY_KV.get('key')
+
+// ✅ Handle null
+const value = await env.MY_KV.get('key')
+if (!value) return new Response('Not found', { status: 404 })
+```
+
+## Environment Gotchas
+
+### Wrong Environment Deployed
+
+**Solution:** Check `npx wrangler deployments list`, use `--env` flag
+
+### Secrets Not Per-Environment
+
+**Solution:** Set per environment: `npx wrangler secret put API_KEY --env staging`
+
+## Development Gotchas
+
+**wrangler dev vs deploy:**
+
+- dev: Uses `preview_id` or local bindings, secrets not available
+- deploy: Uses production `id`, secrets available
+
+**Access secrets in dev:** `npx wrangler dev --remote`  
+**Persist local data:** `npx wrangler dev --persist`
+
+## Performance Gotchas
+
+### Sequential Binding Calls
+
+```typescript
+// ❌ Slow
+const user = await env.DB.prepare('...').first()
+const config = await env.MY_KV.get('config')
+
+// ✅ Parallel
+const [user, config] = await Promise.all([env.DB.prepare('...').first(), env.MY_KV.get('config')])
+```
+
+## Security Gotchas
+
+**❌ Secrets in logs:** `console.log('Key:', env.API_KEY)` - visible in dashboard  
+**✅** `console.log('Key:', env.API_KEY ? '***' : 'missing')`
+
+**❌ Exposing env:** `return Response.json(env)` - exposes all bindings  
+**✅** Never return env object in responses
+
+## Limits Reference
+
+| Resource                  | Limit                  | Impact                         | Plan |
+| ------------------------- | ---------------------- | ------------------------------ | ---- |
+| **Bindings per Worker**   | 64 total               | All binding types combined     | All  |
+| **Environment variables** | 64 max, 5KB each       | Per Worker                     | All  |
+| **Secret size**           | 1KB                    | Per secret                     | All  |
+| **KV key size**           | 512 bytes              | UTF-8 encoded                  | All  |
+| **KV value size**         | 25 MB                  | Per value                      | All  |
+| **KV writes per key**     | 1/second               | Per key; exceeding = 429 error | All  |
+| **KV list() results**     | 1000 keys              | Per call; use cursor for more  | All  |
+| **KV operations**         | 1000 reads/day         | Free tier only                 | Free |
+| **R2 object size**        | 5 TB                   | Per object                     | All  |
+| **R2 operations**         | 1M Class A/month free  | Writes                         | All  |
+| **D1 database size**      | 10 GB                  | Per database                   | All  |
+| **D1 rows per query**     | 100,000                | Result set limit               | All  |
+| **D1 databases**          | 10                     | Free tier                      | Free |
+| **Queue batch size**      | 100 messages           | Per consumer batch             | All  |
+| **Queue message size**    | 128 KB                 | Per message                    | All  |
+| **Service binding calls** | Unlimited              | Counts toward CPU time         | All  |
+| **Durable Objects**       | 1M requests/month free | First 1M                       | Free |
+
+## Debugging Tips
+
+```bash
+# Check configuration
+npx wrangler deploy --dry-run       # Validate config without deploying
+npx wrangler kv namespace list      # List KV namespaces
+npx wrangler secret list            # List secrets (not values)
+npx wrangler deployments list       # Recent deployments
+
+# Inspect bindings
+npx wrangler kv key list --binding=MY_KV
+npx wrangler kv key get --binding=MY_KV "key-name"
+npx wrangler r2 object get my-bucket/file.txt
+npx wrangler d1 execute my-db --command="SELECT * FROM sqlite_master"
+
+# Test locally
+npx wrangler dev                  # Local mode
+npx wrangler dev --remote         # Production bindings
+npx wrangler dev --persist        # Persist data across restarts
+
+# Verify types
+npx wrangler types
+cat .wrangler/types/runtime.d.ts | grep "interface Env"
+
+# Debug specific binding issues
+npx wrangler tail                 # Stream logs in real-time
+npx wrangler tail --format=pretty # Formatted logs
+```
+
+## See Also
+
+- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
+- [Wrangler Commands](https://developers.cloudflare.com/workers/wrangler/commands/)