@umang-boss/claudemon 1.0.0

package/README.md

@@ -0,0 +1,164 @@
+# Claudemon
+
+> Pokemon Gen 1 coding companion for Claude Code -- Gotta code 'em all!
+
+## What is Claudemon?
+
+A gamified coding companion that lives inside Claude Code. Pick a starter Pokemon,
+earn XP from your coding activity, level up, evolve, catch wild Pokemon, and
+fill your Pokedex -- all while you code.
+
+## Features
+
+- **151 Gen 1 Pokemon** with authentic base stats and evolution chains
+- **XP from coding** -- commits, tests, builds, edits, and more
+- **Level up & evolve** -- Charmander -> Charmeleon -> Charizard
+- **Wild encounters** -- Pokemon appear based on your coding activity
+- **Catch 'em all** -- fill your 151-entry Pokedex
+- **Achievements** -- 18 milestones to unlock
+- **Legendary quests** -- multi-step challenges for Articuno, Zapdos, Moltres, Mewtwo, Mew
+- **Colored terminal sprites** -- hand-crafted pixel art in your terminal
+- **Type personalities** -- 15 unique reaction styles
+
+## Quick Start
+
+```bash
+# Install
+bun run cli/install.ts
+
+# Start a new Claude Code session, then:
+/buddy              # Pick your starter
+/buddy show         # See your Pokemon
+/buddy pet          # Bond with your companion
+/buddy stats        # Detailed stats
+/buddy evolve       # Check evolution status
+/buddy catch        # Catch wild Pokemon
+/buddy party        # Manage your party
+/buddy pokedex      # Track your collection
+/buddy achievements # View progress
+/buddy legendary    # Legendary quest chains
+```
+
+## How It Works
+
+Claudemon runs as an MCP (Model Context Protocol) server alongside Claude Code.
+It uses hooks to detect your coding activity and award XP automatically.
+
+### Architecture
+
+```
+Claude Code -> MCP Server (Claudemon)
+           -> Hooks (PostToolUse, Stop, UserPromptSubmit)
+           -> Status Line (name + level + XP bar)
+           -> /buddy Skill (slash commands)
+```
+
+### XP Sources
+
+| Activity | XP | Stat Boosted |
+|----------|-----|-------------|
+| Git commit | +15 | VELOCITY |
+| Tests pass | +12 | STABILITY |
+| Test written | +10 | STABILITY |
+| Build success | +10 | STABILITY |
+| Bug fix | +8 | DEBUGGING |
+| Lint fix | +6 | DEBUGGING |
+| File created | +5 | VELOCITY |
+| File edited | +3 | VELOCITY |
+| Large refactor | +20 | WISDOM |
+
+### Evolution
+
+Pokemon evolve at the same levels as the original Gen 1 games:
+- Level-based: Charmander -> Charmeleon (L16) -> Charizard (L36)
+- Badge-based: Pikachu -> Raichu (Spark Badge -- 200 commits)
+- Collaboration: Kadabra -> Alakazam (10 PRs merged)
+- Stat-based: Eevee -> Flareon/Vaporeon/Jolteon (dominant coding stat)
+
+### Badges
+
+| Badge | Condition | Unlocks |
+|-------|-----------|---------|
+| Blaze Badge | Fix 50 bugs | Fire Stone evolutions |
+| Flow Badge | Pass 100 tests | Water Stone evolutions |
+| Spark Badge | 200 commits | Thunder Stone evolutions |
+| Lunar Badge | 30-day streak | Moon Stone evolutions |
+| Growth Badge | Edit 500 files | Leaf Stone evolutions |
+
+### Trainer Titles
+
+Your title progresses as your Pokemon levels up:
+
+| Level | Title |
+|-------|-------|
+| 1 | Bug Catcher |
+| 6 | Youngster |
+| 11 | Hiker |
+| 21 | Ace Trainer |
+| 31 | Cooltrainer |
+| 41 | Veteran |
+| 51 | Elite Four |
+| 61 | Champion |
+| 76 | Pokemon Master |
+| 91 | Professor |
+
+## CLI Tools
+
+```bash
+# Install Claudemon into Claude Code
+bun run cli/install.ts
+
+# Uninstall (preserves your save data)
+bun run cli/uninstall.ts
+
+# Diagnose installation issues
+bun run cli/doctor.ts
+```
+
+## Development
+
+```bash
+# Run the MCP server directly
+bun run server
+
+# Run tests
+bun test
+
+# Type checking
+bun run typecheck
+
+# Format code
+bun run format
+```
+
+### Project Structure
+
+```
+src/
+  engine/          # Game logic: XP, evolution, encounters, stats
+  gamification/    # Achievements, milestones, legendary quests
+  server/          # MCP server and tool handlers
+  sprites/         # Terminal sprite rendering
+  state/           # Save state management
+cli/               # Install, uninstall, doctor scripts
+hooks/             # PostToolUse, Stop, UserPromptSubmit shell scripts
+skills/buddy/      # /buddy slash command definition
+sprites/full/      # 151 colored terminal sprite files
+statusline/        # Status bar shell script
+tests/             # Test suites
+```
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code) v2.1.80+
+- [Bun](https://bun.sh) v1.0+
+
+## Disclaimer
+
+Pokemon is a trademark of Nintendo/Game Freak/The Pokemon Company.
+Claudemon is a fan project, not affiliated with or endorsed by them.
+Terminal art from [pokemon-colorscripts](https://github.com/tageraf1n/pokemon-colorscripts) (MIT).
+
+## License
+
+MIT

package/bin/claudemon.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Claudemon CLI wrapper — detects Bun and delegates to it.
+ * Works with `npx claudemon` even on systems with only Node.js.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliEntry = resolve(__dirname, "..", "cli", "index.ts");
+const args = process.argv.slice(2);
+
+// Find bun binary
+function findBun() {
+  const home = process.env.HOME || "";
+  const candidates = [
+    `${home}/.bun/bin/bun`,
+    "/usr/local/bin/bun",
+    "/usr/bin/bun",
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  // Try PATH
+  const result = spawnSync("which", ["bun"], { stdio: "pipe" });
+  if (result.status === 0) return "bun";
+  return null;
+}
+
+const bunPath = findBun();
+
+if (bunPath) {
+  const result = spawnSync(bunPath, ["run", cliEntry, ...args], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+} else {
+  console.error(`
+  Claudemon requires Bun (https://bun.sh) to run.
+
+  Install Bun:
+    curl -fsSL https://bun.sh/install | bash
+
+  Then run:
+    npx claudemon install
+  `);
+  process.exit(1);
+}

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+root = "."

package/cli/doctor.ts

@@ -0,0 +1,334 @@
+/**
+ * Claudemon Doctor — diagnostic tool.
+ * Checks the health of the Claudemon installation.
+ *
+ * Usage: bun run cli/doctor.ts
+ */
+
+import { access, stat, unlink, readdir } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { StateManager } from "../src/state/state-manager.js";
+import { PlayerStateSchema } from "../src/state/schemas.js";
+
+import type { ClaudeConfig, ClaudeSettings } from "./shared.js";
+import {
+  readJson,
+  info,
+  CLAUDE_CONFIG,
+  CLAUDE_SETTINGS,
+  STATE_DIR,
+  SKILL_DEST,
+  HOOK_SCRIPT,
+} from "./shared.js";
+
+// ── Local Constants ─────────────────────────────────────────
+
+const STATE_FILE = `${STATE_DIR}/state.json`;
+const LOCK_FILE = `${STATE_DIR}/state.lock`;
+const LOCK_MAX_AGE_MS = 5000;
+const EXPECTED_SPRITE_COUNT = 151;
+const COLORSCRIPT_DIR = resolve(dirname(import.meta.dir), "sprites/colorscripts/small");
+
+// ── Helpers ──────────────────────────────────────────────────
+
+interface CheckResult {
+  label: string;
+  passed: boolean;
+  detail: string;
+}
+
+function formatCheck(result: CheckResult): string {
+  const icon = result.passed ? "\u2713" : "\u2717";
+  return `[${icon}] ${result.label}: ${result.detail}`;
+}
+
+// ── Check 1: Bun Version ─────────────────────────────────────
+
+async function checkBun(): Promise<CheckResult> {
+  try {
+    const proc = Bun.spawn(["bun", "--version"], { stdout: "pipe", stderr: "pipe" });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    return { label: "Bun runtime", passed: true, detail: `v${output.trim()}` };
+  } catch {
+    return { label: "Bun runtime", passed: false, detail: "not found" };
+  }
+}
+
+// ── Check 2: State Directory ─────────────────────────────────
+
+async function checkStateDir(): Promise<CheckResult> {
+  try {
+    await access(STATE_DIR, fsConstants.F_OK);
+    return { label: "State directory", passed: true, detail: "~/.claudemon/" };
+  } catch {
+    return {
+      label: "State directory",
+      passed: false,
+      detail: "~/.claudemon/ not found (run installer)",
+    };
+  }
+}
+
+// ── Check 3: State File ──────────────────────────────────────
+
+async function checkStateFile(): Promise<CheckResult> {
+  const file = Bun.file(STATE_FILE);
+  if (!(await file.exists())) {
+    return { label: "State file", passed: false, detail: "not found (run /buddy starter first)" };
+  }
+
+  try {
+    const text = await file.text();
+    const data = JSON.parse(text) as Record<string, unknown>;
+
+    // Check for active pokemon
+    const party = data["party"];
+    if (Array.isArray(party) && party.length > 0) {
+      const active = party.find(
+        (p: unknown) =>
+          typeof p === "object" &&
+          p !== null &&
+          "isActive" in p &&
+          (p as Record<string, unknown>)["isActive"] === true,
+      );
+      if (active && typeof active === "object" && "pokemonId" in active) {
+        return {
+          label: "State file",
+          passed: true,
+          detail: `valid, active Pokemon #${(active as Record<string, unknown>)["pokemonId"]}`,
+        };
+      }
+      return { label: "State file", passed: true, detail: "valid, but no active Pokemon set" };
+    }
+
+    return { label: "State file", passed: true, detail: "valid JSON, no party members yet" };
+  } catch {
+    return { label: "State file", passed: false, detail: "exists but invalid JSON" };
+  }
+}
+
+// ── Check 4: MCP Server Registration ─────────────────────────
+
+async function checkMcpServer(): Promise<CheckResult> {
+  const config = await readJson<ClaudeConfig>(CLAUDE_CONFIG);
+  if (!config) {
+    return { label: "MCP server", passed: false, detail: "~/.claude.json not found" };
+  }
+
+  if (config.mcpServers && config.mcpServers["claudemon"]) {
+    return { label: "MCP server", passed: true, detail: "registered in ~/.claude.json" };
+  }
+
+  return { label: "MCP server", passed: false, detail: "not registered in ~/.claude.json" };
+}
+
+// ── Check 5: Hooks ───────────────────────────────────────────
+
+async function checkHooks(): Promise<CheckResult> {
+  const settings = await readJson<ClaudeSettings>(CLAUDE_SETTINGS);
+  if (!settings) {
+    return { label: "Hooks", passed: false, detail: "~/.claude/settings.json not found" };
+  }
+
+  if (!settings.hooks || !settings.hooks["PostToolUse"]) {
+    return { label: "Hooks", passed: false, detail: "no PostToolUse hooks configured" };
+  }
+
+  const hasOurHook = settings.hooks["PostToolUse"].some((m) =>
+    m.hooks.some((h) => h.command.includes("post-tool-use.sh")),
+  );
+
+  if (hasOurHook) {
+    return { label: "Hooks", passed: true, detail: "PostToolUse configured" };
+  }
+
+  return { label: "Hooks", passed: false, detail: "PostToolUse exists but missing Claudemon hook" };
+}
+
+// ── Check 6: Skill ───────────────────────────────────────────
+
+async function checkSkill(): Promise<CheckResult> {
+  const file = Bun.file(SKILL_DEST);
+  if (await file.exists()) {
+    return { label: "Skill", passed: true, detail: "/buddy command installed" };
+  }
+  return { label: "Skill", passed: false, detail: "~/.claude/skills/buddy/SKILL.md not found" };
+}
+
+// ── Check 7: Hook Script Executable ──────────────────────────
+
+async function checkHookScript(): Promise<CheckResult> {
+  try {
+    await access(HOOK_SCRIPT, fsConstants.X_OK);
+    return { label: "Hook script", passed: true, detail: "executable" };
+  } catch {
+    const file = Bun.file(HOOK_SCRIPT);
+    if (await file.exists()) {
+      return {
+        label: "Hook script",
+        passed: false,
+        detail: "exists but not executable (run chmod +x)",
+      };
+    }
+    return { label: "Hook script", passed: false, detail: "not found" };
+  }
+}
+
+// ── Check 8: State Manager Load ──────────────────────────────
+
+async function checkStateManager(): Promise<CheckResult> {
+  try {
+    StateManager.resetInstance();
+    const manager = StateManager.getInstance();
+    const state = await manager.load();
+    StateManager.resetInstance();
+
+    if (state) {
+      return { label: "State manager", passed: true, detail: "loaded successfully" };
+    }
+    return { label: "State manager", passed: true, detail: "no state file yet (first run)" };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    StateManager.resetInstance();
+    return { label: "State manager", passed: false, detail: `load failed: ${message}` };
+  }
+}
+
+// ── Check 9: Stale Lock File ────────────────────────────────
+
+async function checkStaleLock(): Promise<CheckResult> {
+  try {
+    const lockStat = await stat(LOCK_FILE);
+    const lockAge = Date.now() - lockStat.mtimeMs;
+
+    if (lockAge > LOCK_MAX_AGE_MS) {
+      // Offer cleanup
+      info(`Stale lock file found (${Math.round(lockAge / 1000)}s old). Cleaning up...`);
+      try {
+        await unlink(LOCK_FILE);
+        return { label: "Lock file", passed: true, detail: "stale lock cleaned up" };
+      } catch {
+        return { label: "Lock file", passed: false, detail: "stale lock found, cleanup failed" };
+      }
+    }
+
+    return {
+      label: "Lock file",
+      passed: true,
+      detail: `active (${Math.round(lockAge / 1000)}s old)`,
+    };
+  } catch {
+    // No lock file — this is the normal case
+    return { label: "Lock file", passed: true, detail: "no lock (clean)" };
+  }
+}
+
+// ── Check 10: Sprite Count ──────────────────────────────────
+
+async function checkSpriteCount(): Promise<CheckResult> {
+  try {
+    await access(COLORSCRIPT_DIR, fsConstants.F_OK);
+    const entries = await readdir(COLORSCRIPT_DIR);
+    const spriteFiles = entries.filter((f) => f.endsWith(".txt"));
+    const count = spriteFiles.length;
+
+    if (count >= EXPECTED_SPRITE_COUNT) {
+      return {
+        label: "Sprites",
+        passed: true,
+        detail: `${count}/${EXPECTED_SPRITE_COUNT} sprite files`,
+      };
+    }
+
+    return {
+      label: "Sprites",
+      passed: false,
+      detail: `only ${count}/${EXPECTED_SPRITE_COUNT} sprite files (some sprites missing)`,
+    };
+  } catch {
+    return { label: "Sprites", passed: false, detail: "colorscripts directory not found" };
+  }
+}
+
+// ── Check 11: State File Validity (Zod) ─────────────────────
+
+async function checkStateValidity(): Promise<CheckResult> {
+  const file = Bun.file(STATE_FILE);
+  if (!(await file.exists())) {
+    return { label: "State validity", passed: true, detail: "no state file yet" };
+  }
+
+  try {
+    const text = await file.text();
+    if (!text.trim()) {
+      return { label: "State validity", passed: false, detail: "state file is empty" };
+    }
+
+    const data = JSON.parse(text) as unknown;
+    const result = PlayerStateSchema.safeParse(data);
+
+    if (result.success) {
+      return { label: "State validity", passed: true, detail: "schema valid" };
+    }
+
+    // Report first few issues
+    const issues = result.error.issues.slice(0, 3);
+    const details = issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    return {
+      label: "State validity",
+      passed: false,
+      detail: `schema errors: ${details}`,
+    };
+  } catch {
+    return { label: "State validity", passed: false, detail: "invalid JSON" };
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────────
+
+export async function doctor(): Promise<void> {
+  console.log("");
+  console.log("Claudemon Doctor");
+  console.log("================");
+  console.log("");
+
+  const checks: CheckResult[] = [
+    await checkBun(),
+    await checkStateDir(),
+    await checkStateFile(),
+    await checkMcpServer(),
+    await checkHooks(),
+    await checkSkill(),
+    await checkHookScript(),
+    await checkStateManager(),
+    await checkStaleLock(),
+    await checkSpriteCount(),
+    await checkStateValidity(),
+  ];
+
+  for (const check of checks) {
+    console.log(formatCheck(check));
+  }
+
+  const passed = checks.filter((c) => c.passed).length;
+  const total = checks.length;
+
+  console.log("");
+  console.log(`Result: ${passed}/${total} checks passed`);
+
+  if (passed < total) {
+    console.log("");
+    console.log("Run 'bun run cli/install.ts' to fix missing components.");
+  }
+
+  console.log("");
+}
+
+// Run if executed directly
+doctor().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`\nDoctor failed: ${message}`);
+  process.exit(1);
+});

package/cli/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+/**
+ * Claudemon CLI entry point.
+ * Routes to install, uninstall, update, or doctor based on first argument.
+ *
+ * Usage:
+ *   npx claudemon install
+ *   npx claudemon uninstall
+ *   npx claudemon update
+ *   npx claudemon doctor
+ */
+
+export {};
+const command = process.argv[2];
+
+switch (command) {
+  case "install":
+    await import("./install.js");
+    break;
+  case "uninstall":
+    await import("./uninstall.js");
+    break;
+  case "update":
+    await import("./update.js");
+    break;
+  case "doctor":
+    await import("./doctor.js");
+    break;
+  default:
+    console.log(`
+Claudemon — Pokemon Gen 1 coding companion for Claude Code
+
+Usage:
+  claudemon install     Set up Claudemon (MCP server, hooks, skill, status line)
+  claudemon uninstall   Remove Claudemon from Claude Code
+  claudemon update      Re-register everything (preserves save data)
+  claudemon doctor      Run diagnostics
+
+After install, start a new Claude Code session and type /buddy
+`);
+    break;
+}