@namch/agent-assistant 1.0.0

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

@@ -0,0 +1,137 @@
+# 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;
+}
+```
+
+## PostgreSQL (node-postgres) - RECOMMENDED
+
+```typescript
+import { Client } from "pg";  // pg@^8.16.3, @types/pg
+
+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();
+    }
+  },
+};
+```
+
+## PostgreSQL (postgres.js)
+
+```typescript
+import postgres from "postgres";  // postgres@^3.4.5
+
+const sql = postgres(env.HYPERDRIVE.connectionString, {
+  max: 5,             // Limit per Worker
+  prepare: true,      // ⚠️ CRITICAL 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` required for Hyperdrive caching.** `false` disables prepared statements + cache.
+
+## MySQL (mysql2)
+
+```typescript
+import { createConnection } from "mysql2/promise";  // mysql2@^3.13.0
+
+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());
+```
+
+## 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.26.2
+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.26.3
+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.

package/skills/cloudflare-expert/references/hyperdrive/configuration.md

@@ -0,0 +1,133 @@
+# Configuration
+
+See [README.md](./README.md) for overview.
+
+## Create Config
+
+**PostgreSQL:**
+```bash
+# Basic
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://user:pass@host:5432/db"
+
+# Custom cache
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://..." \
+  --max-age=120 --swr=30
+
+# No cache
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://..." \
+  --caching-disabled=true
+```
+
+**MySQL:**
+```bash
+npx wrangler hyperdrive create my-db \
+  --connection-string="mysql://user:pass@host:3306/db"
+```
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "compatibility_date": "2024-09-23",
+  "compatibility_flags": ["nodejs_compat"],
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+      "id": "<HYPERDRIVE_ID>",
+      "localConnectionString": "postgres://user:pass@localhost:5432/dev"
+    }
+  ]
+}
+```
+
+**Multiple configs:**
+```jsonc
+{
+  "hyperdrive": [
+    {"binding": "HYPERDRIVE_CACHED", "id": "<ID1>"},
+    {"binding": "HYPERDRIVE_NO_CACHE", "id": "<ID2>"}
+  ]
+}
+```
+
+## Management
+
+```bash
+npx wrangler hyperdrive list
+npx wrangler hyperdrive get <ID>
+npx wrangler hyperdrive update <ID> --max-age=180
+npx wrangler hyperdrive delete <ID>
+```
+
+## Config Options
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `--caching-disabled` | `false` | Disable caching |
+| `--max-age` | `60` | Cache TTL (max 3600s) |
+| `--swr` | `15` | Stale-while-revalidate |
+| `--origin-connection-limit` | 20/100 | Free/paid |
+| `--access-client-id` | - | Tunnel auth |
+| `--access-client-secret` | - | Tunnel auth |
+| `--sslmode` | `require` | PostgreSQL only |
+
+## Private DB via Tunnel
+
+```
+Worker → Hyperdrive → Access → Tunnel → Private Network → DB
+```
+
+**Setup:**
+```bash
+# 1. Create tunnel
+cloudflared tunnel create my-db-tunnel
+
+# 2. Configure hostname in Zero Trust dashboard
+#    Domain: db-tunnel.example.com
+#    Service: TCP -> localhost:5432
+
+# 3. Create service token (Zero Trust > Service Auth)
+#    Save Client ID/Secret
+
+# 4. Create Access app (db-tunnel.example.com)
+#    Policy: Service Auth token from step 3
+
+# 5. Create Hyperdrive
+npx wrangler hyperdrive create my-private-db \
+  --host=db-tunnel.example.com \
+  --user=dbuser --password=dbpass --database=prod \
+  --access-client-id=<ID> --access-client-secret=<SECRET>
+```
+
+**⚠️ Don't specify `--port` with Tunnel** - port configured in tunnel service settings.
+
+## Local Dev
+
+**Option 1: Local (RECOMMENDED):**
+```bash
+# Env var (takes precedence)
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@localhost:5432/dev"
+npx wrangler dev
+
+# wrangler.jsonc
+{"hyperdrive": [{"binding": "HYPERDRIVE", "localConnectionString": "postgres://..."}]}
+```
+
+**Remote DB locally:**
+```bash
+# PostgreSQL
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@remote:5432/db?sslmode=require"
+
+# MySQL
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="mysql://user:pass@remote:3306/db?sslMode=REQUIRED"
+```
+
+**Option 2: Remote execution:**
+```bash
+npx wrangler dev --remote  # Uses deployed config, affects production
+```
+
+See [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md).

package/skills/cloudflare-expert/references/hyperdrive/gotchas.md

@@ -0,0 +1,184 @@
+# Gotchas
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md).
+
+## Limits
+
+**Config:**
+| Limit | Free | Paid |
+|-------|------|------|
+| Max configs | 10 | 25 |
+| Username/DB name | 63 bytes | 63 bytes |
+
+**Connections:**
+| Limit | Free | Paid |
+|-------|------|------|
+| Connection timeout | 15s | 15s |
+| Idle timeout | 10min | 10min |
+| Max origin connections | ~20 | ~100 |
+
+**Queries:**
+| Limit | Value |
+|-------|-------|
+| Max duration | 60s |
+| Max cached response | 50MB |
+
+**Note:** Queries >60s terminated. Responses >50MB returned but not cached.
+
+## Common Errors
+
+```typescript
+try {
+  const result = await client.query("SELECT * FROM users");
+} catch (error: any) {
+  const msg = error.message || "";
+
+  // Pool exhausted
+  if (msg.includes("Failed to acquire a connection")) {
+    console.error("Pool exhausted - long transactions?");
+    return new Response("Service busy", {status: 503});
+  }
+
+  // Connection refused
+  if (msg.includes("connection_refused")) {
+    console.error("DB refusing - firewall/limits?");
+    return new Response("DB unavailable", {status: 503});
+  }
+
+  // Timeout
+  if (msg.includes("timeout") || msg.includes("deadline exceeded")) {
+    console.error("Query timeout - exceeded 60s");
+    return new Response("Query timeout", {status: 504});
+  }
+
+  // Auth failure
+  if (msg.includes("password authentication failed")) {
+    console.error("Auth failed - check credentials");
+    return new Response("Config error", {status: 500});
+  }
+
+  // SSL/TLS
+  if (msg.includes("SSL") || msg.includes("TLS")) {
+    console.error("TLS issue - check sslmode");
+    return new Response("Connection security error", {status: 500});
+  }
+
+  console.error("Unknown DB error:", error);
+  return new Response("Internal error", {status: 500});
+}
+```
+
+## Monitor Connections
+
+**PostgreSQL:**
+```sql
+-- Show Hyperdrive connections
+SELECT usename, application_name, client_addr, state
+FROM pg_stat_activity 
+WHERE application_name = 'Cloudflare Hyperdrive';
+
+-- Count active
+SELECT COUNT(*) FROM pg_stat_activity WHERE application_name = 'Cloudflare Hyperdrive';
+```
+
+## Troubleshooting
+
+**Connection refused:**
+1. Check firewall allows Cloudflare IPs
+2. Verify DB listening on port
+3. Confirm service running
+4. Check credentials
+
+**Pool exhausted:**
+1. Reduce transaction duration
+2. Avoid long queries (>60s)
+3. Don't hold connections during external calls
+4. Upgrade to paid plan
+
+**SSL/TLS failed:**
+1. Add `sslmode=require` (Postgres) or `sslMode=REQUIRED` (MySQL)
+2. Upload CA cert if self-signed
+3. Verify DB has SSL enabled
+4. Check cert expiry
+
+**Queries not cached:**
+1. Verify non-mutating (SELECT)
+2. Check for volatile functions (NOW(), RANDOM())
+3. Confirm caching not disabled
+4. Use `wrangler dev --remote` to test
+5. Check `prepare=true` for postgres.js
+
+**Query timeout (>60s):**
+1. Optimize with indexes
+2. Reduce dataset (LIMIT)
+3. Break into smaller queries
+4. Use async processing
+
+**Local DB connection:**
+1. Verify `localConnectionString` correct
+2. Check DB running
+3. Confirm env var name matches binding
+4. Test with psql/mysql client
+
+**Env var not working:**
+1. Format: `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>`
+2. Binding matches wrangler.jsonc
+3. Variable exported in shell
+4. Restart wrangler dev
+
+## Migration Checklist
+
+- [ ] Create config via Wrangler
+- [ ] Add binding to wrangler.jsonc
+- [ ] Enable `nodejs_compat` flag
+- [ ] Set `compatibility_date` >= `2024-09-23`
+- [ ] Update code to `env.HYPERDRIVE.connectionString` (Postgres) or properties (MySQL)
+- [ ] Configure `localConnectionString`
+- [ ] Set `prepare: true` (postgres.js) or `disableEval: true` (mysql2)
+- [ ] Test locally with `wrangler dev`
+- [ ] Deploy + monitor pool usage
+- [ ] Validate cache with `wrangler dev --remote`
+- [ ] Update firewall (Cloudflare IPs)
+- [ ] Configure observability
+
+## Supported Databases
+
+**PostgreSQL:**
+- PostgreSQL 11+
+- CockroachDB, Timescale, Materialize
+- Neon, Supabase
+
+Recommended: `pg` >= 8.16.3
+
+**MySQL:**
+- MySQL 5.7+
+- PlanetScale
+
+Recommended: `mysql2` >= 3.13.0
+
+**SSL/TLS:**
+- PostgreSQL `sslmode`: `require`, `verify-ca`, `verify-full`
+- MySQL `sslMode`: `REQUIRED`, `VERIFY_CA`, `VERIFY_IDENTITY`
+
+## When NOT to Use
+
+❌ Write-heavy workloads (limited cache benefit)
+❌ Real-time data requirements (<1s freshness)
+❌ Single-region apps close to DB
+❌ Very simple apps (overhead unjustified)
+❌ DB with strict connection limits already exceeded
+
+**Alternatives:**
+- D1 - Cloudflare native distributed SQL
+- Durable Objects - Stateful Workers
+- KV - Global key-value
+- R2 - Object storage
+
+## Resources
+
+- [Docs](https://developers.cloudflare.com/hyperdrive/)
+- [Getting Started](https://developers.cloudflare.com/hyperdrive/get-started/)
+- [Wrangler Reference](https://developers.cloudflare.com/hyperdrive/reference/wrangler-commands/)
+- [Supported DBs](https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/)
+- [Discord #hyperdrive](https://discord.cloudflare.com)
+- [Limit Increase Form](https://forms.gle/ukpeZVLWLnKeixDu7)

package/skills/cloudflare-expert/references/hyperdrive/patterns.md

@@ -0,0 +1,176 @@
+# Patterns
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md).
+
+## High-Traffic Read-Heavy
+
+```typescript
+const sql = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});
+
+// Cacheable: popular content
+const posts = await sql`SELECT * FROM posts WHERE published = true ORDER BY views DESC LIMIT 20`;
+
+// Cacheable: user profiles
+const [user] = await sql`SELECT id, username, bio FROM users WHERE id = ${userId}`;
+```
+
+**Benefits:** Trending/profiles cached (60s), connection pooling handles spikes.
+
+## Mixed Read/Write
+
+```typescript
+interface Env {
+  HYPERDRIVE_CACHED: Hyperdrive;    // max_age=120
+  HYPERDRIVE_REALTIME: Hyperdrive;  // caching disabled
+}
+
+// Reads: cached
+if (req.method === "GET") {
+  const sql = postgres(env.HYPERDRIVE_CACHED.connectionString, {prepare: true});
+  const products = await sql`SELECT * FROM products WHERE category = ${cat}`;
+}
+
+// Writes: no cache (immediate consistency)
+if (req.method === "POST") {
+  const sql = postgres(env.HYPERDRIVE_REALTIME.connectionString, {prepare: true});
+  await sql`INSERT INTO orders ${sql(data)}`;
+}
+```
+
+## Analytics Dashboard
+
+```typescript
+const client = new Client({connectionString: env.HYPERDRIVE.connectionString});
+await client.connect();
+
+// Aggregate queries cached
+const dailyStats = await client.query(`
+  SELECT DATE(created_at) as date, COUNT(*) as orders, SUM(amount) as revenue
+  FROM orders WHERE created_at >= NOW() - INTERVAL '30 days'
+  GROUP BY DATE(created_at) ORDER BY date DESC
+`);
+
+const topProducts = await client.query(`
+  SELECT p.name, COUNT(oi.id) as count, SUM(oi.quantity * oi.price) as revenue
+  FROM order_items oi JOIN products p ON oi.product_id = p.id
+  WHERE oi.created_at >= NOW() - INTERVAL '7 days'
+  GROUP BY p.id, p.name ORDER BY revenue DESC LIMIT 10
+`);
+```
+
+**Benefits:** Expensive aggregations cached, dashboard instant, reduced DB load.
+
+## Multi-Tenant
+
+```typescript
+const tenantId = req.headers.get("X-Tenant-ID");
+const sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});
+
+// Tenant-scoped queries cached separately
+const docs = await sql`
+  SELECT * FROM documents 
+  WHERE tenant_id = ${tenantId} AND deleted_at IS NULL
+  ORDER BY updated_at DESC LIMIT 50
+`;
+```
+
+**Benefits:** Per-tenant caching, shared connection pool, protects DB from multi-tenant load.
+
+## Geographically Distributed
+
+```typescript
+// Worker runs at edge nearest user
+// Connection setup at edge (fast), pooling near DB (efficient)
+const sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});
+const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`;
+
+return Response.json({
+  user,
+  serverRegion: req.cf?.colo,  // Edge location
+});
+```
+
+**Benefits:** Edge setup + DB pooling = global → single-region DB without replication.
+
+## Connection Pooling
+
+Operates in **transaction mode**: connection acquired per transaction, `RESET` on return.
+
+**SET statements:**
+```typescript
+// ✅ Within transaction
+await client.query("BEGIN");
+await client.query("SET work_mem = '256MB'");
+await client.query("SELECT * FROM large_table");  // Uses SET
+await client.query("COMMIT");  // RESET after
+
+// ✅ Single statement
+await client.query("SET work_mem = '256MB'; SELECT * FROM large_table");
+
+// ❌ Across queries (may get different connection)
+await client.query("SET work_mem = '256MB'");
+await client.query("SELECT * FROM large_table");  // SET not applied
+```
+
+**Best practices:**
+```typescript
+// ❌ Long transactions block pooling
+await client.query("BEGIN");
+await processThousands();  // Connection held entire time
+await client.query("COMMIT");
+
+// ✅ Short transactions
+await client.query("BEGIN");
+await client.query("UPDATE users SET status = $1 WHERE id = $2", [status, id]);
+await client.query("COMMIT");
+
+// ✅ SET LOCAL within transaction
+await client.query("BEGIN");
+await client.query("SET LOCAL work_mem = '256MB'");
+await client.query("SELECT * FROM large_table");
+await client.query("COMMIT");
+```
+
+## Performance Tips
+
+**1. Enable prepared statements:**
+```typescript
+// ✅ Best
+const sql = postgres(connectionString, {prepare: true});  // Caching enabled
+
+// ❌ Slower
+const sql = postgres(connectionString, {prepare: false}); // Extra round-trips
+```
+
+**2. Optimize settings:**
+```typescript
+const sql = postgres(connectionString, {
+  max: 5,             // Limit per Worker
+  fetch_types: false, // Skip if not using arrays
+  prepare: true,
+  idle_timeout: 60,   // Match Worker lifetime
+});
+```
+
+**3. Cache-friendly queries:**
+```typescript
+// ✅ Cacheable (deterministic)
+await sql`SELECT * FROM products WHERE category = 'electronics' LIMIT 10`;
+
+// ❌ Not cacheable (volatile)
+await sql`SELECT * FROM logs WHERE created_at > NOW()`;
+
+// ✅ Make cacheable (parameterize)
+const ts = Date.now();
+await sql`SELECT * FROM logs WHERE created_at > ${ts}`;
+```
+
+**4. Monitor cache hits:**
+```typescript
+const start = Date.now();
+const result = await sql`SELECT * FROM users LIMIT 10`;
+const duration = Date.now() - start;
+console.log({duration, likelyCached: duration < 10});  // <10ms = cache hit
+```
+
+See [gotchas.md](./gotchas.md) for limits, troubleshooting.

package/skills/cloudflare-expert/references/images/README.md

@@ -0,0 +1,14 @@
+# Cloudflare Images Skill Reference
+
+**Cloudflare Images** is an end-to-end image management solution providing storage, transformation, optimization, and delivery at scale via Cloudflare's global network....
+
+## In This Reference
+
+- **[configuration.md](./configuration.md)** - Setup, deployment, configuration
+- **[api.md](./api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](./patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](./gotchas.md)** - Troubleshooting, best practices, limitations
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/)

package/skills/cloudflare-expert/references/images/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+See main documentation.

package/skills/cloudflare-expert/references/images/configuration.md

@@ -0,0 +1,45 @@
+## Wrangler Integration
+
+### Upload via Wrangler
+
+Wrangler doesn't have built-in Cloudflare Images commands, but you can use the API:
+
+```typescript
+// scripts/upload-image.ts
+import fs from 'fs';
+import FormData from 'form-data';
+import fetch from 'node-fetch';
+
+async function uploadImage(filePath: string) {
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  
+  const formData = new FormData();
+  formData.append('file', fs.createReadStream(filePath));
+  
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v1`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+      },
+      body: formData,
+    }
+  );
+  
+  const result = await response.json();
+  console.log('Uploaded:', result);
+}
+
+uploadImage('./photo.jpg');
+```
+
+### Access Images from Workers
+
+Store account hash as an environment variable:
+
+```toml
+# wrangler.toml
+[vars]
+IMAGES_ACCOUNT