memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,158 @@
+# Workflow Configuration
+
+## wrangler.jsonc Setup
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  "observability": {
+    "enabled": true, // Enables Workflows dashboard + structured logs
+  },
+  "workflows": [
+    {
+      "name": "my-workflow", // Workflow name
+      "binding": "MY_WORKFLOW", // Env binding
+      "class_name": "MyWorkflow", // TS class name
+      // "script_name": "other-worker" // For cross-script calls
+    },
+  ],
+  "limits": {
+    "cpu_ms": 300000, // 5 min max (default 30s)
+  },
+}
+```
+
+## Step Configuration
+
+```typescript
+// Basic step
+const data = await step.do('step name', async () => ({ result: 'value' }))
+
+// With retry config
+await step.do(
+  'api call',
+  {
+    retries: {
+      limit: 10, // Default: 5, or Infinity
+      delay: '10 seconds', // Default: 10000ms
+      backoff: 'exponential', // constant | linear | exponential
+    },
+    timeout: '30 minutes', // Per-attempt timeout (default: 10min)
+  },
+  async () => {
+    const res = await fetch('https://api.example.com/data')
+    if (!res.ok) throw new Error('Failed')
+    return res.json()
+  }
+)
+```
+
+### Parallel Steps
+
+```typescript
+const [user, settings] = await Promise.all([
+  step.do('fetch user', async () => this.env.KV.get(`user:${id}`)),
+  step.do('fetch settings', async () => this.env.KV.get(`settings:${id}`)),
+])
+```
+
+### Conditional Steps
+
+```typescript
+const config = await step.do('fetch config', async () => this.env.KV.get('flags', { type: 'json' }))
+
+// ✅ Deterministic (based on step output)
+if (config.enableEmail) {
+  await step.do('send email', async () => sendEmail())
+}
+
+// ❌ Non-deterministic (Date.now outside step)
+if (Date.now() > deadline) {
+  /* BAD */
+}
+```
+
+### Dynamic Steps (Loops)
+
+```typescript
+const files = await step.do('list files', async () => this.env.BUCKET.list())
+
+for (const file of files.objects) {
+  await step.do(`process ${file.key}`, async () => {
+    const obj = await this.env.BUCKET.get(file.key)
+    return processData(await obj.arrayBuffer())
+  })
+}
+```
+
+## Multiple Workflows
+
+```jsonc
+{
+  "workflows": [
+    { "name": "user-onboarding", "binding": "USER_ONBOARDING", "class_name": "UserOnboarding" },
+    { "name": "data-processing", "binding": "DATA_PROCESSING", "class_name": "DataProcessing" },
+  ],
+}
+```
+
+Each class extends `WorkflowEntrypoint` with its own `Params` type.
+
+## Cross-Script Bindings
+
+Worker A defines workflow. Worker B calls it by adding `script_name`:
+
+```jsonc
+// Worker B (caller)
+{
+  "workflows": [
+    {
+      "name": "billing-workflow",
+      "binding": "BILLING",
+      "script_name": "billing-worker", // Points to Worker A
+    },
+  ],
+}
+```
+
+## Bindings
+
+Workflows access Cloudflare bindings via `this.env`:
+
+```typescript
+type Env = {
+  MY_WORKFLOW: Workflow
+  KV: KVNamespace
+  DB: D1Database
+  BUCKET: R2Bucket
+  AI: Ai
+  VECTORIZE: VectorizeIndex
+}
+
+await step.do('use bindings', async () => {
+  const kv = await this.env.KV.get('key')
+  const db = await this.env.DB.prepare('SELECT * FROM users').first()
+  const file = await this.env.BUCKET.get('file.txt')
+  const ai = await this.env.AI.run('@cf/meta/llama-2-7b-chat-int8', { prompt: 'Hi' })
+})
+```
+
+## Pages Functions Binding
+
+Pages Functions can trigger Workflows via service bindings:
+
+```typescript
+// functions/_middleware.ts
+export const onRequest: PagesFunction<Env> = async ({ env, request }) => {
+  const instance = await env.MY_WORKFLOW.create({
+    params: { url: request.url },
+  })
+  return new Response(`Started ${instance.id}`)
+}
+```
+
+Configure in wrangler.jsonc under `service_bindings`.
+
+See: [api.md](./api.md), [patterns.md](./patterns.md)

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

@@ -0,0 +1,97 @@
+# Gotchas & Debugging
+
+## Common Errors
+
+### "Step Timeout"
+
+**Cause:** Step execution exceeding 10 minute default timeout or configured timeout  
+**Solution:** Set custom timeout with `step.do('long operation', {timeout: '30 minutes'}, async () => {...})` or increase CPU limit in wrangler.jsonc (max 5min CPU time)
+
+### "waitForEvent Timeout"
+
+**Cause:** Event not received within timeout period (default 24h, max 365d)  
+**Solution:** Wrap in try-catch to handle timeout gracefully and proceed with default behavior
+
+### "Non-Deterministic Step Names"
+
+**Cause:** Using dynamic values like `Date.now()` in step names causes replay issues  
+**Solution:** Use deterministic values like `event.instanceId` for step names
+
+### "State Lost in Variables"
+
+**Cause:** Using module-level or local variables to store state which is lost on hibernation  
+**Solution:** Return values from `step.do()` which are automatically persisted: `const total = await step.do('step 1', async () => 10)`
+
+### "Non-Deterministic Conditionals"
+
+**Cause:** Using non-deterministic logic (like `Date.now()`) outside steps in conditionals  
+**Solution:** Move non-deterministic operations inside steps: `const isLate = await step.do('check', async () => Date.now() > deadline)`
+
+### "Large Step Returns Exceeding Limit"
+
+**Cause:** Returning data >1 MiB from step  
+**Solution:** Store large data in R2 and return only reference: `{ key: 'r2-object-key' }`
+
+### "Step Exceeded CPU Limit But Ran for < 30s"
+
+**Cause:** Confusion between CPU time (active compute) and wall-clock time (includes I/O waits)  
+**Solution:** Network requests, database queries, and sleeps don't count toward CPU. 30s limit = 30s of active processing
+
+### "Idempotency Violation"
+
+**Cause:** Step operations not idempotent, causing duplicate charges or actions on retry  
+**Solution:** Check if operation already completed before executing (e.g., check if customer already charged)
+
+### "Instance ID Collision"
+
+**Cause:** Reusing instance IDs causing conflicts  
+**Solution:** Use unique IDs with timestamp: `await env.MY_WORKFLOW.create({ id: \`${userId}-${Date.now()}\`, params: {} })`
+
+### "Instance Data Disappeared After Completion"
+
+**Cause:** Completed/errored instances are automatically deleted after retention period (3 days free / 30 days paid)  
+**Solution:** Export critical data to KV/R2/D1 before workflow completes
+
+### "Missing await on step.do"
+
+**Cause:** Forgetting to await step.do() causing fire-and-forget behavior  
+**Solution:** Always await step operations: `await step.do('task', ...)`
+
+## Limits
+
+| Limit                        | Free     | Paid                        | Notes                                                |
+| ---------------------------- | -------- | --------------------------- | ---------------------------------------------------- |
+| CPU per step                 | 10ms     | 30s (default), 5min (max)   | Set via `limits.cpu_ms` in wrangler.jsonc            |
+| Step state                   | 1 MiB    | 1 MiB                       | Per step return value                                |
+| Instance state               | 100 MB   | 1 GB                        | Total state per workflow instance                    |
+| Steps per workflow           | 1,024    | 1,024                       | `step.sleep()` doesn't count                         |
+| Executions per day           | 100k     | Unlimited                   | Daily execution limit                                |
+| Concurrent instances         | 25       | 10k                         | Maximum concurrent workflows; waiting state excluded |
+| Queued instances             | 100k     | 1M                          | Maximum queued workflow instances                    |
+| Subrequests per instance     | 50       | 10,000 (default), up to 10M | Maximum outbound requests per workflow instance      |
+| State retention              | 3 days   | 30 days                     | How long completed instances kept                    |
+| Step timeout default         | 10 min   | 10 min                      | Per attempt                                          |
+| waitForEvent timeout default | 24h      | 24h                         | Maximum 365 days                                     |
+| waitForEvent timeout max     | 365 days | 365 days                    | Maximum wait time                                    |
+
+**Note:** Instances in `waiting` state (from `step.sleep` or `step.waitForEvent`) don't count toward concurrent instance limit, allowing millions of sleeping workflows.
+
+## Pricing
+
+| Metric   | Free        | Paid                           | Notes                                              |
+| -------- | ----------- | ------------------------------ | -------------------------------------------------- |
+| Requests | 100k/day    | 10M/mo + $0.30/M               | Workflow invocations                               |
+| CPU time | 10ms/invoke | 30M CPU-ms/mo + $0.02/M CPU-ms | Actual CPU usage                                   |
+| Storage  | 1 GB        | 1 GB/mo + $0.20/GB-mo          | All instances (running/errored/sleeping/completed) |
+
+## References
+
+- [Official Docs](https://developers.cloudflare.com/workflows/)
+- [Get Started Guide](https://developers.cloudflare.com/workflows/get-started/guide/)
+- [Workers API](https://developers.cloudflare.com/workflows/build/workers-api/)
+- [REST API](https://developers.cloudflare.com/api/resources/workflows/)
+- [Examples](https://developers.cloudflare.com/workflows/examples/)
+- [Limits](https://developers.cloudflare.com/workflows/reference/limits/)
+- [Pricing](https://developers.cloudflare.com/workflows/reference/pricing/)
+
+See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)

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

@@ -0,0 +1,245 @@
+# Workflow Patterns
+
+## Image Processing Pipeline
+
+```typescript
+export class ImageProcessingWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    const imageData = await step.do('fetch', async () =>
+      (await this.env.BUCKET.get(event.payload.imageKey)).arrayBuffer()
+    )
+    const description = await step.do(
+      'generate description',
+      async () =>
+        await this.env.AI.run('@cf/llava-hf/llava-1.5-7b-hf', {
+          image: Array.from(new Uint8Array(imageData)),
+          prompt: 'Describe this image',
+          max_tokens: 50,
+        })
+    )
+    await step.waitForEvent('await approval', { event: 'approved', timeout: '24h' })
+    await step.do(
+      'publish',
+      async () => await this.env.BUCKET.put(`public/${event.payload.imageKey}`, imageData)
+    )
+  }
+}
+```
+
+## User Lifecycle
+
+```typescript
+export class UserLifecycleWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    await step.do('welcome email', async () => await sendEmail(event.payload.email, 'Welcome!'))
+    await step.sleep('trial period', '7 days')
+    const hasConverted = await step.do('check conversion', async () => {
+      const user = await this.env.DB.prepare('SELECT subscription_status FROM users WHERE id = ?')
+        .bind(event.payload.userId)
+        .first()
+      return user.subscription_status === 'active'
+    })
+    if (!hasConverted)
+      await step.do(
+        'trial expiration email',
+        async () => await sendEmail(event.payload.email, 'Trial ending')
+      )
+  }
+}
+```
+
+## Data Pipeline
+
+```typescript
+export class DataPipelineWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    const rawData = await step.do(
+      'extract',
+      { retries: { limit: 10, delay: '30s', backoff: 'exponential' } },
+      async () => {
+        const res = await fetch(event.payload.sourceUrl)
+        if (!res.ok) throw new Error('Fetch failed')
+        return res.json()
+      }
+    )
+    const transformed = await step.do('transform', async () =>
+      rawData.map((item) => ({ id: item.id, normalized: normalizeData(item) }))
+    )
+    const dataRef = await step.do('store', async () => {
+      const key = `processed/${Date.now()}.json`
+      await this.env.BUCKET.put(key, JSON.stringify(transformed))
+      return { key }
+    })
+    await step.do('load', async () => {
+      const data = await (await this.env.BUCKET.get(dataRef.key)).json()
+      for (let i = 0; i < data.length; i += 100) {
+        await this.env.DB.batch(
+          data
+            .slice(i, i + 100)
+            .map((item) =>
+              this.env.DB.prepare('INSERT INTO records VALUES (?, ?)').bind(
+                item.id,
+                item.normalized
+              )
+            )
+        )
+      }
+    })
+  }
+}
+```
+
+## Human-in-the-Loop Approval
+
+```typescript
+export class ApprovalWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    await step.do(
+      'create approval',
+      async () =>
+        await this.env.DB.prepare('INSERT INTO approvals (id, user_id, status) VALUES (?, ?, ?)')
+          .bind(event.instanceId, event.payload.userId, 'pending')
+          .run()
+    )
+    try {
+      const approval = await step.waitForEvent<{ approved: boolean }>('wait for approval', {
+        event: 'approval-response',
+        timeout: '48h',
+      })
+      if (approval.approved) {
+        await step.do('process approval', async () => {})
+      } else {
+        await step.do('handle rejection', async () => {})
+      }
+    } catch (e) {
+      await step.do(
+        'auto reject',
+        async () =>
+          await this.env.DB.prepare('UPDATE approvals SET status = ? WHERE id = ?')
+            .bind('auto-rejected', event.instanceId)
+            .run()
+      )
+    }
+  }
+}
+```
+
+## Testing Workflows
+
+### Setup
+
+```typescript
+// vitest.config.ts
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: {
+      workers: {
+        wrangler: { configPath: './wrangler.jsonc' },
+      },
+    },
+  },
+})
+```
+
+### Introspection API
+
+```typescript
+import { introspectWorkflowInstance } from 'cloudflare:test'
+
+const instance = await env.MY_WORKFLOW.create({ params: { userId: '123' } })
+const introspector = await introspectWorkflowInstance(env.MY_WORKFLOW, instance.id)
+
+// Wait for step completion
+const result = await introspector.waitForStepResult({ name: 'fetch user', index: 0 })
+
+// Mock step behavior
+await introspector.modify(async (m) => {
+  await m.mockStepResult({ name: 'api call' }, { mocked: true })
+})
+```
+
+## Best Practices
+
+### ✅ DO
+
+1. **Granular steps**: One API call per step (unless proving idempotency)
+2. **Idempotency**: Check-then-execute; use idempotency keys
+3. **Deterministic names**: Use static or step-output-based names
+4. **Return state**: Persist via step returns, not variables
+5. **Always await**: `await step.do()`, avoid dangling promises
+6. **Deterministic conditionals**: Base on `event.payload` or step outputs
+7. **Store large data externally**: R2/KV for >1 MiB, return refs
+8. **Batch creation**: `createBatch()` for multiple instances
+
+### ❌ DON'T
+
+1. **One giant step**: Breaks durability & retry control
+2. **State outside steps**: Lost on hibernation
+3. **Mutate events**: Events immutable, return new state
+4. **Non-deterministic logic outside steps**: `Math.random()`, `Date.now()` must be in steps
+5. **Side effects outside steps**: May duplicate on restart
+6. **Non-deterministic step names**: Prevents caching
+7. **Ignore timeouts**: `waitForEvent` throws, use try-catch
+8. **Reuse instance IDs**: Must be unique within retention
+
+## Orchestration Patterns
+
+### Fan-Out (Parallel Processing)
+
+```typescript
+const files = await step.do('list', async () => this.env.BUCKET.list())
+await Promise.all(
+  files.objects.map((file, i) =>
+    step.do(`process ${i}`, async () =>
+      processFile(await (await this.env.BUCKET.get(file.key)).arrayBuffer())
+    )
+  )
+)
+```
+
+### Parent-Child Workflows
+
+```typescript
+const child = await step.do(
+  'start child',
+  async () =>
+    await this.env.CHILD_WORKFLOW.create({
+      id: `child-${event.instanceId}`,
+      params: { data: result.data },
+    })
+)
+await step.do('other work', async () => console.log(`Child started: ${child.id}`))
+```
+
+### Race Pattern
+
+```typescript
+const winner = await Promise.race([
+  step.do('option A', async () => slowOperation()),
+  step.do('option B', async () => fastOperation()),
+])
+```
+
+### Scheduled Workflow Chain
+
+```typescript
+export default {
+  async scheduled(event, env) {
+    await env.DAILY_WORKFLOW.create({
+      id: `daily-${event.scheduledTime}`,
+      params: { timestamp: event.scheduledTime },
+    })
+  },
+}
+export class DailyWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    await step.do('daily task', async () => {})
+    await step.sleep('wait 7 days', '7 days')
+    await step.do('weekly followup', async () => {})
+  }
+}
+```
+
+See: [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)

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

@@ -0,0 +1,143 @@
+# Cloudflare Wrangler
+
+Official CLI for Cloudflare Workers - develop, manage, and deploy Workers from the command line.
+
+## What is Wrangler?
+
+Wrangler is the Cloudflare Developer Platform CLI that allows you to:
+
+- Create, develop, and deploy Workers
+- Manage bindings (KV, D1, R2, Durable Objects, etc.)
+- Configure routing and environments
+- Run local development servers
+- Execute migrations and manage resources
+- Perform integration testing
+
+## Installation
+
+```bash
+npm install wrangler --save-dev
+# or globally
+npm install -g wrangler
+```
+
+Run commands: `npx wrangler <command>` (or `pnpm`/`yarn wrangler`)
+
+## Reading Order
+
+| If you want to...                 | Start here                                                          |
+| --------------------------------- | ------------------------------------------------------------------- |
+| Create/deploy Worker quickly      | Essential Commands below → [patterns.md](./patterns.md) §New Worker |
+| Configure bindings (KV, D1, R2)   | [configuration.md](./configuration.md) §Bindings                    |
+| Write integration tests           | [api.md](./api.md) §startWorker                                     |
+| Debug production issues           | [gotchas.md](./gotchas.md) + Essential Commands §Monitoring         |
+| Set up multi-environment workflow | [configuration.md](./configuration.md) §Environments                |
+
+## Essential Commands
+
+### Project & Development
+
+```bash
+wrangler init [name]              # Create new project
+wrangler dev                      # Local dev server (fast, simulated)
+wrangler dev --remote             # Dev with remote resources (production-like)
+wrangler deploy                   # Deploy to production
+wrangler deploy --env staging     # Deploy to environment
+wrangler versions list            # List versions
+wrangler rollback [id]            # Rollback deployment
+wrangler login                    # OAuth login
+wrangler whoami                   # Check auth status
+```
+
+## Resource Management
+
+### KV
+
+```bash
+wrangler kv namespace create NAME
+wrangler kv key put "key" "value" --namespace-id=<id>
+wrangler kv key get "key" --namespace-id=<id>
+```
+
+### D1
+
+```bash
+wrangler d1 create NAME
+wrangler d1 execute NAME --command "SQL"
+wrangler d1 migrations create NAME "description"
+wrangler d1 migrations apply NAME
+```
+
+### R2
+
+```bash
+wrangler r2 bucket create NAME
+wrangler r2 object put BUCKET/key --file path
+wrangler r2 object get BUCKET/key
+```
+
+### Other Resources
+
+```bash
+wrangler queues create NAME
+wrangler vectorize create NAME --dimensions N --metric cosine
+wrangler hyperdrive create NAME --connection-string "..."
+wrangler workflows create NAME
+wrangler constellation create NAME
+wrangler pages project create NAME
+wrangler pages deployment create --project NAME --branch main
+```
+
+### Secrets
+
+```bash
+wrangler secret put NAME          # Set Worker secret
+wrangler secret list              # List Worker secrets
+wrangler secret delete NAME       # Delete Worker secret
+wrangler secret bulk FILE.json    # Bulk upload from JSON
+
+# Secrets Store (centralized, reusable across Workers)
+wrangler secret-store:secret put STORE_NAME SECRET_NAME
+wrangler secret-store:secret list STORE_NAME
+```
+
+### Monitoring
+
+```bash
+wrangler tail                     # Real-time logs
+wrangler tail --env production    # Tail specific env
+wrangler tail --status error      # Filter by status
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, environments, bindings
+- [api.md](./api.md) - Programmatic API (`startWorker`, `getPlatformProxy`, events)
+- [patterns.md](./patterns.md) - Common workflows and development patterns
+- [gotchas.md](./gotchas.md) - Common pitfalls, limits, and troubleshooting
+
+## Quick Decision Tree
+
+```
+Need to test your Worker?
+├─ Testing full Worker with bindings → api.md §startWorker
+├─ Testing individual functions → api.md §getPlatformProxy
+└─ Testing with Vitest → patterns.md §Testing with Vitest
+
+Need to configure something?
+├─ Bindings (KV, D1, R2, etc.) → configuration.md §Bindings
+├─ Multiple environments → configuration.md §Environments
+├─ Static files → configuration.md §Workers Assets
+└─ Routing → configuration.md §Routing
+
+Development not working?
+├─ Local differs from production → Use `wrangler dev --remote`
+├─ Bindings not available → gotchas.md §Binding Not Available
+└─ Auth issues → wrangler login
+```
+
+## See Also
+
+- [workers](../workers/) - Workers runtime API reference
+- [miniflare](../miniflare/) - Local testing with Miniflare
+- [workerd](../workerd/) - Runtime that powers `wrangler dev`