@ramarivera/coding-buddy 0.4.0-alpha.1

package/server/reactions.ts

@@ -0,0 +1,187 @@
+/**
+ * Reaction templates — species-aware buddy responses to events
+ */
+
+import type { Species, Rarity, StatName } from "./engine.ts";
+
+type ReactionReason = "hatch" | "pet" | "error" | "test-fail" | "large-diff" | "turn" | "idle";
+
+interface ReactionPool {
+  [key: string]: string[];
+}
+
+// General reactions by event type
+const REACTIONS: Record<ReactionReason, string[]> = {
+  hatch: [
+    "*blinks* ...where am I?",
+    "*stretches* hello, world!",
+    "*looks around curiously* nice terminal you got here.",
+    "*yawns* ok I'm ready. show me the code.",
+  ],
+  pet: [
+    "*purrs contentedly*",
+    "*happy noises*",
+    "*nuzzles your cursor*",
+    "*wiggles*",
+    "again! again!",
+    "*closes eyes peacefully*",
+  ],
+  error: [
+    "*head tilts* ...that doesn't look right.",
+    "saw that one coming.",
+    "*adjusts glasses* line {line}, maybe?",
+    "*slow blink* the stack trace told you everything.",
+    "have you tried reading the error message?",
+    "*winces*",
+  ],
+  "test-fail": [
+    "*head rotates slowly* ...that test.",
+    "bold of you to assume that would pass.",
+    "*taps clipboard* {count} failed.",
+    "the tests are trying to tell you something.",
+    "*sips tea* interesting.",
+    "*marks calendar* test regression day.",
+  ],
+  "large-diff": [
+    "that's... a lot of changes.",
+    "*counts lines* are you refactoring or rewriting?",
+    "might want to split that PR.",
+    "*nervous laughter* {lines} lines changed.",
+    "bold move. let's see if CI agrees.",
+  ],
+  turn: [
+    "*watches quietly*",
+    "*takes notes*",
+    "*nods*",
+    "...",
+    "*adjusts hat*",
+  ],
+  idle: [
+    "*dozes off*",
+    "*doodles in margins*",
+    "*stares at cursor blinking*",
+    "zzz...",
+  ],
+};
+
+// Species-specific flavor
+const SPECIES_REACTIONS: Partial<Record<Species, Partial<Record<ReactionReason, string[]>>>> = {
+  owl: {
+    error: [
+      "*head rotates 180\u00b0* ...I saw that.",
+      "*unblinking stare* check your types.",
+      "*hoots disapprovingly*",
+    ],
+    pet: ["*ruffles feathers contentedly*", "*dignified hoot*"],
+  },
+  cat: {
+    error: ["*knocks error off table*", "*licks paw, ignoring the stacktrace*"],
+    pet: ["*purrs* ...don't let it go to your head.", "*tolerates you*"],
+    idle: ["*pushes your coffee off the desk*", "*naps on keyboard*"],
+  },
+  duck: {
+    error: ["*quacks at the bug*", "have you tried rubber duck debugging? oh wait."],
+    pet: ["*happy quack*", "*waddles in circles*"],
+  },
+  dragon: {
+    error: ["*smoke curls from nostrils*", "*considers setting the codebase on fire*"],
+    "large-diff": ["*breathes fire on the old code* good riddance."],
+  },
+  ghost: {
+    error: ["*phases through the stack trace*", "I've seen worse... in the afterlife."],
+    idle: ["*floats through walls*", "*haunts your unused imports*"],
+  },
+  robot: {
+    error: ["SYNTAX. ERROR. DETECTED.", "*beeps aggressively*"],
+    "test-fail": ["FAILURE RATE: UNACCEPTABLE.", "*recalculating*"],
+  },
+  axolotl: {
+    error: ["*regenerates your hope*", "*smiles despite everything*"],
+    pet: ["*happy gill wiggle*", "*blushes pink*"],
+  },
+  capybara: {
+    error: ["*unbothered* it'll be fine.", "*continues vibing*"],
+    pet: ["*maximum chill achieved*", "*zen mode activated*"],
+    idle: ["*just sits there, radiating calm*"],
+  },
+};
+
+// Rarity affects reaction quality/length
+const RARITY_BONUS: Partial<Record<Rarity, string[]>> = {
+  legendary: [
+    "*legendary aura intensifies*",
+    "*sparkles knowingly*",
+  ],
+  epic: [
+    "*epic presence noted*",
+  ],
+};
+
+export function getReaction(
+  reason: ReactionReason,
+  species: Species,
+  rarity: Rarity,
+  context?: { line?: number; count?: number; lines?: number },
+): string {
+  // Try species-specific first
+  const speciesPool = SPECIES_REACTIONS[species]?.[reason];
+  const generalPool = REACTIONS[reason];
+
+  // 40% chance of species-specific if available
+  const pool = speciesPool && Math.random() < 0.4 ? speciesPool : generalPool;
+  let reaction = pool[Math.floor(Math.random() * pool.length)];
+
+  // Template substitution
+  if (context?.line) reaction = reaction.replace("{line}", String(context.line));
+  if (context?.count) reaction = reaction.replace("{count}", String(context.count));
+  if (context?.lines) reaction = reaction.replace("{lines}", String(context.lines));
+
+  return reaction;
+}
+
+// ─── Personality generation (fallback names when API unavailable) ────────────
+
+const FALLBACK_NAMES = [
+  "Crumpet", "Soup", "Pickle", "Biscuit", "Moth", "Gravy",
+  "Nugget", "Sprocket", "Miso", "Waffle", "Pixel", "Ember",
+  "Thimble", "Marble", "Sesame", "Cobalt", "Rusty", "Nimbus",
+];
+
+const VIBE_WORDS = [
+  "thunder", "biscuit", "void", "accordion", "moss", "velvet", "rust",
+  "pickle", "crumb", "whisper", "gravy", "frost", "ember", "soup",
+  "marble", "thorn", "honey", "static", "copper", "dusk", "sprocket",
+  "quartz", "soot", "plum", "flint", "oyster", "loom", "anvil",
+  "cork", "bloom", "pebble", "vapor", "mirth", "glint", "cider",
+];
+
+export function generateFallbackName(): string {
+  return FALLBACK_NAMES[Math.floor(Math.random() * FALLBACK_NAMES.length)];
+}
+
+export function generatePersonalityPrompt(
+  species: Species,
+  rarity: Rarity,
+  stats: Record<string, number>,
+  shiny: boolean,
+): string {
+  const vibes: string[] = [];
+  for (let i = 0; i < 4; i++) {
+    vibes.push(VIBE_WORDS[Math.floor(Math.random() * VIBE_WORDS.length)]);
+  }
+
+  const statStr = Object.entries(stats).map(([k, v]) => `${k}:${v}`).join(", ");
+
+  return [
+    "Generate a coding companion — a small creature that lives in a developer's terminal.",
+    "Don't repeat yourself — every companion should feel distinct.",
+    "",
+    `Rarity: ${rarity.toUpperCase()}`,
+    `Species: ${species}`,
+    `Stats: ${statStr}`,
+    `Inspiration words: ${vibes.join(", ")}`,
+    shiny ? "SHINY variant — extra special." : "",
+    "",
+    "Return JSON: {\"name\": \"1-14 chars\", \"personality\": \"2-3 sentences describing behavior\"}",
+  ].filter(Boolean).join("\n");
+}

package/server/state.ts

@@ -0,0 +1,409 @@
+/**
+ * State management — reads/writes companion data to ~/.claude-buddy/
+ *
+ * Storage layout (v3 — single manifest):
+ *   ~/.claude-buddy/
+ *     menagerie.json   <- SSOT: { active, companions: { [slot]: Companion } }
+ *     reaction.$SID.json  <- transient reaction state (session-scoped)
+ *     status.json      <- compact state for the status-line shell script
+ *     config.json      <- user preferences (cooldown, bubble style, etc.)
+ *
+ * Rules:
+ *   - saveCompanionSlot()  APPENDS only — throws if the slot already exists
+ *   - saveCompanion()      UPDATES the currently-active slot (rename / personality)
+ *   - All manifest writes are atomic (write tmp -> rename)
+ *
+ * Combined: PR #4 menagerie + PR #6 session isolation + config
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  renameSync,
+} from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { Companion } from "./engine.ts";
+
+const STATE_DIR = join(homedir(), ".claude-buddy");
+const MANIFEST_FILE = join(STATE_DIR, "menagerie.json");
+const CONFIG_FILE = join(STATE_DIR, "config.json");
+
+// ─── Session ID (PR #6: tmux session isolation) ─────────────────────────────
+
+function sessionId(): string {
+  const pane = process.env.TMUX_PANE;
+  if (!pane) return "default";
+  return pane.replace(/^%/, "");
+}
+
+function reactionFile(): string {
+  return join(STATE_DIR, `reaction.${sessionId()}.json`);
+}
+
+// ─── Manifest schema ─────────────────────────────────────────────────────────
+
+interface Manifest {
+  active: string;
+  companions: Record<string, Companion>;
+}
+
+function emptyManifest(): Manifest {
+  return { active: "buddy", companions: {} };
+}
+
+// ─── Atomic manifest I/O ─────────────────────────────────────────────────────
+
+function loadManifest(): Manifest {
+  try {
+    const raw = readFileSync(MANIFEST_FILE, "utf8");
+    const m = JSON.parse(raw) as Manifest;
+    if (!m.companions) m.companions = {};
+    return m;
+  } catch {
+    return emptyManifest();
+  }
+}
+
+function saveManifest(m: Manifest): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const tmp = MANIFEST_FILE + ".tmp";
+  writeFileSync(tmp, JSON.stringify(m, null, 2));
+  renameSync(tmp, MANIFEST_FILE); // atomic on same filesystem
+}
+
+// ─── Slot helpers ────────────────────────────────────────────────────────────
+
+/** Normalise a string to a safe slot key (a-z0-9-, max 14 chars). */
+export function slugify(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "")
+      .slice(0, 14) || "buddy"
+  );
+}
+
+/**
+ * Return a random fallback name whose slug is not already in the manifest.
+ * Falls back to "buddy-<random 3 digits>" if all names are taken.
+ */
+export function unusedName(): string {
+  const { generateFallbackName } =
+    require("./reactions.ts") as typeof import("./reactions.ts");
+  const taken = new Set(Object.keys(loadManifest().companions));
+  for (let i = 0; i < 50; i++) {
+    const n = generateFallbackName();
+    if (!taken.has(slugify(n))) return n;
+  }
+  let suffix = 0;
+  while (taken.has(`buddy-${suffix}`)) suffix++;
+  return `buddy-${suffix}`;
+}
+
+// ─── Active slot ─────────────────────────────────────────────────────────────
+
+export function loadActiveSlot(): string {
+  const m = loadManifest();
+  if (m.active && m.companions[m.active]) return m.active;
+  const first = Object.keys(m.companions)[0];
+  if (first) {
+    m.active = first;
+    saveManifest(m);
+    return first;
+  }
+  return "buddy";
+}
+
+export function saveActiveSlot(slot: string): void {
+  const m = loadManifest();
+  m.active = slot;
+  saveManifest(m);
+}
+
+// ─── Companion slot API ───────────────────────────────────────────────────────
+
+export function loadCompanionSlot(slot: string): Companion | null {
+  return loadManifest().companions[slot] ?? null;
+}
+
+/**
+ * APPEND a new companion to the manifest.
+ * Throws if the slot already exists — use saveCompanion() to update an existing buddy.
+ */
+export function saveCompanionSlot(companion: Companion, slot: string): void {
+  const m = loadManifest();
+  if (m.companions[slot]) {
+    throw new Error(`Slot "${slot}" already exists. Choose a different name.`);
+  }
+  m.companions[slot] = companion;
+  saveManifest(m);
+}
+
+export function deleteCompanionSlot(slot: string): void {
+  const m = loadManifest();
+  delete m.companions[slot];
+  if (m.active === slot) {
+    m.active = Object.keys(m.companions)[0] ?? "buddy";
+  }
+  saveManifest(m);
+}
+
+export function listCompanionSlots(): Array<{
+  slot: string;
+  companion: Companion;
+}> {
+  return Object.entries(loadManifest().companions).map(([slot, companion]) => ({
+    slot,
+    companion,
+  }));
+}
+
+// ─── Primary companion API ────────────────────────────────────────────────────
+
+export function loadCompanion(): Companion | null {
+  migrateIfNeeded();
+  const m = loadManifest();
+  return m.companions[m.active] ?? null;
+}
+
+/**
+ * UPDATE the currently-active companion (rename, personality changes, etc.).
+ * This is the ONLY intentional in-place update path.
+ */
+export function saveCompanion(companion: Companion): void {
+  const m = loadManifest();
+  m.companions[m.active] = companion;
+  saveManifest(m);
+}
+
+// ─── Migration: legacy companion.json -> single manifest ────────────────────
+
+function migrateIfNeeded(): void {
+  if (existsSync(MANIFEST_FILE)) return;
+
+  const companions: Record<string, Companion> = {};
+  let active = "buddy";
+
+  // Absorb menagerie/<slot>.json files
+  const menagerieDir = join(STATE_DIR, "menagerie");
+  if (existsSync(menagerieDir)) {
+    try {
+      for (const f of readdirSync(menagerieDir).filter((f) =>
+        f.endsWith(".json"),
+      )) {
+        const slot = f.slice(0, -5);
+        try {
+          companions[slot] = JSON.parse(
+            readFileSync(join(menagerieDir, f), "utf8"),
+          );
+        } catch {
+          /* skip malformed */
+        }
+      }
+    } catch {
+      /* noop */
+    }
+  }
+
+  // Absorb legacy companion.json
+  const legacyFile = join(STATE_DIR, "companion.json");
+  if (existsSync(legacyFile) && Object.keys(companions).length === 0) {
+    try {
+      const c: Companion = JSON.parse(readFileSync(legacyFile, "utf8"));
+      const slot = slugify(c.name);
+      companions[slot] = c;
+      active = slot;
+    } catch {
+      /* noop */
+    }
+  }
+
+  // Read active pointer if it exists
+  const activeFile = join(STATE_DIR, "active");
+  if (existsSync(activeFile)) {
+    try {
+      const a = readFileSync(activeFile, "utf8").trim();
+      if (a && companions[a]) active = a;
+    } catch {
+      /* noop */
+    }
+  }
+
+  if (Object.keys(companions).length > 0) {
+    active = active && companions[active] ? active : Object.keys(companions)[0];
+  }
+
+  saveManifest({ active, companions });
+}
+
+// ─── Reaction state (session-scoped for tmux isolation) ──────────────────────
+
+export interface ReactionState {
+  reaction: string;
+  timestamp: number;
+  reason: string;
+}
+
+export function loadReaction(): ReactionState | null {
+  try {
+    const data: ReactionState = JSON.parse(readFileSync(reactionFile(), "utf8"));
+    const { reactionTTL } = loadConfig();
+    if (reactionTTL > 0 && Date.now() - data.timestamp > reactionTTL * 1000) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export function saveReaction(reaction: string, reason: string): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const state: ReactionState = { reaction, timestamp: Date.now(), reason };
+  writeFileSync(reactionFile(), JSON.stringify(state));
+}
+
+// ─── Identity resolution ─────────────────────────────────────────────────────
+
+export function resolveUserId(): string {
+  try {
+    const claudeJson = JSON.parse(
+      readFileSync(join(homedir(), ".claude.json"), "utf8"),
+    );
+    return claudeJson.oauthAccount?.accountUuid ?? claudeJson.userID ?? "anon";
+  } catch {
+    return "anon";
+  }
+}
+
+// ─── Config persistence (PR #6: tmux popup settings) ─────────────────────────
+
+export interface BuddyConfig {
+  commentCooldown: number;
+  reactionTTL: number;
+  bubbleStyle: "classic" | "round";
+  bubblePosition: "top" | "left";
+  showRarity: boolean;
+  statusLineEnabled: boolean;
+}
+
+const DEFAULT_CONFIG: BuddyConfig = {
+  commentCooldown: 30,
+  reactionTTL: 0,
+  bubbleStyle: "classic",
+  bubblePosition: "top",
+  showRarity: true,
+  statusLineEnabled: false,
+};
+
+export function loadConfig(): BuddyConfig {
+  try {
+    const data = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+    return { ...DEFAULT_CONFIG, ...data };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function saveConfig(config: Partial<BuddyConfig>): BuddyConfig {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const current = loadConfig();
+  const merged = { ...current, ...config };
+  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2));
+  return merged;
+}
+
+// ─── Status line state (compact JSON for the shell script) ───────────────────
+
+export interface StatusState {
+  name: string;
+  species: string;
+  rarity: string;
+  stars: string;
+  face: string;
+  eye: string;
+  shiny: boolean;
+  hat: string;
+  reaction: string;
+  muted: boolean;
+  achievement: string;
+}
+
+export function writeStatusState(
+  companion: Companion,
+  reaction?: string,
+  muted?: boolean,
+  achievement?: string,
+): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+  const { renderFace, RARITY_STARS } =
+    require("./engine.ts") as typeof import("./engine.ts");
+  const state: StatusState = {
+    name: companion.name,
+    species: companion.bones.species,
+    rarity: companion.bones.rarity,
+    stars: RARITY_STARS[companion.bones.rarity],
+    face: renderFace(companion.bones.species, companion.bones.eye),
+    eye: companion.bones.eye,
+    shiny: companion.bones.shiny,
+    hat: companion.bones.hat,
+    reaction: reaction ?? "",
+    muted: muted ?? false,
+    achievement: achievement ?? "",
+  };
+  writeFileSync(join(STATE_DIR, "status.json"), JSON.stringify(state));
+}
+
+// ─── Claude Code settings.json patching (for buddy_statusline tool) ──────────
+
+export const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+
+/**
+ * Write settings.statusLine pointing to the given buddy-status script.
+ * Atomic via tmp + rename. Returns false if settings.json is unreachable.
+ */
+export function setBuddyStatusLine(
+  statusScript: string,
+  settingsPath: string = CLAUDE_SETTINGS_PATH,
+): boolean {
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    settings.statusLine = {
+      type: "command",
+      command: statusScript,
+      padding: 1,
+      refreshInterval: 1,
+    };
+    const tmp = settingsPath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, settingsPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove settings.statusLine — but only if it points to buddy-status.sh.
+ * Leaves foreign statusLines untouched. Returns false if no buddy line was
+ * present or settings.json is unreachable.
+ */
+export function unsetBuddyStatusLine(
+  settingsPath: string = CLAUDE_SETTINGS_PATH,
+): boolean {
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    if (!settings.statusLine?.command?.includes("buddy-status.sh")) return false;
+    delete settings.statusLine;
+    const tmp = settingsPath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+    renameSync(tmp, settingsPath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/skills/buddy/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: buddy
+description: "Show, pet, or manage your coding companion. Use when the user types /buddy or mentions their companion by name."
+argument-hint: "[show|pet|stats|help|off|on|rename <name>|personality <text>|achievements|summon [slot]|save [slot]|list|dismiss <slot>|pick|frequency [seconds]|style [classic|round]|position [top|left]|rarity [on|off]|statusline [on|off]]"
+allowed-tools: mcp__claude_buddy__*
+---
+
+# Buddy — Your Coding Companion
+
+Handle the user's `/buddy` command using the claude-buddy MCP tools.
+
+## Command Routing
+
+Based on `$ARGUMENTS`:
+
+| Input                    | Action                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| _(empty)_ or `show`      | Call `buddy_show`                                                                            |
+| `help`                   | Call `buddy_help`                                                                            |
+| `pet`                    | Call `buddy_pet`                                                                             |
+| `stats`                  | Call `buddy_stats`                                                                           |
+| `off`                    | Call `buddy_mute`                                                                            |
+| `on`                     | Call `buddy_unmute`                                                                          |
+| `rename <name>`          | Call `buddy_rename` with the given name                                                      |
+| `personality <text>`     | Call `buddy_set_personality` with the given text                                             |
+| `achievements`           | Call `buddy_achievements`                                                                    |
+| `summon`                 | Call `buddy_summon` with no args — picks a random saved buddy                                |
+| `summon <slot>`          | Call `buddy_summon` with the given slot name                                                 |
+| `save [slot]`            | Call `buddy_save` with optional slot name                                                    |
+| `list`                   | Call `buddy_list`                                                                            |
+| `dismiss <slot>`         | Call `buddy_dismiss` with the slot name                                                      |
+| `pick`                   | Tell user to run `! bun run pick` from the claude-buddy directory (launches interactive TUI) |
+| `frequency`              | Call `buddy_frequency` with no args (show current)                                           |
+| `frequency <seconds>`    | Call `buddy_frequency` with cooldown=seconds                                                 |
+| `style`                  | Call `buddy_style` with no args (show current)                                               |
+| `style <classic\|round>` | Call `buddy_style` with style arg                                                            |
+| `position`               | Call `buddy_style` with no args (show current)                                               |
+| `position <top\|left>`   | Call `buddy_style` with position arg                                                         |
+| `rarity on`              | Call `buddy_style` with showRarity=true                                                      |
+| `rarity off`             | Call `buddy_style` with showRarity=false                                                     |
+| `statusline`             | Call `buddy_statusline` with no args (show current)                                          |
+| `statusline on`          | Call `buddy_statusline` with enabled=true                                                    |
+| `statusline off`         | Call `buddy_statusline` with enabled=false                                                   |
+
+## CRITICAL OUTPUT RULES
+
+The MCP tools return pre-formatted ASCII art with ANSI colors, box-drawing characters, stat bars, and species art. This is the companion's visual identity.
+
+**You MUST output the tool result text EXACTLY as returned — character for character, line for line.** Do NOT:
+
+- Summarize or paraphrase the ASCII art
+- Describe what the companion looks like in prose
+- Add commentary before or after the card
+- Reformat, rephrase, or interpret the output
+- Strip ANSI escape codes
+
+**Just output the raw text content from the tool result. Nothing else.** The ASCII art IS the response.
+
+If the user mentions the buddy's name in normal conversation, call `buddy_react` with reason "turn" and display the result verbatim.