@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/email-workers/configuration.md

@@ -0,0 +1,112 @@
+# Email Workers Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "name": "email-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-27",
+  "send_email": [
+    { "name": "EMAIL" },                                    // Unrestricted
+    { "name": "EMAIL_LOGS", "destination_address": "logs@example.com" },  // Single dest
+    { "name": "EMAIL_TEAM", "allowed_destination_addresses": ["a@ex.com", "b@ex.com"] },
+    { "name": "EMAIL_NOREPLY", "allowed_sender_addresses": ["noreply@ex.com"] }
+  ],
+  "kv_namespaces": [{ "binding": "ARCHIVE", "id": "xxx" }],
+  "r2_buckets": [{ "binding": "ATTACHMENTS", "bucket_name": "email-attachments" }],
+  "vars": { "WEBHOOK_URL": "https://hooks.example.com" }
+}
+```
+
+## TypeScript Types
+
+```typescript
+interface Env {
+  EMAIL: SendEmail;
+  ARCHIVE: KVNamespace;
+  ATTACHMENTS: R2Bucket;
+  WEBHOOK_URL: string;
+}
+
+export default {
+  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {}
+};
+```
+
+## Dependencies
+
+```bash
+npm install postal-mime mimetext
+npm install -D @cloudflare/workers-types wrangler typescript
+```
+
+Use postal-mime v2.x, mimetext v3.x.
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "ES2022", "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "moduleResolution": "bundler", "strict": true
+  }
+}
+```
+
+## Local Development
+
+```bash
+npx wrangler dev
+
+# Test receiving
+curl --request POST 'http://localhost:8787/cdn-cgi/handler/email' \
+  --url-query 'from=sender@example.com' --url-query 'to=recipient@example.com' \
+  --header 'Content-Type: text/plain' --data-raw 'Subject: Test\n\nHello'
+```
+
+Sent emails write to local `.eml` files.
+
+## Deployment Checklist
+
+- [ ] Enable Email Routing in dashboard
+- [ ] Verify destination addresses
+- [ ] Configure DMARC/SPF/DKIM for sending
+- [ ] Create KV/R2 resources if needed
+- [ ] Update wrangler.jsonc with production IDs
+
+```bash
+npx wrangler deploy
+npx wrangler deployments list
+```
+
+## Dashboard Setup
+
+1. **Email Routing:** Domain → Email → Enable Email Routing
+2. **Verify addresses:** Email → Destination addresses → Add & verify
+3. **Bind Worker:** Email → Email Workers → Create route → Select pattern & Worker
+4. **DMARC:** Add TXT `_dmarc.domain.com`: `v=DMARC1; p=quarantine;`
+
+## Secrets
+
+```bash
+npx wrangler secret put API_KEY
+# Access: env.API_KEY
+```
+
+## Monitoring
+
+```bash
+npx wrangler tail
+npx wrangler tail --status error
+npx wrangler tail --format json
+```
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| "Binding not found" | Check `send_email` name matches code |
+| "Invalid destination" | Verify in Email Routing dashboard |
+| Type errors | Install `@cloudflare/workers-types` |

package/skills/cloudflare-deploy/references/email-workers/gotchas.md

@@ -0,0 +1,125 @@
+# Email Workers Gotchas
+
+## Critical Issues
+
+### ReadableStream Single-Use
+
+```typescript
+// ❌ WRONG: Stream consumed twice
+const email = await PostalMime.parse(await new Response(message.raw).arrayBuffer());
+const rawText = await new Response(message.raw).text(); // EMPTY!
+
+// ✅ CORRECT: Buffer first
+const buffer = await new Response(message.raw).arrayBuffer();
+const email = await PostalMime.parse(buffer);
+const rawText = new TextDecoder().decode(buffer);
+```
+
+### ctx.waitUntil() Errors Silent
+
+```typescript
+// ❌ Errors dropped silently
+ctx.waitUntil(fetch(webhookUrl, { method: 'POST', body: data }));
+
+// ✅ Catch and log
+ctx.waitUntil(
+  fetch(webhookUrl, { method: 'POST', body: data })
+    .catch(err => env.ERROR_LOG.put(`error:${Date.now()}`, err.message))
+);
+```
+
+## Security
+
+### Envelope vs Header From (Spoofing)
+
+```typescript
+const envelopeFrom = message.from;               // SMTP MAIL FROM (trusted)
+const headerFrom = (await PostalMime.parse(buffer)).from?.address; // (untrusted)
+// Use envelope for security decisions
+```
+
+### Input Validation
+
+```typescript
+if (message.rawSize > 5_000_000) { message.setReject('Too large'); return; }
+if ((message.headers.get('Subject') || '').length > 1000) {
+  message.setReject('Invalid subject'); return;
+}
+```
+
+### DMARC for Replies
+
+Replies fail silently without DMARC. Verify: `dig TXT _dmarc.example.com`
+
+## Parsing
+
+### Address Parsing
+
+```typescript
+const email = await PostalMime.parse(buffer);
+const fromAddress = email.from?.address || 'unknown';
+const toAddresses = Array.isArray(email.to) ? email.to.map(t => t.address) : [email.to?.address];
+```
+
+### Character Encoding
+
+Let postal-mime handle decoding - `email.subject`, `email.text`, `email.html` are UTF-8.
+
+## API Behavior
+
+### setReject() vs throw
+
+```typescript
+// setReject() for SMTP rejection
+if (blockList.includes(message.from)) { message.setReject('Blocked'); return; }
+
+// throw for worker errors
+if (!env.KV) throw new Error('KV not configured');
+```
+
+### forward() Only X-* Headers
+
+```typescript
+headers.set('X-Processed-By', 'worker');  // ✅ Works
+headers.set('Subject', 'Modified');        // ❌ Dropped
+```
+
+### Reply Requires Verified Domain
+
+```typescript
+// Use same domain as receiving address
+const receivingDomain = message.to.split('@')[1];
+await message.reply(new EmailMessage(`noreply@${receivingDomain}`, message.from, rawMime));
+```
+
+## Performance
+
+### CPU Limit
+
+```typescript
+// Skip parsing large emails
+if (message.rawSize > 5_000_000) {
+  await message.forward('inbox@example.com');
+  return;
+}
+```
+
+Monitor: `npx wrangler tail`
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max message size | 25 MiB |
+| Max rules/zone | 200 |
+| CPU time (free/paid) | 10ms / 50ms |
+| Reply References | 100 |
+
+## Common Errors
+
+| Error | Fix |
+|-------|-----|
+| "Address not verified" | Add in Email Routing dashboard |
+| "Exceeded CPU time" | Use `ctx.waitUntil()` or upgrade |
+| "Stream is locked" | Buffer `message.raw` first |
+| Silent reply failure | Check DMARC records |

package/skills/cloudflare-deploy/references/email-workers/patterns.md

@@ -0,0 +1,102 @@
+# Email Workers Patterns
+
+## Parse Email
+
+```typescript
+import PostalMime from 'postal-mime';
+
+export default {
+  async email(message, env, ctx) {
+    const buffer = await new Response(message.raw).arrayBuffer();
+    const email = await PostalMime.parse(buffer);
+    console.log(email.from, email.subject, email.text, email.attachments.length);
+    await message.forward('inbox@example.com');
+  }
+};
+```
+
+## Filtering
+
+```typescript
+// Allowlist from KV
+const allowList = await env.ALLOWED_SENDERS.get('list', 'json') || [];
+if (!allowList.includes(message.from)) {
+  message.setReject('Not allowed');
+  return;
+}
+
+// Size check (avoid parsing large emails)
+if (message.rawSize > 5_000_000) {
+  await message.forward('inbox@example.com'); // Forward without parsing
+  return;
+}
+```
+
+## Auto-Reply with Threading
+
+```typescript
+import { EmailMessage } from 'cloudflare:email';
+import { createMimeMessage } from 'mimetext';
+
+const msg = createMimeMessage();
+msg.setSender({ addr: 'support@example.com' });
+msg.setRecipient(message.from);
+msg.setSubject(`Re: ${message.headers.get('Subject')}`);
+msg.setHeader('In-Reply-To', message.headers.get('Message-ID') || '');
+msg.addMessage({ contentType: 'text/plain', data: 'Thank you. We will respond.' });
+
+await message.reply(new EmailMessage('support@example.com', message.from, msg.asRaw()));
+```
+
+## Rate-Limited Auto-Reply
+
+```typescript
+const rateKey = `rate:${message.from}`;
+if (!await env.RATE_LIMIT.get(rateKey)) {
+  // Send reply...
+  ctx.waitUntil(env.RATE_LIMIT.put(rateKey, '1', { expirationTtl: 3600 }));
+}
+```
+
+## Subject-Based Routing
+
+```typescript
+const subject = (message.headers.get('Subject') || '').toLowerCase();
+if (subject.includes('billing')) await message.forward('billing@example.com');
+else if (subject.includes('support')) await message.forward('support@example.com');
+else await message.forward('general@example.com');
+```
+
+## Multi-Tenant Routing
+
+```typescript
+// support+tenant123@example.com → tenant123
+const tenantId = message.to.split('@')[0].match(/\+(.+)$/)?.[1] || 'default';
+const config = await env.TENANT_CONFIG.get(tenantId, 'json');
+config?.forwardTo ? await message.forward(config.forwardTo) : message.setReject('Unknown');
+```
+
+## Archive & Extract Attachments
+
+```typescript
+// Archive to KV
+ctx.waitUntil(env.ARCHIVE.put(`email:${Date.now()}`, JSON.stringify({
+  from: message.from, subject: email.subject
+})));
+
+// Attachments to R2
+for (const att of email.attachments) {
+  ctx.waitUntil(env.R2.put(`${Date.now()}-${att.filename}`, att.content));
+}
+```
+
+## Webhook Integration
+
+```typescript
+ctx.waitUntil(
+  fetch(env.WEBHOOK_URL, {
+    method: 'POST',
+    body: JSON.stringify({ from: message.from, subject: message.headers.get('Subject') })
+  }).catch(err => console.error(err))
+);
+```

package/skills/cloudflare-deploy/references/hyperdrive/README.md

@@ -0,0 +1,82 @@
+# Hyperdrive
+
+Accelerates database queries from Workers via connection pooling, edge setup, query caching.
+
+## Key Features
+
+- **Connection Pooling**: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)
+- **Edge Setup**: Connection negotiation at edge, pooling near origin
+- **Query Caching**: Auto-cache non-mutating queries (default 60s TTL)
+- **Support**: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)
+
+## Architecture
+
+```
+Worker → Edge (setup) → Pool (near DB) → Origin
+         ↓ cached reads
+         Cache
+```
+
+## Quick Start
+
+```bash
+# Create config
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://user:pass@host:5432/db"
+
+# wrangler.jsonc
+{
+  "compatibility_flags": ["nodejs_compat"],
+  "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
+}
+```
+
+```typescript
+import { Client } from "pg";
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const client = new Client({
+      connectionString: env.HYPERDRIVE.connectionString,
+    });
+    await client.connect();
+    const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
+    await client.end();
+    return Response.json(result.rows);
+  },
+};
+```
+
+## When to Use
+
+✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads
+❌ Write-heavy, real-time data (<1s), single-region apps close to DB
+
+**💡 Pair with Smart Placement** for Workers making multiple queries - executes near DB to minimize latency.
+
+## Driver Choice
+
+| Driver | Use When | Notes |
+|--------|----------|-------|
+| **pg** (recommended) | General use, TypeScript, ecosystem compatibility | Stable, widely used, works with most ORMs |
+| **postgres.js** | Advanced features, template literals, streaming | Lighter than pg, `prepare: true` is default |
+| **mysql2** | MySQL/MariaDB/PlanetScale | MySQL only, less mature support |
+
+## Reading Order
+
+| New to Hyperdrive | Implementing | Troubleshooting |
+|-------------------|--------------|-----------------|
+| 1. README (this) | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md) |
+| 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md) | 2. [patterns.md](./patterns.md) |
+| 3. [api.md](./api.md) | 3. [patterns.md](./patterns.md) | 3. [api.md](./api.md) |
+
+## In This Reference
+- [configuration.md](./configuration.md) - Setup, wrangler config, Smart Placement
+- [api.md](./api.md) - Binding APIs, query patterns, driver usage
+- [patterns.md](./patterns.md) - Use cases, ORMs, multi-query optimization
+- [gotchas.md](./gotchas.md) - Limits, troubleshooting, connection management
+
+## See Also
+- [smart-placement](../smart-placement/) - Optimize multi-query Workers near databases
+- [d1](../d1/) - Serverless SQLite alternative for edge-native apps
+- [workers](../workers/) - Worker runtime with database bindings

package/skills/cloudflare-deploy/references/hyperdrive/api.md

@@ -0,0 +1,143 @@
+# API Reference
+
+See [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.
+
+## Binding Interface
+
+```typescript
+interface Hyperdrive {
+  connectionString: string;  // PostgreSQL
+  // MySQL properties:
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+}
+
+interface Env {
+  HYPERDRIVE: Hyperdrive;
+}
+```
+
+**Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)
+
+## PostgreSQL (node-postgres) - RECOMMENDED
+
+```typescript
+import { Client } from "pg";  // pg@^8.17.2
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const client = new Client({connectionString: env.HYPERDRIVE.connectionString});
+    try {
+      await client.connect();
+      const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
+      return Response.json(result.rows);
+    } finally {
+      await client.end();
+    }
+  },
+};
+```
+
+**⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.
+
+## PostgreSQL (postgres.js)
+
+```typescript
+import postgres from "postgres";  // postgres@^3.4.8
+
+const sql = postgres(env.HYPERDRIVE.connectionString, {
+  max: 5,             // Limit per Worker (Workers max: 6)
+  prepare: true,      // Enabled by default, required for caching
+  fetch_types: false, // Reduce latency if not using arrays
+});
+
+const users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`;
+```
+
+**⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.
+
+## MySQL (mysql2)
+
+```typescript
+import { createConnection } from "mysql2/promise";  // mysql2@^3.16.2
+
+const conn = await createConnection({
+  host: env.HYPERDRIVE.host,
+  user: env.HYPERDRIVE.user,
+  password: env.HYPERDRIVE.password,
+  database: env.HYPERDRIVE.database,
+  port: env.HYPERDRIVE.port,
+  disableEval: true,  // ⚠️ REQUIRED for Workers
+});
+
+const [results] = await conn.query("SELECT * FROM users WHERE active = ? LIMIT ?", [true, 10]);
+ctx.waitUntil(conn.end());
+```
+
+**⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.
+
+## Query Caching
+
+**Cacheable:**
+```sql
+SELECT * FROM posts WHERE published = true;
+SELECT COUNT(*) FROM users;
+```
+
+**NOT cacheable:**
+```sql
+-- Writes
+INSERT/UPDATE/DELETE
+
+-- Volatile functions
+SELECT NOW();
+SELECT random();
+SELECT LASTVAL();  -- PostgreSQL
+SELECT UUID();     -- MySQL
+```
+
+**Cache config:**
+- Default: `max_age=60s`, `swr=15s`
+- Max `max_age`: 3600s
+- Disable: `--caching-disabled=true`
+
+**Multiple configs pattern:**
+```typescript
+// Reads: cached
+const sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString);
+const posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`;
+
+// Writes/time-sensitive: no cache
+const sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString);
+const orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`;
+```
+
+## ORMs
+
+**Drizzle:**
+```typescript
+import { drizzle } from "drizzle-orm/postgres-js";  // drizzle-orm@^0.45.1
+import postgres from "postgres";
+
+const client = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});
+const db = drizzle(client);
+const users = await db.select().from(users).where(eq(users.active, true)).limit(10);
+```
+
+**Kysely:**
+```typescript
+import { Kysely, PostgresDialect } from "kysely";  // kysely@^0.27+
+import postgres from "postgres";
+
+const db = new Kysely({
+  dialect: new PostgresDialect({
+    postgres: postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}),
+  }),
+});
+const users = await db.selectFrom("users").selectAll().where("active", "=", true).execute();
+```
+
+See [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.