memory-journal-mcp 8.0.1 → 9.1.0

package/skills/cloudflare/references/cron-triggers/gotchas.md

@@ -1,207 +0,0 @@
-# Cron Triggers Gotchas
-
-## Common Errors
-
-### "Timezone Issues"
-
-**Problem:** Cron runs at wrong time relative to local timezone  
-**Cause:** All crons execute in UTC, no local timezone support  
-**Solution:** Convert local time to UTC manually
-
-**Conversion formula:** `utcHour = (localHour - utcOffset + 24) % 24`
-
-**Examples:**
-
-- 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *`
-- 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *`
-- 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *`
-
-**Daylight Saving Time:** Adjust manually when DST changes, or schedule at times unaffected by DST (e.g., 2am-4am local time usually safe)
-
-### "Cron Not Executing"
-
-**Cause:** Missing `scheduled()` export, invalid syntax, propagation delay (<15min), or plan limits  
-**Solution:** Verify export exists, validate at crontab.guru, wait 15+ min after deploy, check plan limits
-
-### "Duplicate Executions"
-
-**Cause:** At-least-once delivery  
-**Solution:** Track execution IDs in KV - see idempotency pattern below
-
-### "Execution Failures"
-
-**Cause:** CPU exceeded, unhandled exceptions, network timeouts, binding errors  
-**Solution:** Use try-catch, AbortController timeouts, `ctx.waitUntil()` for long ops, or Workflows for heavy tasks
-
-### "Local Testing Not Working"
-
-**Problem:** `/__scheduled` endpoint returns 404 or doesn't trigger handler  
-**Cause:** Missing `scheduled()` export, wrangler not running, or incorrect endpoint format  
-**Solution:**
-
-1. Verify `scheduled()` is exported:
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    console.log('Cron triggered')
-  },
-}
-```
-
-2. Start dev server:
-
-```bash
-npx wrangler dev
-```
-
-3. Use correct endpoint format (URL-encode spaces as `+`):
-
-```bash
-# Correct
-curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
-
-# Wrong (will fail)
-curl "http://localhost:8787/__scheduled?cron=*/5 * * * *"
-```
-
-4. Update Wrangler if outdated:
-
-```bash
-npm install -g wrangler@latest
-```
-
-### "waitUntil() Tasks Not Completing"
-
-**Problem:** Background tasks in `ctx.waitUntil()` fail silently or don't execute  
-**Cause:** Promises rejected without error handling, or handler returns before promise settles  
-**Solution:** Always await or handle errors in waitUntil promises:
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    // BAD: Silent failures
-    ctx.waitUntil(riskyOperation())
-
-    // GOOD: Explicit error handling
-    ctx.waitUntil(
-      riskyOperation().catch((err) => {
-        console.error('Background task failed:', err)
-        return logError(err, env)
-      })
-    )
-  },
-}
-```
-
-### "Idempotency Issues"
-
-**Problem:** At-least-once delivery causes duplicate side effects (double charges, duplicate emails)  
-**Cause:** No deduplication mechanism  
-**Solution:** Use KV to track execution IDs:
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const executionId = `${controller.cron}-${controller.scheduledTime}`
-    const existing = await env.EXECUTIONS.get(executionId)
-
-    if (existing) {
-      console.log('Already executed, skipping')
-      controller.noRetry()
-      return
-    }
-
-    await env.EXECUTIONS.put(executionId, '1', { expirationTtl: 86400 }) // 24h TTL
-    await performIdempotentOperation(env)
-  },
-}
-```
-
-### "Security Concerns"
-
-**Problem:** `__scheduled` endpoint exposed in production allows unauthorized cron triggering  
-**Cause:** Testing endpoint available in deployed Workers  
-**Solution:** Block `__scheduled` in production:
-
-```typescript
-export default {
-  async fetch(request, env, ctx) {
-    const url = new URL(request.url)
-
-    // Block __scheduled in production
-    if (url.pathname === '/__scheduled' && env.ENVIRONMENT === 'production') {
-      return new Response('Not Found', { status: 404 })
-    }
-
-    return handleRequest(request, env, ctx)
-  },
-
-  async scheduled(controller, env, ctx) {
-    // Your cron logic
-  },
-}
-```
-
-**Also:** Use `env.API_KEY` for secrets (never hardcode)
-
-**Alternative:** Add middleware to verify request origin:
-
-```typescript
-export default {
-  async fetch(request, env, ctx) {
-    const url = new URL(request.url)
-
-    if (url.pathname === '/__scheduled') {
-      // Check Cloudflare headers to verify internal request
-      const cfRay = request.headers.get('cf-ray')
-      if (!cfRay && env.ENVIRONMENT === 'production') {
-        return new Response('Not Found', { status: 404 })
-      }
-    }
-
-    return handleRequest(request, env, ctx)
-  },
-
-  async scheduled(controller, env, ctx) {
-    // Your cron logic
-  },
-}
-```
-
-## Limits & Quotas
-
-| Limit               | Free             | Paid             | Notes                                    |
-| ------------------- | ---------------- | ---------------- | ---------------------------------------- |
-| Triggers per Worker | 3                | Unlimited        | Maximum cron schedules per Worker        |
-| CPU time            | 10ms             | 50ms             | May need `ctx.waitUntil()` or Workflows  |
-| Execution guarantee | At-least-once    | At-least-once    | Duplicates possible - use idempotency    |
-| Propagation delay   | Up to 15 minutes | Up to 15 minutes | Time for changes to take effect globally |
-| Min interval        | 1 minute         | 1 minute         | Cannot schedule more frequently          |
-| Cron accuracy       | ±1 minute        | ±1 minute        | Execution may drift slightly             |
-
-## Testing Best Practices
-
-**Unit tests:**
-
-- Mock `ScheduledController`, `ExecutionContext`, and bindings
-- Test each cron expression separately
-- Verify `noRetry()` is called when expected
-- Use Vitest with `@cloudflare/vitest-pool-workers` for realistic env
-
-**Integration tests:**
-
-- Test via `/__scheduled` endpoint in dev environment
-- Verify idempotency logic with duplicate `scheduledTime` values
-- Test error handling and retry behavior
-
-**Production:** Start with long intervals (`*/30 * * * *`), monitor Cron Events for 24h, set up alerts before reducing interval
-
-## Resources
-
-- [Cron Triggers Docs](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
-- [Scheduled Handler API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
-- [Cloudflare Workflows](https://developers.cloudflare.com/workflows/)
-- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
-- [Crontab Guru](https://crontab.guru/) - Validator
-- [Vitest Pool Workers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples)

package/skills/cloudflare/references/cron-triggers/patterns.md

@@ -1,274 +0,0 @@
-# Cron Triggers Patterns
-
-## API Data Sync
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const response = await fetch('https://api.example.com/data', {
-      headers: { Authorization: `Bearer ${env.API_KEY}` },
-    })
-    if (!response.ok) throw new Error(`API error: ${response.status}`)
-    ctx.waitUntil(
-      env.MY_KV.put('cached_data', JSON.stringify(await response.json()), { expirationTtl: 3600 })
-    )
-  },
-}
-```
-
-## Database Cleanup
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const result = await env.DB.prepare(
-      `DELETE FROM sessions WHERE expires_at < datetime('now')`
-    ).run()
-    console.log(`Deleted ${result.meta.changes} expired sessions`)
-    ctx.waitUntil(env.DB.prepare('VACUUM').run())
-  },
-}
-```
-
-## Report Generation
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const startOfWeek = new Date()
-    startOfWeek.setDate(startOfWeek.getDate() - 7)
-    const { results } = await env.DB.prepare(
-      `SELECT date, revenue, orders FROM daily_stats WHERE date >= ? ORDER BY date`
-    )
-      .bind(startOfWeek.toISOString())
-      .all()
-    const report = {
-      period: 'weekly',
-      totalRevenue: results.reduce((sum, d) => sum + d.revenue, 0),
-      totalOrders: results.reduce((sum, d) => sum + d.orders, 0),
-      dailyBreakdown: results,
-    }
-    const reportKey = `reports/weekly-${Date.now()}.json`
-    await env.REPORTS_BUCKET.put(reportKey, JSON.stringify(report))
-    ctx.waitUntil(
-      env.SEND_EMAIL.fetch('https://example.com/send', {
-        method: 'POST',
-        body: JSON.stringify({
-          to: 'team@example.com',
-          subject: 'Weekly Report',
-          reportUrl: `https://reports.example.com/${reportKey}`,
-        }),
-      })
-    )
-  },
-}
-```
-
-## Health Checks
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const services = [
-      { name: 'API', url: 'https://api.example.com/health' },
-      { name: 'CDN', url: 'https://cdn.example.com/health' },
-    ]
-    const checks = await Promise.all(
-      services.map(async (service) => {
-        const start = Date.now()
-        try {
-          const response = await fetch(service.url, { signal: AbortSignal.timeout(5000) })
-          return {
-            name: service.name,
-            status: response.ok ? 'up' : 'down',
-            responseTime: Date.now() - start,
-          }
-        } catch (error) {
-          return {
-            name: service.name,
-            status: 'down',
-            responseTime: Date.now() - start,
-            error: error.message,
-          }
-        }
-      })
-    )
-    ctx.waitUntil(env.STATUS_KV.put('health_status', JSON.stringify(checks)))
-    const failures = checks.filter((c) => c.status === 'down')
-    if (failures.length > 0)
-      ctx.waitUntil(
-        fetch(env.ALERT_WEBHOOK, {
-          method: 'POST',
-          body: JSON.stringify({
-            text: `${failures.length} service(s) down: ${failures.map((f) => f.name).join(', ')}`,
-          }),
-        })
-      )
-  },
-}
-```
-
-## Batch Processing (Rate-Limited)
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const queueData = await env.QUEUE_KV.get('pending_items', 'json')
-    if (!queueData || queueData.length === 0) return
-    const batch = queueData.slice(0, 100)
-    const results = await Promise.allSettled(
-      batch.map((item) =>
-        fetch('https://api.example.com/process', {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${env.API_KEY}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify(item),
-        })
-      )
-    )
-    console.log(
-      `Processed ${results.filter((r) => r.status === 'fulfilled').length}/${batch.length} items`
-    )
-    ctx.waitUntil(env.QUEUE_KV.put('pending_items', JSON.stringify(queueData.slice(100))))
-  },
-}
-```
-
-## Queue Integration
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const batch = await env.MY_QUEUE.receive({ batchSize: 100 })
-    const results = await Promise.allSettled(
-      batch.messages.map(async (msg) => {
-        await processMessage(msg.body, env)
-        await msg.ack()
-      })
-    )
-    console.log(
-      `Processed ${results.filter((r) => r.status === 'fulfilled').length}/${batch.messages.length}`
-    )
-  },
-}
-```
-
-## Monitoring & Observability
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const startTime = Date.now()
-    const meta = { cron: controller.cron, scheduledTime: controller.scheduledTime }
-    console.log('[START]', meta)
-    try {
-      const result = await performTask(env)
-      console.log('[SUCCESS]', { ...meta, duration: Date.now() - startTime, count: result.count })
-      ctx.waitUntil(
-        env.METRICS.put(
-          `cron:${controller.scheduledTime}`,
-          JSON.stringify({ ...meta, status: 'success' }),
-          { expirationTtl: 2592000 }
-        )
-      )
-    } catch (error) {
-      console.error('[ERROR]', { ...meta, duration: Date.now() - startTime, error: error.message })
-      ctx.waitUntil(
-        fetch(env.ALERT_WEBHOOK, {
-          method: 'POST',
-          body: JSON.stringify({ text: `Cron failed: ${controller.cron}`, error: error.message }),
-        })
-      )
-      throw error
-    }
-  },
-}
-```
-
-**View logs:** `npx wrangler tail` or Dashboard → Workers & Pages → Worker → Logs
-
-## Durable Objects Coordination
-
-```typescript
-export default {
-  async scheduled(controller, env, ctx) {
-    const stub = env.COORDINATOR.get(env.COORDINATOR.idFromName('cron-lock'))
-    const acquired = await stub.tryAcquireLock(controller.scheduledTime)
-    if (!acquired) {
-      controller.noRetry()
-      return
-    }
-    try {
-      await performTask(env)
-    } finally {
-      await stub.releaseLock()
-    }
-  },
-}
-```
-
-## Python Handler
-
-```python
-from workers import WorkerEntrypoint
-
-class Default(WorkerEntrypoint):
-    async def scheduled(self, controller, env, ctx):
-        data = await env.MY_KV.get("key")
-        ctx.waitUntil(env.DB.execute("DELETE FROM logs WHERE created_at < datetime('now', '-7 days')"))
-```
-
-## Testing Patterns
-
-**Local testing with /\_\_scheduled:**
-
-```bash
-# Start dev server
-npx wrangler dev
-
-# Test specific cron
-curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"
-
-# Test with specific time
-curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"
-```
-
-**Unit tests:**
-
-```typescript
-// test/scheduled.test.ts
-import { describe, it, expect, vi } from 'vitest'
-import { env } from 'cloudflare:test'
-import worker from '../src/index'
-
-describe('Scheduled Handler', () => {
-  it('executes cron', async () => {
-    const controller = {
-      scheduledTime: Date.now(),
-      cron: '*/5 * * * *',
-      type: 'scheduled' as const,
-      noRetry: vi.fn(),
-    }
-    const ctx = { waitUntil: vi.fn(), passThroughOnException: vi.fn() }
-    await worker.scheduled(controller, env, ctx)
-    expect(await env.MY_KV.get('last_run')).toBeDefined()
-  })
-
-  it('calls noRetry on duplicate', async () => {
-    const controller = {
-      scheduledTime: 1704067200000,
-      cron: '0 2 * * *',
-      type: 'scheduled' as const,
-      noRetry: vi.fn(),
-    }
-    await env.EXECUTIONS.put('0 2 * * *-1704067200000', '1')
-    await worker.scheduled(controller, env, { waitUntil: vi.fn(), passThroughOnException: vi.fn() })
-    expect(controller.noRetry).toHaveBeenCalled()
-  })
-})
-```
-
-## See Also
-
-- [README.md](./README.md) - Overview
-- [api.md](./api.md) - Handler implementation
-- [gotchas.md](./gotchas.md) - Troubleshooting

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

@@ -1,137 +0,0 @@
-# Cloudflare D1 Database
-
-Expert guidance for Cloudflare D1, a serverless SQLite database designed for horizontal scale-out across multiple databases.
-
-## Overview
-
-D1 is Cloudflare's managed, serverless database with:
-
-- SQLite SQL semantics and compatibility
-- Built-in disaster recovery via Time Travel (30-day point-in-time recovery)
-- Horizontal scale-out architecture (10 GB per database)
-- Worker and HTTP API access
-- Pricing based on query and storage costs only
-
-**Architecture Philosophy**: D1 is optimized for per-user, per-tenant, or per-entity database patterns rather than single large databases.
-
-## Quick Start
-
-```bash
-# Create database
-wrangler d1 create <database-name>
-
-# Execute migration
-wrangler d1 migrations apply <db-name> --remote
-
-# Local development
-wrangler dev
-```
-
-## Core Query Methods
-
-```typescript
-// .all() - Returns all rows; .first() - First row or null; .first(col) - Single column value
-// .run() - INSERT/UPDATE/DELETE; .raw() - Array of arrays (efficient)
-const { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?')
-  .bind(true)
-  .all()
-const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
-```
-
-## Batch Operations
-
-```typescript
-// Multiple queries in single round trip (atomic transaction)
-const results = await env.DB.batch([
-  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),
-  env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),
-  env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1),
-])
-```
-
-## Sessions API (Paid Plans)
-
-```typescript
-// Create long-running session for analytics/migrations (up to 15 minutes)
-const session = env.DB.withSession()
-try {
-  await session.prepare('CREATE INDEX idx_heavy ON large_table(column)').run()
-  await session.prepare('ANALYZE').run()
-} finally {
-  session.close() // Always close to release resources
-}
-```
-
-## Read Replication (Paid Plans)
-
-```typescript
-// Read from nearest replica for lower latency (automatic failover)
-const user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
-
-// Writes always go to primary
-await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run()
-```
-
-## Platform Limits
-
-| Limit                 | Free Tier        | Paid Plans         |
-| --------------------- | ---------------- | ------------------ |
-| Database size         | 500 MB           | 10 GB per database |
-| Row size              | 1 MB max         | 1 MB max           |
-| Query timeout         | 30 seconds       | 30 seconds         |
-| Batch size            | 1,000 statements | 10,000 statements  |
-| Time Travel retention | 7 days           | 30 days            |
-| Read replicas         | Not available    | Yes (paid add-on)  |
-
-**Pricing**: $5/month per database beyond free tier + $0.001 per 1K reads + $1 per 1M writes + $0.75/GB storage/month
-
-## CLI Commands
-
-```bash
-# Database management
-wrangler d1 create <db-name>
-wrangler d1 list
-wrangler d1 delete <db-name>
-
-# Migrations
-wrangler d1 migrations create <db-name> <migration-name>    # Create new migration file
-wrangler d1 migrations apply <db-name> --remote             # Apply pending migrations
-wrangler d1 migrations apply <db-name> --local              # Apply locally
-wrangler d1 migrations list <db-name> --remote              # Show applied migrations
-
-# Direct SQL execution
-wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"
-wrangler d1 execute <db-name> --local --file=./schema.sql
-
-# Backups & Import/Export
-wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export with schema
-wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
-wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time recovery
-
-# Development
-wrangler dev --persist-to=./.wrangler/state
-```
-
-## Reading Order
-
-**Start here**: Quick Start above → configuration.md (setup) → api.md (queries)
-
-**Common tasks**:
-
-- First time setup: configuration.md → Run migrations
-- Adding queries: api.md → Prepared statements
-- Pagination/caching: patterns.md
-- Production optimization: Read Replication + Sessions API (this file)
-- Debugging: gotchas.md
-
-## In This Reference
-
-- [configuration.md](./configuration.md) - wrangler.jsonc setup, migrations, TypeScript types, ORMs, local dev
-- [api.md](./api.md) - Query methods (.all/.first/.run/.raw), batch, sessions, read replicas, error handling
-- [patterns.md](./patterns.md) - Pagination, bulk operations, caching, multi-tenant, sessions, analytics
-- [gotchas.md](./gotchas.md) - SQL injection, limits by plan tier, performance, common errors
-
-## See Also
-
-- [workers](../workers/) - Worker runtime and fetch handler patterns
-- [hyperdrive](../hyperdrive/) - Connection pooling for external databases