@umang-boss/claudemon 1.0.0

package/src/gamification/achievements.ts

@@ -0,0 +1,204 @@
+/**
+ * Achievement definitions and unlock-checking logic for Claudemon.
+ * All achievements are derived from PlayerState — pure functions, no side effects.
+ */
+
+import type {
+  Achievement,
+  AchievementCondition,
+  PlayerState,
+  UnlockedAchievement,
+} from "../engine/types.js";
+
+// ── Achievement Definitions ──────────────────────────────────
+
+export const ACHIEVEMENTS: readonly Achievement[] = [
+  // ── Trainer Milestones ───────────────────────────────────
+  {
+    id: "first_steps",
+    name: "First Steps",
+    description: "Pick your starter Pokemon",
+    category: "trainer",
+    condition: { type: "party_size", minSize: 1 },
+  },
+  {
+    id: "getting_started",
+    name: "Getting Started",
+    description: "Reach level 10",
+    category: "trainer",
+    condition: { type: "level", minLevel: 10 },
+  },
+  {
+    id: "seasoned",
+    name: "Seasoned Trainer",
+    description: "Reach level 50",
+    category: "trainer",
+    condition: { type: "level", minLevel: 50 },
+  },
+  {
+    id: "master",
+    name: "Pokemon Master",
+    description: "Reach level 100",
+    category: "trainer",
+    condition: { type: "level", minLevel: 100 },
+  },
+  {
+    id: "full_party",
+    name: "Full Party",
+    description: "Have 6 Pokemon in your party",
+    category: "trainer",
+    condition: { type: "party_size", minSize: 6 },
+  },
+  {
+    id: "collector_50",
+    name: "Collector",
+    description: "Catch 50 unique Pokemon",
+    category: "trainer",
+    condition: { type: "pokedex", minCaught: 50 },
+  },
+  {
+    id: "completionist",
+    name: "Completionist",
+    description: "Catch all 151 Pokemon",
+    category: "trainer",
+    condition: { type: "pokedex", minCaught: 151 },
+  },
+
+  // ── Coding Achievements ──────────────────────────────────
+  {
+    id: "bug_catcher_10",
+    name: "Bug Catcher",
+    description: "Fix 10 errors",
+    category: "coding",
+    condition: { type: "counter", counter: "bugs_fixed", threshold: 10 },
+  },
+  {
+    id: "exterminator",
+    name: "Exterminator",
+    description: "Fix 100 errors",
+    category: "coding",
+    condition: { type: "counter", counter: "bugs_fixed", threshold: 100 },
+  },
+  {
+    id: "test_ace",
+    name: "Test Ace",
+    description: "Pass 100 tests",
+    category: "coding",
+    condition: { type: "counter", counter: "tests_passed", threshold: 100 },
+  },
+  {
+    id: "ci_champion",
+    name: "CI Champion",
+    description: "50 successful builds",
+    category: "coding",
+    condition: { type: "counter", counter: "builds_succeeded", threshold: 50 },
+  },
+  {
+    id: "refactor_king",
+    name: "Refactor King",
+    description: "Complete 10 large refactors",
+    category: "coding",
+    condition: { type: "counter", counter: "large_refactors", threshold: 10 },
+  },
+  {
+    id: "iron_coder",
+    name: "Iron Coder",
+    description: "Maintain a 7-day coding streak",
+    category: "coding",
+    condition: { type: "streak", minDays: 7 },
+  },
+  {
+    id: "marathon",
+    name: "Marathon",
+    description: "Maintain a 30-day coding streak",
+    category: "coding",
+    condition: { type: "streak", minDays: 30 },
+  },
+  {
+    id: "centurion",
+    name: "Centurion",
+    description: "Maintain a 100-day coding streak",
+    category: "coding",
+    condition: { type: "streak", minDays: 100 },
+  },
+
+  // ── Pokemon Achievements ─────────────────────────────────
+  {
+    id: "evolution",
+    name: "Evolutionary",
+    description: "Evolve a Pokemon",
+    category: "pokemon",
+    condition: { type: "evolution" },
+  },
+  {
+    id: "badge_collector",
+    name: "Badge Collector",
+    description: "Earn your first badge",
+    category: "pokemon",
+    condition: { type: "badge", badge: "blaze" },
+  },
+];
+
+// ── Condition Checker ────────────────────────────────────────
+
+/** Check whether a single achievement condition is satisfied by the current player state. */
+export function isConditionMet(condition: AchievementCondition, state: PlayerState): boolean {
+  switch (condition.type) {
+    case "counter":
+      return (state.counters[condition.counter] ?? 0) >= condition.threshold;
+
+    case "level": {
+      const highestLevel = getHighestPartyLevel(state);
+      return highestLevel >= condition.minLevel;
+    }
+
+    case "pokedex":
+      return state.pokedex.totalCaught >= condition.minCaught;
+
+    case "streak":
+      return state.streak.currentStreak >= condition.minDays;
+
+    case "badge":
+      return state.badges.includes(condition.badge);
+
+    case "evolution":
+      return hasAnyEvolvedPokemon(state);
+
+    case "party_size":
+      return state.party.length >= condition.minSize;
+  }
+}
+
+// ── Achievement Discovery ────────────────────────────────────
+
+/** Return achievements that are newly unlocked (not already in state.achievements). */
+export function checkNewAchievements(state: PlayerState): Achievement[] {
+  const alreadyUnlocked = new Set(state.achievements.map((a) => a.achievementId));
+
+  return ACHIEVEMENTS.filter(
+    (achievement) =>
+      !alreadyUnlocked.has(achievement.id) && isConditionMet(achievement.condition, state),
+  );
+}
+
+/** Create a timestamped unlock record for an achievement. */
+export function unlockAchievement(achievementId: string): UnlockedAchievement {
+  return {
+    achievementId,
+    unlockedAt: new Date().toISOString(),
+  };
+}
+
+// ── Internal Helpers ─────────────────────────────────────────
+
+/** Get the highest level among all party Pokemon (0 if party is empty). */
+function getHighestPartyLevel(state: PlayerState): number {
+  if (state.party.length === 0) return 0;
+  return Math.max(...state.party.map((p) => p.level));
+}
+
+/** Check whether any Pokemon in party or PC box has evolved (evolvedAt is set). */
+function hasAnyEvolvedPokemon(state: PlayerState): boolean {
+  const allPokemon = [...state.party, ...state.pcBox];
+  return allPokemon.some((p) => p.evolvedAt !== null);
+}

package/src/gamification/legendary-quests.ts

@@ -0,0 +1,265 @@
+/**
+ * Legendary quest chain definitions for Claudemon.
+ * Each legendary Pokemon requires completing a multi-step quest
+ * tied to sustained coding activity.
+ */
+
+import type { AchievementCondition, LegendaryQuest, PlayerState } from "../engine/types.js";
+import { isConditionMet } from "./achievements.js";
+
+// ── Quest Definitions ────────────────────────────────────────
+
+export const LEGENDARY_QUESTS: readonly LegendaryQuest[] = [
+  // ── Articuno (#144) — "The Ice Bird of Endurance" ────────
+  {
+    pokemonId: 144,
+    name: "The Ice Bird of Endurance",
+    steps: [
+      {
+        description: "Maintain a 30-day coding streak",
+        condition: { type: "streak", minDays: 30 },
+      },
+      {
+        description: "Catch 3 Water or Ice type Pokemon",
+        // Approximated as pokedex gate; real type-check in getQuestProgress.
+        condition: { type: "pokedex", minCaught: 3 },
+      },
+      {
+        description: "Maintain a 100-day coding streak",
+        condition: { type: "streak", minDays: 100 },
+      },
+      {
+        description: "Reach level 50 on your active Pokemon",
+        condition: { type: "level", minLevel: 50 },
+      },
+    ],
+  },
+
+  // ── Zapdos (#145) — "The Thunder of Testing" ────────────
+  {
+    pokemonId: 145,
+    name: "The Thunder of Testing",
+    steps: [
+      {
+        description: "Pass 100 tests",
+        condition: { type: "counter", counter: "tests_passed", threshold: 100 },
+      },
+      {
+        description: "Write 50 test files",
+        condition: { type: "counter", counter: "tests_written", threshold: 50 },
+      },
+      {
+        description: "Pass 500 tests",
+        condition: { type: "counter", counter: "tests_passed", threshold: 500 },
+      },
+      {
+        description: "Pass 1000 tests lifetime",
+        condition: { type: "counter", counter: "tests_passed", threshold: 1000 },
+      },
+    ],
+  },
+
+  // ── Moltres (#146) — "The Flame of Debugging" ──────────
+  {
+    pokemonId: 146,
+    name: "The Flame of Debugging",
+    steps: [
+      {
+        description: "Fix 50 bugs",
+        condition: { type: "counter", counter: "bugs_fixed", threshold: 50 },
+      },
+      {
+        description: "Earn the Blaze Badge",
+        condition: { type: "badge", badge: "blaze" },
+      },
+      {
+        description: "Fix 200 bugs",
+        condition: { type: "counter", counter: "bugs_fixed", threshold: 200 },
+      },
+      {
+        description: "Fix 500 bugs lifetime",
+        condition: { type: "counter", counter: "bugs_fixed", threshold: 500 },
+      },
+    ],
+  },
+
+  // ── Mewtwo (#150) — "The Ultimate Creation" ─────────────
+  {
+    pokemonId: 150,
+    name: "The Ultimate Creation",
+    steps: [
+      {
+        description: "Catch 50 unique Pokemon",
+        condition: { type: "pokedex", minCaught: 50 },
+      },
+      {
+        description: "Reach level 75 on any Pokemon",
+        condition: { type: "level", minLevel: 75 },
+      },
+      {
+        description: "Catch 100 unique Pokemon",
+        condition: { type: "pokedex", minCaught: 100 },
+      },
+      {
+        description: "Catch 140 unique Pokemon",
+        condition: { type: "pokedex", minCaught: 140 },
+      },
+    ],
+  },
+
+  // ── Mew (#151) — "The Myth" ─────────────────────────────
+  {
+    pokemonId: 151,
+    name: "The Myth",
+    steps: [
+      {
+        description: "Maintain a 100-day coding streak",
+        condition: { type: "streak", minDays: 100 },
+      },
+      {
+        description: "Catch all 3 legendary birds (Articuno, Zapdos, Moltres)",
+        // Gate: must have at least 148 caught (birds are #144-146).
+        // Real check in getQuestProgress verifies specific IDs.
+        condition: { type: "pokedex", minCaught: 148 },
+      },
+      {
+        description: "Catch Mewtwo",
+        // Gate: must have at least 149 caught (Mewtwo is #150).
+        // Real check in getQuestProgress verifies specific ID.
+        condition: { type: "pokedex", minCaught: 149 },
+      },
+      {
+        description: "Maintain a 365-day coding streak",
+        condition: { type: "streak", minDays: 365 },
+      },
+    ],
+  },
+];
+
+// ── Quest Progress ───────────────────────────────────────────
+
+/** IDs of Water and Ice type Pokemon in Gen 1 Pokedex. */
+const WATER_ICE_POKEMON_IDS: ReadonlySet<number> = new Set([
+  // Water types
+  7,
+  8,
+  9, // Squirtle line
+  54,
+  55, // Psyduck, Golduck
+  60,
+  61,
+  62, // Poliwag line
+  72,
+  73, // Tentacool, Tentacruel
+  79,
+  80, // Slowpoke, Slowbro
+  86,
+  87, // Seel, Dewgong (also Ice)
+  90,
+  91, // Shellder, Cloyster (also Ice)
+  98,
+  99, // Krabby, Kingler
+  116,
+  117, // Horsea, Seadra
+  118,
+  119, // Goldeen, Seaking
+  120,
+  121, // Staryu, Starmie
+  129,
+  130, // Magikarp, Gyarados
+  131, // Lapras (Water/Ice)
+  134, // Vaporeon
+  138,
+  139, // Omanyte, Omastar
+  140,
+  141, // Kabuto, Kabutops
+  // Ice types (not already listed)
+  124, // Jynx (Ice/Psychic)
+  144, // Articuno (Ice/Flying)
+]);
+
+/** Legendary bird Pokedex IDs. */
+const LEGENDARY_BIRD_IDS: readonly number[] = [144, 145, 146];
+
+/** Mewtwo Pokedex ID. */
+const MEWTWO_ID = 150;
+
+export interface QuestProgress {
+  readonly quest: LegendaryQuest;
+  readonly stepsCompleted: number;
+  readonly totalSteps: number;
+}
+
+/**
+ * Calculate completion progress for every legendary quest.
+ * Steps are checked sequentially — a later step cannot complete
+ * until all earlier steps are done.
+ */
+export function getQuestProgress(state: PlayerState): QuestProgress[] {
+  return LEGENDARY_QUESTS.map((quest) => {
+    let stepsCompleted = 0;
+
+    for (const step of quest.steps) {
+      if (isStepComplete(quest.pokemonId, step.description, step.condition, state)) {
+        stepsCompleted++;
+      } else {
+        break; // Steps are sequential — stop at first incomplete.
+      }
+    }
+
+    return {
+      quest,
+      stepsCompleted,
+      totalSteps: quest.steps.length,
+    };
+  });
+}
+
+// ── Internal Helpers ─────────────────────────────────────────
+
+/**
+ * Check whether a quest step is complete.
+ * Uses isConditionMet for standard conditions, with overrides
+ * for steps that require specific-Pokemon or type-based checks.
+ */
+function isStepComplete(
+  questPokemonId: number,
+  stepDescription: string,
+  condition: AchievementCondition,
+  state: PlayerState,
+): boolean {
+  // Articuno step 2: catch 3 Water/Ice type Pokemon
+  if (questPokemonId === 144 && stepDescription.includes("Water or Ice")) {
+    return countCaughtByIds(state, WATER_ICE_POKEMON_IDS) >= 3;
+  }
+
+  // Mew step 2: catch all 3 legendary birds
+  if (questPokemonId === 151 && stepDescription.includes("legendary birds")) {
+    return LEGENDARY_BIRD_IDS.every((id) => isPokemonCaught(state, id));
+  }
+
+  // Mew step 3: catch Mewtwo
+  if (questPokemonId === 151 && stepDescription.includes("Mewtwo")) {
+    return isPokemonCaught(state, MEWTWO_ID);
+  }
+
+  // Default: delegate to the standard condition checker.
+  return isConditionMet(condition, state);
+}
+
+/** Check whether a specific Pokemon ID has been caught in the Pokedex. */
+function isPokemonCaught(state: PlayerState, pokemonId: number): boolean {
+  const entry = state.pokedex.entries[pokemonId];
+  return entry !== undefined && entry.caught;
+}
+
+/** Count how many Pokemon from a given ID set have been caught. */
+function countCaughtByIds(state: PlayerState, ids: ReadonlySet<number>): number {
+  let count = 0;
+  for (const id of ids) {
+    if (isPokemonCaught(state, id)) {
+      count++;
+    }
+  }
+  return count;
+}

package/src/gamification/milestones.ts

@@ -0,0 +1,86 @@
+/**
+ * Milestone discovery definitions for Claudemon.
+ * Specific Pokemon appear when coding counters reach defined thresholds.
+ * Check these after every counter increment.
+ */
+
+import type { EventCounterKey } from "../engine/types.js";
+
+// ── Milestone Types ──────────────────────────────────────────
+
+export interface MilestoneDiscovery {
+  readonly pokemonId: number;
+  readonly counter: EventCounterKey;
+  readonly threshold: number;
+  readonly message: string;
+}
+
+// ── Milestone Definitions ────────────────────────────────────
+
+export const MILESTONES: readonly MilestoneDiscovery[] = [
+  {
+    pokemonId: 16, // Pidgey
+    counter: "commits",
+    threshold: 1,
+    message: "Every journey starts with a first step!",
+  },
+  {
+    pokemonId: 66, // Machop
+    counter: "tests_passed",
+    threshold: 10,
+    message: "Your code is getting stronger!",
+  },
+  {
+    pokemonId: 74, // Geodude
+    counter: "builds_succeeded",
+    threshold: 1,
+    message: "Solid foundations!",
+  },
+  {
+    pokemonId: 63, // Abra
+    counter: "commits",
+    threshold: 50,
+    message: "You're getting quick!",
+  },
+  {
+    pokemonId: 89, // Muk
+    counter: "bugs_fixed",
+    threshold: 100,
+    message: "You've seen some ugly code...",
+  },
+  {
+    pokemonId: 129, // Magikarp
+    counter: "commits",
+    threshold: 200,
+    message: "Humble beginnings... just wait",
+  },
+  {
+    pokemonId: 137, // Porygon
+    counter: "tests_written",
+    threshold: 100,
+    message: "A digital creation for a digital creator!",
+  },
+  {
+    pokemonId: 143, // Snorlax
+    counter: "files_edited",
+    threshold: 500,
+    message: "All that hard work... time for a nap?",
+  },
+];
+
+// ── Milestone Checker ────────────────────────────────────────
+
+/**
+ * Return milestones whose thresholds are met but whose Pokemon
+ * have not yet been caught (not in the provided pokedex set).
+ */
+export function checkNewMilestones(
+  counters: Record<string, number>,
+  caughtPokemonIds: Set<number>,
+): MilestoneDiscovery[] {
+  return MILESTONES.filter(
+    (milestone) =>
+      !caughtPokemonIds.has(milestone.pokemonId) &&
+      (counters[milestone.counter] ?? 0) >= milestone.threshold,
+  );
+}

package/src/hooks/award-xp.ts

@@ -0,0 +1,131 @@
+/**
+ * award-xp.ts — Lightweight bun script called by the PostToolUse hook.
+ * Usage: bun run award-xp.ts <event_type> <counter_key>
+ *
+ * Loads state, awards XP to the active Pokemon, applies stat boosts,
+ * increments the event counter, updates the streak, and saves.
+ * Emits a terminal bell on level-up.
+ */
+
+import type { XpEventType, EventCounterKey } from "../engine/types.js";
+import { BELL } from "../engine/constants.js";
+import { StateManager } from "../state/state-manager.js";
+import { addXp, createXpEvent } from "../engine/xp.js";
+import { applyStatBoost } from "../engine/stats.js";
+import { POKEMON_BY_ID } from "../engine/pokemon-data.js";
+import { checkEvolution, getNewlyEarnedBadges } from "../engine/evolution.js";
+import { shouldTriggerEncounter, generateEncounter } from "../engine/encounters.js";
+
+const eventType = process.argv[2] as XpEventType;
+const counterKey = process.argv[3] as EventCounterKey | undefined;
+
+if (!eventType) {
+  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);
+}
+
+const pokemon = stateManager.getActivePokemon();
+if (!pokemon) {
+  process.exit(0);
+}
+
+const pokemonData = POKEMON_BY_ID.get(pokemon.pokemonId);
+if (!pokemonData) {
+  process.exit(0);
+}
+
+// Create XP event from the event type
+const xpEvent = createXpEvent(eventType);
+
+// Award XP and check for level-up
+const levelUp = addXp(pokemon, xpEvent.xp, pokemonData);
+
+// Apply stat boost if the event provides one
+if (xpEvent.statBoost && xpEvent.boostAmount > 0) {
+  applyStatBoost(pokemon, xpEvent.statBoost, xpEvent.boostAmount);
+}
+
+// Track total XP earned by the trainer
+state.totalXpEarned += xpEvent.xp;
+
+// Increment the event counter directly on state (avoids extra save from incrementCounter)
+if (counterKey) {
+  state.counters[counterKey] += 1;
+}
+
+// Update the daily coding streak
+// Inline the streak logic to avoid the extra save from updateStreak()
+const today = new Date();
+const todayStr = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}-${String(today.getDate()).padStart(2, "0")}`;
+const { streak } = state;
+
+if (streak.lastActiveDate !== todayStr) {
+  if (streak.lastActiveDate === null) {
+    streak.currentStreak = 1;
+    streak.totalDaysActive = 1;
+  } else {
+    const last = new Date(streak.lastActiveDate);
+    const now = new Date(todayStr);
+    const diffMs = now.getTime() - last.getTime();
+    const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));
+
+    if (diffDays === 1) {
+      streak.currentStreak += 1;
+    } else {
+      streak.currentStreak = 1;
+    }
+    streak.totalDaysActive += 1;
+  }
+
+  if (streak.currentStreak > streak.longestStreak) {
+    streak.longestStreak = streak.currentStreak;
+  }
+
+  streak.lastActiveDate = todayStr;
+}
+
+// Check for newly earned badges
+const newBadges = getNewlyEarnedBadges(state);
+for (const badge of newBadges) {
+  state.badges.push(badge);
+}
+
+// Check if evolution is available (sets flag in status for status line indicator)
+const evolutionReady = checkEvolution(pokemon, state) !== null;
+
+// Track XP toward next encounter and trigger if threshold met
+state.xpSinceLastEncounter = (state.xpSinceLastEncounter ?? 0) + xpEvent.xp;
+let encounterTriggered = false;
+
+if (shouldTriggerEncounter(state.xpSinceLastEncounter) && !state.pendingEncounter) {
+  const encounter = generateEncounter(eventType, state);
+  if (encounter) {
+    state.pendingEncounter = encounter;
+    state.xpSinceLastEncounter = 0;
+    encounterTriggered = true;
+  }
+}
+
+// Single atomic save for all mutations
+await stateManager.save();
+
+// Write status for the status line (includes evolution flag and encounter notification)
+if (encounterTriggered && state.pendingEncounter) {
+  const encSpecies = POKEMON_BY_ID.get(state.pendingEncounter.pokemonId);
+  const encName = encSpecies?.name ?? "???";
+  await stateManager.writeEncounterStatus(encName);
+} else {
+  await stateManager.writeStatus(evolutionReady);
+}
+
+// Terminal bell on level-up, evolution available, or encounter (written to stderr so it reaches the terminal)
+if ((levelUp || evolutionReady || encounterTriggered) && state.config.bellEnabled) {
+  process.stderr.write(BELL);
+}