@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/cloudflare/references/workflows/api.md

@@ -0,0 +1,125 @@
+# Workflow APIs
+
+## Step APIs
+
+```typescript
+// step.do()
+const result = await step.do('step name', async () => { /* logic */ });
+const result = await step.do('step name', { retries, timeout }, async () => {});
+
+// step.sleep()
+await step.sleep('description', '1 hour');
+await step.sleep('description', 5000); // ms
+
+// step.sleepUntil()
+await step.sleepUntil('description', Date.parse('2024-12-31'));
+
+// step.waitForEvent()
+const data = await step.waitForEvent<PayloadType>('wait', {type: 'webhook-type', timeout: '24h'}); // Default 24h, max 365d
+try { const event = await step.waitForEvent('wait', { type: 'approval', timeout: '1h' }); } catch (e) { /* Timeout */ }
+```
+
+## Instance Management
+
+```typescript
+// Create single
+const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); // id optional, auto-generated if omitted
+
+// Batch (max 100, idempotent: skips existing IDs)
+const instances = await env.MY_WORKFLOW.createBatch([{id: 'user1', params: {name: 'John'}}, {id: 'user2', params: {name: 'Jane'}}]);
+
+// Get & Status
+const instance = await env.MY_WORKFLOW.get('instance-id');
+const status = await instance.status(); // {status: 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting' | 'waitingForPause' | 'unknown', error?, output?}
+
+// Control
+await instance.pause(); await instance.resume(); await instance.terminate(); await instance.restart();
+
+// Send Events
+await instance.sendEvent({type: 'approval', payload: { approved: true }}); // Must match waitForEvent type
+```
+
+## Triggering Workflows
+
+```typescript
+// From Worker
+export default { async fetch(req, env) { const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); return Response.json({ id: instance.id }); }};
+
+// From Queue
+export default { async queue(batch, env) { for (const msg of batch.messages) { await env.MY_WORKFLOW.create({id: `job-${msg.id}`, params: msg.body}); } }};
+
+// From Cron
+export default { async scheduled(event, env) { await env.CLEANUP_WORKFLOW.create({id: `cleanup-${Date.now()}`, params: { timestamp: event.scheduledTime }}); }};
+
+// From Another Workflow (non-blocking)
+export class ParentWorkflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event, step) {
+    const child = await step.do('start child', async () => await this.env.CHILD_WORKFLOW.create({id: `child-${event.instanceId}`, params: {}}));
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import { NonRetryableError } from 'cloudflare:workflows';
+
+// NonRetryableError
+await step.do('validate', async () => {
+  if (!event.payload.paymentMethod) throw new NonRetryableError('Payment method required');
+  const res = await fetch('https://api.example.com/charge', { method: 'POST' });
+  if (res.status === 401) throw new NonRetryableError('Invalid credentials'); // Don't retry
+  if (!res.ok) throw new Error('Retryable failure'); // Will retry
+  return res.json();
+});
+
+// Catching Errors
+try { await step.do('risky op', async () => { throw new NonRetryableError('Failed'); }); } catch (e) { await step.do('cleanup', async () => {}); }
+
+// Idempotency
+await step.do('charge', async () => {
+  const sub = await fetch(`https://api/subscriptions/${id}`).then(r => r.json());
+  if (sub.charged) return sub; // Already done
+  return await fetch(`https://api/subscriptions/${id}`, {method: 'POST', body: JSON.stringify({ amount: 10.0 })}).then(r => r.json());
+});
+```
+
+## Wrangler CLI
+
+```bash
+npm create cloudflare@latest my-workflow -- --template "cloudflare/workflows-starter"
+npx wrangler deploy
+npx wrangler workflows list
+npx wrangler workflows trigger my-workflow '{"userId":"user123"}'
+npx wrangler workflows instances list my-workflow
+npx wrangler workflows instances describe my-workflow instance-id
+npx wrangler workflows instances pause/resume/terminate my-workflow instance-id
+```
+
+## REST API
+
+```bash
+# Create
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances" -H "Authorization: Bearer {token}" -d '{"id":"custom-id","params":{"userId":"user123"}}'
+
+# Status
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status" -H "Authorization: Bearer {token}"
+
+# Send Event
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events" -H "Authorization: Bearer {token}" -d '{"type":"approval","payload":{"approved":true}}'
+```
+
+## Bindings
+
+```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' });
+});
+```
+
+See: [configuration.md](./configuration.md), [patterns.md](./patterns.md)

package/dist/template/.opencode/skill/cloudflare/references/workflows/configuration.md

@@ -0,0 +1,177 @@
+# Workflow Configuration
+
+## Wrangler Setup
+
+**wrangler.toml:**
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-10-22"
+
+[[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 = 300_000  # 5 min max (default 30s)
+```
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "name": "my-worker",
+  "workflows": [
+    { "name": "my-workflow", "binding": "MY_WORKFLOW", "class_name": "MyWorkflow" }
+  ],
+  "limits": { "cpu_ms": 300000 }
+}
+```
+
+## Step Configuration
+
+### Basic Step
+```typescript
+const data = await step.do('step name', async () => {
+  return { result: 'value' };
+});
+```
+
+### Retry Config
+```typescript
+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());
+  });
+}
+```
+
+## Sleep & Scheduling
+
+```typescript
+// Relative
+await step.sleep('wait 1 hour', '1 hour');
+await step.sleep('wait 30 days', '30 days');
+await step.sleep('wait 5s', 5000); // ms
+
+// Absolute
+await step.sleepUntil('launch date', Date.parse('24 Oct 2024 13:00:00 UTC'));
+await step.sleepUntil('deadline', new Date('2024-12-31T23:59:59Z'));
+```
+
+Units: second, minute, hour, day, week, month, year. Max: 365 days.
+Sleeping instances don't count toward concurrency.
+
+## Parameters
+
+**Pass from Worker:**
+```typescript
+const instance = await env.MY_WORKFLOW.create({
+  id: crypto.randomUUID(),
+  params: { userId: 'user123', email: 'user@example.com' }
+});
+```
+
+**Access in Workflow:**
+```typescript
+async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+  const userId = event.payload.userId;
+  const instanceId = event.instanceId;
+  const createdAt = event.timestamp;
+}
+```
+
+**CLI Trigger:**
+```bash
+npx wrangler workflows trigger my-workflow '{"userId":"user123"}'
+```
+
+## Multiple Workflows
+
+```typescript
+export class UserOnboarding extends WorkflowEntrypoint<Env, UserParams> {
+  async run(event, step) { /* ... */ }
+}
+
+export class DataProcessing extends WorkflowEntrypoint<Env, DataParams> {
+  async run(event, step) { /* ... */ }
+}
+```
+
+```toml
+[[workflows]]
+name = "user-onboarding"
+binding = "USER_ONBOARDING"
+class_name = "UserOnboarding"
+
+[[workflows]]
+name = "data-processing"
+binding = "DATA_PROCESSING"
+class_name = "DataProcessing"
+```
+
+## Cross-Script Bindings
+
+**billing-worker** defines workflow:
+```toml
+[[workflows]]
+name = "billing-workflow"
+binding = "BILLING"
+class_name = "BillingWorkflow"
+```
+
+**web-api-worker** calls it:
+```toml
+[[workflows]]
+name = "billing-workflow"
+binding = "BILLING"
+class_name = "BillingWorkflow"
+script_name = "billing-worker"
+```
+
+See: [api.md](./api.md), [patterns.md](./patterns.md)

package/dist/template/.opencode/skill/cloudflare/references/workflows/gotchas.md

@@ -0,0 +1,136 @@
+# Gotchas & Debugging
+
+## Timeout Issues
+
+### Step Timeout
+- **Default**: 10 min/attempt
+- **CPU Limit**: 30s default, max 5min (wrangler.toml `limits.cpu_ms = 300_000`)
+
+```typescript
+await step.do('long operation', {timeout: '30 minutes'}, async () => { /* ... */ });
+```
+
+### waitForEvent Timeout
+- **Default**: 24h, **Max**: 365d, **Throws on timeout**
+
+```typescript
+try {
+  const event = await step.waitForEvent('wait', { type: 'approval', timeout: '1h' });
+} catch (e) { /* Timeout - proceed with default */ }
+```
+
+## Limits
+
+| Limit | Free | Paid |
+|-------|------|------|
+| CPU per step | 10ms | 30s (default), 5min (max) |
+| Step state | 1 MiB | 1 MiB |
+| Instance state | 100 MB | 1 GB |
+| Steps per workflow | 1,024 | 1,024 |
+| Executions/day | 100k | Unlimited |
+| Concurrent instances | 25 | 10k |
+| State retention | 3d | 30d |
+
+Note: `step.sleep()` doesn't count toward step limit
+
+## Debugging
+
+### Logs
+```typescript
+await step.do('process', async () => {
+  console.log('Logged once per successful step'); // ✅
+  return result;
+});
+console.log('Outside step'); // ⚠️ May duplicate on restart
+```
+
+### Instance Status
+```bash
+npx wrangler workflows instances describe my-workflow instance-id
+```
+
+```typescript
+const instance = await env.MY_WORKFLOW.get('instance-id');
+const status = await instance.status();
+// status: queued | running | paused | errored | terminated | complete | waiting | waitingForPause | unknown
+```
+
+## Common Pitfalls
+
+### Non-Deterministic Step Names
+```typescript
+// ❌ BAD: await step.do(`step-${Date.now()}`, ...)
+// ✅ GOOD: await step.do(`step-${event.instanceId}`, ...)
+```
+
+### State in Variables
+```typescript
+// ❌ BAD: let total = 0; await step.do('step 1', async () => { total += 10; }); // Lost on hibernation
+// ✅ GOOD: const total = await step.do('step 1', async () => 10); // Persisted
+```
+
+### Non-Deterministic Conditionals
+```typescript
+// ❌ BAD: if (Date.now() > deadline) { await step.do(...) }
+// ✅ GOOD: const isLate = await step.do('check', async () => Date.now() > deadline); if (isLate) { await step.do(...) }
+```
+
+### Large Step Returns
+```typescript
+// ❌ BAD: return await fetchHugeDataset(); // 5 MiB
+// ✅ GOOD: Store in R2, return { key }
+```
+
+### Idempotency Ignored
+```typescript
+// ❌ BAD: await step.do('charge', async () => await chargeCustomer(...)); // Charges on retry
+// ✅ GOOD: Check if already charged first
+```
+
+### Instance ID Collision
+```typescript
+// ❌ BAD: await env.MY_WORKFLOW.create({ id: userId, params: {} }); // Reuses IDs
+// ✅ GOOD: await env.MY_WORKFLOW.create({ id: `${userId}-${Date.now()}`, params: {} });
+```
+
+### Missing await
+```typescript
+// ❌ BAD: step.do('task', ...); // Fire-and-forget
+// ✅ GOOD: await step.do('task', ...);
+```
+
+## Pricing
+
+| Metric | Free | Paid |
+|--------|------|------|
+| Requests | 100k/day | 10M/mo + $0.30/M |
+| CPU time | 10ms/invoke | 30M CPU-ms/mo + $0.02/M CPU-ms |
+| Storage | 1 GB | 1 GB/mo + $0.20/GB-mo |
+
+Storage: Includes all instances (running/errored/sleeping/completed). Retention: 3d (Free), 30d (Paid)
+
+## TypeScript Types
+
+```typescript
+import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent, NonRetryableError } from 'cloudflare:workers';
+
+interface Env { MY_WORKFLOW: Workflow<MyParams>; KV: KVNamespace; DB: D1Database; }
+
+export class MyWorkflow extends WorkflowEntrypoint<Env, MyParams> {
+  async run(event: WorkflowEvent<MyParams>, step: WorkflowStep) {
+    const user = await step.do('fetch', async () => await this.env.KV.get<User>(`user:${event.payload.userId}`, { type: 'json' }));
+  }
+}
+```
+
+## 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/dist/template/.opencode/skill/cloudflare/references/workflows/patterns.md

@@ -0,0 +1,132 @@
+# 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', { type: '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' }, timeout: '5 minutes'}, 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', {retries: { limit: 5, delay: '1m', backoff: 'linear' }}, 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', { type: '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());
+    }
+  }
+}
+```
+
+## 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}`));
+```
+
+### Promise.race
+```typescript
+const result = await step.do('race', async () => await Promise.race([step.do('option A', async () => { await sleep(1000); return 'A'; }), step.do('option B', async () => 'B')]));
+```
+
+### 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/dist/template/.opencode/skill/cloudflare/references/wrangler/README.md

@@ -0,0 +1,90 @@
+# 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`)
+
+## Essential Commands
+
+### Project & Development
+```bash
+wrangler init [name]              # Create new project
+wrangler dev                      # Local dev server
+wrangler dev --remote             # Dev with remote resources
+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 "..."
+```
+
+### Secrets
+```bash
+wrangler secret put NAME          # Set secret
+wrangler secret list              # List secrets
+wrangler secret delete NAME       # Delete secret
+```
+
+### 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 (`unstable_startWorker`, `getPlatformProxy`)
+- [patterns.md](./patterns.md) - Common workflows and development patterns
+- [gotchas.md](./gotchas.md) - Common pitfalls, limits, and troubleshooting