cli-jaw 0.1.0

package/skills_ref/durable-objects/references/testing.md

@@ -0,0 +1,264 @@
+# Testing Durable Objects
+
+Use `@cloudflare/vitest-pool-workers` to test DOs inside the Workers runtime.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm i -D vitest@~3.2.0 @cloudflare/vitest-pool-workers
+```
+
+### vitest.config.ts
+
+```typescript
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: {
+      workers: {
+        wrangler: { configPath: "./wrangler.toml" },
+      },
+    },
+  },
+});
+```
+
+### TypeScript Config (test/tsconfig.json)
+
+```jsonc
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "types": ["@cloudflare/vitest-pool-workers"]
+  },
+  "include": ["./**/*.ts", "../src/worker-configuration.d.ts"]
+}
+```
+
+### Environment Types (env.d.ts)
+
+```typescript
+declare module "cloudflare:test" {
+  interface ProvidedEnv extends Env {}
+}
+```
+
+## Unit Tests (Direct DO Access)
+
+```typescript
+import { env } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("Counter DO", () => {
+  it("should increment", async () => {
+    const stub = env.COUNTER.getByName("test-counter");
+    
+    expect(await stub.increment()).toBe(1);
+    expect(await stub.increment()).toBe(2);
+    expect(await stub.getCount()).toBe(2);
+  });
+
+  it("isolates different instances", async () => {
+    const stub1 = env.COUNTER.getByName("counter-1");
+    const stub2 = env.COUNTER.getByName("counter-2");
+    
+    await stub1.increment();
+    await stub1.increment();
+    await stub2.increment();
+    
+    expect(await stub1.getCount()).toBe(2);
+    expect(await stub2.getCount()).toBe(1);
+  });
+});
+```
+
+## Integration Tests (HTTP via SELF)
+
+```typescript
+import { SELF } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("Worker HTTP", () => {
+  it("should increment via POST", async () => {
+    const res = await SELF.fetch("http://example.com?id=test", {
+      method: "POST",
+    });
+    
+    expect(res.status).toBe(200);
+    const data = await res.json<{ count: number }>();
+    expect(data.count).toBe(1);
+  });
+
+  it("should get count via GET", async () => {
+    await SELF.fetch("http://example.com?id=get-test", { method: "POST" });
+    await SELF.fetch("http://example.com?id=get-test", { method: "POST" });
+    
+    const res = await SELF.fetch("http://example.com?id=get-test");
+    const data = await res.json<{ count: number }>();
+    expect(data.count).toBe(2);
+  });
+});
+```
+
+## Direct Internal Access
+
+Use `runInDurableObject()` to access instance internals and storage:
+
+```typescript
+import { env, runInDurableObject } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+import { Counter } from "../src";
+
+describe("DO internals", () => {
+  it("can verify storage directly", async () => {
+    const stub = env.COUNTER.getByName("direct-test");
+    await stub.increment();
+    await stub.increment();
+
+    await runInDurableObject(stub, async (instance: Counter, state) => {
+      expect(instance).toBeInstanceOf(Counter);
+      
+      const result = state.storage.sql
+        .exec<{ value: number }>(
+          "SELECT value FROM counters WHERE name = ?",
+          "default"
+        )
+        .one();
+      expect(result.value).toBe(2);
+    });
+  });
+});
+```
+
+## List DO IDs
+
+```typescript
+import { env, listDurableObjectIds } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("DO listing", () => {
+  it("can list all IDs in namespace", async () => {
+    const id1 = env.COUNTER.idFromName("list-1");
+    const id2 = env.COUNTER.idFromName("list-2");
+    
+    await env.COUNTER.get(id1).increment();
+    await env.COUNTER.get(id2).increment();
+    
+    const ids = await listDurableObjectIds(env.COUNTER);
+    expect(ids.length).toBe(2);
+    expect(ids.some(id => id.equals(id1))).toBe(true);
+    expect(ids.some(id => id.equals(id2))).toBe(true);
+  });
+});
+```
+
+## Testing Alarms
+
+Use `runDurableObjectAlarm()` to trigger alarms immediately:
+
+```typescript
+import { env, runInDurableObject, runDurableObjectAlarm } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("DO alarms", () => {
+  it("can trigger alarms immediately", async () => {
+    const stub = env.COUNTER.getByName("alarm-test");
+    await stub.increment();
+    await stub.increment();
+    expect(await stub.getCount()).toBe(2);
+
+    // Schedule alarm
+    await runInDurableObject(stub, async (instance, state) => {
+      await state.storage.setAlarm(Date.now() + 60_000);
+    });
+
+    // Execute immediately without waiting
+    const ran = await runDurableObjectAlarm(stub);
+    expect(ran).toBe(true);
+
+    // Verify alarm handler ran (if it resets counter)
+    expect(await stub.getCount()).toBe(0);
+
+    // No alarm scheduled now
+    const ranAgain = await runDurableObjectAlarm(stub);
+    expect(ranAgain).toBe(false);
+  });
+});
+```
+
+Example alarm handler:
+```typescript
+async alarm(): Promise<void> {
+  this.ctx.storage.sql.exec("DELETE FROM counters");
+}
+```
+
+## Test Isolation
+
+Each test gets isolated storage automatically. DOs from one test don't affect others:
+
+```typescript
+describe("Isolation", () => {
+  it("first test creates DO", async () => {
+    const stub = env.COUNTER.getByName("isolated");
+    await stub.increment();
+    expect(await stub.getCount()).toBe(1);
+  });
+
+  it("second test has fresh state", async () => {
+    const ids = await listDurableObjectIds(env.COUNTER);
+    expect(ids.length).toBe(0); // Previous test's DO is gone
+    
+    const stub = env.COUNTER.getByName("isolated");
+    expect(await stub.getCount()).toBe(0); // Fresh instance
+  });
+});
+```
+
+## SQLite Storage Testing
+
+```typescript
+describe("SQLite", () => {
+  it("can verify SQL storage", async () => {
+    const stub = env.COUNTER.getByName("sqlite-test");
+    await stub.increment("page-views");
+    await stub.increment("page-views");
+    await stub.increment("api-calls");
+
+    await runInDurableObject(stub, async (instance, state) => {
+      const rows = state.storage.sql
+        .exec<{ name: string; value: number }>(
+          "SELECT name, value FROM counters ORDER BY name"
+        )
+        .toArray();
+
+      expect(rows).toEqual([
+        { name: "api-calls", value: 1 },
+        { name: "page-views", value: 2 },
+      ]);
+
+      expect(state.storage.sql.databaseSize).toBeGreaterThan(0);
+    });
+  });
+});
+```
+
+## Running Tests
+
+```bash
+npx vitest        # Watch mode
+npx vitest run    # Single run
+```
+
+package.json:
+```json
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```

package/skills_ref/durable-objects/references/workers.md

@@ -0,0 +1,346 @@
+# Cloudflare Workers Best Practices
+
+High-level guidance for Workers that invoke Durable Objects.
+
+## Wrangler Configuration
+
+### wrangler.jsonc (Recommended)
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-12-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "durable_objects": {
+    "bindings": [
+      { "name": "CHAT_ROOM", "class_name": "ChatRoom" },
+      { "name": "USER_SESSION", "class_name": "UserSession" }
+    ]
+  },
+
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["ChatRoom", "UserSession"] }
+  ],
+
+  // Environment variables
+  "vars": {
+    "ENVIRONMENT": "production"
+  },
+
+  // KV namespaces
+  "kv_namespaces": [
+    { "binding": "CONFIG", "id": "abc123" }
+  ],
+
+  // R2 buckets
+  "r2_buckets": [
+    { "binding": "UPLOADS", "bucket_name": "my-uploads" }
+  ],
+
+  // D1 databases
+  "d1_databases": [
+    { "binding": "DB", "database_id": "xyz789" }
+  ]
+}
+```
+
+### wrangler.toml (Alternative)
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[durable_objects.bindings]]
+name = "CHAT_ROOM"
+class_name = "ChatRoom"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatRoom"]
+
+[vars]
+ENVIRONMENT = "production"
+```
+
+## TypeScript Types
+
+### Environment Interface
+
+```typescript
+// src/types.ts
+import { ChatRoom } from "./durable-objects/chat-room";
+import { UserSession } from "./durable-objects/user-session";
+
+export interface Env {
+  // Durable Objects
+  CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
+  USER_SESSION: DurableObjectNamespace<UserSession>;
+
+  // KV
+  CONFIG: KVNamespace;
+
+  // R2
+  UPLOADS: R2Bucket;
+
+  // D1
+  DB: D1Database;
+
+  // Environment variables
+  ENVIRONMENT: string;
+  API_KEY: string; // From secrets
+}
+```
+
+### Export Durable Object Classes
+
+```typescript
+// src/index.ts
+export { ChatRoom } from "./durable-objects/chat-room";
+export { UserSession } from "./durable-objects/user-session";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Worker handler
+  },
+};
+```
+
+## Worker Handler Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    try {
+      // Route to appropriate handler
+      if (url.pathname.startsWith("/api/rooms")) {
+        return handleRooms(request, env);
+      }
+      if (url.pathname.startsWith("/api/users")) {
+        return handleUsers(request, env);
+      }
+
+      return new Response("Not Found", { status: 404 });
+    } catch (error) {
+      console.error("Request failed:", error);
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  },
+};
+
+async function handleRooms(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url);
+  const roomId = url.searchParams.get("room");
+
+  if (!roomId) {
+    return Response.json({ error: "Missing room parameter" }, { status: 400 });
+  }
+
+  const stub = env.CHAT_ROOM.getByName(roomId);
+
+  if (request.method === "POST") {
+    const body = await request.json<{ userId: string; message: string }>();
+    const result = await stub.sendMessage(body.userId, body.message);
+    return Response.json(result);
+  }
+
+  const messages = await stub.getMessages();
+  return Response.json(messages);
+}
+```
+
+## Request Validation
+
+```typescript
+import { z } from "zod";
+
+const SendMessageSchema = z.object({
+  userId: z.string().min(1),
+  message: z.string().min(1).max(1000),
+});
+
+async function handleSendMessage(request: Request, env: Env): Promise<Response> {
+  const body = await request.json();
+  const result = SendMessageSchema.safeParse(body);
+
+  if (!result.success) {
+    return Response.json(
+      { error: "Validation failed", details: result.error.issues },
+      { status: 400 }
+    );
+  }
+
+  const stub = env.CHAT_ROOM.getByName(result.data.userId);
+  const message = await stub.sendMessage(result.data.userId, result.data.message);
+  return Response.json(message);
+}
+```
+
+## Observability & Logging
+
+### Structured Logging
+
+```typescript
+function log(level: "info" | "warn" | "error", message: string, data?: Record<string, unknown>) {
+  console.log(JSON.stringify({
+    level,
+    message,
+    timestamp: new Date().toISOString(),
+    ...data,
+  }));
+}
+
+// Usage
+log("info", "Request received", { path: url.pathname, method: request.method });
+log("error", "DO call failed", { roomId, error: String(error) });
+```
+
+### Request Tracing
+
+```typescript
+async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const requestId = crypto.randomUUID();
+  const startTime = Date.now();
+
+  try {
+    const response = await processRequest(request, env);
+
+    log("info", "Request completed", {
+      requestId,
+      duration: Date.now() - startTime,
+      status: response.status,
+    });
+
+    return response;
+  } catch (error) {
+    log("error", "Request failed", {
+      requestId,
+      duration: Date.now() - startTime,
+      error: String(error),
+    });
+    throw error;
+  }
+}
+```
+
+### Tail Workers (Production)
+
+For production logging, use Tail Workers to forward logs:
+
+```jsonc
+// wrangler.jsonc
+{
+  "tail_consumers": [
+    { "service": "log-collector" }
+  ]
+}
+```
+
+## Error Handling
+
+### Graceful DO Errors
+
+```typescript
+async function callDO(stub: DurableObjectStub<ChatRoom>, method: string): Promise<Response> {
+  try {
+    const result = await stub.getMessages();
+    return Response.json(result);
+  } catch (error) {
+    if (error instanceof Error) {
+      // DO threw an error
+      log("error", "DO operation failed", { error: error.message });
+      return Response.json(
+        { error: "Service temporarily unavailable" },
+        { status: 503 }
+      );
+    }
+    throw error;
+  }
+}
+```
+
+### Timeout Handling
+
+```typescript
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error("Timeout")), ms)
+  );
+  return Promise.race([promise, timeout]);
+}
+
+// Usage
+const result = await withTimeout(stub.processData(data), 5000);
+```
+
+## CORS Handling
+
+```typescript
+function corsHeaders(): HeadersInit {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+  };
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: corsHeaders() });
+    }
+
+    const response = await handleRequest(request, env);
+    
+    // Add CORS headers to response
+    const newHeaders = new Headers(response.headers);
+    Object.entries(corsHeaders()).forEach(([k, v]) => newHeaders.set(k, v));
+    
+    return new Response(response.body, {
+      status: response.status,
+      headers: newHeaders,
+    });
+  },
+};
+```
+
+## Secrets Management
+
+Set secrets via wrangler CLI (not in config files):
+
+```bash
+wrangler secret put API_KEY
+wrangler secret put DATABASE_URL
+```
+
+Access in code:
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiKey = env.API_KEY; // From secret
+    // ...
+  },
+};
+```
+
+## Development Commands
+
+```bash
+# Local development
+wrangler dev
+
+# Deploy
+wrangler deploy
+
+# Tail logs
+wrangler tail
+
+# List DOs
+wrangler d1 execute DB --command "SELECT * FROM _cf_DO"
+```

package/skills_ref/email-draft-polish/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: email-draft-polish
+description: Draft, rewrite, or condense emails with target tone, length, and audience; use for cold outreach, replies, status updates, or escalations where clarity and brevity matter.
+metadata:
+  short-description: Draft or polish emails to fit tone/length
+---
+
+# Email Draft & Polish
+
+Create or refine emails with precise tone and constraints.
+
+## Inputs to ask for
+- Goal (inform, persuade, apologize, escalate), audience, tone (warm/formal/direct), desired length, must-include points, taboo topics, and call-to-action.
+- If replying: include full thread and whether to quote or paraphrase.
+
+## Workflow
+1) Outline: list the key points, questions, and CTA; confirm any missing facts.
+2) Draft: write a concise body with subject line; keep paragraphs short; surface CTA early.
+3) Variants: offer 2–3 tone/length variants if the ask is vague (e.g., “concise,” “detailed,” “bullet-only”).
+4) QA: check for hedging vs. directness as requested, remove jargon, ensure names/links are correct, and guard against over-promising.
+
+## Output format
+- Subject line, greeting, body, closing/signature placeholder.
+- Optional TL;DR (1–2 sentences) and bullet summary for chat channels.

package/skills_ref/error-message-explainer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: error-message-explainer
+description: Explain compiler/runtime errors in plain language. Use when a junior developer needs help understanding an error message.
+---
+
+# Error Message Explainer
+
+## Purpose
+Explain compiler/runtime errors in plain language.
+
+## Inputs to request
+- Full error text and stack trace.
+- Code snippet around the failing line.
+- Runtime or compiler version.
+
+## Workflow
+1. Restate the error in simple terms.
+2. Point to the most likely offending line or call.
+3. Provide one or two possible fixes.
+
+## Output
+- Plain-language explanation.
+- Fix suggestions with examples.
+
+## Quality bar
+- Cite the exact line or symbol if possible.
+- Offer the smallest viable fix first.