memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/workers-for-platforms/patterns.md

@@ -0,0 +1,210 @@
+# Multi-Tenant Patterns
+
+## Billing by Plan
+
+```typescript
+interface Env {
+  DISPATCHER: DispatchNamespace
+  CUSTOMERS_KV: KVNamespace
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userWorkerName = new URL(request.url).hostname.split('.')[0]
+    const customerPlan = await env.CUSTOMERS_KV.get(userWorkerName)
+
+    const plans = {
+      enterprise: { cpuMs: 50, subRequests: 50 },
+      pro: { cpuMs: 20, subRequests: 20 },
+      free: { cpuMs: 10, subRequests: 5 },
+    }
+    const limits = plans[customerPlan as keyof typeof plans] || plans.free
+
+    const userWorker = env.DISPATCHER.get(userWorkerName, {}, { limits })
+    return await userWorker.fetch(request)
+  },
+}
+```
+
+## Resource Isolation
+
+**Complete isolation:** Create unique resources per customer
+
+- KV namespace per customer
+- D1 database per customer
+- R2 bucket per customer
+
+```typescript
+const bindings = [
+  {
+    type: 'kv_namespace',
+    name: 'USER_KV',
+    namespace_id: `customer-${customerId}-kv`,
+  },
+]
+```
+
+## Hostname Routing
+
+### Wildcard Route (Recommended)
+
+Configure `*/*` route on SaaS domain → dispatch Worker
+
+**Benefits:**
+
+- Supports subdomains + custom vanity domains
+- No per-route limits (regular Workers limited to 100 routes)
+- Programmatic control
+- Works with any DNS proxy settings
+
+**Setup:**
+
+1. Cloudflare for SaaS custom hostnames
+2. Fallback origin (dummy `A 192.0.2.0` if Worker is origin)
+3. DNS CNAME to SaaS domain
+4. `*/*` route → dispatch Worker
+5. Routing logic in dispatch Worker
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const hostname = new URL(request.url).hostname
+    const hostnameData = await env.ROUTING_KV.get(`hostname:${hostname}`, { type: 'json' })
+
+    if (!hostnameData?.workerName) {
+      return new Response('Hostname not configured', { status: 404 })
+    }
+
+    const userWorker = env.DISPATCHER.get(hostnameData.workerName)
+    return await userWorker.fetch(request)
+  },
+}
+```
+
+### Subdomain-Only
+
+1. Wildcard DNS: `*.saas.com` → origin
+2. Route: `*.saas.com/*` → dispatch Worker
+3. Extract subdomain for routing
+
+### Orange-to-Orange (O2O) Behavior
+
+When customers use Cloudflare and CNAME to your Workers domain:
+
+| Scenario                                | Behavior               | Route Pattern             |
+| --------------------------------------- | ---------------------- | ------------------------- |
+| Customer not on Cloudflare              | Standard routing       | `*/*` or `*.domain.com/*` |
+| Customer on Cloudflare (proxied CNAME)  | Invokes Worker at edge | `*/*` required            |
+| Customer on Cloudflare (DNS-only CNAME) | Standard routing       | Any route works           |
+
+**Recommendation:** Always use `*/*` wildcard for consistent O2O behavior.
+
+### Custom Metadata Routing
+
+For Cloudflare for SaaS: Store worker name in custom hostname `custom_metadata`, retrieve in dispatch worker to route requests. Requires custom hostnames as subdomains of your domain.
+
+## Observability
+
+### Logpush
+
+- Enable on dispatch Worker → captures all user Worker logs
+- Filter by `Outcome` or `Script Name`
+
+### Tail Workers
+
+- Real-time logs with custom formatting
+- Receives HTTP status, `console.log()`, exceptions, diagnostics
+
+### Analytics Engine
+
+```typescript
+// Track violations
+env.ANALYTICS.writeDataPoint({
+  indexes: [customerName],
+  blobs: ['cpu_limit_exceeded'],
+})
+```
+
+### GraphQL
+
+```graphql
+query {
+  viewer {
+    accounts(filter: { accountTag: $accountId }) {
+      workersInvocationsAdaptive(filter: { dispatchNamespaceName: "production" }) {
+        sum {
+          requests
+          errors
+          cpuTime
+        }
+      }
+    }
+  }
+}
+```
+
+## Use Case Implementations
+
+### AI Code Execution
+
+```typescript
+async function deployGeneratedCode(name: string, code: string) {
+  const file = new File([code], `${name}.mjs`, { type: 'application/javascript+module' })
+  await client.workersForPlatforms.dispatch.namespaces.scripts.update('production', name, {
+    account_id: accountId,
+    metadata: { main_module: `${name}.mjs`, tags: [name, 'ai-generated'] },
+    files: [file],
+  })
+}
+
+// Short limits for untrusted code
+const userWorker = env.DISPATCHER.get(sessionId, {}, { limits: { cpuMs: 5, subRequests: 3 } })
+```
+
+**VibeSDK:** For AI-powered code generation + deployment platforms, see [VibeSDK](https://github.com/cloudflare/vibesdk) - handles AI generation, sandbox execution, live preview, and deployment.
+
+Reference: [AI Vibe Coding Platform Architecture](https://developers.cloudflare.com/reference-architecture/diagrams/ai/ai-vibe-coding-platform/)
+
+### Edge Functions Platform
+
+```typescript
+// Route: /customer-id/function-name
+const [customerId, functionName] = new URL(request.url).pathname.split('/').filter(Boolean)
+const workerName = `${customerId}-${functionName}`
+const userWorker = env.DISPATCHER.get(workerName)
+```
+
+### Website Builder
+
+- Deploy static assets + Worker code
+- See [api.md](./api.md#static-assets) for full implementation
+- Salt hashes for asset isolation
+
+## Best Practices
+
+### Architecture
+
+- One namespace per environment (production, staging)
+- Platform logic in dispatch Worker (auth, rate limiting, validation)
+- Isolation automatic (no shared cache, untrusted mode)
+
+### Routing
+
+- Use `*/*` wildcard routes
+- Store mappings in KV
+- Handle missing Workers gracefully
+
+### Limits & Security
+
+- Set custom limits by plan
+- Track violations with Analytics Engine
+- Use outbound Workers for egress control
+- Sanitize responses
+
+### Tags
+
+- Tag all Workers: customer ID, plan, environment
+- Enable bulk operations
+- Filter efficiently
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)

package/skills/cloudflare/references/workers-playground/README.md

@@ -0,0 +1,131 @@
+# Cloudflare Workers Playground Skill Reference
+
+## Overview
+
+Cloudflare Workers Playground is a browser-based sandbox for instantly experimenting with, testing, and deploying Cloudflare Workers without authentication or setup. This skill provides patterns, APIs, and best practices specifically for Workers Playground development.
+
+**URL:** [workers.cloudflare.com/playground](https://workers.cloudflare.com/playground)
+
+## ⚠️ Playground Constraints
+
+**Playground is NOT production-equivalent:**
+
+- ✅ Real Workers runtime, instant testing, shareable URLs
+- ❌ No TypeScript (JavaScript only)
+- ❌ No bindings (KV, D1, R2, Durable Objects)
+- ❌ No environment variables or secrets
+- ❌ ES modules only (no Service Worker format)
+- ⚠️ Safari broken (use Chrome/Firefox)
+
+**For production:** Use `wrangler` CLI. Playground is for rapid prototyping.
+
+## Quick Start
+
+Minimal Worker:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    return new Response('Hello World')
+  },
+}
+```
+
+JSON API:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const data = { message: 'Hello', timestamp: Date.now() }
+    return Response.json(data)
+  },
+}
+```
+
+Proxy with modification:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    const response = await fetch('https://example.com')
+    const modified = new Response(response.body, response)
+    modified.headers.set('X-Custom-Header', 'added-by-worker')
+    return modified
+  },
+}
+```
+
+Import from CDN:
+
+```javascript
+import { Hono } from 'https://esm.sh/hono@3'
+
+export default {
+  async fetch(request) {
+    const app = new Hono()
+    app.get('/', (c) => c.text('Hello Hono!'))
+    return app.fetch(request)
+  },
+}
+```
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Start here: playground setup, constraints, deployment
+2. **[api.md](api.md)** - Core APIs: Request, Response, ExecutionContext, fetch, Cache
+3. **[patterns.md](patterns.md)** - Common use cases: routing, proxying, A/B testing, multi-module code
+4. **[gotchas.md](gotchas.md)** - Troubleshooting: errors, browser issues, limits, best practices
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, deployment, configuration
+- **[api.md](api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations
+
+## Key Features
+
+**No Setup Required:**
+
+- Open URL and start coding
+- No CLI, no account, no config files
+- Code executes in real Cloudflare Workers runtime
+
+**Instant Preview:**
+
+- Live preview pane with browser tab or HTTP tester
+- Auto-reload on code changes
+- DevTools integration (right-click → Inspect)
+
+**Share & Deploy:**
+
+- Copy Link generates permanent shareable URL
+- Deploy button publishes to production in ~30 seconds
+- Get `*.workers.dev` subdomain immediately
+
+## Common Use Cases
+
+- **API development:** Test endpoints before wrangler setup
+- **Learning Workers:** Experiment with APIs without local environment
+- **Prototyping:** Quick POCs for edge logic
+- **Sharing examples:** Generate shareable links for bug reports or demos
+- **Framework testing:** Import from CDN (Hono, itty-router, etc.)
+
+## Limitations vs Production
+
+| Feature          | Playground       | Production (wrangler)    |
+| ---------------- | ---------------- | ------------------------ |
+| Language         | JavaScript only  | JS + TypeScript          |
+| Bindings         | None             | KV, D1, R2, DO, AI, etc. |
+| Environment vars | None             | Full support             |
+| Module format    | ES only          | ES + Service Worker      |
+| CPU time         | 10ms (Free plan) | 10ms Free / 50ms Paid    |
+| Custom domains   | No               | Yes                      |
+| Analytics        | No               | Yes                      |
+
+## See Also
+
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
+- [Workers Examples](https://developers.cloudflare.com/workers/examples/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
+- [Workers API Reference](https://developers.cloudflare.com/workers/runtime-apis/)

package/skills/cloudflare/references/workers-playground/api.md

@@ -0,0 +1,101 @@
+# Workers Playground API
+
+## Handler
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    // request: Request, env: {} (empty in playground), ctx: ExecutionContext
+    return new Response('Hello')
+  },
+}
+```
+
+## Request
+
+```javascript
+const method = request.method // "GET", "POST"
+const url = new URL(request.url) // Parse URL
+const headers = request.headers // Headers object
+const body = await request.json() // Read body (consumes stream)
+const clone = request.clone() // Clone before reading body
+
+// Query params
+url.searchParams.get('page') // Single value
+url.searchParams.getAll('tag') // Array
+
+// Cloudflare metadata
+request.cf.country // "US"
+request.cf.colo // "SFO"
+```
+
+## Response
+
+```javascript
+// Text
+return new Response('Hello', { status: 200 });
+
+// JSON
+return Response.json({ data }, { status: 200, headers: {...} });
+
+// Redirect
+return Response.redirect('/new-path', 301);
+
+// Modify existing
+const modified = new Response(response.body, response);
+modified.headers.set('X-Custom', 'value');
+```
+
+## ExecutionContext
+
+```javascript
+// Background work (after response sent)
+ctx.waitUntil(fetch('https://logs.example.com', { method: 'POST', body: '...' }))
+return new Response('OK') // Returns immediately
+```
+
+## Fetch
+
+```javascript
+const response = await fetch('https://api.example.com')
+const data = await response.json()
+
+// With options
+await fetch(url, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'Alice' }),
+})
+```
+
+## Cache
+
+```javascript
+const cache = caches.default
+
+// Check cache
+let response = await cache.match(request)
+if (!response) {
+  response = await fetch(origin)
+  await cache.put(request, response.clone()) // Clone before put!
+}
+return response
+```
+
+## Crypto
+
+```javascript
+crypto.randomUUID() // UUID v4
+crypto.getRandomValues(new Uint8Array(16))
+
+// SHA-256 hash
+const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(data))
+```
+
+## Limits (Playground = Free Plan)
+
+| Resource    | Limit  |
+| ----------- | ------ |
+| CPU time    | 10ms   |
+| Subrequests | 50     |
+| Memory      | 128 MB |

package/skills/cloudflare/references/workers-playground/configuration.md

@@ -0,0 +1,169 @@
+# Configuration
+
+## Getting Started
+
+Navigate to [workers.cloudflare.com/playground](https://workers.cloudflare.com/playground)
+
+- **No account required** for testing
+- **No CLI or local setup** needed
+- Code executes in real Cloudflare Workers runtime
+- Share code via URL (never expires)
+
+## Playground Constraints
+
+⚠️ **Important Limitations**
+
+| Constraint                | Playground              | Production Workers                |
+| ------------------------- | ----------------------- | --------------------------------- |
+| **Module Format**         | ES modules only         | ES modules or Service Worker      |
+| **TypeScript**            | Not supported (JS only) | Supported via build step          |
+| **Bindings**              | Not available           | KV, D1, R2, Durable Objects, etc. |
+| **wrangler.toml**         | Not used                | Required for config               |
+| **Environment Variables** | Not available           | Full support                      |
+| **Secrets**               | Not available           | Full support                      |
+| **Custom Domains**        | Not available           | Full support                      |
+
+**Playground is for rapid prototyping only.** For production apps, use `wrangler` CLI.
+
+## Code Editor
+
+### Syntax Requirements
+
+Must export default object with `fetch` handler:
+
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    return new Response('Hello World')
+  },
+}
+```
+
+**Key Points:**
+
+- Must use ES modules (`export default`)
+- `fetch` method receives `(request, env, ctx)`
+- Must return `Response` object
+- TypeScript not supported (use plain JavaScript)
+
+### Multi-Module Code
+
+Import from external URLs or inline modules:
+
+```javascript
+// Import from CDN
+import { Hono } from 'https://esm.sh/hono@3'
+
+// Or paste library code and import relatively
+// (See patterns.md for multi-module examples)
+
+export default {
+  async fetch(request) {
+    const app = new Hono()
+    app.get('/', (c) => c.text('Hello'))
+    return app.fetch(request)
+  },
+}
+```
+
+## Preview Panel
+
+### Browser Tab
+
+Default interactive preview with address bar:
+
+- Enter custom URL paths
+- Automatic reload on code changes
+- DevTools available (right-click → Inspect)
+
+### HTTP Test Panel
+
+Switch to **HTTP** tab for raw HTTP testing:
+
+- Change HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
+- Add/edit request headers
+- Modify request body (JSON, form data, text)
+- View response headers and body
+- Test different content types
+
+Example HTTP test:
+
+```
+Method: POST
+URL: /api/users
+Headers:
+  Content-Type: application/json
+  Authorization: Bearer token123
+Body:
+{
+  "name": "Alice",
+  "email": "alice@example.com"
+}
+```
+
+## Sharing Code
+
+**Copy Link** button generates shareable URL:
+
+- Code embedded in URL fragment
+- Links never expire
+- No account required
+- Can be bookmarked for later
+
+Example: `https://workers.cloudflare.com/playground#abc123...`
+
+## Deploying from Playground
+
+Click **Deploy** button to move code to production:
+
+1. **Log in** to Cloudflare account (creates free account if needed)
+2. **Review** Worker name and code
+3. **Deploy** to global network (takes ~30 seconds)
+4. **Get URL**: Deployed to `<name>.workers.dev` subdomain
+5. **Manage** from dashboard: add bindings, custom domains, analytics
+
+**After deploy:**
+
+- Code runs on Cloudflare's global network (300+ cities)
+- Can add KV, D1, R2, Durable Objects bindings
+- Configure custom domains and routes
+- View analytics and logs
+- Set environment variables and secrets
+
+**Note:** Deployed Workers are production-ready but start on Free plan (100k requests/day).
+
+## Browser Compatibility
+
+| Browser     | Status          | Notes                                     |
+| ----------- | --------------- | ----------------------------------------- |
+| Chrome/Edge | ✅ Full support | Recommended                               |
+| Firefox     | ✅ Full support | Works well                                |
+| Safari      | ⚠️ Broken       | Preview fails with "PreviewRequestFailed" |
+
+**Safari users:** Use Chrome, Firefox, or Edge for Workers Playground.
+
+## DevTools Integration
+
+1. **Open preview** in browser tab
+2. **Right-click** → Inspect Element
+3. **Console tab** shows Worker logs:
+   - `console.log()` output
+   - Uncaught errors
+   - Network requests (subrequests)
+
+**Note:** DevTools show client-side console, not Worker execution logs. For production logging, use Logpush or Tail Workers.
+
+## Limits in Playground
+
+Same as production Free plan:
+
+| Resource      | Limit     | Notes                |
+| ------------- | --------- | -------------------- |
+| CPU time      | 10ms      | Per request          |
+| Memory        | 128 MB    | Per request          |
+| Script size   | 1 MB      | After compression    |
+| Subrequests   | 50        | Outbound fetch calls |
+| Request size  | 100 MB    | Incoming             |
+| Response size | Unlimited | Outgoing (streamed)  |
+
+**Exceeding CPU time** throws error immediately. Optimize hot paths or upgrade to Paid plan (50ms CPU).

package/skills/cloudflare/references/workers-playground/gotchas.md

@@ -0,0 +1,88 @@
+# Workers Playground Gotchas
+
+## Platform Limitations
+
+| Limitation             | Impact               | Workaround                     |
+| ---------------------- | -------------------- | ------------------------------ |
+| Safari broken          | Preview fails        | Use Chrome/Firefox/Edge        |
+| TypeScript unsupported | TS syntax errors     | Write plain JS or use JSDoc    |
+| No bindings            | `env` always `{}`    | Mock data or use external APIs |
+| No env vars            | Can't access secrets | Hardcode for testing           |
+
+## Common Runtime Errors
+
+### "Response body already read"
+
+```javascript
+// ❌ Body consumed twice
+const body = await request.text()
+await fetch(url, { body: request.body }) // Error!
+
+// ✅ Clone first
+const clone = request.clone()
+const body = await request.text()
+await fetch(url, { body: clone.body })
+```
+
+### "Worker exceeded CPU time"
+
+**Limit:** 10ms (free), 50ms (paid)
+
+```javascript
+// ✅ Move slow work to background
+ctx.waitUntil(fetch('https://analytics.example.com', {...}));
+return new Response('OK'); // Return immediately
+```
+
+### "Too many subrequests"
+
+**Limit:** 50 (free), 1000 (paid)
+
+```javascript
+// ❌ 100 individual fetches
+// ✅ Batch into single API call
+await fetch('https://api.example.com/batch', {
+  body: JSON.stringify({ ids: [...] })
+});
+```
+
+## Best Practices
+
+```javascript
+// Clone before caching
+await cache.put(request, response.clone());
+return response;
+
+// Validate input early
+if (request.method !== 'POST') return new Response('', { status: 405 });
+
+// Handle errors
+try { ... } catch (e) {
+  return Response.json({ error: e.message }, { status: 500 });
+}
+```
+
+## Limits
+
+| Resource    | Free   | Paid   |
+| ----------- | ------ | ------ |
+| CPU time    | 10ms   | 50ms   |
+| Memory      | 128 MB | 128 MB |
+| Subrequests | 50     | 10,000 |
+
+## Browser Support
+
+| Browser | Status         |
+| ------- | -------------- |
+| Chrome  | ✅ Recommended |
+| Firefox | ✅ Works       |
+| Edge    | ✅ Works       |
+| Safari  | ❌ Broken      |
+
+## Debugging
+
+```javascript
+console.log('URL:', request.url) // View in browser DevTools Console
+```
+
+**Note:** `console.log` works in playground. For production, use Logpush or Tail Workers.