@ramarivera/coding-buddy 0.4.0-alpha.1

package/cli/hunt.ts

@@ -0,0 +1,167 @@
+/**
+ * claude-buddy hunt — brute-force search for a specific buddy
+ *
+ * Rules:
+ *   - Asks for a name before saving
+ *   - If no name given, picks a random unused name from the manifest
+ *   - Appends to the manifest — never overwrites an existing slot
+ */
+
+import {
+  searchBuddy, renderBuddy, SPECIES, RARITIES, STAT_NAMES,
+  type Species, type Rarity, type StatName, type SearchCriteria,
+} from "../server/engine.ts";
+import {
+  saveCompanionSlot, saveActiveSlot, writeStatusState,
+  slugify, unusedName, listCompanionSlots,
+} from "../server/state.ts";
+import { createInterface } from "readline";
+
+const CYAN  = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED   = "\x1b[31m";
+const BOLD  = "\x1b[1m";
+const DIM   = "\x1b[2m";
+const NC    = "\x1b[0m";
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+function ask(prompt: string): Promise<string> {
+  return new Promise((resolve) => rl.question(prompt, resolve));
+}
+
+function pickFromList<T extends string>(label: string, items: readonly T[]): Promise<T> {
+  return new Promise(async (resolve) => {
+    console.log(`\n${BOLD}${label}${NC}`);
+    items.forEach((item, i) => console.log(`  ${CYAN}${(i + 1).toString().padStart(2)}${NC}) ${item}`));
+    while (true) {
+      const ans = await ask(`\n  Choice [1-${items.length}]: `);
+      const idx = parseInt(ans) - 1;
+      if (idx >= 0 && idx < items.length) { resolve(items[idx]); return; }
+      console.log(`  ${RED}Invalid. Enter 1-${items.length}.${NC}`);
+    }
+  });
+}
+
+async function main() {
+  console.log(`
+${CYAN}╔══════════════════════════════════════════════════════════╗${NC}
+${CYAN}║${NC}  ${BOLD}claude-buddy hunt${NC} — find your perfect companion          ${CYAN}║${NC}
+${CYAN}╚══════════════════════════════════════════════════════════╝${NC}
+`);
+
+  const species = await pickFromList("Species:", SPECIES);
+  console.log(`${GREEN}✓${NC} ${species}`);
+
+  const rarity = await pickFromList("Rarity:", RARITIES);
+  console.log(`${GREEN}✓${NC} ${rarity}`);
+
+  const shinyAns = await ask(`\n  Shiny? (much longer search) [y/N]: `);
+  const wantShiny = shinyAns.toLowerCase() === "y";
+  console.log(`${GREEN}✓${NC} shiny: ${wantShiny ? "yes" : "any"}`);
+
+  let wantPeak: StatName | undefined;
+  let wantDump: StatName | undefined;
+
+  const statsAns = await ask(`\n  Configure stats? [Y/n]: `);
+  if (statsAns.toLowerCase() !== "n") {
+    wantPeak = await pickFromList("Peak stat (highest):", STAT_NAMES);
+    const dumpOptions = STAT_NAMES.filter((s) => s !== wantPeak);
+    wantDump = await pickFromList("Dump stat (lowest):", dumpOptions as any);
+    console.log(`${GREEN}✓${NC} peak=${wantPeak} dump=${wantDump}`);
+  }
+
+  let maxAttempts = 10_000_000;
+  if (rarity === "legendary") maxAttempts = 200_000_000;
+  else if (rarity === "epic") maxAttempts = 50_000_000;
+  if (wantShiny) maxAttempts *= 3;
+
+  console.log(`\n${DIM}  Max attempts: ${(maxAttempts / 1e6).toFixed(0)}M${NC}`);
+
+  const startAns = await ask(`\n  Start search? [Y/n]: `);
+  if (startAns.toLowerCase() === "n") { rl.close(); return; }
+
+  console.log(`\n${CYAN}→${NC}  Searching...\n`);
+
+  const criteria: SearchCriteria = { species, rarity, wantShiny };
+  if (wantPeak) criteria.wantPeak = wantPeak;
+  if (wantDump) criteria.wantDump = wantDump;
+
+  const results = searchBuddy(criteria, maxAttempts, (checked, found) => {
+    process.stderr.write(`\r  ${(checked / 1e6).toFixed(0)}M checked, ${found} matches   `);
+  });
+
+  console.log("");
+
+  if (results.length === 0) {
+    console.log(`${RED}✗${NC}  No matches found. Try less restrictive criteria.`);
+    rl.close();
+    return;
+  }
+
+  console.log(`${GREEN}✓${NC}  ${results.length} matches found!\n`);
+
+  // Show top 5
+  const top = results.slice(0, 5);
+  for (let i = 0; i < top.length; i++) {
+    const r = top[i];
+    const stats = STAT_NAMES.map((n) => `${n.slice(0, 3)}:${r.bones.stats[n]}`).join(" ");
+    const shiny = r.bones.shiny ? "✨ " : "   ";
+    console.log(`  ${CYAN}${i + 1}${NC}) ${shiny}eye=${r.bones.eye} hat=${r.bones.hat}  ${stats}`);
+  }
+
+  const pickAns = await ask(`\n  Apply which? [1-${top.length}, q to cancel]: `);
+  if (pickAns === "q") { rl.close(); return; }
+
+  const pickIdx = parseInt(pickAns) - 1;
+  if (pickIdx < 0 || pickIdx >= top.length) {
+    console.log(`${RED}Invalid.${NC}`);
+    rl.close();
+    return;
+  }
+
+  const chosen = top[pickIdx];
+  console.log(`\n${renderBuddy(chosen.bones)}\n`);
+
+  // ─── Ask for a name ────────────────────────────────────────────────────────
+  const existing = new Set(listCompanionSlots().map((e) => slugify(e.companion.name)));
+  const suggested = unusedName();
+  console.log(`\n${DIM}  Existing buddies: ${[...existing].join(", ") || "none"}${NC}`);
+
+  let chosenName = "";
+  while (true) {
+    const raw = await ask(
+      `  Name this buddy (Enter for "${suggested}"): `,
+    );
+    chosenName = raw.trim() || suggested;
+    const slot = slugify(chosenName);
+    if (existing.has(slot)) {
+      console.log(`  ${YELLOW}⚠${NC}  Slot "${slot}" already taken — pick another name.`);
+    } else {
+      break;
+    }
+  }
+
+  const slot = slugify(chosenName);
+  const companion = {
+    bones: chosen.bones,
+    name: chosenName,
+    personality: `A ${chosen.bones.rarity} ${chosen.bones.species} who watches code with quiet intensity.`,
+    hatchedAt: Date.now(),
+    userId: chosen.userId,
+  };
+
+  saveCompanionSlot(companion, slot);
+  saveActiveSlot(slot);
+  writeStatusState(companion, `*${chosenName} arrives*`);
+
+  console.log(`${GREEN}✓${NC}  ${chosenName} saved to slot "${slot}" and set as active.`);
+  console.log(`\n${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+  console.log(`${GREEN}  Done! Restart Claude Code to see your new buddy.${NC}`);
+  console.log(`${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n`);
+
+  rl.close();
+}
+
+main();

package/cli/index.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+/**
+ * claude-buddy CLI
+ *
+ * Usage:
+ *   npx claude-buddy              Interactive install
+ *   npx claude-buddy install      Install MCP + skill + hooks + statusline
+ *   npx claude-buddy show         Show current buddy
+ *   npx claude-buddy pick         Interactive two-pane buddy picker (saved + search)
+ *   npx claude-buddy hunt         Search for a specific buddy (non-interactive)
+ *   npx claude-buddy uninstall    Remove all integrations
+ *   npx claude-buddy verify       Verify what buddy your ID produces
+ */
+
+const args = process.argv.slice(2);
+const command = args[0] || "install";
+
+switch (command) {
+  case "install":
+    await import("./install.ts");
+    break;
+  case "show":
+    await import("./show.ts");
+    break;
+  case "pick":
+    await import("./pick.ts");
+    break;
+  case "hunt":
+    await import("./hunt.ts");
+    break;
+  case "uninstall":
+    await import("./uninstall.ts");
+    break;
+  case "verify":
+    await import("./verify.ts");
+    break;
+  case "doctor":
+    await import("./doctor.ts");
+    break;
+  case "test-statusline":
+    await import("./test-statusline.ts");
+    break;
+  case "backup":
+    await import("./backup.ts");
+    break;
+  case "settings":
+    await import("./settings.ts");
+    break;
+  case "disable":
+    await import("./disable.ts");
+    break;
+  case "enable":
+    await import("./install.ts");
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    showHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    showHelp();
+    process.exit(1);
+}
+
+function showHelp() {
+  console.log(`
+claude-buddy — permanent coding companion for Claude Code
+
+Setup:
+  install-buddy     Set up MCP server, skill, hooks, and status line
+  enable            Same as install-buddy (re-enable after disable)
+  disable           Temporarily deactivate buddy (data preserved)
+  uninstall         Remove all claude-buddy integrations
+
+Buddy:
+  show              Display your current buddy
+  pick              Interactive two-pane buddy picker (browse saved + search)
+  hunt              Search for a specific buddy (non-interactive)
+  verify            Verify what buddy your current ID produces
+
+Settings:
+  settings          Show current settings
+  settings cooldown <n>  Set comment cooldown (0-300 seconds)
+  settings ttl <n>       Set reaction display duration (0-300s, 0 = permanent)
+
+Diagnostics:
+  doctor            Run diagnostic report (paste output in bug reports)
+  test-statusline   Test status line rendering in Claude Code
+  backup            Snapshot or restore all claude-buddy state
+
+In Claude Code:
+  /buddy            Show companion card with ASCII art + stats
+  /buddy pet        Pet your companion
+  /buddy stats      Detailed stat card
+  /buddy off        Mute reactions
+  /buddy on         Unmute reactions
+  /buddy rename     Rename companion (1-14 chars)
+  /buddy personality  Set custom personality text
+  /buddy summon     Summon a saved buddy (omit slot for random)
+  /buddy save       Save current buddy to a named slot
+  /buddy list       List all saved buddies
+  /buddy dismiss    Remove a saved buddy slot
+  /buddy pick       Launch interactive TUI picker (! bun run pick)
+  /buddy frequency  Show or set comment cooldown (tmux only)
+  /buddy style      Show or set bubble style (tmux only)
+  /buddy position   Show or set bubble position (tmux only)
+  /buddy rarity     Show or hide rarity stars (tmux only)
+
+Usage:
+  bun run <command>           e.g. bun run show, bun run doctor
+  claude-buddy <command>      if globally linked (bun link)
+  bun run help                Show this help
+`);
+}

package/cli/install.ts

@@ -0,0 +1,335 @@
+/**
+ * claude-buddy installer
+ *
+ * Registers: MCP server (in ~/.claude.json), skill, hooks, status line (in settings.json)
+ * Checks: bun, jq, ~/.claude/ directory
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, cpSync } from "fs";
+import { execSync } from "child_process";
+import { join, resolve, dirname } from "path";
+import { homedir } from "os";
+
+import { generateBones, renderBuddy, renderFace, RARITY_STARS } from "../server/engine.ts";
+import { loadCompanion, saveCompanion, resolveUserId, writeStatusState } from "../server/state.ts";
+import { generateFallbackName } from "../server/reactions.ts";
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const NC = "\x1b[0m";
+
+const CLAUDE_DIR = join(homedir(), ".claude");
+const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
+const BUDDY_DIR = join(CLAUDE_DIR, "skills", "buddy");
+const PROJECT_ROOT = resolve(dirname(import.meta.dir));
+
+function banner() {
+  console.log(`
+${CYAN}╔══════════════════════════════════════════════════════════╗${NC}
+${CYAN}║${NC}  ${BOLD}claude-buddy${NC} — permanent coding companion              ${CYAN}║${NC}
+${CYAN}║${NC}  ${DIM}MCP + Skill + StatusLine + Hooks${NC}                        ${CYAN}║${NC}
+${CYAN}╚══════════════════════════════════════════════════════════╝${NC}
+`);
+}
+
+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}`); }
+
+// ─── Preflight checks ──────────────────────────────────────────────────────
+
+function preflight(): boolean {
+  let pass = true;
+
+  // Check bun
+  try {
+    execSync("bun --version", { stdio: "ignore" });
+    ok("bun found");
+  } catch {
+    err("bun not found. Install: curl -fsSL https://bun.sh/install | bash");
+    pass = false;
+  }
+
+  // Check jq (needed for status line + hooks)
+  try {
+    execSync("jq --version", { stdio: "ignore" });
+    ok("jq found");
+  } catch {
+    warn("jq not found — installing...");
+    try {
+      execSync("sudo apt-get install -y jq 2>/dev/null || brew install jq 2>/dev/null", { stdio: "ignore" });
+      ok("jq installed");
+    } catch {
+      err("Could not install jq. Install manually: apt install jq / brew install jq");
+      pass = false;
+    }
+  }
+
+  // Check ~/.claude/ exists
+  if (!existsSync(CLAUDE_DIR)) {
+    err("~/.claude/ not found. Start Claude Code once first, then re-run.");
+    pass = false;
+  } else {
+    ok("~/.claude/ found");
+  }
+
+  // Check ~/.claude.json exists
+  const claudeJson = join(homedir(), ".claude.json");
+  if (!existsSync(claudeJson)) {
+    err("~/.claude.json not found. Start Claude Code once first, then re-run.");
+    pass = false;
+  } else {
+    ok("~/.claude.json found");
+  }
+
+  return pass;
+}
+
+// ─── Load / update settings.json ────────────────────────────────────────────
+
+function loadSettings(): Record<string, any> {
+  try {
+    return JSON.parse(readFileSync(SETTINGS_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveSettings(settings: Record<string, any>) {
+  mkdirSync(CLAUDE_DIR, { recursive: true });
+  writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+}
+
+// ─── Step 1: Register MCP server (in ~/.claude.json) ────────────────────────
+
+function installMcp() {
+  const serverPath = join(PROJECT_ROOT, "server", "index.ts");
+  const claudeJsonPath = join(homedir(), ".claude.json");
+
+  let claudeJson: Record<string, any> = {};
+  try {
+    claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf8"));
+  } catch { /* fresh config */ }
+
+  if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
+
+  claudeJson.mcpServers["claude-buddy"] = {
+    command: "bun",
+    args: [serverPath],
+    cwd: PROJECT_ROOT,
+  };
+
+  writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+  ok("MCP server registered in ~/.claude.json");
+}
+
+// ─── Step 2: Install skill ──────────────────────────────────────────────────
+
+function installSkill() {
+  const srcSkill = join(PROJECT_ROOT, "skills", "buddy", "SKILL.md");
+  mkdirSync(BUDDY_DIR, { recursive: true });
+  cpSync(srcSkill, join(BUDDY_DIR, "SKILL.md"), { force: true });
+  ok("Skill installed: ~/.claude/skills/buddy/SKILL.md");
+}
+
+// ─── Step 3: Configure status line (with animation refresh) ─────────────────
+
+function installStatusLine(settings: Record<string, any>) {
+  const statusScript = join(PROJECT_ROOT, "statusline", "buddy-status.sh");
+
+  settings.statusLine = {
+    type: "command",
+    command: statusScript,
+    padding: 1,
+    refreshInterval: 1,  // 1 second — drives the buddy animation
+  };
+
+  ok("Status line configured (with animation refresh)");
+}
+
+// ─── Step 3b: Configure tmux popup mode (if in tmux) ────────────────────────
+
+function detectTmux(): boolean {
+  if (!process.env.TMUX) return false;
+  try {
+    const ver = execSync("tmux -V 2>/dev/null", { encoding: "utf8" }).trim();
+    const match = ver.match(/(\d+)\.(\d+)/);
+    if (!match) return false;
+    const major = parseInt(match[1]), minor = parseInt(match[2]);
+    return major > 3 || (major === 3 && minor >= 2);
+  } catch {
+    return false;
+  }
+}
+
+function installPopupHooks(settings: Record<string, any>) {
+  const popupManager = join(PROJECT_ROOT, "popup", "popup-manager.sh");
+
+  if (!settings.hooks) settings.hooks = {};
+
+  // SessionStart: open popup
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+    (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+  );
+  settings.hooks.SessionStart.push({
+    hooks: [{ type: "command", command: `${popupManager} start` }],
+  });
+
+  // SessionEnd: close popup
+  if (!settings.hooks.SessionEnd) settings.hooks.SessionEnd = [];
+  settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(
+    (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+  );
+  settings.hooks.SessionEnd.push({
+    hooks: [{ type: "command", command: `${popupManager} stop` }],
+  });
+
+  ok("Popup hooks registered: SessionStart + SessionEnd");
+}
+
+// ─── Step 4: Register hooks ─────────────────────────────────────────────────
+
+function installHooks(settings: Record<string, any>) {
+  const reactHook    = join(PROJECT_ROOT, "hooks", "react.sh");
+  const commentHook  = join(PROJECT_ROOT, "hooks", "buddy-comment.sh");
+  const nameHook     = join(PROJECT_ROOT, "hooks", "name-react.sh");
+
+  if (!settings.hooks) settings.hooks = {};
+
+  // PostToolUse: detect errors/test failures/successes in Bash output
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+    (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+  );
+  settings.hooks.PostToolUse.push({
+    matcher: "Bash",
+    hooks: [{ type: "command", command: reactHook }],
+  });
+
+  // Stop: extract <!-- buddy: --> comment from Claude's response
+  if (!settings.hooks.Stop) settings.hooks.Stop = [];
+  settings.hooks.Stop = settings.hooks.Stop.filter(
+    (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+  );
+  settings.hooks.Stop.push({
+    hooks: [{ type: "command", command: commentHook }],
+  });
+
+  // UserPromptSubmit: detect buddy's name in user message → instant status line reaction
+  if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
+    (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+  );
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [{ type: "command", command: nameHook }],
+  });
+
+  ok("Hooks registered: PostToolUse + Stop + UserPromptSubmit");
+}
+
+// ─── Step 5: Ensure MCP tools are allowed ───────────────────────────────────
+
+function ensurePermissions(settings: Record<string, any>) {
+  if (!settings.permissions) settings.permissions = {};
+  if (!settings.permissions.allow) settings.permissions.allow = [];
+
+  const allow: string[] = settings.permissions.allow;
+  if (!allow.includes("mcp__*") && !allow.some((p: string) => p.startsWith("mcp__claude_buddy"))) {
+    allow.push("mcp__claude_buddy__*");
+    ok("Permission added: mcp__claude_buddy__*");
+  } else {
+    ok("MCP permissions already configured");
+  }
+}
+
+// ─── Step 6: Initialize companion ───────────────────────────────────────────
+
+function initCompanion() {
+  let companion = loadCompanion();
+  if (companion) {
+    info(`Existing companion found: ${companion.name} (${companion.bones.rarity} ${companion.bones.species})`);
+    return companion;
+  }
+
+  const userId = resolveUserId();
+  info(`Generating companion from user ID: ${userId.slice(0, 12)}...`);
+
+  const bones = generateBones(userId);
+  companion = {
+    bones,
+    name: generateFallbackName(),
+    personality: `A ${bones.rarity} ${bones.species} who watches code with quiet intensity.`,
+    hatchedAt: Date.now(),
+    userId,
+  };
+
+  saveCompanion(companion);
+  writeStatusState(companion);
+  ok(`Companion hatched: ${companion.name}`);
+
+  return companion;
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+banner();
+
+info("Checking requirements...\n");
+if (!preflight()) {
+  console.log(`\n${RED}Installation aborted. Fix the issues above and retry.${NC}\n`);
+  process.exit(1);
+}
+
+console.log("");
+info("Installing claude-buddy...\n");
+
+const settings = loadSettings();
+
+installMcp();
+installSkill();
+
+const useTmuxPopup = detectTmux();
+if (useTmuxPopup) {
+  info("tmux detected (>= 3.2) -- using popup overlay mode");
+  installPopupHooks(settings);
+  // Disable status line to avoid duplicate buddy rendering
+  if (settings.statusLine?.command?.includes("buddy")) {
+    delete settings.statusLine;
+    ok("Status line disabled (popup replaces it)");
+  }
+} else {
+  installStatusLine(settings);
+}
+
+installHooks(settings);
+ensurePermissions(settings);
+saveSettings(settings);
+
+console.log("");
+const companion = initCompanion();
+
+console.log("");
+console.log(renderBuddy(companion.bones));
+console.log("");
+console.log(`  ${BOLD}${companion.name}${NC} -- ${companion.personality}`);
+console.log("");
+
+const modeMsg = useTmuxPopup ? "popup overlay" : "status line";
+console.log(`${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+console.log(`${GREEN}  Done! Restart Claude Code and type /buddy${NC}`);
+console.log(`${GREEN}  Display mode: ${modeMsg}${NC}`);
+console.log(`${GREEN}  Your companion is now permanent -- survives any update.${NC}`);
+console.log(`${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
+console.log("");
+console.log(`${DIM}  /buddy        show your companion`);
+console.log(`  /buddy pet    pet your companion`);
+console.log(`  /buddy stats  detailed stat card`);
+console.log(`  /buddy off    mute reactions`);
+console.log(`  /buddy on     unmute reactions${NC}`);
+console.log("");