@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,141 @@
+# D1 API Reference
+
+## Prepared Statements (Required for Security)
+
+```typescript
+// ❌ NEVER: Direct string interpolation (SQL injection risk)
+const result = await env.DB.prepare(`SELECT * FROM users WHERE id = ${userId}`).all();
+
+// ✅ CORRECT: Prepared statements with bind()
+const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all();
+
+// Multiple parameters
+const result = await env.DB.prepare('SELECT * FROM users WHERE email = ? AND active = ?').bind(email, true).all();
+```
+
+## Query Execution Methods
+
+```typescript
+// .all() - Returns all rows
+const { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?').bind(true).all();
+// results: Array of row objects; success: boolean
+// meta: { duration: number, rows_read: number, rows_written: number }
+
+// .first() - Returns first row or null
+const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+
+// .first(columnName) - Returns single column value
+const email = await env.DB.prepare('SELECT email FROM users WHERE id = ?').bind(userId).first('email');
+// Returns string | number | null
+
+// .run() - For INSERT/UPDATE/DELETE (no row data returned)
+const result = await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();
+// result.meta: { duration, rows_read, rows_written, last_row_id, changes }
+
+// .raw() - Returns array of arrays (efficient for large datasets)
+const rawResults = await env.DB.prepare('SELECT id, name FROM users').raw();
+// [[1, 'Alice'], [2, 'Bob']]
+```
+
+## Batch Operations
+
+```typescript
+// Execute multiple queries in single round trip (atomic transaction)
+const results = await env.DB.batch([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),
+  env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),
+  env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1)
+]);
+// results is array: [result1, result2, result3]
+
+// Batch with same prepared statement, different params
+const userIds = [1, 2, 3];
+const stmt = env.DB.prepare('SELECT * FROM users WHERE id = ?');
+const results = await env.DB.batch(userIds.map(id => stmt.bind(id)));
+```
+
+## Transactions (via batch)
+
+```typescript
+// D1 executes batch() as atomic transaction - all succeed or all fail
+const results = await env.DB.batch([
+  env.DB.prepare('INSERT INTO accounts (id, balance) VALUES (?, ?)').bind(1, 100),
+  env.DB.prepare('INSERT INTO accounts (id, balance) VALUES (?, ?)').bind(2, 200),
+  env.DB.prepare('UPDATE accounts SET balance = balance - ? WHERE id = ?').bind(50, 1),
+  env.DB.prepare('UPDATE accounts SET balance = balance + ? WHERE id = ?').bind(50, 2)
+]);
+```
+
+## Error Handling
+
+```typescript
+async function getUser(userId: number, env: Env): Promise<Response> {
+  try {
+    const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all();
+    if (!result.success) return new Response('Database error', { status: 500 });
+    if (result.results.length === 0) return new Response('User not found', { status: 404 });
+    return Response.json(result.results[0]);
+  } catch (error) {
+    return new Response('Internal error', { status: 500 });
+  }
+}
+
+// Constraint violations
+try {
+  await env.DB.prepare('INSERT INTO users (email, name) VALUES (?, ?)').bind(email, name).run();
+} catch (error) {
+  if (error.message?.includes('UNIQUE constraint failed')) return new Response('Email exists', { status: 409 });
+  throw error;
+}
+```
+
+## REST API (HTTP) Access
+
+```typescript
+// Access D1 via Cloudflare REST API (external to Workers)
+const response = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/d1/database/${DATABASE_ID}/query`,
+  {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${CLOUDFLARE_API_TOKEN}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      sql: 'SELECT * FROM users WHERE id = ?',
+      params: [userId]
+    })
+  }
+);
+
+const data = await response.json();
+```
+
+## Testing
+
+```typescript
+import { unstable_dev } from 'wrangler';
+
+describe('D1 Tests', () => {
+  let worker: Awaited<ReturnType<typeof unstable_dev>>;
+  beforeAll(async () => { worker = await unstable_dev('src/index.ts', { experimental: { disableExperimentalWarning: true } }); });
+  afterAll(async () => { await worker.stop(); });
+  it('should query users', async () => { expect((await worker.fetch('/api/users')).status).toBe(200); });
+});
+```
+
+## Debugging
+
+```typescript
+// Log query metadata
+const result = await env.DB.prepare('SELECT * FROM users').all();
+console.log('Duration:', result.meta.duration, 'ms', 'Rows:', result.meta.rows_read);
+
+// EXPLAIN for query plans
+const plan = await env.DB.prepare('EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?').bind(email).all();
+```
+
+```bash
+sqlite3 .wrangler/state/v3/d1/<database-id>.sqlite  # Inspect local DB
+.tables; .schema users; .indexes users; PRAGMA table_info(users);
+```

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

@@ -0,0 +1,127 @@
+# D1 Configuration
+
+## wrangler.toml Setup
+
+```toml
+name = "your-worker-name"; main = "src/index.ts"; compatibility_date = "2024-01-01"
+
+[[d1_databases]]
+binding = "DB"                    # Env variable name
+database_name = "your-db-name"    # Human-readable name
+database_id = "your-database-id"  # UUID from dashboard/CLI
+migrations_dir = "migrations"     # Optional
+
+# Multiple databases
+[[d1_databases]]
+binding = "ANALYTICS_DB"; database_name = "analytics-db"; database_id = "yyy-yyy-yyy"
+```
+
+## TypeScript Types
+
+```typescript
+interface Env { DB: D1Database; ANALYTICS_DB?: D1Database; }
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const result = await env.DB.prepare('SELECT * FROM users').all();
+    return Response.json(result.results);
+  }
+}
+```
+
+## Migrations
+
+File structure: `migrations/0001_initial_schema.sql`, `0002_add_posts.sql`, etc.
+
+### Example Migration
+
+```sql
+-- migrations/0001_initial_schema.sql
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT UNIQUE NOT NULL,
+  name TEXT NOT NULL,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_users_email ON users(email);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT,
+  published BOOLEAN DEFAULT 0,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+CREATE INDEX idx_posts_published ON posts(published);
+```
+
+### Running Migrations
+
+```bash
+wrangler d1 execute <db-name> --local --file=./migrations/0001_schema.sql    # Local
+wrangler d1 execute <db-name> --remote --file=./migrations/0001_schema.sql   # Production
+wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"      # Direct
+
+# Track migrations: CREATE TABLE schema_version (version INT PRIMARY KEY, name TEXT, applied_at INT)
+```
+
+## Indexing Strategy
+
+```sql
+-- Index frequently queried columns
+CREATE INDEX idx_users_email ON users(email);
+
+-- Composite indexes for multi-column queries
+CREATE INDEX idx_posts_user_published ON posts(user_id, published);
+
+-- Covering indexes (include queried columns)
+CREATE INDEX idx_users_email_name ON users(email, name);
+
+-- Partial indexes for filtered queries
+CREATE INDEX idx_active_users ON users(email) WHERE active = 1;
+
+-- Check if query uses index
+EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?;
+```
+
+## Drizzle ORM
+
+```typescript
+// drizzle.config.ts
+export default {
+  schema: './src/schema.ts', out: './migrations', dialect: 'sqlite', driver: 'd1-http',
+  dbCredentials: { accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, databaseId: process.env.D1_DATABASE_ID!, token: process.env.CLOUDFLARE_API_TOKEN! }
+} satisfies Config;
+
+// schema.ts
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  email: text('email').notNull().unique(),
+  name: text('name').notNull()
+});
+
+// worker.ts
+import { drizzle } from 'drizzle-orm/d1';
+import { users } from './schema';
+export default {
+  async fetch(request: Request, env: Env) {
+    const db = drizzle(env.DB);
+    return Response.json(await db.select().from(users));
+  }
+}
+```
+
+## Local Development
+
+```bash
+wrangler dev --persist-to=./.wrangler/state  # Persist across restarts
+# Local DB: .wrangler/state/v3/d1/<database-id>.sqlite
+sqlite3 .wrangler/state/v3/d1/<database-id>.sqlite  # Inspect
+```

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

@@ -0,0 +1,70 @@
+# D1 Gotchas & Troubleshooting
+
+## SQL Injection Prevention (CRITICAL)
+
+```typescript
+// ❌ NEVER: String interpolation - SQL injection vulnerability
+await env.DB.prepare(`SELECT * FROM users WHERE id = ${userId}`).all(); // DANGEROUS!
+
+// ✅ ALWAYS: Prepared statements with bind()
+await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all();
+```
+
+Attacker could pass `1 OR 1=1` to dump table or `1; DROP TABLE users;--` to delete data.
+
+## Common Errors
+
+**Missing Table:** "no such table" → Run migrations first  
+**Unique Constraint:** "UNIQUE constraint failed" → Catch and return 409  
+**Query Timeout:** 30s exceeded → Break into smaller queries or add indexes
+
+## N+1 Query Problem
+
+```typescript
+// ❌ BAD: N+1 queries (multiple round trips)
+for (const post of posts.results) {
+  const author = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(post.user_id).first();
+}
+
+// ✅ GOOD: Single JOIN or batch()
+const postsWithAuthors = await env.DB.prepare(`
+  SELECT posts.*, users.name FROM posts JOIN users ON posts.user_id = users.id
+`).all();
+```
+
+## Missing Indexes
+
+```sql
+EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?;  -- Check for "USING INDEX"
+CREATE INDEX idx_users_email ON users(email);  -- Add if missing
+```
+
+## Limits to Watch
+
+| Limit | Value | Impact |
+|-------|-------|--------|
+| Database size | 10 GB | Design for multiple DBs per tenant |
+| Row size | 1 MB | Store large files in R2, not D1 |
+| Query timeout | 30s | Break long queries into smaller chunks |
+| Batch size | 10,000 statements | Split large batches |
+
+## Local vs Remote
+
+Local uses `.wrangler/state/v3/d1/<database-id>.sqlite`. Always test migrations locally before remote.
+
+## Data Types
+
+**Boolean:** SQLite uses INTEGER (0/1) not boolean - bind 1 or 0, not true/false  
+**Date/Time:** Use TEXT (ISO 8601) or INTEGER (unix timestamp), not native DATE/TIME
+
+## Best Practices
+
+- ✅ Use prepared statements with bind() - ALWAYS
+- ✅ Create indexes on frequently queried columns
+- ✅ Use batch() for multiple queries (reduces latency)
+- ✅ Design for horizontal scaling (multiple small DBs vs single large DB)
+- ✅ Test migrations locally before applying remotely
+- ✅ Monitor query performance via meta.duration
+- ❌ Don't store binary data directly (use R2 for blobs)
+- ❌ Don't use single large database (scale horizontally instead)
+- ❌ Don't run long transactions (30s timeout)

package/dist/template/.opencode/skill/cloudflare/references/d1/patterns.md

@@ -0,0 +1,144 @@
+# D1 Patterns & Best Practices
+
+## Pagination
+
+```typescript
+async function getUsers({ page, pageSize }: { page: number; pageSize: number }, env: Env) {
+  const offset = (page - 1) * pageSize;
+  const [countResult, dataResult] = await env.DB.batch([
+    env.DB.prepare('SELECT COUNT(*) as total FROM users'),
+    env.DB.prepare('SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?').bind(pageSize, offset)
+  ]);
+  return { data: dataResult.results, total: countResult.results[0].total, page, pageSize, totalPages: Math.ceil(countResult.results[0].total / pageSize) };
+}
+```
+
+## Conditional Queries
+
+```typescript
+async function searchUsers(filters: { name?: string; email?: string; active?: boolean }, env: Env) {
+  const conditions: string[] = [], params: any[] = [];
+  if (filters.name) { conditions.push('name LIKE ?'); params.push(`%${filters.name}%`); }
+  if (filters.email) { conditions.push('email = ?'); params.push(filters.email); }
+  if (filters.active !== undefined) { conditions.push('active = ?'); params.push(filters.active ? 1 : 0); }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  return await env.DB.prepare(`SELECT * FROM users ${whereClause}`).bind(...params).all();
+}
+```
+
+## Bulk Insert
+
+```typescript
+async function bulkInsertUsers(users: Array<{ name: string; email: string }>, env: Env) {
+  const stmt = env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
+  const batch = users.map(user => stmt.bind(user.name, user.email));
+  return await env.DB.batch(batch);
+}
+```
+
+## Caching with KV
+
+```typescript
+async function getCachedUser(userId: number, env: { DB: D1Database; CACHE: KVNamespace }) {
+  const cacheKey = `user:${userId}`;
+  const cached = await env.CACHE?.get(cacheKey, 'json');
+  if (cached) return cached;
+  const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+  if (user) await env.CACHE?.put(cacheKey, JSON.stringify(user), { expirationTtl: 300 });
+  return user;
+}
+```
+
+## Query Optimization
+
+```typescript
+// ✅ Use indexes in WHERE clauses
+const users = await env.DB.prepare('SELECT * FROM users WHERE email = ?').bind(email).all();
+
+// ✅ Limit result sets
+const recentPosts = await env.DB.prepare('SELECT * FROM posts ORDER BY created_at DESC LIMIT 100').all();
+
+// ✅ Use batch() for multiple independent queries
+const [user, posts, comments] = await env.DB.batch([
+  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId),
+  env.DB.prepare('SELECT * FROM posts WHERE user_id = ?').bind(userId),
+  env.DB.prepare('SELECT * FROM comments WHERE user_id = ?').bind(userId)
+]);
+
+// ❌ Avoid N+1 queries
+for (const post of posts) {
+  const author = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(post.user_id).first(); // Bad: multiple round trips
+}
+
+// ✅ Use JOINs instead
+const postsWithAuthors = await env.DB.prepare(`
+  SELECT posts.*, users.name as author_name
+  FROM posts
+  JOIN users ON posts.user_id = users.id
+`).all();
+```
+
+## Multi-Tenant SaaS
+
+```typescript
+// Each tenant gets own database
+export default {
+  async fetch(request: Request, env: { [key: `TENANT_${string}`]: D1Database }) {
+    const tenantId = request.headers.get('X-Tenant-ID');
+    const data = await env[`TENANT_${tenantId}`].prepare('SELECT * FROM records').all();
+    return Response.json(data.results);
+  }
+}
+```
+
+## Session Storage
+
+```typescript
+async function createSession(userId: number, token: string, env: Env) {
+  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
+  return await env.DB.prepare(`
+    INSERT INTO sessions (user_id, token, expires_at, created_at)
+    VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+  `).bind(userId, token, expiresAt).run();
+}
+
+async function validateSession(token: string, env: Env) {
+  return await env.DB.prepare(`
+    SELECT s.*, u.email, u.name
+    FROM sessions s
+    JOIN users u ON s.user_id = u.id
+    WHERE s.token = ? AND s.expires_at > CURRENT_TIMESTAMP
+  `).bind(token).first();
+}
+```
+
+## Analytics/Events
+
+```typescript
+async function logEvent(event: { type: string; userId?: number; metadata: any }, env: Env) {
+  return await env.DB.prepare(`
+    INSERT INTO events (type, user_id, metadata, timestamp)
+    VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+  `).bind(event.type, event.userId || null, JSON.stringify(event.metadata)).run();
+}
+
+async function getEventStats(startDate: string, endDate: string, env: Env) {
+  return await env.DB.prepare(`
+    SELECT type, COUNT(*) as count
+    FROM events
+    WHERE timestamp BETWEEN ? AND ?
+    GROUP BY type
+    ORDER BY count DESC
+  `).bind(startDate, endDate).all();
+}
+```
+
+## Time Travel & Backups
+
+```bash
+wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time
+wrangler d1 time-travel info <db-name>  # List restore points (30-day window)
+wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export
+wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
+wrangler d1 execute <db-name> --remote --file=./backup.sql  # Import
+```

package/dist/template/.opencode/skill/cloudflare/references/ddos/README.md

@@ -0,0 +1,34 @@
+# Cloudflare DDoS Protection
+
+Autonomous, always-on protection against DDoS attacks across L3/4 and L7.
+
+## Protection Types
+
+- **HTTP DDoS (L7)**: Protects HTTP/HTTPS traffic, phase `ddos_l7`, zone/account level
+- **Network DDoS (L3/4)**: UDP/SYN/DNS floods, phase `ddos_l4`, account level only
+- **Adaptive DDoS**: Learns 7-day baseline, detects deviations (Enterprise)
+
+## Key Features
+
+- Always-on managed rulesets (cannot disable)
+- Sensitivity levels: `default` (high), `medium`, `low`, `eoff` (essentially off)
+- Actions: `block`, `managed_challenge`, `challenge`, `log` (Enterprise Advanced only)
+- Override by category/tag or individual rule ID
+- Custom expressions for traffic filtering (Enterprise Advanced)
+- Alert configuration for attack notifications
+
+## Rule Limits
+
+- Free/Pro/Business: 1 override rule
+- Enterprise Advanced: Up to 10 rules
+
+## Scope Hierarchy
+
+Zone overrides take precedence over account overrides.
+
+## See Also
+
+- [configuration.md](./configuration.md) - Dashboard & rule setup
+- [api.md](./api.md) - API endpoints & management
+- [patterns.md](./patterns.md) - Protection strategies
+- [gotchas.md](./gotchas.md) - False positives & tuning

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

@@ -0,0 +1,136 @@
+# DDoS API
+
+## Endpoints
+
+### HTTP DDoS (L7)
+
+```typescript
+// Zone-level
+PUT /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint
+GET /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint
+
+// Account-level (Enterprise Advanced)
+PUT /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint
+GET /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint
+```
+
+### Network DDoS (L3/4)
+
+```typescript
+// Account-level only
+PUT /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint
+GET /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint
+```
+
+## TypeScript SDK
+
+```typescript
+import Cloudflare from "cloudflare";
+
+const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });
+
+// Get HTTP DDoS ruleset
+const ruleset = await client.zones.rulesets.phases.entrypoint.get("ddos_l7", {
+  zone_id: zoneId,
+});
+
+// Update HTTP DDoS ruleset
+await client.zones.rulesets.phases.entrypoint.update("ddos_l7", {
+  zone_id: zoneId,
+  rules: [
+    {
+      action: "execute",
+      expression: "true",
+      action_parameters: {
+        id: managedRulesetId,
+        overrides: {
+          sensitivity_level: "medium",
+          action: "managed_challenge",
+        },
+      },
+    },
+  ],
+});
+
+// Network DDoS (account level)
+const l4Ruleset = await client.accounts.rulesets.phases.entrypoint.get("ddos_l4", {
+  account_id: accountId,
+});
+```
+
+## Alert Configuration
+
+```typescript
+interface DDoSAlertConfig {
+  name: string;
+  enabled: boolean;
+  alert_type: "http_ddos_attack_alert" | "layer_3_4_ddos_attack_alert" 
+    | "advanced_http_ddos_attack_alert" | "advanced_layer_3_4_ddos_attack_alert";
+  filters?: {
+    zones?: string[];
+    hostnames?: string[];
+    requests_per_second?: number;
+    packets_per_second?: number;
+    megabits_per_second?: number;
+    ip_prefixes?: string[]; // CIDR
+    ip_addresses?: string[];
+    protocols?: string[];
+  };
+  mechanisms: {
+    email?: Array<{ id: string }>;
+    webhooks?: Array<{ id: string }>;
+    pagerduty?: Array<{ id: string }>;
+  };
+}
+
+// Create alert
+await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${accountId}/alerting/v3/policies`,
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(alertConfig),
+  }
+);
+```
+
+## Worker Integration
+
+```typescript
+// DDoS config management worker
+interface Env {
+  CLOUDFLARE_API_TOKEN: string;
+  ZONE_ID: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === "/configure") {
+      const response = await fetch(
+        `https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/rulesets/phases/ddos_l7/entrypoint`,
+        {
+          method: "PUT",
+          headers: {
+            Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            description: "Dynamic DDoS config",
+            rules: [/* ... */],
+          }),
+        }
+      );
+      return response;
+    }
+
+    return new Response("Not found", { status: 404 });
+  },
+};
+```
+
+See [patterns.md](./patterns.md) for complete worker examples.