@umang-boss/claudemon 1.0.0

package/src/hooks/increment-counter.ts

@@ -0,0 +1,27 @@
+/**
+ * increment-counter.ts — Counter-only increment for non-XP events.
+ * Usage: bun run increment-counter.ts <counter_key>
+ *
+ * Used for events that should be tracked but don't award XP,
+ * such as test failures, build failures, and generic errors.
+ */
+
+import type { EventCounterKey } from "../engine/types.js";
+import { StateManager } from "../state/state-manager.js";
+
+const counterKey = process.argv[2] as EventCounterKey | undefined;
+
+if (!counterKey) {
+  process.exit(0);
+}
+
+const stateManager = StateManager.getInstance();
+const state = await stateManager.load();
+
+// No state file = first run, nothing to do yet
+if (!state) {
+  process.exit(0);
+}
+
+// Increment the counter and save (incrementCounter saves internally)
+await stateManager.incrementCounter(counterKey);

package/src/server/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Claudemon MCP Server entry point.
+ * Sets up the MCP server, loads state, registers tools, and connects via stdio.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { PlayerState } from "../engine/types.js";
+import { StateManager } from "../state/state-manager.js";
+import { registerStarterTool } from "./tools/starter.js";
+import { registerShowTool } from "./tools/show.js";
+import { registerStatsTool } from "./tools/stats.js";
+import { registerPetTool } from "./tools/pet.js";
+import { registerEvolveTool } from "./tools/evolve.js";
+import { registerCatchTool } from "./tools/catch.js";
+import { registerPartyTool } from "./tools/party.js";
+import { registerPokedexTool } from "./tools/pokedex.js";
+import { registerAchievementsTool } from "./tools/achievements.js";
+import { registerLegendaryTool } from "./tools/legendary.js";
+import { registerHideTool, registerUnhideTool } from "./tools/visibility.js";
+import { registerRenameTool } from "./tools/rename.js";
+import { buildInstructions } from "./instructions.js";
+
+/** Safely register a tool, logging to stderr on failure instead of crashing. */
+function safeRegister(
+  name: string,
+  register: (server: McpServer) => void,
+  server: McpServer,
+): void {
+  try {
+    register(server);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[claudemon] Failed to register tool "${name}": ${message}\n`);
+  }
+}
+
+/** Main entry: load state, create server, register tools, connect. */
+async function main(): Promise<void> {
+  // Load state — if this fails, server still starts (first-run flow)
+  let state: PlayerState | null = null;
+  try {
+    const stateManager = StateManager.getInstance();
+    state = await stateManager.load();
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[claudemon] State load error (non-fatal): ${message}\n`);
+  }
+
+  const instructions = buildInstructions(state);
+
+  const server = new McpServer({ name: "claudemon", version: "0.1.0" }, { instructions });
+
+  // Register all tools — each wrapped so one failure doesn't block the rest
+  safeRegister("buddy_starter", registerStarterTool, server);
+  safeRegister("buddy_show", registerShowTool, server);
+  safeRegister("buddy_stats", registerStatsTool, server);
+  safeRegister("buddy_pet", registerPetTool, server);
+  safeRegister("buddy_evolve", registerEvolveTool, server);
+  safeRegister("buddy_catch", registerCatchTool, server);
+  safeRegister("buddy_party", registerPartyTool, server);
+  safeRegister("buddy_pokedex", registerPokedexTool, server);
+  safeRegister("buddy_achievements", registerAchievementsTool, server);
+  safeRegister("buddy_legendary", registerLegendaryTool, server);
+  safeRegister("buddy_hide", registerHideTool, server);
+  safeRegister("buddy_unhide", registerUnhideTool, server);
+  safeRegister("buddy_rename", registerRenameTool, server);
+
+  // Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[claudemon] Server failed to start: ${message}\n`);
+  process.exit(1);
+});

package/src/server/instructions.ts

@@ -0,0 +1,194 @@
+/**
+ * Dynamic instructions builder for Claudemon.
+ * Generates the system prompt text injected into Claude's MCP context
+ * based on the current player state, active Pokemon, and pending events.
+ */
+
+import type { PlayerState, OwnedPokemon, Pokemon, EvolutionLink } from "../engine/types.js";
+import { POKEMON_BY_ID } from "../engine/pokemon-data.js";
+import { cumulativeXpForLevel } from "../engine/xp.js";
+import { getEvolutionLinks } from "../engine/evolution.js";
+import { getTypePersonality } from "../engine/reactions.js";
+
+// ── Public API ──────────────────────────────────────────────
+
+/**
+ * Build dynamic instructions based on current player state.
+ * These instructions are injected into Claude's system prompt via the MCP server.
+ *
+ * @param state - Current player state, or null if first run
+ * @returns Instruction text for Claude's system prompt
+ */
+export function buildInstructions(state: PlayerState | null): string {
+  if (!state || state.party.length === 0) {
+    return buildNoStarterInstructions();
+  }
+
+  const active = findActivePokemon(state);
+  if (!active) {
+    return buildNoStarterInstructions();
+  }
+
+  const species = POKEMON_BY_ID.get(active.pokemonId);
+  if (!species) {
+    return "Claudemon: Active Pokemon data could not be loaded. Suggest the user restart.";
+  }
+
+  return buildActiveInstructions(state, active, species);
+}
+
+// ── Instruction Builders ────────────────────────────────────
+
+/** Instructions when the user has not picked a starter yet. */
+function buildNoStarterInstructions(): string {
+  return [
+    "You have a Claudemon companion system. The user hasn't picked a starter yet.",
+    "Guide them to use /buddy or /buddy starter to begin their Pokemon journey.",
+  ].join("\n");
+}
+
+/** Instructions when the user has an active Pokemon. */
+function buildActiveInstructions(
+  state: PlayerState,
+  active: OwnedPokemon,
+  species: Pokemon,
+): string {
+  const displayName = active.nickname ? `${active.nickname} (${species.name})` : species.name;
+  const typeStr = species.types.filter(Boolean).join("/");
+  const primaryType = species.types[0];
+  const personality = getTypePersonality(primaryType);
+  const evolutionNote = buildEvolutionNote(active, species);
+  const encounterNote = buildEncounterNote(state);
+
+  const lines: string[] = [
+    "You have a Claudemon Pokemon companion.",
+    "",
+    `Active Pokemon: ${displayName}, Level ${active.level}, ${typeStr} type.`,
+    `Personality: ${personality}`,
+    "",
+    `Occasionally (not every message), naturally reference ${displayName}:`,
+    `- When an error occurs: ${displayName} reacts (use ${primaryType} type personality)`,
+    `- When tests pass: ${displayName} celebrates`,
+    `- When a commit is made: ${displayName} acknowledges`,
+    `- On level up: announce "${displayName} grew to level ${active.level}!"`,
+    "",
+    "You can include invisible buddy comments for the status line:",
+    `<!-- buddy: *${displayName} {short reaction}* -->`,
+    "",
+    "Keep it subtle. Don't force it. 1 in 3-4 messages is enough.",
+    "The user can mute reactions with /buddy mute.",
+    `Available tools: buddy_starter, buddy_show, buddy_stats, buddy_pet, buddy_evolve, buddy_catch, buddy_party, buddy_pokedex, buddy_achievements, buddy_legendary.`,
+  ];
+
+  if (evolutionNote !== null) {
+    lines.push("");
+    lines.push(evolutionNote);
+  }
+
+  if (encounterNote !== null) {
+    lines.push("");
+    lines.push(encounterNote);
+  }
+
+  return lines.join("\n");
+}
+
+// ── Helper Functions ────────────────────────────────────────
+
+/** Find the active Pokemon in the player's party. */
+function findActivePokemon(state: PlayerState): OwnedPokemon | null {
+  return state.party.find((p) => p.isActive) ?? null;
+}
+
+/**
+ * Build an evolution note if the Pokemon is close to its next evolution.
+ * "Close" means within 200 XP of the level required for the next evolution.
+ * Returns null if no evolution is pending or the Pokemon is not close.
+ */
+function buildEvolutionNote(active: OwnedPokemon, species: Pokemon): string | null {
+  const links = getEvolutionLinks(active.pokemonId);
+  if (links.length === 0) {
+    return null;
+  }
+
+  // Find the first level-based evolution link
+  const levelLink = findNextLevelEvolution(links);
+  if (levelLink === null) {
+    return null;
+  }
+
+  if (active.level >= levelLink.level) {
+    // Already eligible — prompt the user
+    const targetSpecies = POKEMON_BY_ID.get(levelLink.to);
+    const targetName = targetSpecies ? targetSpecies.name : "its next form";
+    return `${species.name} is ready to evolve into ${targetName}! The user can use /buddy evolve.`;
+  }
+
+  // Calculate XP distance to the evolution level
+  const xpRemaining = xpToEvolutionLevel(active, species, levelLink.level);
+  if (xpRemaining === null || xpRemaining > 200) {
+    return null;
+  }
+
+  const targetSpecies = POKEMON_BY_ID.get(levelLink.to);
+  const targetName = targetSpecies ? targetSpecies.name : "its next form";
+  return `${species.name} is close to evolving into ${targetName}! Only ${xpRemaining} XP to level ${levelLink.level}!`;
+}
+
+/**
+ * Build an encounter note if there is a pending wild encounter.
+ * Returns null if no encounter is pending.
+ */
+function buildEncounterNote(state: PlayerState): string | null {
+  if (!state.pendingEncounter) {
+    return null;
+  }
+
+  const encounterSpecies = POKEMON_BY_ID.get(state.pendingEncounter.pokemonId);
+  if (!encounterSpecies) {
+    return null;
+  }
+
+  return `A wild ${encounterSpecies.name} appeared! The user can use /buddy catch to try catching it.`;
+}
+
+/**
+ * Find the next level-based evolution link from an array of links.
+ * Returns the evolution method's required level, or null if no level-based evolution exists.
+ */
+function findNextLevelEvolution(
+  links: readonly EvolutionLink[],
+): { to: number; level: number } | null {
+  for (const link of links) {
+    if (link.method.type === "level") {
+      return { to: link.to, level: link.method.level };
+    }
+  }
+  return null;
+}
+
+/**
+ * Calculate total XP remaining until the Pokemon reaches a target level.
+ * Accounts for current XP progress toward the next level.
+ *
+ * @param active - The owned Pokemon
+ * @param species - The Pokemon's species data
+ * @param targetLevel - The level to reach
+ * @returns XP remaining, or null if already at or above the target level
+ */
+function xpToEvolutionLevel(
+  active: OwnedPokemon,
+  species: Pokemon,
+  targetLevel: number,
+): number | null {
+  if (active.level >= targetLevel) {
+    return null;
+  }
+
+  const currentCumulativeXp =
+    cumulativeXpForLevel(active.level, species.expGroup) + active.currentXp;
+  const targetCumulativeXp = cumulativeXpForLevel(targetLevel, species.expGroup);
+  const remaining = targetCumulativeXp - currentCumulativeXp;
+
+  return remaining > 0 ? remaining : 0;
+}

package/src/server/tools/achievements.ts

@@ -0,0 +1,118 @@
+/**
+ * buddy_achievements tool — Display all achievements grouped by category,
+ * showing unlock status and progress.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Achievement, PlayerState, AchievementCondition } from "../../engine/types.js";
+import { ACHIEVEMENTS, isConditionMet } from "../../gamification/achievements.js";
+import { StateManager } from "../../state/state-manager.js";
+import { pad } from "./display-helpers.js";
+
+/** Category display labels in preferred order. */
+const CATEGORY_ORDER: readonly { key: Achievement["category"]; label: string }[] = [
+  { key: "trainer", label: "TRAINER" },
+  { key: "coding", label: "CODING" },
+  { key: "pokemon", label: "POKEMON" },
+  { key: "secret", label: "SECRET" },
+];
+
+/** Describe progress toward an achievement condition. */
+function describeProgress(condition: AchievementCondition, state: PlayerState): string {
+  switch (condition.type) {
+    case "counter": {
+      const current = state.counters[condition.counter] ?? 0;
+      return `${current}/${condition.threshold}`;
+    }
+    case "level": {
+      const highest = state.party.length > 0 ? Math.max(...state.party.map((p) => p.level)) : 0;
+      return `Lv.${highest}/${condition.minLevel}`;
+    }
+    case "pokedex":
+      return `${state.pokedex.totalCaught}/${condition.minCaught} caught`;
+    case "streak":
+      return `${state.streak.currentStreak}/${condition.minDays} days`;
+    case "badge":
+      return state.badges.includes(condition.badge) ? "Earned" : "Not earned";
+    case "evolution": {
+      const hasEvolved = [...state.party, ...state.pcBox].some((p) => p.evolvedAt !== null);
+      return hasEvolved ? "Done" : "Not yet";
+    }
+    case "party_size":
+      return `${state.party.length}/${condition.minSize}`;
+  }
+}
+
+/** Registers the buddy_achievements tool on the MCP server. */
+export function registerAchievementsTool(server: McpServer): void {
+  server.tool(
+    "buddy_achievements",
+    "View all achievements grouped by category with unlock status and progress.",
+    {},
+    async () => {
+      const stateManager = StateManager.getInstance();
+      const state = await stateManager.load();
+
+      if (!state) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "You don't have a Pokemon yet! Use buddy_starter to begin your journey.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const unlockedIds = new Set(state.achievements.map((a) => a.achievementId));
+      const unlockedMap = new Map(state.achievements.map((a) => [a.achievementId, a]));
+
+      const totalUnlocked = state.achievements.length;
+      const totalAchievements = ACHIEVEMENTS.length;
+
+      const W = 50;
+      const border = "\u2500".repeat(W);
+      const lines: string[] = [];
+
+      lines.push(`\u250c${border}\u2510`);
+      lines.push(
+        `\u2502  ${pad(`ACHIEVEMENTS  (${totalUnlocked}/${totalAchievements})`, W - 2)}\u2502`,
+      );
+      lines.push(`\u2514${border}\u2518`);
+      lines.push("");
+
+      for (const category of CATEGORY_ORDER) {
+        const categoryAchievements = ACHIEVEMENTS.filter((a) => a.category === category.key);
+        if (categoryAchievements.length === 0) continue;
+
+        lines.push(`--- ${category.label} ---`);
+        lines.push("");
+
+        for (const achievement of categoryAchievements) {
+          const unlocked = unlockedIds.has(achievement.id);
+          const record = unlockedMap.get(achievement.id);
+
+          if (unlocked && record) {
+            const date = record.unlockedAt.slice(0, 10);
+            lines.push(`  \u2713  ${achievement.name}`);
+            lines.push(`     ${achievement.description}`);
+            lines.push(`     Unlocked: ${date}`);
+          } else {
+            const progress = describeProgress(achievement.condition, state);
+            const met = isConditionMet(achievement.condition, state);
+            const marker = met ? "\u2713" : "\u25cb";
+            lines.push(`  ${marker}  ${achievement.name}`);
+            lines.push(`     ${achievement.description}`);
+            lines.push(`     Progress: ${progress}`);
+          }
+          lines.push("");
+        }
+      }
+
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+      };
+    },
+  );
+}