memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,166 @@
+# Configuration
+
+See [README.md](./README.md) for overview.
+
+## Create Config
+
+**PostgreSQL:**
+
+```bash
+# Basic
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://user:pass@host:5432/db"
+
+# Custom cache
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://..." \
+  --max-age=120 --swr=30
+
+# No cache
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://..." \
+  --caching-disabled=true
+```
+
+**MySQL:**
+
+```bash
+npx wrangler hyperdrive create my-db \
+  --connection-string="mysql://user:pass@host:3306/db"
+```
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "compatibility_date": "2025-01-01", // Use latest for new projects
+  "compatibility_flags": ["nodejs_compat"],
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+      "id": "<HYPERDRIVE_ID>",
+      "localConnectionString": "postgres://user:pass@localhost:5432/dev",
+    },
+  ],
+}
+```
+
+**Generate TypeScript types:** Run `npx wrangler types` to auto-generate `worker-configuration.d.ts` from your wrangler.jsonc.
+
+**Multiple configs:**
+
+```jsonc
+{
+  "hyperdrive": [
+    { "binding": "HYPERDRIVE_CACHED", "id": "<ID1>" },
+    { "binding": "HYPERDRIVE_NO_CACHE", "id": "<ID2>" },
+  ],
+}
+```
+
+## Management
+
+```bash
+npx wrangler hyperdrive list
+npx wrangler hyperdrive get <ID>
+npx wrangler hyperdrive update <ID> --max-age=180
+npx wrangler hyperdrive delete <ID>
+```
+
+## Config Options
+
+Hyperdrive create/update CLI flags:
+
+| Option                      | Default   | Notes                  |
+| --------------------------- | --------- | ---------------------- |
+| `--caching-disabled`        | `false`   | Disable caching        |
+| `--max-age`                 | `60`      | Cache TTL (max 3600s)  |
+| `--swr`                     | `15`      | Stale-while-revalidate |
+| `--origin-connection-limit` | 20/100    | Free/paid              |
+| `--access-client-id`        | -         | Tunnel auth            |
+| `--access-client-secret`    | -         | Tunnel auth            |
+| `--sslmode`                 | `require` | PostgreSQL only        |
+
+## Smart Placement Integration
+
+For Workers making **multiple queries** per request, enable Smart Placement to execute near your database:
+
+```jsonc
+{
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "placement": {
+    "mode": "smart",
+  },
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+      "id": "<HYPERDRIVE_ID>",
+    },
+  ],
+}
+```
+
+**Benefits:** Multi-query Workers run closer to DB, reducing round-trip latency. See [patterns.md](./patterns.md) for examples.
+
+## Private DB via Tunnel
+
+```
+Worker → Hyperdrive → Access → Tunnel → Private Network → DB
+```
+
+**Setup:**
+
+```bash
+# 1. Create tunnel
+cloudflared tunnel create my-db-tunnel
+
+# 2. Configure hostname in Zero Trust dashboard
+#    Domain: db-tunnel.example.com
+#    Service: TCP -> localhost:5432
+
+# 3. Create service token (Zero Trust > Service Auth)
+#    Save Client ID/Secret
+
+# 4. Create Access app (db-tunnel.example.com)
+#    Policy: Service Auth token from step 3
+
+# 5. Create Hyperdrive
+npx wrangler hyperdrive create my-private-db \
+  --host=db-tunnel.example.com \
+  --user=dbuser --password=dbpass --database=prod \
+  --access-client-id=<ID> --access-client-secret=<SECRET>
+```
+
+**⚠️ Don't specify `--port` with Tunnel** - port configured in tunnel service settings.
+
+## Local Dev
+
+**Option 1: Local (RECOMMENDED):**
+
+```bash
+# Env var (takes precedence)
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@localhost:5432/dev"
+npx wrangler dev
+
+# wrangler.jsonc
+{"hyperdrive": [{"binding": "HYPERDRIVE", "localConnectionString": "postgres://..."}]}
+```
+
+**Remote DB locally:**
+
+```bash
+# PostgreSQL
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@remote:5432/db?sslmode=require"
+
+# MySQL
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="mysql://user:pass@remote:3306/db?sslMode=REQUIRED"
+```
+
+**Option 2: Remote execution:**
+
+```bash
+npx wrangler dev --remote  # Uses deployed config, affects production
+```
+
+See [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md).

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

@@ -0,0 +1,77 @@
+# Gotchas
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md).
+
+## Common Errors
+
+### "Too many open connections" / "Connection limit exceeded"
+
+**Cause:** Workers have a hard limit of **6 concurrent connections per invocation**  
+**Solution:** Set `max: 5` in driver config, reuse connections, ensure proper cleanup with `client.end()` or `ctx.waitUntil(conn.end())`
+
+### "Failed to acquire a connection (Pool exhausted)"
+
+**Cause:** All connections in pool are in use, often due to long-running transactions  
+**Solution:** Reduce transaction duration, avoid queries >60s, don't hold connections during external calls, or upgrade to paid plan for more connections
+
+### "connection_refused"
+
+**Cause:** Database refusing connections due to firewall, connection limits, or service down  
+**Solution:** Check firewall allows Cloudflare IPs, verify DB listening on port, confirm service running, and validate credentials
+
+### "Query timeout (deadline exceeded)"
+
+**Cause:** Query execution exceeding 60s timeout limit  
+**Solution:** Optimize with indexes, reduce dataset with LIMIT, break into smaller queries, or use async processing
+
+### "password authentication failed"
+
+**Cause:** Invalid credentials in Hyperdrive configuration  
+**Solution:** Check username and password in Hyperdrive config match database credentials
+
+### "SSL/TLS connection error"
+
+**Cause:** SSL/TLS configuration mismatch between Hyperdrive and database  
+**Solution:** Add `sslmode=require` (Postgres) or `sslMode=REQUIRED` (MySQL), upload CA cert if self-signed, verify DB has SSL enabled, and check cert expiry
+
+### "Queries not being cached"
+
+**Cause:** Query is mutating (INSERT/UPDATE/DELETE), contains volatile functions (NOW(), RANDOM()), or caching disabled  
+**Solution:** Verify query is non-mutating SELECT, avoid volatile functions, confirm caching enabled, use `wrangler dev --remote` to test, and set `prepare=true` for postgres.js
+
+### "Slow multi-query Workers despite Hyperdrive"
+
+**Cause:** Worker executing at edge, each query round-trips to DB region  
+**Solution:** Enable Smart Placement (`"placement": {"mode": "smart"}` in wrangler.jsonc) to execute Worker near DB. See [patterns.md](./patterns.md) Multi-Query pattern.
+
+### "Local database connection failed"
+
+**Cause:** `localConnectionString` incorrect or database not running  
+**Solution:** Verify `localConnectionString` correct, check DB running, confirm env var name matches binding, and test with psql/mysql client
+
+### "Environment variable not working"
+
+**Cause:** Environment variable format incorrect or not exported  
+**Solution:** Use format `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>`, ensure binding matches wrangler.jsonc, export variable in shell, and restart wrangler dev
+
+## Limits
+
+| Limit                  | Free     | Paid     | Notes                                            |
+| ---------------------- | -------- | -------- | ------------------------------------------------ |
+| Max configs            | 10       | 25       | Hyperdrive configurations per account            |
+| Worker connections     | 6        | 6        | Max concurrent connections per Worker invocation |
+| Username/DB name       | 63 bytes | 63 bytes | Maximum length                                   |
+| Connection timeout     | 15s      | 15s      | Time to establish connection                     |
+| Idle timeout           | 10 min   | 10 min   | Connection idle timeout                          |
+| Max origin connections | ~20      | ~100     | Connections to origin database                   |
+| Query duration max     | 60s      | 60s      | Queries >60s terminated                          |
+| Cached response max    | 50 MB    | 50 MB    | Responses >50MB returned but not cached          |
+
+## Resources
+
+- [Docs](https://developers.cloudflare.com/hyperdrive/)
+- [Getting Started](https://developers.cloudflare.com/hyperdrive/get-started/)
+- [Wrangler Reference](https://developers.cloudflare.com/hyperdrive/reference/wrangler-commands/)
+- [Supported DBs](https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/)
+- [Discord #hyperdrive](https://discord.cloudflare.com)
+- [Limit Increase Form](https://forms.gle/ukpeZVLWLnKeixDu7)

package/skills/cloudflare/references/hyperdrive/patterns.md

@@ -0,0 +1,203 @@
+# Patterns
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md).
+
+## High-Traffic Read-Heavy
+
+```typescript
+const sql = postgres(env.HYPERDRIVE.connectionString, { max: 5, prepare: true })
+
+// Cacheable: popular content
+const posts = await sql`SELECT * FROM posts WHERE published = true ORDER BY views DESC LIMIT 20`
+
+// Cacheable: user profiles
+const [user] = await sql`SELECT id, username, bio FROM users WHERE id = ${userId}`
+```
+
+**Benefits:** Trending/profiles cached (60s), connection pooling handles spikes.
+
+## Mixed Read/Write
+
+```typescript
+interface Env {
+  HYPERDRIVE_CACHED: Hyperdrive // max_age=120
+  HYPERDRIVE_REALTIME: Hyperdrive // caching disabled
+}
+
+// Reads: cached
+if (req.method === 'GET') {
+  const sql = postgres(env.HYPERDRIVE_CACHED.connectionString, { prepare: true })
+  const products = await sql`SELECT * FROM products WHERE category = ${cat}`
+}
+
+// Writes: no cache (immediate consistency)
+if (req.method === 'POST') {
+  const sql = postgres(env.HYPERDRIVE_REALTIME.connectionString, { prepare: true })
+  await sql`INSERT INTO orders ${sql(data)}`
+}
+```
+
+## Analytics Dashboard
+
+```typescript
+const client = new Client({ connectionString: env.HYPERDRIVE.connectionString })
+await client.connect()
+
+// Aggregate queries cached (use fixed timestamps for caching)
+const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()
+const dailyStats = await client.query(
+  `
+  SELECT DATE(created_at) as date, COUNT(*) as orders, SUM(amount) as revenue
+  FROM orders WHERE created_at >= $1
+  GROUP BY DATE(created_at) ORDER BY date DESC
+`,
+  [thirtyDaysAgo]
+)
+
+const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()
+const topProducts = await client.query(
+  `
+  SELECT p.name, COUNT(oi.id) as count, SUM(oi.quantity * oi.price) as revenue
+  FROM order_items oi JOIN products p ON oi.product_id = p.id
+  WHERE oi.created_at >= $1
+  GROUP BY p.id, p.name ORDER BY revenue DESC LIMIT 10
+`,
+  [sevenDaysAgo]
+)
+```
+
+**Benefits:** Expensive aggregations cached (avoid NOW() for cacheability), dashboard instant, reduced DB load.
+
+## Multi-Tenant
+
+```typescript
+const tenantId = req.headers.get('X-Tenant-ID')
+const sql = postgres(env.HYPERDRIVE.connectionString, { prepare: true })
+
+// Tenant-scoped queries cached separately
+const docs = await sql`
+  SELECT * FROM documents 
+  WHERE tenant_id = ${tenantId} AND deleted_at IS NULL
+  ORDER BY updated_at DESC LIMIT 50
+`
+```
+
+**Benefits:** Per-tenant caching, shared connection pool, protects DB from multi-tenant load.
+
+## Geographically Distributed
+
+```typescript
+// Worker runs at edge nearest user
+// Connection setup at edge (fast), pooling near DB (efficient)
+const sql = postgres(env.HYPERDRIVE.connectionString, { prepare: true })
+const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`
+
+return Response.json({
+  user,
+  serverRegion: req.cf?.colo, // Edge location
+})
+```
+
+**Benefits:** Edge setup + DB pooling = global → single-region DB without replication.
+
+## Multi-Query + Smart Placement
+
+For Workers making **multiple queries** per request, enable Smart Placement to execute near DB:
+
+```jsonc
+// wrangler.jsonc
+{
+  "placement": { "mode": "smart" },
+  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<ID>" }],
+}
+```
+
+```typescript
+const sql = postgres(env.HYPERDRIVE.connectionString, { prepare: true })
+
+// Multiple queries benefit from Smart Placement
+const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`
+const orders =
+  await sql`SELECT * FROM orders WHERE user_id = ${userId} ORDER BY created_at DESC LIMIT 10`
+const stats =
+  await sql`SELECT COUNT(*) as total, SUM(amount) as spent FROM orders WHERE user_id = ${userId}`
+
+return Response.json({ user, orders, stats })
+```
+
+**Benefits:** Worker executes near DB → reduces latency for each query. Without Smart Placement, each query round-trips from edge.
+
+## Connection Pooling
+
+Operates in **transaction mode**: connection acquired per transaction, `RESET` on return.
+
+**SET statements:**
+
+```typescript
+// ✅ Within transaction
+await client.query('BEGIN')
+await client.query("SET work_mem = '256MB'")
+await client.query('SELECT * FROM large_table') // Uses SET
+await client.query('COMMIT') // RESET after
+
+// ✅ Single statement
+await client.query("SET work_mem = '256MB'; SELECT * FROM large_table")
+
+// ❌ Across queries (may get different connection)
+await client.query("SET work_mem = '256MB'")
+await client.query('SELECT * FROM large_table') // SET not applied
+```
+
+**Best practices:**
+
+```typescript
+// ❌ Long transactions block pooling
+await client.query('BEGIN')
+await processThousands() // Connection held entire time
+await client.query('COMMIT')
+
+// ✅ Short transactions
+await client.query('BEGIN')
+await client.query('UPDATE users SET status = $1 WHERE id = $2', [status, id])
+await client.query('COMMIT')
+
+// ✅ SET LOCAL within transaction
+await client.query('BEGIN')
+await client.query("SET LOCAL work_mem = '256MB'")
+await client.query('SELECT * FROM large_table')
+await client.query('COMMIT')
+```
+
+## Performance Tips
+
+**Enable prepared statements (required for caching):**
+
+```typescript
+const sql = postgres(connectionString, { prepare: true }) // Default, enables caching
+```
+
+**Optimize connection settings:**
+
+```typescript
+const sql = postgres(connectionString, {
+  max: 5, // Stay under Workers' 6 connection limit
+  fetch_types: false, // Reduce latency if not using arrays
+  idle_timeout: 60, // Match Worker lifetime
+})
+```
+
+**Write cache-friendly queries:**
+
+```typescript
+// ✅ Cacheable (deterministic)
+await sql`SELECT * FROM products WHERE category = 'electronics' LIMIT 10`
+
+// ❌ Not cacheable (volatile NOW())
+await sql`SELECT * FROM logs WHERE created_at > NOW()`
+
+// ✅ Cacheable (parameterized timestamp)
+const ts = Date.now()
+await sql`SELECT * FROM logs WHERE created_at > ${ts}`
+```
+
+See [gotchas.md](./gotchas.md) for limits, troubleshooting.

package/skills/cloudflare/references/images/README.md

@@ -0,0 +1,65 @@
+# Cloudflare Images Skill Reference
+
+**Cloudflare Images** is an end-to-end image management solution providing storage, transformation, optimization, and delivery at scale via Cloudflare's global network.
+
+## Quick Decision Tree
+
+**Need to:**
+
+- **Transform in Worker?** → [api.md](api.md#workers-binding-api-2026-primary-method) (Workers Binding API)
+- **Upload from Worker?** → [api.md](api.md#upload-from-worker) (REST API)
+- **Upload from client?** → [patterns.md](patterns.md#upload-from-client-direct-creator-upload) (Direct Creator Upload)
+- **Set up variants?** → [configuration.md](configuration.md#variants-configuration)
+- **Serve responsive images?** → [patterns.md](patterns.md#responsive-images)
+- **Add watermarks?** → [patterns.md](patterns.md#watermarking)
+- **Fix errors?** → [gotchas.md](gotchas.md#common-errors)
+
+## Reading Order
+
+**For building image upload/transform feature:**
+
+1. [configuration.md](configuration.md) - Setup Workers binding
+2. [api.md](api.md#workers-binding-api-2026-primary-method) - Learn transform API
+3. [patterns.md](patterns.md#upload-from-client-direct-creator-upload) - Direct upload pattern
+4. [gotchas.md](gotchas.md) - Check limits and errors
+
+**For URL-based transforms:**
+
+1. [configuration.md](configuration.md#variants-configuration) - Create variants
+2. [api.md](api.md#url-transform-api) - URL syntax
+3. [patterns.md](patterns.md#responsive-images) - Responsive patterns
+
+**For troubleshooting:**
+
+1. [gotchas.md](gotchas.md#common-errors) - Error messages
+2. [gotchas.md](gotchas.md#limits) - Size/format limits
+
+## Core Methods
+
+| Method                           | Use Case              | Location             |
+| -------------------------------- | --------------------- | -------------------- |
+| `env.IMAGES.input().transform()` | Transform in Worker   | [api.md:11](api.md)  |
+| REST API `/images/v1`            | Upload images         | [api.md:57](api.md)  |
+| Direct Creator Upload            | Client-side upload    | [api.md:127](api.md) |
+| URL transforms                   | Static image delivery | [api.md:112](api.md) |
+
+## In This Reference
+
+- **[api.md](api.md)** - Complete API: Workers binding, REST endpoints, URL transforms
+- **[configuration.md](configuration.md)** - Setup: wrangler.toml, variants, auth, signed URLs
+- **[patterns.md](patterns.md)** - Patterns: responsive images, watermarks, format negotiation, caching
+- **[gotchas.md](gotchas.md)** - Troubleshooting: limits, errors, best practices
+
+## Key Features
+
+- **Automatic Optimization** - AVIF/WebP format negotiation
+- **On-the-fly Transforms** - Resize, crop, blur, sharpen via URL or API
+- **Workers Binding** - Transform images in Workers (2026 primary method)
+- **Direct Upload** - Secure client-side uploads without backend proxy
+- **Global Delivery** - Cached at 300+ Cloudflare data centers
+- **Watermarking** - Overlay images programmatically
+
+## See Also
+
+- [Official Docs](https://developers.cloudflare.com/images/)
+- [Workers Examples](https://developers.cloudflare.com/images/tutorials/)

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

@@ -0,0 +1,101 @@
+# API Reference
+
+## Workers Binding API
+
+```toml
+# wrangler.toml
+[images]
+binding = "IMAGES"
+```
+
+### Transform Images
+
+```typescript
+const imageResponse = await env.IMAGES.input(fileBuffer)
+  .transform({ width: 800, height: 600, fit: 'cover', quality: 85, format: 'avif' })
+  .output()
+return imageResponse.response()
+```
+
+### Transform Options
+
+```typescript
+interface TransformOptions {
+  width?: number
+  height?: number
+  fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad'
+  quality?: number // 1-100
+  format?: 'avif' | 'webp' | 'jpeg' | 'png'
+  dpr?: number // 1-3
+  gravity?: 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'face' | string
+  sharpen?: number // 0-10
+  blur?: number // 1-250
+  rotate?: 90 | 180 | 270
+  background?: string // CSS color for pad
+  metadata?: 'none' | 'copyright' | 'keep'
+  brightness?: number
+  contrast?: number
+  gamma?: number // 0-2
+}
+```
+
+### Draw/Watermark
+
+```typescript
+await env.IMAGES.input(baseImage)
+  .draw(env.IMAGES.input(watermark).transform({ width: 100 }), { top: 10, left: 10, opacity: 0.8 })
+  .output()
+```
+
+## REST API
+
+### Upload Image
+
+```bash
+curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
+  -H "Authorization: Bearer {token}" -F file=@image.jpg -F metadata='{"key":"value"}'
+```
+
+### Other Operations
+
+```bash
+GET  /accounts/{account_id}/images/v1/{image_id}      # Get details
+DELETE /accounts/{account_id}/images/v1/{image_id}   # Delete
+GET  /accounts/{account_id}/images/v1?page=1         # List
+```
+
+## URL Transform API
+
+```
+https://imagedelivery.net/{hash}/{id}/width=800,height=600,fit=cover,format=avif
+```
+
+**Params:** `w=`, `h=`, `fit=`, `q=`, `f=`, `dpr=`, `gravity=`, `sharpen=`, `blur=`, `rotate=`, `background=`, `metadata=`
+
+## Direct Creator Upload
+
+```typescript
+// 1. Get upload URL (backend)
+const { result } = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v2/direct_upload`,
+  {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ requireSignedURLs: false }),
+  }
+).then((r) => r.json())
+
+// 2. Client uploads to result.uploadURL
+const formData = new FormData()
+formData.append('file', file)
+await fetch(result.uploadURL, { method: 'POST', body: formData })
+```
+
+## Error Codes
+
+| Code | Message           | Solution                 |
+| ---- | ----------------- | ------------------------ |
+| 5400 | Invalid format    | Use JPEG, PNG, GIF, WebP |
+| 5401 | Too large         | Max 100MB                |
+| 5403 | Invalid transform | Check params             |
+| 9413 | Rate limit        | Implement backoff        |