@mohanscodex/spectra-code 0.4.9 → 0.5.0

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

@@ -0,0 +1,151 @@
+# 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-deploy/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 step | 50 | 1,000 | Maximum outbound requests per step |
+| 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-deploy/references/workflows/patterns.md

@@ -0,0 +1,175 @@
+# 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.params.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.params.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.params.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.params.userId).first();
+      return user.subscription_status === 'active';
+    });
+    if (!hasConverted) await step.do('trial expiration email', async () => await sendEmail(event.params.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.params.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.params.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-deploy/references/wrangler/README.md

@@ -0,0 +1,141 @@
+# 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
+
+- [auth.md](./auth.md) - Authentication setup (`wrangler login`, API tokens)
+- [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 → auth.md
+
+Authentication issues?
+├─ "Not logged in" / "Unauthorized" → auth.md
+├─ First time deploying → `wrangler login` (one-time OAuth)
+└─ CI/CD setup → auth.md §API Token
+```
+
+## See Also
+
+- [workers](../workers/) - Workers runtime API reference
+- [miniflare](../miniflare/) - Local testing with Miniflare
+- [workerd](../workerd/) - Runtime that powers `wrangler dev`