@umang-boss/claudemon 1.0.0

package/src/server/tools/rename.ts

@@ -0,0 +1,63 @@
+/**
+ * buddy_rename tool — Give your active Pokemon a nickname.
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { StateManager } from "../../state/state-manager.js";
+
+/** Register the buddy_rename tool. */
+export function registerRenameTool(server: McpServer): void {
+  server.tool(
+    "buddy_rename",
+    "Give your active Pokemon a nickname (max 20 chars). Use empty string to reset to species name.",
+    { name: z.string().max(20) },
+    async (params) => {
+      const stateManager = StateManager.getInstance();
+      const state = await stateManager.load();
+
+      if (!state || state.party.length === 0) {
+        return {
+          content: [{ type: "text" as const, text: "No Pokemon to rename! Pick a starter first." }],
+          isError: true,
+        };
+      }
+
+      const active = stateManager.getActivePokemon();
+      if (!active) {
+        return {
+          content: [{ type: "text" as const, text: "No active Pokemon found." }],
+          isError: true,
+        };
+      }
+
+      const species = POKEMON_BY_ID.get(active.pokemonId);
+      const speciesName = species?.name ?? "Pokemon";
+      const newName = params.name.trim();
+
+      if (newName === "") {
+        active.nickname = null;
+        await stateManager.save();
+        await stateManager.writeStatus();
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Nickname removed. Your buddy is back to ${speciesName}.`,
+            },
+          ],
+        };
+      }
+
+      const oldName = active.nickname ?? speciesName;
+      active.nickname = newName;
+      await stateManager.save();
+      await stateManager.writeStatus();
+
+      return {
+        content: [{ type: "text" as const, text: `${oldName} is now known as **${newName}**!` }],
+      };
+    },
+  );
+}

package/src/server/tools/show.ts

@@ -0,0 +1,136 @@
+/**
+ * buddy_show tool — Display the active Pokemon with stats and XP.
+ * Supports "full" and "compact" display modes.
+ * Shows the pokemon-colorscript ANSI sprite art.
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CodingStat } from "../../engine/types.js";
+import { CODING_STATS } from "../../engine/types.js";
+import { POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { STAT_DISPLAY_NAMES } from "../../engine/constants.js";
+import { renderStatBar, getTrainerTitle } from "../../engine/stats.js";
+import { xpProgressPercent, xpToNextLevel } from "../../engine/xp.js";
+import { StateManager } from "../../state/state-manager.js";
+import { formatTypes, renderXpBar, pad } from "./display-helpers.js";
+
+/** Registers the buddy_show tool on the MCP server. */
+export function registerShowTool(server: McpServer): void {
+  server.tool(
+    "buddy_show",
+    "Display your active Pokemon's status, stats, and XP progress.",
+    { detail: z.enum(["full", "compact"]).optional() },
+    async (params) => {
+      const stateManager = StateManager.getInstance();
+      const state = await stateManager.load();
+
+      if (!state || state.party.length === 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "You don't have a Pokemon yet! Use buddy_starter to pick your first partner.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const active = stateManager.getActivePokemon();
+      if (!active) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "No active Pokemon found in your party. Something went wrong with your save data.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const species = POKEMON_BY_ID.get(active.pokemonId);
+      if (!species) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Could not find species data for Pokemon ID ${active.pokemonId}.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const detail = params.detail ?? "full";
+      const percent = xpProgressPercent(active, species);
+
+      // Compact mode: single line
+      if (detail === "compact") {
+        const displayName = active.nickname ? `${active.nickname} (${species.name})` : species.name;
+        const xpBar = renderXpBar(percent, 15);
+        const text = `${displayName}  Lv.${active.level}  [${xpBar}] ${percent}% XP`;
+        return {
+          content: [{ type: "text" as const, text }],
+        };
+      }
+
+      // Full mode: detailed card with sprite image
+      const displayName = active.nickname ? `${species.name} (${active.nickname})` : species.name;
+
+      const needed = xpToNextLevel(active.level, species.expGroup);
+      const title = getTrainerTitle(active.level);
+      const typeStr = formatTypes(species.types);
+      const personality = active.personality ?? species.description;
+
+      const W = 42;
+      const border = "\u2500".repeat(W);
+      const lines: string[] = [];
+
+      lines.push(`\u250c${border}\u2510`);
+      lines.push(`\u2502  ${pad(`${displayName}   Lv.${active.level}`, W - 2)}\u2502`);
+      lines.push(`\u2502  ${pad(typeStr, W - 2)}\u2502`);
+      lines.push(`\u2502${" ".repeat(W)}\u2502`);
+      lines.push(`\u2502  ${pad(`"${personality}"`, W - 2)}\u2502`);
+      lines.push(`\u2502${" ".repeat(W)}\u2502`);
+
+      // Coding stats
+      for (const stat of CODING_STATS) {
+        const value = active.codingStats[stat as CodingStat];
+        const bar = renderStatBar(value);
+        const label = STAT_DISPLAY_NAMES[stat as CodingStat].padEnd(10);
+        lines.push(`\u2502  ${pad(`${label} ${bar}  ${String(value).padStart(3)}`, W - 2)}\u2502`);
+      }
+
+      lines.push(`\u2502${" ".repeat(W)}\u2502`);
+
+      // XP bar
+      const xpBar = renderXpBar(percent);
+      lines.push(`\u2502  ${pad(`XP: [${xpBar}] ${percent}%`, W - 2)}\u2502`);
+
+      if (needed > 0) {
+        lines.push(`\u2502  ${pad(`Next level: ${needed} XP needed`, W - 2)}\u2502`);
+      } else {
+        lines.push(`\u2502  ${pad("MAX LEVEL", W - 2)}\u2502`);
+      }
+
+      lines.push(`\u2502${" ".repeat(W)}\u2502`);
+      lines.push(`\u2502  ${pad(`Trainer: ${state.trainerName} \u2014 ${title}`, W - 2)}\u2502`);
+
+      const streakDisplay =
+        state.streak.currentStreak > 0
+          ? `Streak: ${state.streak.currentStreak} days`
+          : "Streak: 0 days";
+      lines.push(`\u2502  ${pad(streakDisplay, W - 2)}\u2502`);
+      lines.push(`\u2514${border}\u2518`);
+
+      // Prepend colorscript sprite if available
+      // ANSI colorscripts don't render in MCP text output — skip sprites here
+      // Users can view sprites in terminal: cat sprites/colorscripts/small/{id}-{name}.txt
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+      };
+    },
+  );
+}

package/src/server/tools/starter.ts

@@ -0,0 +1,175 @@
+/**
+ * buddy_starter tool — First-run starter Pokemon selection.
+ * Presents 3 daily-deterministic Pokemon from the starter pool.
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OwnedPokemon, CodingStats } from "../../engine/types.js";
+import { POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { STARTER_POOL } from "../../engine/starter-pool.js";
+import { STARTER_LEVEL } from "../../engine/constants.js";
+import { initCodingStats } from "../../engine/stats.js";
+import { StateManager } from "../../state/state-manager.js";
+import { formatTypes } from "./display-helpers.js";
+
+/** Simple string hash for deterministic seeding. */
+function hashString(str: string): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash + char) | 0;
+  }
+  return Math.abs(hash);
+}
+
+/** Deterministic shuffle using a seed, returns a new array. */
+function seededShuffle<T>(array: readonly T[], seed: number): T[] {
+  const result = [...array];
+  let s = seed;
+  for (let i = result.length - 1; i > 0; i--) {
+    // Simple LCG for deterministic pseudo-random
+    s = (s * 1664525 + 1013904223) & 0x7fffffff;
+    const j = s % (i + 1);
+    [result[i], result[j]] = [result[j]!, result[i]!];
+  }
+  return result;
+}
+
+/** Get today's date string in YYYY-MM-DD for daily seed. */
+function todayString(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/** Generate today's 3 starter options (deterministic per day). */
+function getDailyStarters(): number[] {
+  const seed = hashString(`claudemon-starter-${todayString()}`);
+  const shuffled = seededShuffle(STARTER_POOL, seed);
+  return [shuffled[0]!, shuffled[1]!, shuffled[2]!];
+}
+
+/** Generate a UUID v4. */
+function generateUUID(): string {
+  return crypto.randomUUID();
+}
+
+/** Registers the buddy_starter tool on the MCP server. */
+export function registerStarterTool(server: McpServer): void {
+  server.tool(
+    "buddy_starter",
+    "Pick your starter Pokemon! Call without a choice to see today's 3 options, or with choice (1, 2, or 3) to pick one.",
+    { choice: z.number().min(1).max(3).optional() },
+    async (params) => {
+      const stateManager = StateManager.getInstance();
+      const existingState = await stateManager.load();
+
+      // Block if player already has Pokemon
+      if (existingState !== null && existingState.party.length > 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "You already have a Pokemon partner! Use buddy_show to check on them.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const starterIds = getDailyStarters();
+
+      // No choice provided — show the 3 options
+      if (params.choice === undefined) {
+        const lines: string[] = ["Welcome to Claudemon! Choose your coding companion:", ""];
+
+        for (let i = 0; i < 3; i++) {
+          const pokemonId = starterIds[i]!;
+          const species = POKEMON_BY_ID.get(pokemonId);
+          if (!species) continue;
+
+          const stats = initCodingStats(species.baseStats);
+          const topStat = (Object.entries(stats) as Array<[keyof CodingStats, number]>).sort(
+            (a, b) => b[1] - a[1],
+          )[0]!;
+
+          lines.push(
+            `  ${i + 1}. **${species.name}** (${formatTypes(species.types)})`,
+            `     "${species.description}"`,
+            `     Best stat: ${topStat[0].toUpperCase()} (${topStat[1]})`,
+            "",
+          );
+        }
+
+        lines.push("Call buddy_starter with choice: 1, 2, or 3 to pick your partner!");
+
+        return {
+          content: [{ type: "text" as const, text: lines.join("\n") }],
+        };
+      }
+
+      // Choice provided — create the starter
+      const chosenIndex = params.choice - 1;
+      const chosenId = starterIds[chosenIndex]!;
+      const species = POKEMON_BY_ID.get(chosenId);
+
+      if (!species) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Something went wrong looking up that Pokemon. Please try again.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const starter: OwnedPokemon = {
+        id: generateUUID(),
+        pokemonId: species.id,
+        nickname: null,
+        level: STARTER_LEVEL,
+        currentXp: 0,
+        totalXp: 0,
+        codingStats: initCodingStats(species.baseStats),
+        happiness: 70,
+        caughtAt: new Date().toISOString(),
+        evolvedAt: null,
+        isActive: true,
+        personality: species.description,
+        shiny: false,
+        isStarter: true,
+      };
+
+      const trainerId = generateUUID();
+      const trainerName = "Trainer";
+      await stateManager.initializePlayer(trainerId, trainerName, starter);
+      await stateManager.writeStatus();
+
+      const lines: string[] = [];
+
+      lines.push(
+        `Congratulations! You chose **${species.name}**!`,
+        "",
+        `  Species: ${species.name} (#${String(species.id).padStart(3, "0")})`,
+        `  Type: ${formatTypes(species.types)}`,
+        `  Level: ${STARTER_LEVEL}`,
+        `  Exp Group: ${species.expGroup}`,
+        "",
+        `  "${species.description}"`,
+        "",
+        `Your coding journey begins now. Write code, fix bugs, and watch ${species.name} grow!`,
+        "",
+        "Use buddy_show to see your Pokemon, or buddy_pet to bond with them.",
+      );
+
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+      };
+    },
+  );
+}

package/src/server/tools/stats.ts

@@ -0,0 +1,123 @@
+/**
+ * buddy_stats tool — Detailed stat breakdown for the active Pokemon.
+ * Shows coding stats, base values, activity bonuses, and XP details.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CodingStat } from "../../engine/types.js";
+import { CODING_STATS } from "../../engine/types.js";
+import { POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { STAT_DISPLAY_NAMES } from "../../engine/constants.js";
+import { renderStatBar, calculateDisplayStat } from "../../engine/stats.js";
+import { xpProgressPercent, xpToNextLevel, cumulativeXpForLevel } from "../../engine/xp.js";
+import { StateManager } from "../../state/state-manager.js";
+import { renderXpBar, CODING_TO_BASE } from "./display-helpers.js";
+
+/** Registers the buddy_stats tool on the MCP server. */
+export function registerStatsTool(server: McpServer): void {
+  server.tool(
+    "buddy_stats",
+    "Show a detailed stat breakdown for your active Pokemon, including base values, activity bonuses, and XP info.",
+    {},
+    async () => {
+      const stateManager = StateManager.getInstance();
+      const state = await stateManager.load();
+
+      if (!state || state.party.length === 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "You don't have a Pokemon yet! Use buddy_starter to pick your first partner.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const active = stateManager.getActivePokemon();
+      if (!active) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "No active Pokemon found in your party.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const species = POKEMON_BY_ID.get(active.pokemonId);
+      if (!species) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Could not find species data for Pokemon ID ${active.pokemonId}.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const lines: string[] = [];
+
+      lines.push(`== ${species.name} Lv.${active.level} -- Stat Breakdown ==`);
+      lines.push("");
+
+      // Column header
+      lines.push("  STAT        BAR           VALUE   BASE  BONUS");
+      lines.push("  " + "\u2500".repeat(48));
+
+      for (const stat of CODING_STATS) {
+        const codingStat = stat as CodingStat;
+        const baseKey = CODING_TO_BASE[codingStat];
+        const baseValue = species.baseStats[baseKey];
+
+        // The initial coding stat was floor(baseStat * 0.5).
+        // Current activity bonus = current codingStats value - initial value.
+        const initialValue = Math.floor(baseValue * 0.5);
+        const activityBonus = active.codingStats[codingStat] - initialValue;
+
+        const displayValue = calculateDisplayStat(baseValue, active.level, activityBonus);
+        const bar = renderStatBar(displayValue);
+        const label = STAT_DISPLAY_NAMES[codingStat].padEnd(10);
+
+        lines.push(
+          `  ${label} ${bar}  ${String(displayValue).padStart(4)}` +
+            `   ${String(baseValue).padStart(3)}` +
+            `   ${activityBonus >= 0 ? "+" : ""}${activityBonus}`,
+        );
+      }
+
+      lines.push("");
+      lines.push("  " + "\u2500".repeat(48));
+      lines.push("");
+
+      // XP details
+      const percent = xpProgressPercent(active, species);
+      const needed = xpToNextLevel(active.level, species.expGroup);
+      const cumulativeNow = cumulativeXpForLevel(active.level, species.expGroup);
+      const xpBar = renderXpBar(percent);
+
+      lines.push("  XP Details:");
+      lines.push(`    Exp Group:      ${species.expGroup}`);
+      lines.push(`    Level:          ${active.level}`);
+      lines.push(`    Current XP:     ${active.currentXp} / ${needed > 0 ? needed : "MAX"}`);
+      lines.push(`    Total XP:       ${active.totalXp}`);
+      lines.push(`    Cumulative:     ${cumulativeNow} (to reach Lv.${active.level})`);
+      lines.push(`    Progress:       [${xpBar}] ${percent}%`);
+
+      if (needed > 0) {
+        lines.push(`    To next level:  ${needed - active.currentXp} XP remaining`);
+      } else {
+        lines.push("    MAX LEVEL REACHED");
+      }
+
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+      };
+    },
+  );
+}

package/src/server/tools/visibility.ts

@@ -0,0 +1,65 @@
+/**
+ * buddy_hide / buddy_show_sprite — Toggle sprite visibility in status line.
+ * Writes to ~/.claudemon/config.json which the status line script reads.
+ */
+
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getStateDir } from "../../engine/constants.js";
+import { ensureDir, atomicWrite, safeRead } from "../../state/io.js";
+import { join } from "node:path";
+
+interface BuddyDisplayConfig {
+  spriteHidden: boolean;
+  [key: string]: unknown;
+}
+
+async function getConfigPath(): Promise<string> {
+  return join(getStateDir(), "config.json");
+}
+
+async function readConfig(): Promise<BuddyDisplayConfig> {
+  const path = await getConfigPath();
+  const data = await safeRead<BuddyDisplayConfig>(path);
+  return data ?? { spriteHidden: false };
+}
+
+async function writeConfig(config: BuddyDisplayConfig): Promise<void> {
+  const path = await getConfigPath();
+  await ensureDir(getStateDir());
+  await atomicWrite(path, JSON.stringify(config, null, 2));
+}
+
+/** Register buddy_hide tool — hides sprite from status line */
+export function registerHideTool(server: McpServer): void {
+  server.tool("buddy_hide", "Hide the Pokemon sprite from the status line.", {}, async () => {
+    const config = await readConfig();
+    config.spriteHidden = true;
+    await writeConfig(config);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: "Sprite hidden from status line. Use /buddy unhide to show it again.",
+        },
+      ],
+    };
+  });
+}
+
+/** Register buddy_unhide tool — shows sprite in status line */
+export function registerUnhideTool(server: McpServer): void {
+  server.tool("buddy_unhide", "Show the Pokemon sprite in the status line.", {}, async () => {
+    const config = await readConfig();
+    config.spriteHidden = false;
+    await writeConfig(config);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: "Sprite restored to status line!",
+        },
+      ],
+    };
+  });
+}

package/src/sprites/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Sprite loader for pokemon-colorscripts.
+ * Reads pre-rendered ANSI art from small .txt files.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { POKEMON_BY_ID } from "../engine/pokemon-data.js";
+
+const COLORSCRIPT_DIR = join(import.meta.dir, "../../sprites/colorscripts/small");
+
+const cache = new Map<number, string>();
+
+/** Normalize Pokemon name to match colorscript filename convention */
+function normalizeSpriteName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace("♀", "-f")
+    .replace("♂", "-m")
+    .replace("'", "")
+    .replace(". ", "-")
+    .replace(" ", "-");
+}
+
+/** Load a small colorscript sprite (~11 lines). Used everywhere. */
+export function loadSmallSprite(pokemonId: number): string | null {
+  const cached = cache.get(pokemonId);
+  if (cached !== undefined) return cached;
+
+  const pokemon = POKEMON_BY_ID.get(pokemonId);
+  if (!pokemon) return null;
+
+  const fileName = `${pokemonId}-${normalizeSpriteName(pokemon.name)}.txt`;
+  const filePath = join(COLORSCRIPT_DIR, fileName);
+
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    cache.set(pokemonId, content);
+    return content;
+  } catch {
+    return null;
+  }
+}

package/src/state/io.ts

@@ -0,0 +1,91 @@
+/**
+ * Atomic file I/O helpers for state persistence.
+ * All disk writes go through atomicWrite to prevent corruption.
+ */
+
+import { rename, mkdir, copyFile, unlink, stat } from "node:fs/promises";
+
+/** Write data atomically via temp file + rename */
+export async function atomicWrite(path: string, data: string): Promise<void> {
+  const tmpPath = `${path}.${Date.now()}.tmp`;
+  await Bun.write(tmpPath, data);
+  await rename(tmpPath, path);
+}
+
+/** Read and parse JSON, returning null if file doesn't exist or contains invalid JSON */
+export async function safeRead<T>(path: string): Promise<T | null> {
+  const file = Bun.file(path);
+  const exists = await file.exists();
+  if (!exists) {
+    return null;
+  }
+  try {
+    const text = await file.text();
+    if (!text.trim()) {
+      return null;
+    }
+    return JSON.parse(text) as T;
+  } catch {
+    // Invalid JSON — return null so caller can handle corruption recovery
+    return null;
+  }
+}
+
+/** Ensure directory exists, creating parents as needed */
+export async function ensureDir(path: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+}
+
+/**
+ * Backup a corrupted file by copying it to `<path>.corrupt.<timestamp>`.
+ * Logs the backup path to stderr so the user knows where to find it.
+ */
+export async function backupCorrupted(path: string): Promise<string> {
+  const backupPath = `${path}.corrupt.${Date.now()}`;
+  try {
+    await copyFile(path, backupPath);
+  } catch {
+    // If copy fails (e.g., file vanished), nothing to back up
+  }
+  return backupPath;
+}
+
+/** Maximum age (ms) before a lock file is considered stale */
+const LOCK_MAX_AGE_MS = 5000;
+
+/** Retry delay (ms) when a fresh lock is detected */
+const LOCK_RETRY_DELAY_MS = 100;
+
+/**
+ * Execute a function while holding a simple file lock.
+ * Creates a `.lock` file before the operation and removes it after.
+ * If a lock file exists but is older than 5 seconds, it is treated as stale
+ * (left behind by a dead process) and overwritten.
+ */
+export async function withLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+  // Check for existing lock
+  try {
+    const lockStat = await stat(lockPath);
+    const lockAge = Date.now() - lockStat.mtimeMs;
+    if (lockAge < LOCK_MAX_AGE_MS) {
+      // Lock is fresh — wait briefly then proceed (best-effort advisory lock)
+      await new Promise((r) => setTimeout(r, LOCK_RETRY_DELAY_MS));
+    }
+    // Stale lock or retry — proceed to overwrite
+  } catch {
+    // No lock file exists — proceed
+  }
+
+  // Acquire lock
+  await Bun.write(lockPath, String(Date.now()));
+  try {
+    return await fn();
+  } finally {
+    // Release lock
+    try {
+      await unlink(lockPath);
+    } catch {
+      // Ignore — lock may have been cleaned up by another process or doctor
+    }
+  }
+}