opencastle 0.33.9 → 0.34.0

package/src/orchestrator/customizations/agents/skill-matrix.md

@@ -77,6 +77,11 @@ When resolving, load **all** skills listed in the slot's entries.
 | `e2e-testing` | Browser automation | UI/UX Expert, Testing Expert |
 | `task-management` | Issue tracking, workflow states | Team Lead |
 | `knowledge-management` | Knowledge base, research, ADRs, specs | Team Lead, Researcher, Documentation Writer, Architect |
+| `design` | Design tokens, component inspection, asset export | UI/UX Expert |
+| `email` | Transactional email, templates, delivery | Developer |
+| `payments` | Payment processing, subscriptions, webhooks | Developer |
+| `observability` | Error tracking, performance monitoring, tracing | DevOps Expert, Performance Expert |
+| `notifications` | Team messaging, alerts, bot integrations | Developer |
 
 ### Example: Add a second plugin
 

package/src/orchestrator/plugins/cloudflare/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: cloudflare-platform
+description: "Creates and deploys Cloudflare Workers, configures wrangler.toml bindings, sets up KV/D1/R2 storage and Durable Objects, manages Pages deployments, and implements edge function patterns. Use when building or deploying Cloudflare Workers, setting up Pages, working with KV/D1/R2 storage, configuring wrangler.toml, or deploying edge applications."
+---
+
+# Cloudflare Platform
+
+## Topic Routing
+
+Read the matching reference before writing code for any of these topics:
+
+| Topic | Reference |
+|-------|-----------|
+| Workers & edge functions | `references/workers.md` |
+| Storage (KV, D1, R2) | `references/storage.md` |
+| Pages & deployment | `references/deployment.md` |
+
+## Critical Rules
+
+**Workers**
+- Use Web standard Fetch API, not Node.js globals (`process`, `Buffer`, `fs`) — Workers run in V8 isolates
+- Define all bindings (KV, D1, R2, secrets) in `wrangler.toml` and access them via the `env` parameter
+- Workers have 0ms cold starts — keep dependencies minimal; free tier has a 1MB bundle limit
+- Use `ctx.waitUntil(promise)` for non-blocking side effects (logging, analytics) that outlast the response
+
+**Storage Selection**
+- **KV** — key-value store for config, sessions, cache (eventually consistent reads)
+- **D1** — SQLite at the edge for relational SQL; strongly consistent
+- **R2** — object/file storage (S3-compatible); no egress costs
+- **Durable Objects** — stateful coordination; use for real-time collaboration, rate limiters, and counters
+- **Queues** — async message processing; use for background tasks
+
+**D1**
+- Use `env.DB.prepare(sql).bind(...params).run()` for all DML; always use parameterized queries
+- Use `env.DB.batch([...stmts])` for multiple queries in a single round trip
+- D1 is SQLite — avoid MySQL/Postgres-only SQL syntax
+
+**MCP Code Mode**
+- The Cloudflare MCP uses Code Mode: only 2 tools are available — `search` and `execute`
+- `search` searches the Cloudflare API spec; `execute` runs JavaScript against the Cloudflare API
+- This approach uses ~1k tokens per operation vs ~244k for native tool exposure
+
+**Wrangler**
+- Use `wrangler.toml` (or `wrangler.jsonc`) for all config — `npx wrangler dev` for local dev
+- `npx wrangler deploy` for production; `wrangler tail` for live log streaming
+- Store secrets with `wrangler secret put VAR_NAME` — never hardcode in `wrangler.toml`
+
+**Security**
+- Access secrets via `env.VAR_NAME` — never hardcode credentials in Worker code
+- Use Cloudflare Turnstile for CAPTCHA; configure WAF rules for API protection
+- Validate all inputs at the Worker boundary — Workers are publicly accessible
+
+## Basic Worker with KV
+
+```typescript
+// src/index.ts
+export interface Env {
+  SESSIONS: KVNamespace; // bound in wrangler.toml
+  API_SECRET: string;    // secret bound in wrangler.toml
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/session') {
+      const sessionId = request.headers.get('x-session-id');
+      if (!sessionId) return new Response('Missing session', { status: 400 });
+
+      const data = await env.SESSIONS.get(sessionId, { type: 'json' });
+      if (!data) return new Response('Not found', { status: 404 });
+
+      // Non-blocking analytics — does not delay the response
+      ctx.waitUntil(logAnalytics(sessionId));
+
+      return Response.json(data);
+    }
+
+    return new Response('Not found', { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+## Storage Decision Guide
+
+```
+I need to store data → What type?
+├── Key-value pairs (cache, sessions, feature flags) → KV
+├── Relational/SQL data → D1
+├── Files, images, blobs → R2
+├── Stateful coordination (counters, locks, chat) → Durable Objects
+└── Async job queue → Queues
+```
+
+## Reference Files
+
+- `references/workers.md` — Worker structure, bindings, env, waitUntil, Durable Objects, Cron Triggers, Wrangler commands
+- `references/storage.md` — KV, D1, R2 APIs; decision guide for choosing between storage types
+- `references/deployment.md` — Pages setup, wrangler.toml, secrets, custom domains, CI/CD integration
+
+## Quick Workflow: Deploy a Cloudflare Worker
+1. Create project: `npm create cloudflare@latest` and select "Hello World" Worker template
+2. Define bindings (KV, D1, secrets) in `wrangler.toml` under `[[kv_namespaces]]` / `[[d1_databases]]`
+3. Verify resources exist: `npx wrangler kv:namespace list` / `npx wrangler d1 list` — create any missing resources before continuing
+   - **If resource missing:** `npx wrangler kv:namespace create <NAME>` or `npx wrangler d1 create <DB>` → copy the ID into `wrangler.toml`
+4. Implement the `fetch` handler in `src/index.ts` — type the `Env` interface to match your bindings
+5. Test locally: `npx wrangler dev` — verify the worker responds correctly at `http://localhost:8787`
+   - **If dev fails:** check `wrangler.toml` syntax → verify binding IDs match → run `npx wrangler whoami` to confirm account auth
+6. Deploy: `npx wrangler deploy` — confirm the deployment URL is returned
+   - **If deploy fails:** check `wrangler.toml` bindings match created resources → verify `compatibility_date` is set → check account permissions
+7. Monitor with `wrangler tail` for live logs from production

package/src/orchestrator/plugins/cloudflare/config.ts

@@ -0,0 +1,24 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'cloudflare',
+  name: 'Cloudflare',
+  category: 'tech',
+  subCategory: 'deployment',
+  label: 'Cloudflare',
+  hint: 'Workers, Pages, KV, D1, R2, and edge computing',
+  skillName: 'cloudflare-platform',
+  mcpServerKey: 'Cloudflare',
+  mcpConfig: {
+    type: 'http',
+    url: 'https://mcp.cloudflare.com/mcp',
+  },
+  authType: 'oauth',
+  envVars: [],
+  agentToolMap: {
+    'developer': ['search', 'execute'],
+    'devops-expert': ['search', 'execute'],
+  },
+  docsUrl: null,
+  officialDocs: 'https://developers.cloudflare.com/',
+};

package/src/orchestrator/plugins/cloudflare/references/deployment.md

@@ -0,0 +1,147 @@
+# Cloudflare Deployment
+
+## wrangler.toml Reference
+
+```toml
+name = "my-app"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+compatibility_flags = ["nodejs_compat"]  # enable Node.js compat layer
+
+# Environment variables (non-secret)
+[vars]
+ENVIRONMENT = "production"
+API_BASE_URL = "https://api.example.com"
+
+# Secrets — set via CLI, NOT stored here:
+# wrangler secret put DB_PASSWORD
+
+# KV binding
+[[kv_namespaces]]
+binding = "CACHE"
+id = "abc123def456"
+preview_id = "preview_abc123"  # for `wrangler dev --remote`
+
+# D1 binding
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "xyz789"
+
+# R2 binding
+[[r2_buckets]]
+binding = "ASSETS"
+bucket_name = "my-assets"
+
+# Service binding (call another Worker)
+[[services]]
+binding = "AUTH_WORKER"
+service = "auth-service"
+
+# Cron Triggers
+[triggers]
+crons = ["0 0 * * *"]  # midnight UTC daily
+
+# Per-environment overrides
+[env.staging]
+name = "my-app-staging"
+vars = { ENVIRONMENT = "staging" }
+```
+
+## Pages Setup
+
+```bash
+# Create a new Pages project
+npm create cloudflare@latest my-app -- --framework=nextjs
+
+# Deploy from CLI
+npx wrangler pages deploy ./dist --project-name=my-app
+
+# Deploy a specific branch (creates preview)
+npx wrangler pages deploy ./dist --project-name=my-app --branch=feature-xyz
+```
+
+### Pages Functions
+
+```typescript
+// functions/api/hello.ts — file-based routing in /functions
+interface Env {
+  MY_KV: KVNamespace;
+}
+
+export const onRequest: PagesFunction<Env> = async (context) => {
+  const data = await context.env.MY_KV.get('greeting');
+  return Response.json({ message: data ?? 'Hello!' });
+};
+```
+
+## Environment Variables & Secrets
+
+```bash
+# List current secrets
+wrangler secret list
+
+# Add a secret (prompts for value)
+wrangler secret put DATABASE_URL
+
+# Add a secret for a specific environment
+wrangler secret put DATABASE_URL --env staging
+
+# Bulk secrets from .dev.vars (local dev only — never commit this file)
+# .dev.vars format: KEY=value (one per line)
+```
+
+## Custom Domains
+
+```bash
+# Add a custom domain via dashboard or CLI
+wrangler domains add my-worker.example.com
+
+# For Pages: configure in the Cloudflare Dashboard under
+# Pages → Project → Custom Domains
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+Generate an API token at Cloudflare Dashboard → My Profile → API Tokens → Create Token (use the "Edit Cloudflare Workers" template).
+
+## Preview Deployments
+
+```bash
+# Create a preview deployment (does not affect production)
+npx wrangler deploy --env staging
+
+# View deployment history
+npx wrangler deployments list
+```
+
+## Rollback
+
+```bash
+# List recent deployments with version IDs
+npx wrangler deployments list
+
+# Roll back to a previous deployment
+npx wrangler rollback <version-id>
+```

package/src/orchestrator/plugins/cloudflare/references/storage.md

@@ -0,0 +1,118 @@
+# Cloudflare Storage
+
+## Storage Decision Guide
+
+| Need | Use |
+|------|-----|
+| Config, feature flags, sessions, cache | KV (eventually consistent) |
+| Relational SQL data, strong consistency | D1 (SQLite) |
+| Files, images, large blobs | R2 (S3-compatible) |
+| Stateful coordination, locks, real-time sync | Durable Objects |
+| Background job queues | Queues |
+
+---
+
+## KV (Key-Value)
+
+```typescript
+// Read
+const value = await env.MY_KV.get('key');
+const json = await env.MY_KV.get<MyType>('key', { type: 'json' });
+const buffer = await env.MY_KV.get('key', { type: 'arrayBuffer' });
+
+// Write
+await env.MY_KV.put('key', 'value');
+await env.MY_KV.put('key', JSON.stringify(data));
+await env.MY_KV.put('key', 'value', {
+  expirationTtl: 3600,          // expire in 1 hour
+  metadata: { userId: '123' },  // up to 1024 bytes of metadata
+});
+
+// Delete
+await env.MY_KV.delete('key');
+
+// List keys
+const { keys, list_complete, cursor } = await env.MY_KV.list({ prefix: 'user:' });
+for (const key of keys) {
+  console.log(key.name, key.metadata);
+}
+```
+
+**KV limits:** Reads are eventually consistent (up to 60s lag). Max value size: 25MB. Max key size: 512 bytes.
+
+---
+
+## D1 (SQLite at Edge)
+
+```typescript
+// Single query
+const stmt = env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId);
+const { results } = await stmt.all<User>();
+const user = await stmt.first<User>();
+
+// Insert / update
+const result = await env.DB
+  .prepare('INSERT INTO posts (id, title, author_id) VALUES (?, ?, ?)')
+  .bind(id, title, authorId)
+  .run();
+console.log(result.meta.changes); // rows affected
+
+// Batch (multiple queries in one round trip)
+const results = await env.DB.batch([
+  env.DB.prepare('INSERT INTO logs (event) VALUES (?)').bind('login'),
+  env.DB.prepare('UPDATE users SET last_seen = ? WHERE id = ?').bind(now, userId),
+]);
+
+// Dump (returns all results)
+const { results: allUsers } = await env.DB.prepare('SELECT * FROM users').all<User>();
+```
+
+**Always use parameterized queries** — never interpolate user input into SQL strings.
+
+### D1 Migrations
+
+```bash
+# Create migration file
+wrangler d1 migrations create my-db add-users-table
+
+# Apply migrations (local)
+wrangler d1 migrations apply my-db --local
+
+# Apply migrations (remote/production)
+wrangler d1 migrations apply my-db --remote
+```
+
+---
+
+## R2 (Object Storage)
+
+```typescript
+// Upload
+await env.MY_BUCKET.put('images/photo.jpg', imageBuffer, {
+  httpMetadata: { contentType: 'image/jpeg' },
+  customMetadata: { uploadedBy: userId },
+});
+
+// Download
+const object = await env.MY_BUCKET.get('images/photo.jpg');
+if (!object) return new Response('Not found', { status: 404 });
+
+// Stream the body directly to the response
+return new Response(object.body, {
+  headers: { 'Content-Type': object.httpMetadata?.contentType ?? 'application/octet-stream' },
+});
+
+// Delete
+await env.MY_BUCKET.delete('images/photo.jpg');
+
+// List
+const { objects, truncated, cursor } = await env.MY_BUCKET.list({ prefix: 'images/' });
+
+// Multipart upload (large files >100MB)
+const upload = await env.MY_BUCKET.createMultipartUpload('large-file.zip');
+const part1 = await upload.uploadPart(1, chunk1);
+const part2 = await upload.uploadPart(2, chunk2);
+await upload.complete([part1, part2]);
+```
+
+**R2 is S3-compatible** — existing S3 SDKs work with R2 by pointing to the R2 endpoint URL.

package/src/orchestrator/plugins/cloudflare/references/workers.md

@@ -0,0 +1,135 @@
+# Cloudflare Workers
+
+## Worker Structure
+
+```typescript
+// src/index.ts
+export interface Env {
+  // Declare all bindings here — must match wrangler.toml
+  MY_KV: KVNamespace;
+  MY_DB: D1Database;
+  MY_BUCKET: R2Bucket;
+  MY_SECRET: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Handle HTTP requests
+    return new Response('Hello World');
+  },
+
+  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
+    // Handle Cron Triggers
+    ctx.waitUntil(doScheduledWork(env));
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+## Bindings in wrangler.toml
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "abc123"
+
+[[d1_databases]]
+binding = "MY_DB"
+database_name = "my-db"
+database_id = "xyz789"
+
+[[r2_buckets]]
+binding = "MY_BUCKET"
+bucket_name = "my-bucket"
+
+[vars]
+ENVIRONMENT = "production"
+
+# Secrets are NOT stored in wrangler.toml — use: wrangler secret put SECRET_NAME
+```
+
+## ctx.waitUntil
+
+Use `ctx.waitUntil()` for async work that must not block the response:
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const response = await handleRequest(request, env);
+
+    // Logs, analytics, cache warming — run after response is sent
+    ctx.waitUntil(logToAnalytics(request, response, env));
+
+    return response;
+  },
+};
+```
+
+## Routing
+
+```typescript
+import { Router } from 'itty-router'; // popular lightweight router
+
+const router = Router();
+
+router
+  .get('/api/users', (request, env) => handleGetUsers(env))
+  .post('/api/users', (request, env) => handleCreateUser(request, env))
+  .all('*', () => new Response('Not found', { status: 404 }));
+
+export default { fetch: router.fetch } satisfies ExportedHandler<Env>;
+```
+
+## Durable Objects (basics)
+
+```typescript
+// src/counter.ts
+export class Counter implements DurableObject {
+  state: DurableObjectState;
+
+  constructor(state: DurableObjectState, env: Env) {
+    this.state = state;
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const count = (await this.state.storage.get<number>('count')) ?? 0;
+    const newCount = count + 1;
+    await this.state.storage.put('count', newCount);
+    return Response.json({ count: newCount });
+  }
+}
+```
+
+```toml
+# wrangler.toml
+[[durable_objects.bindings]]
+name = "COUNTER"
+class_name = "Counter"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["Counter"]
+```
+
+## Cron Triggers
+
+```toml
+# wrangler.toml
+[triggers]
+crons = ["0 * * * *"]  # every hour
+```
+
+## Wrangler Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npx wrangler dev` | Local development server (hot reload) |
+| `npx wrangler deploy` | Deploy to production |
+| `npx wrangler tail` | Live log streaming from production |
+| `wrangler secret put NAME` | Store a secret securely |
+| `wrangler kv:key put --binding=KV key value` | Write a KV value |
+| `wrangler d1 execute DB --command="SELECT 1"` | Run a D1 SQL command |
+| `wrangler whoami` | Verify authenticated account |