@ramarivera/coding-buddy 0.4.0-alpha.1

package/cli/backup.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env bun
+/**
+ * claude-buddy backup — snapshot all claude-buddy related state
+ *
+ * Usage:
+ *   bun run backup                 Create a new snapshot
+ *   bun run backup list            List all backups
+ *   bun run backup show <ts>       Show what's in a backup
+ *   bun run backup restore         Restore the latest backup
+ *   bun run backup restore <ts>    Restore a specific backup
+ *   bun run backup delete <ts>     Delete a specific backup
+ *
+ * Backups are stored in ~/.claude-buddy/backups/YYYY-MM-DD-HHMMSS/
+ *
+ * What gets backed up:
+ *   - ~/.claude/settings.json (full file)
+ *   - ~/.claude.json mcpServers["claude-buddy"] block (only our entry)
+ *   - ~/.claude/skills/buddy/SKILL.md
+ *   - ~/.claude-buddy/companion.json
+ *   - ~/.claude-buddy/status.json
+ *   - ~/.claude-buddy/reaction.json
+ */
+
+import {
+  readFileSync, writeFileSync, mkdirSync, existsSync,
+  readdirSync, statSync, rmSync, copyFileSync,
+} from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const HOME = homedir();
+const BACKUPS_DIR = join(HOME, ".claude-buddy", "backups");
+const SETTINGS = join(HOME, ".claude", "settings.json");
+const CLAUDE_JSON = join(HOME, ".claude.json");
+const SKILL = join(HOME, ".claude", "skills", "buddy", "SKILL.md");
+const STATE_DIR = join(HOME, ".claude-buddy");
+
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const NC = "\x1b[0m";
+
+function ok(msg: string) { console.log(`${GREEN}✓${NC}  ${msg}`); }
+function info(msg: string) { console.log(`${CYAN}→${NC}  ${msg}`); }
+function warn(msg: string) { console.log(`${YELLOW}⚠${NC}  ${msg}`); }
+function err(msg: string) { console.log(`${RED}✗${NC}  ${msg}`); }
+
+function timestamp(): string {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function tryRead(path: string): string | null {
+  try { return readFileSync(path, "utf8"); } catch { return null; }
+}
+
+function listBackups(): string[] {
+  if (!existsSync(BACKUPS_DIR)) return [];
+  return readdirSync(BACKUPS_DIR)
+    .filter(f => /^\d{4}-\d{2}-\d{2}-\d{6}$/.test(f))
+    .filter(f => statSync(join(BACKUPS_DIR, f)).isDirectory())
+    .sort();
+}
+
+// ─── Create backup ──────────────────────────────────────────────────────────
+
+function createBackup(): string {
+  const ts = timestamp();
+  const dir = join(BACKUPS_DIR, ts);
+  mkdirSync(dir, { recursive: true });
+
+  const manifest: Record<string, any> = { timestamp: ts, files: [] };
+
+  // 1. settings.json
+  const settings = tryRead(SETTINGS);
+  if (settings) {
+    writeFileSync(join(dir, "settings.json"), settings);
+    manifest.files.push("settings.json");
+    ok(`Backed up: ~/.claude/settings.json`);
+  } else {
+    warn(`Skipped: ~/.claude/settings.json (not found)`);
+  }
+
+  // 2. claude.json mcpServers["claude-buddy"]
+  const claudeJsonRaw = tryRead(CLAUDE_JSON);
+  if (claudeJsonRaw) {
+    try {
+      const claudeJson = JSON.parse(claudeJsonRaw);
+      const ourMcp = claudeJson.mcpServers?.["claude-buddy"];
+      if (ourMcp) {
+        writeFileSync(join(dir, "mcpserver.json"), JSON.stringify(ourMcp, null, 2));
+        manifest.files.push("mcpserver.json");
+        ok(`Backed up: ~/.claude.json → mcpServers["claude-buddy"]`);
+      } else {
+        warn(`Skipped: ~/.claude.json mcpServers["claude-buddy"] (not registered)`);
+      }
+    } catch {
+      err(`Failed to parse ~/.claude.json`);
+    }
+  }
+
+  // 3. SKILL.md
+  const skill = tryRead(SKILL);
+  if (skill) {
+    writeFileSync(join(dir, "SKILL.md"), skill);
+    manifest.files.push("SKILL.md");
+    ok(`Backed up: ~/.claude/skills/buddy/SKILL.md`);
+  } else {
+    warn(`Skipped: ~/.claude/skills/buddy/SKILL.md (not found)`);
+  }
+
+  // 4-6. ~/.claude-buddy/ state files (don't back up the backups dir itself)
+  const stateDestDir = join(dir, "claude-buddy");
+  mkdirSync(stateDestDir, { recursive: true });
+  const stateFiles = ["companion.json", "status.json", "reaction.json"];
+  for (const f of stateFiles) {
+    const src = join(STATE_DIR, f);
+    if (existsSync(src)) {
+      copyFileSync(src, join(stateDestDir, f));
+      manifest.files.push(`claude-buddy/${f}`);
+      ok(`Backed up: ~/.claude-buddy/${f}`);
+    }
+  }
+
+  writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  return ts;
+}
+
+// ─── List backups ───────────────────────────────────────────────────────────
+
+function cmdList() {
+  const backups = listBackups();
+  if (backups.length === 0) {
+    info("No backups found.");
+    info(`Run '${BOLD}bun run backup${NC}' to create one.`);
+    return;
+  }
+  console.log(`\n${BOLD}claude-buddy backups${NC}\n`);
+  for (const ts of backups) {
+    const manifestPath = join(BACKUPS_DIR, ts, "manifest.json");
+    const manifest = tryRead(manifestPath);
+    let count = "?";
+    if (manifest) {
+      try {
+        count = String(JSON.parse(manifest).files?.length ?? 0);
+      } catch {}
+    }
+    const isLatest = ts === backups[backups.length - 1];
+    const tag = isLatest ? `${GREEN}(latest)${NC}` : "";
+    console.log(`  ${CYAN}${ts}${NC}  ${DIM}${count} files${NC}  ${tag}`);
+  }
+  console.log("");
+}
+
+// ─── Show backup contents ───────────────────────────────────────────────────
+
+function cmdShow(ts: string) {
+  const dir = join(BACKUPS_DIR, ts);
+  if (!existsSync(dir)) {
+    err(`Backup not found: ${ts}`);
+    process.exit(1);
+  }
+  const manifest = tryRead(join(dir, "manifest.json"));
+  if (!manifest) {
+    err("manifest.json missing");
+    process.exit(1);
+  }
+  const data = JSON.parse(manifest);
+  console.log(`\n${BOLD}Backup ${ts}${NC}\n`);
+  console.log(`  ${DIM}Files:${NC}`);
+  for (const f of data.files) {
+    console.log(`    - ${f}`);
+  }
+  console.log("");
+}
+
+// ─── Restore backup ─────────────────────────────────────────────────────────
+
+function restoreBackup(ts: string) {
+  const dir = join(BACKUPS_DIR, ts);
+  if (!existsSync(dir)) {
+    err(`Backup not found: ${ts}`);
+    process.exit(1);
+  }
+
+  info(`Restoring backup ${ts}...\n`);
+
+  // 1. settings.json — overwrite
+  const settingsBak = join(dir, "settings.json");
+  if (existsSync(settingsBak)) {
+    mkdirSync(join(HOME, ".claude"), { recursive: true });
+    copyFileSync(settingsBak, SETTINGS);
+    ok("Restored: ~/.claude/settings.json");
+  }
+
+  // 2. claude.json mcpServers — merge our entry back in
+  const mcpBak = join(dir, "mcpserver.json");
+  if (existsSync(mcpBak)) {
+    const ourMcp = JSON.parse(readFileSync(mcpBak, "utf8"));
+    let claudeJson: Record<string, any> = {};
+    try {
+      claudeJson = JSON.parse(readFileSync(CLAUDE_JSON, "utf8"));
+    } catch { /* empty */ }
+    if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
+    claudeJson.mcpServers["claude-buddy"] = ourMcp;
+    writeFileSync(CLAUDE_JSON, JSON.stringify(claudeJson, null, 2));
+    ok("Restored: ~/.claude.json → mcpServers[\"claude-buddy\"]");
+  }
+
+  // 3. SKILL.md
+  const skillBak = join(dir, "SKILL.md");
+  if (existsSync(skillBak)) {
+    mkdirSync(join(HOME, ".claude", "skills", "buddy"), { recursive: true });
+    copyFileSync(skillBak, SKILL);
+    ok("Restored: ~/.claude/skills/buddy/SKILL.md");
+  }
+
+  // 4. ~/.claude-buddy/ state files
+  const stateDir = join(dir, "claude-buddy");
+  if (existsSync(stateDir)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+    for (const f of readdirSync(stateDir)) {
+      copyFileSync(join(stateDir, f), join(STATE_DIR, f));
+      ok(`Restored: ~/.claude-buddy/${f}`);
+    }
+  }
+
+  console.log(`\n${GREEN}Restore complete.${NC} Restart Claude Code to apply.\n`);
+}
+
+// ─── Delete backup ──────────────────────────────────────────────────────────
+
+function cmdDelete(ts: string) {
+  const dir = join(BACKUPS_DIR, ts);
+  if (!existsSync(dir)) {
+    err(`Backup not found: ${ts}`);
+    process.exit(1);
+  }
+  rmSync(dir, { recursive: true });
+  ok(`Deleted backup ${ts}`);
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+const action = process.argv[2] || "create";
+const arg = process.argv[3];
+
+switch (action) {
+  case "create":
+  case undefined: {
+    console.log(`\n${BOLD}Creating claude-buddy backup...${NC}\n`);
+    const ts = createBackup();
+    console.log(`\n${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+    console.log(`${GREEN}  Backup created: ${ts}${NC}`);
+    console.log(`${GREEN}  Location: ${BACKUPS_DIR}/${ts}${NC}`);
+    console.log(`${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n`);
+    console.log(`${DIM}  Restore with: bun run backup restore${NC}`);
+    console.log(`${DIM}  Or:           bun run backup restore ${ts}${NC}\n`);
+    break;
+  }
+
+  case "list":
+  case "ls":
+    cmdList();
+    break;
+
+  case "show": {
+    if (!arg) {
+      err("Usage: bun run backup show <timestamp>");
+      process.exit(1);
+    }
+    cmdShow(arg);
+    break;
+  }
+
+  case "restore": {
+    let ts = arg;
+    if (!ts) {
+      const all = listBackups();
+      if (all.length === 0) {
+        err("No backups to restore");
+        process.exit(1);
+      }
+      ts = all[all.length - 1];
+      info(`Restoring latest backup: ${ts}`);
+    }
+    restoreBackup(ts);
+    break;
+  }
+
+  case "delete":
+  case "rm": {
+    if (!arg) {
+      err("Usage: bun run backup delete <timestamp>");
+      process.exit(1);
+    }
+    cmdDelete(arg);
+    break;
+  }
+
+  case "--help":
+  case "-h":
+    console.log(`
+${BOLD}claude-buddy backup${NC} — snapshot and restore all claude-buddy state
+
+${BOLD}Commands:${NC}
+  bun run backup                 Create a new snapshot
+  bun run backup list            List all backups
+  bun run backup show <ts>       Show what's in a backup
+  bun run backup restore         Restore the latest backup
+  bun run backup restore <ts>    Restore a specific backup
+  bun run backup delete <ts>     Delete a specific backup
+
+${BOLD}What gets backed up:${NC}
+  - ~/.claude/settings.json (full)
+  - ~/.claude.json mcpServers["claude-buddy"] (only our entry)
+  - ~/.claude/skills/buddy/SKILL.md
+  - ~/.claude-buddy/companion.json
+  - ~/.claude-buddy/status.json
+  - ~/.claude-buddy/reaction.json
+
+${BOLD}Backup location:${NC}
+  ${BACKUPS_DIR}/<timestamp>/
+`);
+    break;
+
+  default:
+    err(`Unknown action: ${action}`);
+    console.log(`Run 'bun run backup --help' for usage.`);
+    process.exit(1);
+}

package/cli/disable.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+/**
+ * claude-buddy disable — temporarily deactivate buddy without losing data
+ *
+ * Removes: MCP server, status line, hooks
+ * Keeps: companion data, backups, skill files
+ *
+ * Re-enable with: bun run install-buddy
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const NC = "\x1b[0m";
+
+function ok(msg: string) { console.log(`${GREEN}✓${NC}  ${msg}`); }
+function warn(msg: string) { console.log(`${YELLOW}⚠${NC}  ${msg}`); }
+
+const HOME = homedir();
+const CLAUDE_JSON = join(HOME, ".claude.json");
+const SETTINGS = join(HOME, ".claude", "settings.json");
+
+console.log(`\n${BOLD}Disabling claude-buddy...${NC}\n`);
+
+// 1. Remove MCP server from ~/.claude.json
+try {
+  const claudeJson = JSON.parse(readFileSync(CLAUDE_JSON, "utf8"));
+  if (claudeJson.mcpServers?.["claude-buddy"]) {
+    delete claudeJson.mcpServers["claude-buddy"];
+    if (Object.keys(claudeJson.mcpServers).length === 0) delete claudeJson.mcpServers;
+    writeFileSync(CLAUDE_JSON, JSON.stringify(claudeJson, null, 2));
+    ok("MCP server removed from ~/.claude.json");
+  } else {
+    warn("MCP server was not registered");
+  }
+} catch {
+  warn("Could not update ~/.claude.json");
+}
+
+// 2. Remove status line + hooks from settings.json
+try {
+  const settings = JSON.parse(readFileSync(SETTINGS, "utf8"));
+  let changed = false;
+
+  if (settings.statusLine?.command?.includes("buddy")) {
+    delete settings.statusLine;
+    ok("Status line removed");
+    changed = true;
+  }
+
+  if (settings.hooks) {
+    for (const hookType of ["PostToolUse", "Stop", "SessionStart", "SessionEnd"]) {
+      if (settings.hooks[hookType]) {
+        const before = settings.hooks[hookType].length;
+        settings.hooks[hookType] = settings.hooks[hookType].filter(
+          (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+        );
+        if (settings.hooks[hookType].length < before) changed = true;
+        if (settings.hooks[hookType].length === 0) delete settings.hooks[hookType];
+      }
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  }
+
+  if (changed) {
+    writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + "\n");
+    ok("Hooks and status line removed from settings.json");
+  }
+} catch {
+  warn("Could not update settings.json");
+}
+
+// 3. Stop tmux popup if running
+try {
+  if (process.env.TMUX) {
+    const { execSync } = await import("child_process");
+    execSync("tmux display-popup -C 2>/dev/null", { stdio: "ignore" });
+  }
+} catch { /* not in tmux */ }
+
+console.log(`
+${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}
+${GREEN}  Buddy disabled.${NC}
+${GREEN}  Companion data is preserved at ~/.claude-buddy/${NC}
+${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}
+
+${DIM}  Restart Claude Code for changes to take effect.
+  Re-enable anytime with: bun run install-buddy${NC}
+`);

package/cli/doctor.ts

@@ -0,0 +1,220 @@
+#!/usr/bin/env bun
+/**
+ * claude-buddy doctor — comprehensive diagnostic report
+ *
+ * Run: bun run doctor
+ *
+ * Outputs a complete environment report for bug reports.
+ * Copy the entire output and paste it in a GitHub issue.
+ */
+
+import { readFileSync, existsSync, statSync } from "fs";
+import { execSync } from "child_process";
+import { join, resolve, dirname } from "path";
+import { homedir } from "os";
+
+const PROJECT_ROOT = resolve(dirname(import.meta.dir));
+const HOME = homedir();
+const STATUS_SCRIPT = join(PROJECT_ROOT, "statusline", "buddy-status.sh");
+
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const NC = "\x1b[0m";
+
+function section(title: string) {
+  console.log(`\n${CYAN}${BOLD}━━━ ${title} ${"━".repeat(Math.max(0, 60 - title.length))}${NC}`);
+}
+
+function row(label: string, value: string) {
+  console.log(`  ${DIM}${label.padEnd(28)}${NC} ${value}`);
+}
+
+function ok(msg: string) { console.log(`  ${GREEN}✓${NC} ${msg}`); }
+function warn(msg: string) { console.log(`  ${YELLOW}⚠${NC} ${msg}`); }
+function err(msg: string) { console.log(`  ${RED}✗${NC} ${msg}`); }
+
+function tryExec(cmd: string, fallback = "(failed)"): string {
+  try {
+    return execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return fallback;
+  }
+}
+
+function tryRead(path: string): string | null {
+  try { return readFileSync(path, "utf8"); } catch { return null; }
+}
+
+function tryParseJson(text: string | null): any | null {
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+// ─── Header ─────────────────────────────────────────────────────────────────
+
+console.log(`${CYAN}${BOLD}
+╔══════════════════════════════════════════════════════════╗
+║  claude-buddy doctor — diagnostic report                 ║
+╚══════════════════════════════════════════════════════════╝${NC}`);
+
+console.log(`\n${DIM}Copy this entire output into your GitHub issue.${NC}`);
+
+// ─── Environment ────────────────────────────────────────────────────────────
+
+section("Environment");
+row("OS", tryExec("uname -srm"));
+row("Hostname", tryExec("uname -n"));
+row("User shell", process.env.SHELL ?? "(unset)");
+row("Bash version", tryExec("bash --version | head -1"));
+row("Bun version", tryExec("bun --version"));
+row("Node version", tryExec("node --version", "(not installed)"));
+row("jq version", tryExec("jq --version", "(not installed)"));
+row("Claude Code version", tryExec("claude --version", "(not in PATH)"));
+
+// ─── Terminal ───────────────────────────────────────────────────────────────
+
+section("Terminal");
+row("TERM", process.env.TERM ?? "(unset)");
+row("COLORTERM", process.env.COLORTERM ?? "(unset)");
+row("TERM_PROGRAM", process.env.TERM_PROGRAM ?? "(unset)");
+row("LANG", process.env.LANG ?? "(unset)");
+row("COLUMNS env var", process.env.COLUMNS ?? "(unset in subprocess)");
+row("stty size", tryExec("stty size 2>/dev/null", "(no tty)"));
+row("tput cols", tryExec("tput cols 2>/dev/null", "(failed)"));
+
+// ─── Filesystem checks ──────────────────────────────────────────────────────
+
+section("Filesystem");
+const procExists = existsSync("/proc");
+row("/proc exists", procExists ? `${GREEN}yes${NC} (Linux)` : `${RED}no${NC} (macOS/BSD)`);
+row("~/.claude/ exists", existsSync(join(HOME, ".claude")) ? "yes" : "no");
+row("~/.claude.json exists", existsSync(join(HOME, ".claude.json")) ? "yes" : "no");
+row("~/.claude-buddy/ exists", existsSync(join(HOME, ".claude-buddy")) ? "yes" : "no");
+row("Project root", PROJECT_ROOT);
+row("Status script exists", existsSync(STATUS_SCRIPT) ? "yes" : `${RED}no${NC}`);
+
+// ─── claude-buddy state ─────────────────────────────────────────────────────
+
+section("claude-buddy state");
+const menagerie = tryParseJson(tryRead(join(HOME, ".claude-buddy", "menagerie.json")));
+const status = tryParseJson(tryRead(join(HOME, ".claude-buddy", "status.json")));
+
+if (menagerie) {
+  const activeSlot = menagerie.active ?? "buddy";
+  const companion = menagerie.companions?.[activeSlot];
+  row("Active slot", activeSlot);
+  row("Total slots", String(Object.keys(menagerie.companions ?? {}).length));
+  if (companion) {
+    row("Companion name", companion.name ?? "(none)");
+    row("Species", companion.bones?.species ?? "(none)");
+    row("Rarity", companion.bones?.rarity ?? "(none)");
+    row("Hat", companion.bones?.hat ?? "(none)");
+    row("Eye", companion.bones?.eye ?? "(none)");
+    row("Shiny", String(companion.bones?.shiny ?? false));
+  } else {
+    err(`No companion found in active slot "${activeSlot}"`);
+  }
+} else {
+  err("No manifest found at ~/.claude-buddy/menagerie.json");
+}
+
+if (status) {
+  row("Status muted", String(status.muted ?? false));
+  row("Current reaction", status.reaction || "(none)");
+} else {
+  warn("No status state at ~/.claude-buddy/status.json");
+}
+
+// ─── settings.json ──────────────────────────────────────────────────────────
+
+section("Claude Code config");
+const settings = tryParseJson(tryRead(join(HOME, ".claude", "settings.json")));
+const claudeJson = tryParseJson(tryRead(join(HOME, ".claude.json")));
+
+if (settings?.statusLine) {
+  console.log(`  ${DIM}statusLine:${NC}`);
+  console.log(`    ${JSON.stringify(settings.statusLine, null, 2).split("\n").join("\n    ")}`);
+} else {
+  warn("No statusLine in ~/.claude/settings.json");
+}
+
+if (settings?.hooks) {
+  console.log(`  ${DIM}hooks:${NC}`);
+  for (const event of Object.keys(settings.hooks)) {
+    const count = settings.hooks[event]?.length ?? 0;
+    row(`  ${event}`, `${count} entr${count === 1 ? "y" : "ies"}`);
+  }
+} else {
+  warn("No hooks configured");
+}
+
+if (claudeJson?.mcpServers?.["claude-buddy"]) {
+  ok("MCP server registered in ~/.claude.json");
+  console.log(`    ${JSON.stringify(claudeJson.mcpServers["claude-buddy"], null, 2).split("\n").join("\n    ")}`);
+} else {
+  err("MCP server NOT registered in ~/.claude.json");
+}
+
+const skillPath = join(HOME, ".claude", "skills", "buddy", "SKILL.md");
+if (existsSync(skillPath)) {
+  ok(`Skill installed: ${skillPath}`);
+} else {
+  err(`Skill missing: ${skillPath}`);
+}
+
+// ─── Live status line test ──────────────────────────────────────────────────
+
+section("Live status line output");
+console.log(`  ${DIM}(running: echo '{}' | ${STATUS_SCRIPT})${NC}\n`);
+const liveOutput = tryExec(`echo '{}' | bash "${STATUS_SCRIPT}" 2>&1`, "(script failed)");
+const lines = liveOutput.split("\n");
+console.log(lines.map(l => `  │ ${l}`).join("\n"));
+console.log(`  ${DIM}(${lines.length} lines, total ${liveOutput.length} bytes)${NC}`);
+
+// ─── Padding strategy test ──────────────────────────────────────────────────
+
+section("Padding strategy test");
+console.log(`  ${DIM}Each row should appear right-aligned with marker '|END'.${NC}`);
+console.log(`  ${DIM}If a row is misaligned, that strategy is broken in this terminal.${NC}\n`);
+
+const PAD = 40;
+const strategies: [string, string][] = [
+  ["space (will be trimmed!)", " "],
+  ["braille blank U+2800", "\u2800"],
+  ["non-breaking space U+00A0", "\u00A0"],
+  ["dot .", "."],
+  ["middle dot ·", "\u00B7"],
+];
+
+for (const [name, ch] of strategies) {
+  const padding = ch.repeat(PAD);
+  console.log(`  ${padding}|END  ${DIM}← ${name}${NC}`);
+}
+
+// ─── string-width comparison ────────────────────────────────────────────────
+
+section("Display width vs string-width (npm)");
+console.log(`  ${DIM}Most terminals render Braille Blank as 2 columns.${NC}`);
+console.log(`  ${DIM}But the npm 'string-width' package counts it as 1.${NC}`);
+console.log(`  ${DIM}Claude Code uses string-width for layout calculations.${NC}\n`);
+
+try {
+  // Try to load string-width if available
+  const sw = require("string-width");
+  row("string-width(' ')", String(sw(" ")));
+  row("string-width('\\u2800')", String(sw("\u2800")));
+  row("string-width('\\u00A0')", String(sw("\u00A0")));
+  row("string-width('-o-OO-o-')", String(sw("-o-OO-o-")));
+  row("string-width('⠀⠀⠀⠀⠀-o-OO-o-')", String(sw("\u2800\u2800\u2800\u2800\u2800-o-OO-o-")));
+} catch {
+  warn("string-width not installed in project — skipping comparison");
+}
+
+// ─── Footer ─────────────────────────────────────────────────────────────────
+
+console.log(`\n${CYAN}${BOLD}━━━ End of report ${"━".repeat(46)}${NC}\n`);
+console.log(`${DIM}Copy everything above into your GitHub issue.${NC}\n`);