memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,204 @@
+# Programmatic API
+
+## Miniflare Class
+
+```typescript
+class Miniflare {
+  constructor(options: MiniflareOptions)
+
+  // Lifecycle
+  ready: Promise<URL> // Resolves when server ready, returns URL
+  dispose(): Promise<void> // Cleanup resources
+  setOptions(options: MiniflareOptions): Promise<void> // Reload config
+
+  // Event dispatching
+  dispatchFetch(url: string | URL | Request, init?: RequestInit): Promise<Response>
+  getWorker(name?: string): Promise<Worker>
+
+  // Bindings access
+  getBindings<Bindings = Record<string, unknown>>(name?: string): Promise<Bindings>
+  getCf(name?: string): Promise<IncomingRequestCfProperties | undefined>
+  getKVNamespace(name: string): Promise<KVNamespace>
+  getR2Bucket(name: string): Promise<R2Bucket>
+  getDurableObjectNamespace(name: string): Promise<DurableObjectNamespace>
+  getDurableObjectStorage(id: DurableObjectId): Promise<DurableObjectStorage>
+  getD1Database(name: string): Promise<D1Database>
+  getCaches(): Promise<CacheStorage>
+  getQueueProducer(name: string): Promise<QueueProducer>
+
+  // Debugging
+  getInspectorURL(): Promise<URL> // Chrome DevTools inspector URL
+}
+```
+
+## Event Dispatching
+
+**Fetch (no HTTP server):**
+
+```js
+const res = await mf.dispatchFetch('http://localhost:8787/path', {
+  method: 'POST',
+  headers: { Authorization: 'Bearer token' },
+  body: JSON.stringify({ data: 'value' }),
+})
+```
+
+**Custom Host routing:**
+
+```js
+const res = await mf.dispatchFetch('http://localhost:8787/', {
+  headers: { Host: 'api.example.com' },
+})
+```
+
+**Scheduled:**
+
+```js
+const worker = await mf.getWorker()
+const result = await worker.scheduled({ cron: '30 * * * *' })
+// result: { outcome: "ok", noRetry: false }
+```
+
+**Queue:**
+
+```js
+const worker = await mf.getWorker()
+const result = await worker.queue('queue-name', [
+  { id: 'msg1', timestamp: new Date(), body: 'data', attempts: 1 },
+])
+// result: { outcome: "ok", retryAll: false, ackAll: false, ... }
+```
+
+## Bindings Access
+
+**Environment variables:**
+
+```js
+// Basic usage
+const bindings = await mf.getBindings();
+console.log(bindings.SECRET_KEY);
+
+// With type safety (recommended):
+interface Env {
+  SECRET_KEY: string;
+  API_URL: string;
+  KV: KVNamespace;
+}
+const env = await mf.getBindings<Env>();
+env.SECRET_KEY; // string (typed!)
+env.KV.get("key"); // KVNamespace methods available
+```
+
+**Request.cf object:**
+
+```js
+const cf = await mf.getCf()
+console.log(cf?.colo) // "DFW"
+console.log(cf?.country) // "US"
+```
+
+**KV:**
+
+```js
+const ns = await mf.getKVNamespace('TEST_NAMESPACE')
+await ns.put('key', 'value')
+const value = await ns.get('key')
+```
+
+**R2:**
+
+```js
+const bucket = await mf.getR2Bucket('BUCKET')
+await bucket.put('file.txt', 'content')
+const object = await bucket.get('file.txt')
+```
+
+**Durable Objects:**
+
+```js
+const ns = await mf.getDurableObjectNamespace('COUNTER')
+const id = ns.idFromName('test')
+const stub = ns.get(id)
+const res = await stub.fetch('http://localhost/')
+
+// Access storage directly:
+const storage = await mf.getDurableObjectStorage(id)
+await storage.put('key', 'value')
+```
+
+**D1:**
+
+```js
+const db = await mf.getD1Database('DB')
+await db.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`)
+await db.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice').run()
+```
+
+**Cache:**
+
+```js
+const caches = await mf.getCaches()
+const defaultCache = caches.default
+await defaultCache.put('http://example.com', new Response('cached'))
+```
+
+**Queue producer:**
+
+```js
+const producer = await mf.getQueueProducer('QUEUE')
+await producer.send({ body: 'message data' })
+```
+
+## Lifecycle
+
+**Reload:**
+
+```js
+await mf.setOptions({
+  scriptPath: 'worker.js',
+  bindings: { VERSION: '2.0' },
+})
+```
+
+**Watch (manual):**
+
+```js
+import { watch } from 'fs'
+
+const config = { scriptPath: 'worker.js' }
+const mf = new Miniflare(config)
+
+watch('worker.js', async () => {
+  console.log('Reloading...')
+  await mf.setOptions(config)
+})
+```
+
+**Cleanup:**
+
+```js
+await mf.dispose()
+```
+
+## Debugging
+
+**Inspector URL for DevTools:**
+
+```js
+const url = await mf.getInspectorURL()
+console.log(`DevTools: ${url}`)
+// Open in Chrome DevTools for breakpoints, profiling
+```
+
+**Wait for server ready:**
+
+```js
+const mf = new Miniflare({ scriptPath: 'worker.js' })
+const url = await mf.ready // Promise<URL>
+console.log(`Server running at ${url}`) // http://127.0.0.1:8787
+
+// Note: dispatchFetch() waits automatically, no need to await ready
+const res = await mf.dispatchFetch('http://localhost/') // Works immediately
+```
+
+See [configuration.md](./configuration.md) for all constructor options.

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

@@ -0,0 +1,174 @@
+# Configuration
+
+## Script Loading
+
+```js
+// Inline
+new Miniflare({ modules: true, script: `export default { ... }` })
+
+// File-based
+new Miniflare({ scriptPath: 'worker.js' })
+
+// Multi-module
+new Miniflare({
+  scriptPath: 'src/index.js',
+  modules: true,
+  modulesRules: [
+    { type: 'ESModule', include: ['**/*.js'] },
+    { type: 'Text', include: ['**/*.txt'] },
+  ],
+})
+```
+
+## Compatibility
+
+```js
+new Miniflare({
+  compatibilityDate: '2026-01-01', // Use recent date for latest features
+  compatibilityFlags: [
+    'nodejs_compat', // Node.js APIs (process, Buffer, etc)
+    'streams_enable_constructors', // Stream constructors
+  ],
+  upstream: 'https://example.com', // Fallback for unhandled requests
+})
+```
+
+**Critical:** Use `compatibilityDate: "2026-01-01"` or latest to match production runtime. Old dates limit available APIs.
+
+## HTTP Server & Request.cf
+
+```js
+new Miniflare({
+  port: 8787, // Default: 8787
+  host: '127.0.0.1',
+  https: true, // Self-signed cert
+  liveReload: true, // Auto-reload HTML
+
+  cf: true, // Fetch live Request.cf data (cached)
+  // cf: "./cf.json",      // Or load from file
+  // cf: { colo: "DFW" },  // Or inline mock
+})
+```
+
+**Note:** For tests, use `dispatchFetch()` (no port conflicts).
+
+## Storage Bindings
+
+```js
+new Miniflare({
+  // KV
+  kvNamespaces: ['TEST_NAMESPACE', 'CACHE'],
+  kvPersist: './kv-data', // Optional: persist to disk
+
+  // R2
+  r2Buckets: ['BUCKET', 'IMAGES'],
+  r2Persist: './r2-data',
+
+  // Durable Objects
+  modules: true,
+  durableObjects: {
+    COUNTER: 'Counter', // className
+    API_OBJECT: { className: 'ApiObject', scriptName: 'api-worker' },
+  },
+  durableObjectsPersist: './do-data',
+
+  // D1
+  d1Databases: ['DB'],
+  d1Persist: './d1-data',
+
+  // Cache
+  cache: true, // Default
+  cachePersist: './cache-data',
+})
+```
+
+## Bindings
+
+```js
+new Miniflare({
+  // Environment variables
+  bindings: {
+    SECRET_KEY: 'my-secret-value',
+    API_URL: 'https://api.example.com',
+    DEBUG: true,
+  },
+
+  // Other bindings
+  wasmBindings: { ADD_MODULE: './add.wasm' },
+  textBlobBindings: { TEXT: './data.txt' },
+  queueProducers: ['QUEUE'],
+})
+```
+
+## Multiple Workers
+
+```js
+new Miniflare({
+  workers: [
+    {
+      name: 'main',
+      kvNamespaces: { DATA: 'shared' },
+      serviceBindings: { API: 'api-worker' },
+      script: `export default { ... }`,
+    },
+    {
+      name: 'api-worker',
+      kvNamespaces: { DATA: 'shared' }, // Shared storage
+      script: `export default { ... }`,
+    },
+  ],
+})
+```
+
+**With routing:**
+
+```js
+workers: [
+  { name: "api", scriptPath: "./api.js", routes: ["api.example.com/*"] },
+  { name: "web", scriptPath: "./web.js", routes: ["example.com/*"] },
+],
+```
+
+## Logging & Performance
+
+```js
+import { Log, LogLevel } from 'miniflare'
+
+new Miniflare({
+  log: new Log(LogLevel.DEBUG), // DEBUG | INFO | WARN | ERROR | NONE
+  scriptTimeout: 30000, // CPU limit (ms)
+  workersConcurrencyLimit: 10, // Max concurrent workers
+})
+```
+
+## Workers Sites
+
+```js
+new Miniflare({
+  sitePath: './public',
+  siteInclude: ['**/*.html', '**/*.css'],
+  siteExclude: ['**/*.map'],
+})
+```
+
+## From wrangler.toml
+
+Miniflare doesn't auto-read `wrangler.toml`:
+
+```toml
+# wrangler.toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2026-01-01"
+[[kv_namespaces]]
+binding = "KV"
+```
+
+```js
+// Miniflare equivalent
+new Miniflare({
+  scriptPath: 'src/index.ts',
+  compatibilityDate: '2026-01-01',
+  kvNamespaces: ['KV'],
+})
+```

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

@@ -0,0 +1,179 @@
+# Gotchas & Troubleshooting
+
+## Miniflare Limitations
+
+**Not supported:**
+
+- Analytics Engine (use mocks)
+- Cloudflare Images/Stream
+- Browser Rendering API
+- Tail Workers
+- Workers for Platforms (partial support)
+
+**Behavior differences from production:**
+
+- Runs workerd locally, not Cloudflare edge
+- Storage is local (filesystem/memory), not distributed
+- `Request.cf` is cached/mocked, not real edge data
+- Performance differs from edge
+- Caching implementation may vary slightly
+
+## Common Errors
+
+### "Cannot find module"
+
+**Cause:** Module path wrong or `modulesRules` not configured  
+**Solution:**
+
+```js
+new Miniflare({
+  modules: true,
+  modulesRules: [{ type: 'ESModule', include: ['**/*.js'] }],
+})
+```
+
+### "Data not persisting"
+
+**Cause:** Persist paths are files, not directories  
+**Solution:**
+
+```js
+kvPersist: "./data/kv",  // Directory, not file
+```
+
+### "Cannot run TypeScript"
+
+**Cause:** Miniflare doesn't transpile TypeScript  
+**Solution:** Build first with esbuild/tsc, then run compiled JS
+
+### "`request.cf` is undefined"
+
+**Cause:** CF data not configured  
+**Solution:**
+
+```js
+new Miniflare({ cf: true }) // Or cf: "./cf.json"
+```
+
+### "EADDRINUSE" port conflict
+
+**Cause:** Multiple instances using same port  
+**Solution:** Use `dispatchFetch()` (no HTTP server) or `port: 0` for auto-assign
+
+### "Durable Object not found"
+
+**Cause:** Class export doesn't match config name  
+**Solution:**
+
+```js
+export class Counter {} // Must match
+new Miniflare({ durableObjects: { COUNTER: 'Counter' } })
+```
+
+## Debugging
+
+**Enable verbose logging:**
+
+```js
+import { Log, LogLevel } from 'miniflare'
+new Miniflare({ log: new Log(LogLevel.DEBUG) })
+```
+
+**Chrome DevTools:**
+
+```js
+const url = await mf.getInspectorURL()
+console.log(`DevTools: ${url}`) // Open in Chrome
+```
+
+**Inspect bindings:**
+
+```js
+const env = await mf.getBindings()
+console.log(Object.keys(env))
+```
+
+**Verify storage:**
+
+```js
+const ns = await mf.getKVNamespace('TEST')
+const { keys } = await ns.list()
+```
+
+## Best Practices
+
+**✓ Do:**
+
+- Use `dispatchFetch()` for tests (no HTTP server)
+- In-memory storage for CI (omit persist options)
+- New instances per test for isolation
+- Type-safe bindings with interfaces
+- `await mf.dispose()` in cleanup
+
+**✗ Avoid:**
+
+- HTTP server in tests
+- Shared instances without cleanup
+- Old compatibility dates (use 2026+)
+
+## Migration Guides
+
+### From Miniflare 2.x to 3+
+
+Breaking changes in v3+:
+
+| v2                   | v3+                             |
+| -------------------- | ------------------------------- |
+| `getBindings()` sync | `getBindings()` returns Promise |
+| `ready` is void      | `ready` returns `Promise<URL>`  |
+| service-worker-mock  | Built on workerd                |
+| Different options    | Restructured constructor        |
+
+**Example migration:**
+
+```js
+// v2
+const bindings = mf.getBindings()
+mf.ready // void
+
+// v3+
+const bindings = await mf.getBindings()
+const url = await mf.ready // Promise<URL>
+```
+
+### From unstable_dev to Miniflare
+
+```js
+// Old (deprecated)
+import { unstable_dev } from 'wrangler'
+const worker = await unstable_dev('src/index.ts')
+
+// New
+import { Miniflare } from 'miniflare'
+const mf = new Miniflare({ scriptPath: 'src/index.ts' })
+```
+
+### From Wrangler Dev
+
+Miniflare doesn't auto-read `wrangler.toml`:
+
+```js
+// Translate manually:
+new Miniflare({
+  scriptPath: 'dist/worker.js',
+  compatibilityDate: '2026-01-01',
+  kvNamespaces: ['KV'],
+  bindings: { API_KEY: process.env.API_KEY },
+})
+```
+
+## Resource Limits
+
+| Limit      | Value            | Notes                            |
+| ---------- | ---------------- | -------------------------------- |
+| CPU time   | 30s default      | Configurable via `scriptTimeout` |
+| Storage    | Filesystem       | Performance varies by disk       |
+| Memory     | System dependent | No artificial limits             |
+| Request.cf | Cached/mocked    | Not live edge data               |
+
+See [patterns.md](./patterns.md) for testing examples.