memory-journal-mcp 8.0.1 → 9.1.0

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

@@ -1,214 +0,0 @@
-# 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

@@ -1,200 +0,0 @@
-# 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

@@ -1,210 +0,0 @@
-# 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/)