memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,188 @@
+# Wrangler Programmatic API
+
+Node.js APIs for testing and development.
+
+## startWorker (Testing)
+
+Starts Worker with real local bindings for integration tests. Stable API (replaces `unstable_startWorker`).
+
+```typescript
+import { startWorker } from 'wrangler'
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert'
+
+describe('worker', () => {
+  let worker
+
+  before(async () => {
+    worker = await startWorker({
+      config: 'wrangler.jsonc',
+      environment: 'development',
+    })
+  })
+
+  after(async () => {
+    await worker.dispose()
+  })
+
+  it('responds with 200', async () => {
+    const response = await worker.fetch('http://example.com')
+    assert.strictEqual(response.status, 200)
+  })
+})
+```
+
+### Options
+
+| Option        | Type                          | Description                                                                            |
+| ------------- | ----------------------------- | -------------------------------------------------------------------------------------- |
+| `config`      | `string`                      | Path to wrangler.jsonc                                                                 |
+| `environment` | `string`                      | Environment name from config                                                           |
+| `persist`     | `boolean \| { path: string }` | Enable persistent state                                                                |
+| `bundle`      | `boolean`                     | Enable bundling (default: true)                                                        |
+| `remote`      | `false \| true \| "minimal"`  | Remote mode: `false` (local), `true` (full remote), `"minimal"` (remote bindings only) |
+
+### Remote Mode
+
+```typescript
+// Local mode (default) - fast, simulated
+const worker = await startWorker({ config: 'wrangler.jsonc' })
+
+// Full remote mode - production-like, slower
+const worker = await startWorker({
+  config: 'wrangler.jsonc',
+  remote: true,
+})
+
+// Minimal remote mode - remote bindings, local Worker
+const worker = await startWorker({
+  config: 'wrangler.jsonc',
+  remote: 'minimal',
+})
+```
+
+## getPlatformProxy
+
+Emulate bindings in Node.js without starting Worker.
+
+```typescript
+import { getPlatformProxy } from 'wrangler'
+
+const { env, dispose, caches } = await getPlatformProxy<Env>({
+  configPath: 'wrangler.jsonc',
+  environment: 'production',
+  persist: { path: '.wrangler/state' },
+})
+
+// Use bindings
+const value = await env.MY_KV.get('key')
+await env.DB.prepare('SELECT * FROM users').all()
+await env.ASSETS.put('file.txt', 'content')
+
+// Platform APIs
+await caches.default.put('https://example.com', new Response('cached'))
+
+await dispose()
+```
+
+Use for unit tests (test functions, not full Worker) or scripts that need bindings.
+
+## Type Generation
+
+Generate types from config: `wrangler types` → creates `worker-configuration.d.ts`
+
+## Event System
+
+Listen to Worker lifecycle events for advanced workflows.
+
+```typescript
+import { startWorker } from 'wrangler'
+
+const worker = await startWorker({
+  config: 'wrangler.jsonc',
+  bundle: true,
+})
+
+// Bundle events
+worker.on('bundleStart', (details) => {
+  console.log('Bundling started:', details.config)
+})
+
+worker.on('bundleComplete', (details) => {
+  console.log('Bundle ready:', details.duration)
+})
+
+// Reconfiguration events
+worker.on('reloadStart', () => {
+  console.log('Worker reloading...')
+})
+
+worker.on('reloadComplete', () => {
+  console.log('Worker reloaded')
+})
+
+await worker.dispose()
+```
+
+### Dynamic Reconfiguration
+
+```typescript
+import { startWorker } from 'wrangler'
+
+const worker = await startWorker({ config: 'wrangler.jsonc' })
+
+// Replace entire config
+await worker.setConfig({
+  config: 'wrangler.staging.jsonc',
+  environment: 'staging',
+})
+
+// Patch specific fields
+await worker.patchConfig({
+  vars: { DEBUG: 'true' },
+})
+
+await worker.dispose()
+```
+
+## unstable_dev (Deprecated)
+
+Use `startWorker` instead.
+
+## Multi-Worker Registry
+
+Test multiple Workers with service bindings.
+
+```typescript
+import { startWorker } from 'wrangler'
+
+const auth = await startWorker({ config: './auth/wrangler.jsonc' })
+const api = await startWorker({
+  config: './api/wrangler.jsonc',
+  bindings: { AUTH: auth }, // Service binding
+})
+
+const response = await api.fetch('http://example.com/api/login')
+// API Worker calls AUTH Worker via env.AUTH.fetch()
+
+await api.dispose()
+await auth.dispose()
+```
+
+## Best Practices
+
+- Use `startWorker` for integration tests (tests full Worker)
+- Use `getPlatformProxy` for unit tests (tests individual functions)
+- Use `remote: true` when debugging production-specific issues
+- Use `remote: "minimal"` for faster tests with real bindings
+- Enable `persist: true` for debugging (state survives runs)
+- Run `wrangler types` after config changes
+- Always `dispose()` to prevent resource leaks
+- Listen to bundle events for build monitoring
+- Use multi-worker registry for testing service bindings
+
+## See Also
+
+- [README.md](./README.md) - CLI commands
+- [configuration.md](./configuration.md) - Config
+- [patterns.md](./patterns.md) - Testing patterns

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

@@ -0,0 +1,198 @@
+# Wrangler Configuration
+
+Configuration reference for wrangler.jsonc (recommended).
+
+## Config Format
+
+**wrangler.jsonc recommended** (v3.91.0+) - provides schema validation.
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date
+  "vars": { "API_KEY": "dev-key" },
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "abc123" }],
+}
+```
+
+## Field Inheritance
+
+Inheritable: `name`, `main`, `compatibility_date`, `routes`, `triggers`
+Non-inheritable (define per env): `vars`, bindings (KV, D1, R2, etc.)
+
+## Environments
+
+```jsonc
+{
+  "name": "my-worker",
+  "vars": { "ENV": "dev" },
+  "env": {
+    "production": {
+      "name": "my-worker-prod",
+      "vars": { "ENV": "prod" },
+      "route": { "pattern": "example.com/*", "zone_name": "example.com" },
+    },
+  },
+}
+```
+
+Deploy: `wrangler deploy --env production`
+
+## Routing
+
+```jsonc
+// Custom domain (recommended)
+{ "routes": [{ "pattern": "api.example.com", "custom_domain": true }] }
+
+// Zone-based
+{ "routes": [{ "pattern": "api.example.com/*", "zone_name": "example.com" }] }
+
+// workers.dev
+{ "workers_dev": true }
+```
+
+## Bindings
+
+```jsonc
+// Variables
+{ "vars": { "API_URL": "https://api.example.com" } }
+
+// KV
+{ "kv_namespaces": [{ "binding": "CACHE", "id": "abc123" }] }
+
+// D1
+{ "d1_databases": [{ "binding": "DB", "database_id": "abc-123" }] }
+
+// R2
+{ "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-assets" }] }
+
+// Durable Objects
+{ "durable_objects": {
+  "bindings": [{
+    "name": "COUNTER",
+    "class_name": "Counter",
+    "script_name": "my-worker"  // Required for external DOs
+  }]
+} }
+{ "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Counter"] }] }
+
+// Service Bindings
+{ "services": [{ "binding": "AUTH", "service": "auth-worker" }] }
+
+// Queues
+{ "queues": {
+  "producers": [{ "binding": "TASKS", "queue": "task-queue" }],
+  "consumers": [{ "queue": "task-queue", "max_batch_size": 10 }]
+} }
+
+// Vectorize
+{ "vectorize": [{ "binding": "VECTORS", "index_name": "embeddings" }] }
+
+// Hyperdrive (requires nodejs_compat_v2 for pg/postgres)
+{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "hyper-id" }] }
+{ "compatibility_flags": ["nodejs_compat_v2"] }  // For pg/postgres
+
+// Workers AI
+{ "ai": { "binding": "AI" } }
+
+// Workflows
+{ "workflows": [{ "binding": "WORKFLOW", "name": "my-workflow", "class_name": "MyWorkflow" }] }
+
+// Secrets Store (centralized secrets)
+{ "secrets_store": [{ "binding": "SECRETS", "id": "store-id" }] }
+
+// Constellation (AI inference)
+{ "constellation": [{ "binding": "MODEL", "project_id": "proj-id" }] }
+```
+
+## Workers Assets (Static Files)
+
+Recommended for serving static files (replaces old `site` config).
+
+```jsonc
+{
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS",
+    "html_handling": "auto-trailing-slash", // or "none", "force-trailing-slash"
+    "not_found_handling": "single-page-application", // or "404-page", "none"
+  },
+}
+```
+
+Access in Worker:
+
+```typescript
+export default {
+  async fetch(request, env) {
+    // Try serving static asset first
+    const asset = await env.ASSETS.fetch(request)
+    if (asset.status !== 404) return asset
+
+    // Custom logic for non-assets
+    return new Response('API response')
+  },
+}
+```
+
+## Placement
+
+Control where Workers run geographically.
+
+```jsonc
+{
+  "placement": {
+    "mode": "smart", // or "off"
+  },
+}
+```
+
+- `"smart"`: Run Worker near data sources (D1, Durable Objects) to reduce latency
+- `"off"`: Default distribution (run everywhere)
+
+## Auto-Provisioning (Beta)
+
+Omit resource IDs - Wrangler creates them and writes back to config on deploy.
+
+```jsonc
+{ "kv_namespaces": [{ "binding": "MY_KV" }] } // No id - auto-provisioned
+```
+
+After deploy, ID is added to config automatically.
+
+## Advanced
+
+```jsonc
+// Cron Triggers
+{ "triggers": { "crons": ["0 0 * * *"] } }
+
+// Observability (tracing)
+{ "observability": { "enabled": true, "head_sampling_rate": 0.1 } }
+
+// Runtime Limits
+{ "limits": { "cpu_ms": 100 } }
+
+// Browser Rendering
+{ "browser": { "binding": "BROWSER" } }
+
+// mTLS Certificates
+{ "mtls_certificates": [{ "binding": "CERT", "certificate_id": "cert-uuid" }] }
+
+// Logpush (stream logs to R2/S3)
+{ "logpush": true }
+
+// Tail Consumers (process logs with another Worker)
+{ "tail_consumers": [{ "service": "log-worker" }] }
+
+// Unsafe bindings (access to arbitrary bindings)
+{ "unsafe": { "bindings": [{ "name": "MY_BINDING", "type": "plain_text", "text": "value" }] } }
+```
+
+## See Also
+
+- [README.md](./README.md) - Overview and commands
+- [api.md](./api.md) - Programmatic API
+- [patterns.md](./patterns.md) - Workflows
+- [gotchas.md](./gotchas.md) - Common issues

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

@@ -0,0 +1,212 @@
+# Wrangler Common Issues
+
+## Common Errors
+
+### "Binding ID vs name mismatch"
+
+**Cause:** Confusion between binding name (code) and resource ID
+**Solution:** Bindings use `binding` (code name) and `id`/`database_id`/`bucket_name` (resource ID). Preview bindings need separate IDs: `preview_id`, `preview_database_id`
+
+### "Environment not inheriting config"
+
+**Cause:** Non-inheritable keys not redefined per environment
+**Solution:** Non-inheritable keys (bindings, vars) must be redefined per environment. Inheritable keys (routes, compatibility_date) can be overridden
+
+### "Local dev behavior differs from production"
+
+**Cause:** Using local simulation instead of remote execution
+**Solution:** Choose appropriate remote mode:
+
+- `wrangler dev` (default): Local simulation, fast, limited accuracy
+- `wrangler dev --remote`: Full remote execution, production-accurate, slower
+- Use `remote: "minimal"` in tests for fast tests with real remote bindings
+
+### "startWorker doesn't match production"
+
+**Cause:** Using local mode when remote resources needed
+**Solution:** Use `remote` option:
+
+```typescript
+const worker = await startWorker({
+  config: 'wrangler.jsonc',
+  remote: true, // or "minimal" for faster tests
+})
+```
+
+### "Unexpected runtime changes"
+
+**Cause:** Missing compatibility_date
+**Solution:** Always set `compatibility_date`:
+
+```jsonc
+{ "compatibility_date": "2025-01-01" }
+```
+
+### "Durable Object binding not working"
+
+**Cause:** Missing script_name for external DOs
+**Solution:** Always specify `script_name` for external Durable Objects:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MY_DO", "class_name": "MyDO", "script_name": "my-worker" }],
+  },
+}
+```
+
+For local DOs in same Worker, `script_name` is optional.
+
+### "Auto-provisioned resources not appearing"
+
+**Cause:** IDs written back to config on first deploy, but config not reloaded
+**Solution:** After first deploy with auto-provisioning, config file is updated with IDs. Commit the updated config. On subsequent deploys, existing resources are reused.
+
+### "Secrets not available in local dev"
+
+**Cause:** Secrets set with `wrangler secret put` only work in deployed Workers
+**Solution:** For local dev, use `.dev.vars`
+
+### "Node.js compatibility error"
+
+**Cause:** Missing Node.js compatibility flag
+**Solution:** Some bindings (Hyperdrive with `pg`) require:
+
+```jsonc
+{ "compatibility_flags": ["nodejs_compat_v2"] }
+```
+
+### "Workers Assets 404 errors"
+
+**Cause:** Asset path mismatch or incorrect `html_handling`
+**Solution:**
+
+- Check `assets.directory` points to correct build output
+- Set `html_handling: "auto-trailing-slash"` for SPAs
+- Use `not_found_handling: "single-page-application"` to serve index.html for 404s
+
+```jsonc
+{
+  "assets": {
+    "directory": "./dist",
+    "html_handling": "auto-trailing-slash",
+    "not_found_handling": "single-page-application",
+  },
+}
+```
+
+### "Placement not reducing latency"
+
+**Cause:** Misunderstanding of Smart Placement
+**Solution:** Smart Placement only helps when Worker accesses D1 or Durable Objects. It doesn't affect KV, R2, or external API latency.
+
+```jsonc
+{ "placement": { "mode": "smart" } } // Only beneficial with D1/DOs
+```
+
+### "unstable_startWorker not found"
+
+**Cause:** Using outdated API
+**Solution:** Use stable `startWorker` instead:
+
+```typescript
+import { startWorker } from 'wrangler' // Not unstable_startWorker
+```
+
+### "outboundService not mocking fetch"
+
+**Cause:** Mock function not returning Response
+**Solution:** Always return Response, use `fetch(req)` for passthrough:
+
+```typescript
+const worker = await startWorker({
+  outboundService: (req) => {
+    if (shouldMock(req)) {
+      return new Response('mocked')
+    }
+    return fetch(req) // Required for non-mocked requests
+  },
+})
+```
+
+## Limits
+
+| Resource/Limit           | Value     | Notes                  |
+| ------------------------ | --------- | ---------------------- |
+| Bindings per Worker      | 64        | Total across all types |
+| Environments             | Unlimited | Named envs in config   |
+| Config file size         | ~1MB      | Keep reasonable        |
+| Workers Assets size      | 25 MB     | Per deployment         |
+| Workers Assets files     | 20,000    | Max number of files    |
+| Script size (compressed) | 1 MB      | Free, 10 MB paid       |
+| CPU time                 | 10-50ms   | Free, 50-500ms paid    |
+| Subrequest limit         | 50        | Free, 10,000 paid      |
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+wrangler logout
+wrangler login
+wrangler whoami
+```
+
+### Configuration Errors
+
+```bash
+wrangler check  # Validate config
+```
+
+Use wrangler.jsonc with `$schema` for validation.
+
+### Binding Not Available
+
+- Check binding exists in config
+- For environments, ensure binding defined for that env
+- Local dev: some bindings need `--remote`
+
+### Deployment Failures
+
+```bash
+wrangler tail              # Check logs
+wrangler deploy --dry-run  # Validate
+wrangler whoami            # Check account limits
+```
+
+### Local Development Issues
+
+```bash
+rm -rf .wrangler/state     # Clear local state
+wrangler dev --remote      # Use remote bindings
+wrangler dev --persist-to ./local-state  # Custom persist location
+wrangler dev --inspector-port 9229  # Enable debugging
+```
+
+### Testing Issues
+
+```bash
+# If tests hang, ensure dispose() is called
+worker.dispose()  // Always cleanup
+
+# If bindings don't work in tests
+const worker = await startWorker({
+  config: "wrangler.jsonc",
+  remote: "minimal"  // Use remote bindings
+});
+```
+
+## Resources
+
+- Docs: https://developers.cloudflare.com/workers/wrangler/
+- Config: https://developers.cloudflare.com/workers/wrangler/configuration/
+- Commands: https://developers.cloudflare.com/workers/wrangler/commands/
+- Examples: https://github.com/cloudflare/workers-sdk/tree/main/templates
+- Discord: https://discord.gg/cloudflaredev
+
+## See Also
+
+- [README.md](./README.md) - Commands
+- [configuration.md](./configuration.md) - Config
+- [api.md](./api.md) - Programmatic API
+- [patterns.md](./patterns.md) - Workflows