@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/resend/references/send-email.md

@@ -0,0 +1,318 @@
+# Send Email with Resend
+
+## Overview
+
+Resend provides two endpoints for sending emails:
+
+| Approach   | Endpoint             | Use Case                                                                  |
+| ---------- | -------------------- | ------------------------------------------------------------------------- |
+| **Single** | `POST /emails`       | Individual transactional emails, emails with attachments, scheduled sends |
+| **Batch**  | `POST /emails/batch` | Multiple distinct emails in one request (max 100), bulk notifications     |
+
+**Choose batch when:**
+
+- Sending 2+ distinct emails at once
+- Reducing API calls is important (rate limit: 2 requests/second by default)
+- No attachments or scheduling needed
+
+**Choose single when:**
+
+- Sending one email
+- Email needs attachments
+- Email needs to be scheduled
+- Different recipients need different timing
+
+## Quick Start
+
+1. **Detect project language** from config files (package.json, requirements.txt, go.mod, etc.)
+2. **Install SDK** (preferred) or use cURL
+3. **Choose single or batch** based on decision matrix above
+4. **Implement best practices** - Idempotency keys, error handling, retries
+
+## Single Email
+
+**Endpoint:** `POST /emails` (prefer SDK over cURL)
+
+### Required Parameters
+
+| Parameter        | Type     | Description                                         |
+| ---------------- | -------- | --------------------------------------------------- |
+| `from`           | string   | Sender address. Format: `"Name <email@domain.com>"` |
+| `to`             | string[] | Recipient addresses (max 50)                        |
+| `subject`        | string   | Email subject line                                  |
+| `html` or `text` | string   | Email body content                                  |
+
+### Optional Parameters
+
+| Parameter      | Type     | Description                       |
+| -------------- | -------- | --------------------------------- |
+| `cc`           | string[] | CC recipients                     |
+| `bcc`          | string[] | BCC recipients                    |
+| `reply_to`     | string[] | Reply-to addresses                |
+| `scheduled_at` | string   | Schedule send time (ISO 8601)     |
+| `attachments`  | array    | File attachments (max 40MB total) |
+| `tags`         | array    | Key/value pairs for tracking      |
+| `headers`      | object   | Custom headers                    |
+
+### Example (Node.js)
+
+```typescript
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+const { data, error } = await resend.emails.send(
+  {
+    from: "Acme <onboarding@resend.dev>",
+    to: ["delivered@resend.dev"],
+    subject: "Hello World",
+    html: "<p>Email body here</p>",
+  },
+  { idempotencyKey: `welcome-email/${userId}` },
+);
+
+if (error) {
+  console.error("Failed:", error.message);
+  return;
+}
+console.log("Sent:", data.id);
+```
+
+### Example (Python)
+
+```python
+import resend
+import os
+
+resend.api_key = os.environ["RESEND_API_KEY"]
+
+params: resend.Emails.SendParams = {
+    "from": "Acme <onboarding@resend.dev>",
+    "to": ["delivered@resend.dev"],
+    "subject": "Hello World",
+    "html": "<p>Email body here</p>",
+}
+
+email = resend.Emails.send(params)
+print(email)
+```
+
+## Batch Email
+
+**Endpoint:** `POST /emails/batch`
+
+### Limitations
+
+- **No attachments** - Use single sends for emails with attachments
+- **No scheduling** - Use single sends for scheduled emails
+- **Atomic** - If one email fails validation, the entire batch fails
+- **Max 100 emails** per request
+- **Max 50 recipients** per individual email in the batch
+
+### Example (Node.js)
+
+```typescript
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+const { data, error } = await resend.batch.send(
+  [
+    {
+      from: "Acme <notifications@acme.com>",
+      to: ["delivered@resend.dev"],
+      subject: "Order Shipped",
+      html: "<p>Your order has shipped!</p>",
+    },
+    {
+      from: "Acme <notifications@acme.com>",
+      to: ["delivered@resend.dev"],
+      subject: "Order Confirmed",
+      html: "<p>Your order is confirmed!</p>",
+    },
+  ],
+  { idempotencyKey: `batch-orders/${batchId}` },
+);
+
+if (error) {
+  console.error("Batch failed:", error.message);
+  return;
+}
+console.log(
+  "Sent:",
+  data.map((e) => e.id),
+);
+```
+
+## Large Batches (100+ Emails)
+
+For sends larger than 100 emails, chunk into multiple batch requests:
+
+1. **Split into chunks** of 100 emails each
+2. **Use unique idempotency keys** per chunk: `<batch-prefix>/chunk-<index>`
+3. **Send chunks in parallel** for better throughput
+4. **Track results** per chunk to handle partial failures
+
+## Best Practices
+
+### Idempotency Keys
+
+Prevent duplicate emails when retrying failed requests.
+
+| Key Facts           |                                                                  |
+| ------------------- | ---------------------------------------------------------------- |
+| **Format (single)** | `<event-type>/<entity-id>` (e.g., `welcome-email/user-123`)      |
+| **Format (batch)**  | `batch-<event-type>/<batch-id>` (e.g., `batch-orders/batch-456`) |
+| **Expiration**      | 24 hours                                                         |
+| **Max length**      | 256 characters                                                   |
+
+### Error Handling
+
+| Code     | Action                                            |
+| -------- | ------------------------------------------------- |
+| 400, 422 | Fix request parameters, don't retry               |
+| 401, 403 | Check API key / verify domain, don't retry        |
+| 409      | Idempotency conflict - use new key or fix payload |
+| 429      | Rate limited - retry with exponential backoff     |
+| 500      | Server error - retry with exponential backoff     |
+
+### Retry Strategy
+
+```typescript
+async function sendWithRetry(emailData, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    const { data, error } = await resend.emails.send(emailData);
+
+    if (!error) return data;
+
+    // Don't retry client errors
+    if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+      throw error;
+    }
+
+    // Exponential backoff for rate limits and server errors
+    const delay = Math.pow(2, i) * 1000;
+    await new Promise((r) => setTimeout(r, delay));
+  }
+  throw new Error("Max retries exceeded");
+}
+```
+
+## Deliverability
+
+### Required
+
+| Practice                       | Why                                     |
+| ------------------------------ | --------------------------------------- |
+| **Valid SPF, DKIM, DMARC**     | Authenticate email, prevent spoofing    |
+| **Links match sending domain** | Mismatched domains trigger spam filters |
+| **Include plain text version** | Accessibility and deliverability        |
+| **Avoid "no-reply" addresses** | Use real addresses for trust signals    |
+| **Keep body under 102KB**      | Gmail clips larger messages             |
+
+### Recommended
+
+| Practice                               | Why                                                  |
+| -------------------------------------- | ---------------------------------------------------- |
+| **Use subdomains**                     | Protects reputation (e.g., `notifications.acme.com`) |
+| **Disable tracking for transactional** | Open/click tracking can trigger spam filters         |
+
+## Webhooks
+
+Track email delivery status in real-time:
+
+| Event                            | When to use                          |
+| -------------------------------- | ------------------------------------ |
+| `email.delivered`                | Confirm successful delivery          |
+| `email.bounced`                  | Remove from mailing list, alert user |
+| `email.complained`               | Unsubscribe user (spam complaint)    |
+| `email.opened` / `email.clicked` | Track engagement (marketing only)    |
+
+**Always verify webhook signatures:**
+
+```typescript
+const event = resend.webhooks.verify({
+  payload,
+  headers: {
+    "svix-id": req.headers.get("svix-id"),
+    "svix-timestamp": req.headers.get("svix-timestamp"),
+    "svix-signature": req.headers.get("svix-signature"),
+  },
+  secret: process.env.RESEND_WEBHOOK_SECRET,
+});
+```
+
+## Tags
+
+Key/value pairs for tracking and filtering:
+
+```typescript
+tags: [
+  { name: "user_id", value: "usr_123" },
+  { name: "email_type", value: "welcome" },
+  { name: "plan", value: "enterprise" },
+];
+```
+
+**Constraints:** ASCII letters, numbers, underscores, dashes only. Max 256 chars each.
+
+## Templates
+
+Use pre-built templates instead of sending HTML:
+
+```typescript
+const { data, error } = await resend.emails.send({
+  from: "Acme <hello@acme.com>",
+  to: ["delivered@resend.dev"],
+  subject: "Welcome!",
+  template: {
+    id: "tmpl_abc123",
+    variables: {
+      USER_NAME: "John", // Case-sensitive!
+      ORDER_TOTAL: "$99.00",
+    },
+  },
+});
+```
+
+**Important:** Variable names are **case-sensitive**. Templates must be **published** before use.
+
+## Testing
+
+**Never test with fake addresses at real providers (`test@gmail.com`)** - destroys reputation.
+
+### Safe Testing
+
+| Method         | Address                 | Result                        |
+| -------------- | ----------------------- | ----------------------------- |
+| **Delivered**  | `delivered@resend.dev`  | Simulates successful delivery |
+| **Bounced**    | `bounced@resend.dev`    | Simulates hard bounce         |
+| **Complained** | `complained@resend.dev` | Simulates spam complaint      |
+
+## Domain Warm-up
+
+New domains must gradually increase volume:
+
+**New domain schedule:**
+| Day | Max emails/day |
+|-----|---------------|
+| 1 | 150 |
+| 2 | 250 |
+| 3 | 400 |
+| 4 | 700 |
+| 5 | 1,000 |
+| 6 | 1,500 |
+| 7 | 2,000 |
+
+**Monitor:** Bounce rate < 4%, Spam complaint rate < 0.08%
+
+## Common Mistakes
+
+| Mistake                          | Fix                                   |
+| -------------------------------- | ------------------------------------- |
+| Retrying without idempotency key | Always include - prevents duplicates  |
+| Batch for attachments            | Use single sends instead              |
+| Retrying 400/422 errors          | Fix request, don't retry              |
+| Tracking on transactional        | Disable for receipts, password resets |
+| Testing with fake emails         | Use `delivered@resend.dev`            |
+| High volume on new domain        | Warm up gradually                     |

package/dist/template/.opencode/skill/root-cause-tracing/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: root-cause-tracing
+description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
+version: 1.0.0
+tags: [debugging, workflow]
+dependencies: []
+---
+
+# Root Cause Tracing
+
+> **Replaces** ad-hoc print-statement debugging and "try random fixes until it works" approaches
+
+## When to Use
+
+- Errors occur deep in a call stack and the immediate failure is just a symptom
+- You need to trace where invalid data or state originated
+
+## When NOT to Use
+
+- The error is at the entry point and the root cause is obvious
+- You’re doing feature work with no failures to trace
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Fixing symptoms where error appears | Hides origin; bug returns via other paths | Trace backward until original trigger is found |
+| Skipping stack trace analysis | Misses the real caller and bad input source | Read full stack, file paths, and line numbers first |
+| Adding instrumentation without hypothesis | Produces noisy logs and slows investigation | Instrument one boundary at a time to answer a specific question |
+| Guessing the cause without evidence | Leads to random fixes and regressions | Form evidence-backed hypothesis, then test |
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+
+**What code directly causes this?**
+
+```typescript
+await execFileAsync("git", ["init"], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+
+**What value was passed?**
+
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+
+**Where did empty string come from?**
+
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create("name", context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error("DEBUG git init:", {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync("git", ["init"], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script: @find-polluter.sh
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution
+
+## See Also
+
+- **systematic-debugging** - Full four-phase process before/after tracing deep stack failures

package/dist/template/.opencode/skill/root-cause-tracing/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0