tanuki-telemetry 1.4.0 → 1.4.2

package/install.sh

@@ -7,7 +7,7 @@ set -e
 
 TANUKI_DIR="${TANUKI_DIR:-$HOME/.claude/mcp-servers/telemetry}"
 DATA_DIR="${DATA_DIR:-$HOME/.tanuki/data}"
-VERSION="1.1.0"
+VERSION="1.4.0"
 
 echo ""
 echo "  ┌─────────────────────────┐"
@@ -15,8 +15,8 @@ echo "  │  TANUKI  //  v${VERSION}     │"
 echo "  └─────────────────────────┘"
 echo ""
 
-# Check prerequisites
-command -v docker >/dev/null 2>&1 || { echo "Error: docker is required. Install Docker Desktop first."; exit 1; }
+# Check prerequisites (Node only — no Docker required)
+command -v node >/dev/null 2>&1 || { echo "Error: node is required. Install Node.js 18+ first."; exit 1; }
 command -v git >/dev/null 2>&1 || { echo "Error: git is required."; exit 1; }
 
 # Clone or update
@@ -27,58 +27,90 @@ if [ -d "$TANUKI_DIR/.git" ]; then
 else
   echo "[1/4] Cloning tanuki..."
   mkdir -p "$(dirname "$TANUKI_DIR")"
-  git clone https://github.com/anthropics/tanuki-telemetry.git "$TANUKI_DIR" 2>/dev/null || {
+  git clone https://github.com/ykim-24/tanuki-telemetry.git "$TANUKI_DIR" 2>/dev/null || {
     echo "  Repo not accessible — using local copy"
   }
 fi
 
 cd "$TANUKI_DIR"
 
-# Create data directory
-mkdir -p "$DATA_DIR"
+# Create data directories
+mkdir -p "$DATA_DIR/screenshots"
+mkdir -p "$DATA_DIR/artifacts"
+mkdir -p "$DATA_DIR/walkthrough-screenshots"
 
-# Build Docker images
-echo "[2/4] Building Docker images..."
-docker build -t telemetry-mcp:latest -t telemetry-dashboard:latest . -q
+# Install and build
+echo "[2/4] Building..."
+npm ci --silent 2>/dev/null || npm install --silent
+npm run build
 
-# Stop existing dashboard if running
+# Start dashboard (native Node, no Docker)
 echo "[3/4] Starting dashboard..."
-docker rm -f telemetry-dashboard 2>/dev/null || true
-docker run -d --rm \
-  --name telemetry-dashboard \
-  -p 3333:3333 \
-  -v "$DATA_DIR:/data" \
-  telemetry-dashboard:latest
+chmod +x start-dashboard.sh
+DATA_DIR="$DATA_DIR" ./start-dashboard.sh stop 2>/dev/null || true
+DATA_DIR="$DATA_DIR" ./start-dashboard.sh start
 
-# Configure Claude Code MCP
-echo "[4/4] Configuring Claude Code..."
+# Install skills
+echo "[4/5] Installing skills..."
+mkdir -p "$HOME/.claude/commands" "$HOME/.claude/scripts"
+for cmd in skills/commands/*.md; do
+  [ -f "$cmd" ] && cp "$cmd" "$HOME/.claude/commands/" && echo "  ✓ $(basename "$cmd")"
+done
+for script in skills/scripts/*; do
+  [ -f "$script" ] && cp "$script" "$HOME/.claude/scripts/" && chmod +x "$HOME/.claude/scripts/$(basename "$script")" && echo "  ✓ $(basename "$script")"
+done
+
+# Configure Claude Code MCP (native Node, no Docker)
+echo "[5/5] Configuring Claude Code..."
 CLAUDE_CONFIG="$HOME/.claude.json"
 if [ -f "$CLAUDE_CONFIG" ]; then
-  # Check if telemetry MCP is already configured
   if grep -q '"telemetry"' "$CLAUDE_CONFIG" 2>/dev/null; then
-    echo "  MCP already configured in .claude.json"
+    # Update to native mode
+    python3 -c "
+import json
+with open('$CLAUDE_CONFIG', 'r') as f:
+    config = json.load(f)
+config['mcpServers']['telemetry'] = {
+    'type': 'stdio',
+    'command': 'node',
+    'args': ['$TANUKI_DIR/dist/index.js'],
+    'env': {'DATA_DIR': '$DATA_DIR'}
+}
+with open('$CLAUDE_CONFIG', 'w') as f:
+    json.dump(config, f, indent=2)
+"
+    echo "  ✓ Updated MCP config to native mode"
   else
-    echo "  Add this to your .claude.json mcpServers:"
-    echo ""
-    echo '  "telemetry": {'
-    echo '    "type": "stdio",'
-    echo '    "command": "docker",'
-    echo '    "args": ["run", "--rm", "-i", "-v", "'$DATA_DIR':/data", "--entrypoint", "node", "telemetry-mcp:latest", "dist/index.js"]'
-    echo '  }'
-    echo ""
+    python3 -c "
+import json
+with open('$CLAUDE_CONFIG', 'r') as f:
+    config = json.load(f)
+if 'mcpServers' not in config:
+    config['mcpServers'] = {}
+config['mcpServers']['telemetry'] = {
+    'type': 'stdio',
+    'command': 'node',
+    'args': ['$TANUKI_DIR/dist/index.js'],
+    'env': {'DATA_DIR': '$DATA_DIR'}
+}
+with open('$CLAUDE_CONFIG', 'w') as f:
+    json.dump(config, f, indent=2)
+"
+    echo "  ✓ Added telemetry MCP to .claude.json"
   fi
 else
-  echo "  No .claude.json found — create one with:"
+  echo "  Add this to your .claude.json:"
   echo ""
-  echo '  { "mcpServers": { "telemetry": { "type": "stdio", "command": "docker", "args": ["run", "--rm", "-i", "-v", "'$DATA_DIR':/data", "--entrypoint", "node", "telemetry-mcp:latest", "dist/index.js"] } } }'
+  echo "  \"mcpServers\": { \"telemetry\": { \"type\": \"stdio\", \"command\": \"node\", \"args\": [\"$TANUKI_DIR/dist/index.js\"], \"env\": { \"DATA_DIR\": \"$DATA_DIR\" } } }"
   echo ""
 fi
 
-# Wait for dashboard to start
+# Verify
 sleep 2
-if curl -s http://localhost:3333/health | grep -q '"ok":true'; then
+if curl -s http://localhost:3333/health 2>/dev/null | grep -q '"ok":true'; then
   echo ""
-  echo "  Tanuki is running at http://localhost:3333"
+  echo "  ✓ Tanuki is running at http://localhost:3333"
+  echo "  ✓ Restart Claude Code to connect the MCP server"
   echo ""
 else
   echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanuki-telemetry",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Workflow monitor and telemetry dashboard for Claude Code autonomous agents",
   "type": "module",
   "bin": {

package/skills/commands/compare-image.md

@@ -0,0 +1,414 @@
+# Compare Image — Visual Diff with Qualitative Annotations
+
+Compare two sets of images (reference vs actual) with pixel-diff heatmaps and qualitative callouts. Works for any before/after image comparison: UI screenshots, design mockups, rendered templates, chart output, etc.
+
+## Usage
+
+```
+/compare-image <ref-dir> <actual-dir>
+/compare-image ./mockups ./screenshots
+/compare-image --ref ./expected --actual ./output --session-id=<existing-session>
+/compare-image --ref ./v1-screenshots --actual ./v2-screenshots --output-dir=./diffs
+```
+
+**Arguments:**
+- `ref-dir`: Directory containing reference (expected) images — PNGs, numbered or named.
+- `actual-dir`: Directory containing actual (generated/current) images to compare against.
+- `--session-id=<id>`: Attach to an existing telemetry session instead of creating a new one.
+- `--output-dir=<path>`: Override output directory (default: `$TANUKI_OUTPUTS/comparisons/`)
+- `--label=<name>`: Label for this comparison set (default: derived from directory names).
+
+---
+
+## Prerequisites
+
+- **Python packages:** `fitz` (PyMuPDF — only if comparing PDFs), `PIL` (Pillow), `numpy`
+- **agent-browser** via `npx agent-browser` (only if capturing live screenshots)
+
+---
+
+## Workflow
+
+### Phase 1: Setup & Discovery
+
+1. **Parse arguments** — extract directories and flags.
+2. **Create telemetry session** (unless `--session-id` provided):
+   ```
+   mcp__telemetry__log_session_start({ worktree_name: "image-comparison-<date>" })
+   ```
+3. **Discover image pairs** — match reference and actual images by filename or index:
+   - Sort both directories by filename
+   - Pair them 1:1 (ref-01.png ↔ actual-01.png, or by matching name stems)
+   - Report any unmatched images
+4. **Log event** with pair count and any mismatches.
+
+### Phase 2: Prepare Reference Images
+
+Depending on your source format, prepare reference PNGs:
+
+- **Already PNGs:** Use directly — no conversion needed.
+- **From PDF:** Render pages to PNGs via PyMuPDF:
+  ```python
+  import fitz
+  doc = fitz.open(pdf_path)
+  for i, page in enumerate(doc):
+      zoom = 1920 / page.rect.width
+      mat = fitz.Matrix(zoom, zoom)
+      pix = page.get_pixmap(matrix=mat)
+      pix.save(f'ref/image-{i+1:02d}.png')
+  ```
+- **From live URL:** Capture with agent-browser:
+  ```bash
+  npx agent-browser --url "http://localhost:3000/page" --width 1920 --height 1080 --output ref/page.png
+  ```
+
+### Phase 3: Prepare Actual Images
+
+Same as Phase 2 — get actual/generated images as PNGs by whatever method fits your use case (screenshots, renders, exports, etc.).
+
+### Phase 4: Qualitative Analysis (visual review)
+
+For each image pair, **read both images** and identify every meaningful difference. Think of this as a visual code review — call out specifics, not just "things changed."
+
+| Category | What to look for |
+|----------|-----------------|
+| **Layout** | Element positioning, spacing, alignment, column/grid structure |
+| **Text** | Content differences, missing text, placeholder values, truncation |
+| **Images/icons** | Missing assets, wrong variants, broken renders, placeholder boxes |
+| **Color/style** | Background, accent colors, borders, gradients, opacity |
+| **Typography** | Font size, weight, color, line height changes |
+| **Data** | Missing values, wrong numbers, empty states |
+| **Chrome/UI** | Headers, footers, navigation, page numbers, timestamps |
+
+**Severity classification:**
+- **CRITICAL** (red): Missing content, broken layout, data that should exist but doesn't
+- **NOTABLE** (yellow): Important differences — content changes, removed elements, placeholder values
+- **MINOR** (blue): Rendering differences — font antialiasing, sub-pixel spacing, minor color shifts
+- **GOOD** (green): Things that match correctly — always include at least one positive finding per pair
+
+Build a `callouts` list for each pair: `[{severity, title, details}]` (max 4 per image).
+
+### Phase 5: Generate Comparison Images
+
+Each comparison image has three columns plus qualitative callout boxes.
+
+**Layout:**
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Title: "Page 3 — Dashboard"                              [DIFF 18.2%] │
+├────────────────────────┬──────────────────────┬──────────────────────────┤
+│  REFERENCE             │  PIXEL DIFF HEATMAP  │  ACTUAL                  │
+│  (Expected)            │  (red = changes)     │  (Current)               │
+│  [green border]        │  [red border]        │  [blue border]           │
+│  [533x450]             │  [533x450]           │  [533x450]              │
+├────────────────────────┴──────────────────────┴──────────────────────────┤
+│  DIFFERENCES:                                                            │
+│  ┌─CRITICAL────────┐ ┌─NOTABLE─────────┐ ┌─MINOR──────────┐ ┌─GOOD───┐│
+│  │ Title           │ │ Title           │ │ Title          │ │ Title   ││
+│  │ Details...      │ │ Details...      │ │ Details...     │ │ Details ││
+│  └─────────────────┘ └─────────────────┘ └────────────────┘ └─────────┘│
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+**Python implementation** (Pillow + numpy):
+
+```python
+from PIL import Image, ImageDraw, ImageFont, ImageFilter
+import numpy as np
+
+# --- Constants ---
+COL_W, COL_H = 533, 450   # 3 equal columns
+CALLOUT_H = 170
+PAD = 20
+
+COLORS = {
+    "critical": ((200, 40, 40), (255, 80, 80)),
+    "notable":  ((180, 130, 0), (255, 200, 50)),
+    "minor":    ((60, 130, 180), (100, 180, 240)),
+    "good":     ((40, 150, 40), (80, 200, 80)),
+}
+
+try:
+    FONT_TITLE   = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 28)
+    FONT_LABEL   = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 18)
+    FONT_CALLOUT = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 14)
+    FONT_SMALL   = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 12)
+except Exception:
+    FONT_TITLE = FONT_LABEL = FONT_CALLOUT = FONT_SMALL = ImageFont.load_default()
+
+
+def normalize_to_size(img, target_w, target_h, bg_color=(255, 255, 255)):
+    """
+    Scale image to fit within target_w x target_h preserving aspect ratio,
+    then center it on a background. No stretching, no black bars.
+    """
+    img_w, img_h = img.size
+    scale = min(target_w / img_w, target_h / img_h)
+    new_w = int(img_w * scale)
+    new_h = int(img_h * scale)
+    scaled = img.resize((new_w, new_h), Image.LANCZOS)
+
+    canvas = Image.new("RGB", (target_w, target_h), bg_color)
+    offset_x = (target_w - new_w) // 2
+    offset_y = (target_h - new_h) // 2
+    canvas.paste(scaled, (offset_x, offset_y))
+    return canvas
+
+
+def compute_diff_heatmap(ref, gen, threshold=25):
+    """
+    Compute a red pixel-diff heatmap overlaid on the actual image.
+    Returns (overlay_image, diff_percentage).
+    """
+    ref_arr = np.array(ref.convert("RGB"), dtype=np.float32)
+    gen_arr = np.array(gen.convert("RGB"), dtype=np.float32)
+    diff = np.abs(ref_arr - gen_arr).mean(axis=2)  # grayscale diff per pixel
+
+    diff_pct = (diff > threshold).sum() / diff.size * 100
+
+    # Normalize diff to 0-255 intensity
+    diff_norm = np.clip(diff * (255 / max(diff.max(), 1)), 0, 255).astype(np.uint8)
+
+    # Create red overlay: high-diff pixels get bright red, low-diff transparent
+    overlay_rgba = np.zeros((*diff_norm.shape, 4), dtype=np.uint8)
+    mask = diff_norm > threshold
+    overlay_rgba[mask, 0] = 255                          # R
+    overlay_rgba[mask, 1] = 0                            # G
+    overlay_rgba[mask, 2] = 0                            # B
+    overlay_rgba[mask, 3] = np.clip(diff_norm[mask], 60, 180)  # A (semi-transparent)
+
+    red_overlay = Image.fromarray(overlay_rgba, mode="RGBA")
+    heatmap = Image.alpha_composite(gen.convert("RGBA"), red_overlay).convert("RGB")
+
+    return heatmap, diff_pct
+
+
+def create_comparison(ref_path, gen_path, out_path, label, callouts):
+    """
+    Generate a full comparison image with 3 columns side by side:
+    REFERENCE | HEATMAP | ACTUAL — all same height, equal width.
+    Plus qualitative callout boxes below.
+    """
+    ref = normalize_to_size(Image.open(ref_path), COL_W, COL_H)
+    gen = normalize_to_size(Image.open(gen_path), COL_W, COL_H)
+
+    heatmap, diff_pct = compute_diff_heatmap(ref, gen)
+    heatmap_col = heatmap
+
+    content_w = COL_W * 3 + PAD * 4
+    total_h = PAD + 40 + 24 + COL_H + PAD + 24 + CALLOUT_H + PAD
+    canvas = Image.new("RGB", (content_w, total_h), (25, 25, 25))
+    draw = ImageDraw.Draw(canvas)
+
+    y = PAD
+
+    # --- Title bar + diff badge ---
+    draw.text((PAD, y), label, fill=(255, 255, 255), font=FONT_TITLE)
+    badge_text = f"DIFF {diff_pct:.1f}%"
+    if diff_pct < 5:
+        badge_color = (40, 150, 40)
+    elif diff_pct < 20:
+        badge_color = (180, 130, 0)
+    else:
+        badge_color = (200, 40, 40)
+    badge_x = content_w - PAD - 140
+    draw.rectangle([badge_x, y, badge_x + 130, y + 30], fill=badge_color)
+    draw.text((badge_x + 8, y + 6), badge_text, fill=(255, 255, 255), font=FONT_LABEL)
+    y += 44
+
+    # --- Column labels ---
+    col1_x = PAD
+    col2_x = PAD * 2 + COL_W
+    col3_x = PAD * 3 + COL_W * 2
+    draw.text((col1_x, y), "REFERENCE (Expected)", fill=(140, 200, 140), font=FONT_LABEL)
+    draw.text((col2_x, y), "PIXEL DIFF HEATMAP", fill=(200, 120, 120), font=FONT_LABEL)
+    draw.text((col3_x, y), "ACTUAL (Current)", fill=(140, 160, 240), font=FONT_LABEL)
+    y += 24
+
+    # --- 3 images side by side ---
+    canvas.paste(ref, (col1_x, y))
+    canvas.paste(heatmap_col, (col2_x, y))
+    canvas.paste(gen, (col3_x, y))
+    draw.rectangle([col1_x - 1, y - 1, col1_x + COL_W, y + COL_H], outline=(100, 200, 100), width=2)
+    draw.rectangle([col2_x - 1, y - 1, col2_x + COL_W, y + COL_H], outline=(200, 60, 60), width=2)
+    draw.rectangle([col3_x - 1, y - 1, col3_x + COL_W, y + COL_H], outline=(100, 120, 240), width=2)
+    y += COL_H + PAD
+
+    # --- Callout boxes ---
+    draw.text((PAD, y), "DIFFERENCES:", fill=(220, 220, 220), font=FONT_LABEL)
+    y += 24
+    num = min(len(callouts), 4)
+    if num > 0:
+        box_w = (content_w - PAD * (num + 1)) // num
+        box_h = CALLOUT_H - 30
+        for i, c in enumerate(callouts[:4]):
+            bx = PAD + i * (box_w + PAD)
+            bg, accent = COLORS.get(c["severity"], COLORS["minor"])
+            draw.rectangle([bx, y, bx + box_w, y + box_h], fill=(40, 40, 40), outline=accent, width=2)
+            draw.rectangle([bx + 2, y + 2, bx + 80, y + 20], fill=bg)
+            draw.text((bx + 6, y + 3), c["severity"].upper(), fill=(255, 255, 255), font=FONT_SMALL)
+            draw.text((bx + 8, y + 24), c["title"], fill=accent, font=FONT_CALLOUT)
+            # Wrap details text
+            words = c["details"].split()
+            lines, current = [], ""
+            for w in words:
+                test = f"{current} {w}".strip()
+                bbox = draw.textbbox((0, 0), test, font=FONT_SMALL)
+                if bbox[2] - bbox[0] > box_w - 16 and current:
+                    lines.append(current)
+                    current = w
+                else:
+                    current = test
+            if current:
+                lines.append(current)
+            for j, line in enumerate(lines[:4]):
+                draw.text((bx + 8, y + 42 + j * 16), line, fill=(200, 200, 200), font=FONT_SMALL)
+
+    canvas.save(out_path, quality=95)
+    return diff_pct
+```
+
+### Phase 6: Upload to Telemetry (structured findings)
+
+Each image comparison produces telemetry artifacts: a screenshot, structured finding events per callout, and an image-level summary event.
+
+#### 6a. Screenshots per image pair
+
+**The comparison image is always the primary output:**
+```
+mcp__telemetry__log_screenshot({
+  session_id,
+  phase: "verification",
+  description: "[COMPARISON] <label> <N> — <highest severity>: <key finding>",
+  file_path: "<absolute path to comparison PNG>"
+})
+```
+
+Also log as an artifact for download/browsing on the dashboard:
+```
+mcp__telemetry__log_artifact({
+  session_id,
+  file_path: "<absolute path to comparison PNG>",
+  artifact_type: "comparison",
+  description: "<label> image <N> comparison",
+  metadata: { label: "<label>", image_number: <N>, diff_pct: <X.X> }
+})
+```
+
+#### 6b. Structured finding event per callout
+
+For **each individual finding**, log a `comparison_finding` event with queryable metadata:
+
+```
+mcp__telemetry__log_event({
+  session_id,
+  phase: "verification",
+  event_type: "info",
+  message: "<severity>: <title> — <label> image <N>",
+  metadata: {
+    type: "comparison_finding",
+    label: "<label>",
+    image_number: <N>,
+    image_name: "<filename>",
+    severity: "<critical|notable|minor|good>",
+    finding_title: "<short title>",
+    finding_details: "<full description>",
+    diff_pct: <X.X>,
+    comparison_image: "<absolute path>",
+    ref_image: "<absolute path>",
+    actual_image: "<absolute path>"
+  }
+})
+```
+
+#### 6c. Image-level summary event
+
+After logging all findings for an image pair:
+
+```
+mcp__telemetry__log_event({
+  session_id,
+  phase: "verification",
+  event_type: "info",
+  message: "Compared <label> image <N> (<name>) — <highest severity>, diff <X.X>%",
+  metadata: {
+    type: "comparison_image_summary",
+    label: "<label>",
+    image_number: <N>,
+    image_name: "<filename>",
+    diff_pct: <X.X>,
+    highest_severity: "<critical|notable|minor|good>",
+    finding_count: { critical: <N>, notable: <N>, minor: <N>, good: <N> },
+    comparison_image: "<absolute path>"
+  }
+})
+```
+
+#### 6d. Final rollup event
+
+After all image pairs:
+
+```
+mcp__telemetry__log_event({
+  session_id,
+  phase: "deliverables",
+  event_type: "info",
+  message: "Image comparison complete — <N> images, <C> critical, <N> notable findings",
+  metadata: {
+    type: "comparison_rollup",
+    label: "<label>",
+    total_images: <N>,
+    total_findings: <N>,
+    by_severity: { critical: <N>, notable: <N>, minor: <N>, good: <N> },
+    avg_diff_pct: <X.X>
+  }
+})
+```
+
+#### Querying findings programmatically
+
+```sql
+-- All critical findings across sessions
+SELECT * FROM events
+WHERE metadata->>'type' = 'comparison_finding'
+  AND metadata->>'severity' = 'critical';
+
+-- All findings for a specific comparison
+SELECT * FROM events
+WHERE metadata->>'type' = 'comparison_finding'
+  AND metadata->>'label' = 'homepage-redesign';
+
+-- Image summaries sorted by diff percentage
+SELECT * FROM events
+WHERE metadata->>'type' = 'comparison_image_summary'
+ORDER BY (metadata->>'diff_pct')::float DESC;
+```
+
+### Phase 7: Summary Output
+
+```markdown
+## Image Comparison Results
+
+| Image | Diff % | Severity | Key Finding |
+|-------|:------:|----------|-------------|
+| 01 — Homepage | 12.3% | NOTABLE | Header layout shifted, CTA button color changed |
+| 02 — Dashboard | 18.2% | CRITICAL | Chart data missing, sidebar collapsed |
+| ... | ... | ... | ... |
+
+**Critical:** <count> images
+**Notable:** <count> images
+**Good:** <count> images
+
+**Output:** <output-dir>/comparisons/
+**Telemetry:** Session <id>
+```
+
+---
+
+## Common Use Cases
+
+- **UI regression testing:** Compare screenshots before/after a code change
+- **Design fidelity:** Compare design mockup PNGs against implemented page screenshots
+- **Generated content:** Compare expected output against LLM/AI-generated output
+- **Email templates:** Compare HTML email reference renders against actual sends
+- **Chart/data viz:** Compare expected chart renders against actual output