@umang-boss/claudemon 1.0.0

package/src/engine/starter-pool.ts

@@ -0,0 +1,47 @@
+/**
+ * Starter pool — base-stage common Pokemon eligible for random
+ * starter selection. Only first-in-chain, common-rarity Pokemon.
+ */
+
+/** Pokemon IDs eligible for random starter selection */
+export const STARTER_POOL: readonly number[] = [
+  10, // Caterpie
+  13, // Weedle
+  16, // Pidgey
+  19, // Rattata
+  21, // Spearow
+  23, // Ekans
+  27, // Sandshrew
+  29, // Nidoran♀
+  32, // Nidoran♂
+  39, // Jigglypuff
+  41, // Zubat
+  43, // Oddish
+  46, // Paras
+  48, // Venonat
+  50, // Diglett
+  52, // Meowth
+  54, // Psyduck
+  56, // Mankey
+  60, // Poliwag
+  66, // Machop
+  69, // Bellsprout
+  72, // Tentacool
+  74, // Geodude
+  77, // Ponyta
+  79, // Slowpoke
+  81, // Magnemite
+  84, // Doduo
+  86, // Seel
+  88, // Grimer
+  90, // Shellder
+  92, // Gastly
+  96, // Drowzee
+  98, // Krabby
+  100, // Voltorb
+  104, // Cubone
+  109, // Koffing
+  116, // Horsea
+  118, // Goldeen
+  129, // Magikarp
+] as const;

package/src/engine/stats.ts

@@ -0,0 +1,97 @@
+/**
+ * Coding stat system for Claudemon.
+ * Maps Gen 1 base stats to coding-themed stats with display utilities.
+ */
+
+import type { BaseStats, CodingStats, CodingStat, OwnedPokemon } from "./types.js";
+import { BASE_STAT_TO_CODING } from "./types.js";
+import { TRAINER_TITLES } from "./constants.js";
+
+/** Full block for filled portion of stat bar */
+const BLOCK_FILLED = "\u2588";
+
+/** Light shade block for empty portion of stat bar */
+const BLOCK_EMPTY = "\u2591";
+
+/**
+ * Create initial coding stats from a pokemon's base stats.
+ * Scaled to ~50% of base value since starters begin at level 5.
+ * @param baseStats - The species' base stat block
+ * @returns Initial coding stats for a newly caught pokemon
+ */
+export function initCodingStats(baseStats: BaseStats): CodingStats {
+  const stats: CodingStats = {
+    stamina: 0,
+    debugging: 0,
+    stability: 0,
+    velocity: 0,
+    wisdom: 0,
+  };
+
+  for (const [baseStat, codingStat] of Object.entries(BASE_STAT_TO_CODING) as Array<
+    [keyof BaseStats, CodingStat]
+  >) {
+    stats[codingStat] = Math.floor(baseStats[baseStat] * 0.5);
+  }
+
+  return stats;
+}
+
+/**
+ * Calculate the effective display value of a coding stat.
+ * Formula: floor(baseStat * (0.5 + level/200)) + activityBonus
+ * @param baseStat - The species' base stat value
+ * @param level - The pokemon's current level
+ * @param activityBonus - Accumulated bonus from coding activity
+ * @returns The effective stat value for display
+ */
+export function calculateDisplayStat(
+  baseStat: number,
+  level: number,
+  activityBonus: number,
+): number {
+  return Math.floor(baseStat * (0.5 + level / 200)) + activityBonus;
+}
+
+/**
+ * Increment a coding stat's activity bonus on an owned pokemon. Mutates in place.
+ * @param pokemon - The owned pokemon instance to boost
+ * @param stat - Which coding stat to boost
+ * @param amount - How much to add to the stat
+ */
+export function applyStatBoost(pokemon: OwnedPokemon, stat: CodingStat, amount: number): void {
+  pokemon.codingStats[stat] += amount;
+}
+
+/**
+ * Render a Unicode progress bar for a stat value.
+ * @param value - Stat value (0-100 range)
+ * @param maxWidth - Character width of the bar (default 10)
+ * @returns Unicode bar string like "████████░░"
+ */
+export function renderStatBar(value: number, maxWidth: number = 10): string {
+  const clamped = Math.max(0, Math.min(100, value));
+  const filled = Math.round((clamped / 100) * maxWidth);
+  const empty = maxWidth - filled;
+  return BLOCK_FILLED.repeat(filled) + BLOCK_EMPTY.repeat(empty);
+}
+
+/**
+ * Get the trainer title based on highest pokemon level.
+ * @param highestLevel - The highest level among the trainer's pokemon
+ * @returns The trainer's title string
+ */
+export function getTrainerTitle(highestLevel: number): string {
+  // Titles are sorted ascending by minLevel; find the last one that qualifies
+  let title = "Bug Catcher"; // Fallback for level 0
+
+  for (const entry of TRAINER_TITLES) {
+    if (highestLevel >= entry.minLevel) {
+      title = entry.title;
+    } else {
+      break;
+    }
+  }
+
+  return title;
+}

package/src/engine/types.ts

@@ -0,0 +1,312 @@
+/**
+ * Core type definitions for Claudemon.
+ * Single source of truth for all shared interfaces and types.
+ */
+
+// ── Pokemon Types ──────────────────────────────────────────
+
+export const POKEMON_TYPES = [
+  "Normal",
+  "Fire",
+  "Water",
+  "Electric",
+  "Grass",
+  "Ice",
+  "Fighting",
+  "Poison",
+  "Ground",
+  "Flying",
+  "Psychic",
+  "Bug",
+  "Rock",
+  "Ghost",
+  "Dragon",
+] as const;
+
+export type PokemonType = (typeof POKEMON_TYPES)[number];
+
+export const EXP_GROUPS = ["fast", "medium_fast", "medium_slow", "slow"] as const;
+
+export type ExpGroup = (typeof EXP_GROUPS)[number];
+
+export const RARITY_TIERS = ["common", "uncommon", "rare", "legendary", "mythical"] as const;
+
+export type RarityTier = (typeof RARITY_TIERS)[number];
+
+// ── Base Stats (Gen 1 layout) ──────────────────────────────
+
+export interface BaseStats {
+  readonly hp: number;
+  readonly attack: number;
+  readonly defense: number;
+  readonly speed: number;
+  readonly special: number;
+}
+
+// ── Pokemon Species (static, immutable Pokedex entry) ──────
+
+export interface Pokemon {
+  readonly id: number;
+  readonly name: string;
+  readonly types: readonly [PokemonType, PokemonType?];
+  readonly baseStats: BaseStats;
+  readonly expGroup: ExpGroup;
+  readonly evolutionChainId: number;
+  readonly rarity: RarityTier;
+  readonly catchRate: number; // 1-255, higher = easier to catch
+  readonly description: string; // Short flavor text
+}
+
+// ── Evolution ──────────────────────────────────────────────
+
+export type EvolutionMethod =
+  | { readonly type: "level"; readonly level: number }
+  | { readonly type: "badge"; readonly badge: BadgeType }
+  | { readonly type: "collaboration" }
+  | { readonly type: "stat"; readonly stat: CodingStat; readonly minValue: number };
+
+export interface EvolutionLink {
+  readonly from: number; // Pokemon ID
+  readonly to: number; // Pokemon ID
+  readonly method: EvolutionMethod;
+}
+
+export interface EvolutionChain {
+  readonly id: number;
+  readonly links: readonly EvolutionLink[];
+}
+
+// ── Coding Stats (mapped from Gen 1 stats) ─────────────────
+
+export const CODING_STATS = ["stamina", "debugging", "stability", "velocity", "wisdom"] as const;
+
+export type CodingStat = (typeof CODING_STATS)[number];
+
+export interface CodingStats {
+  stamina: number; // HP → session endurance, streaks
+  debugging: number; // Attack → bug-finding, error fixing
+  stability: number; // Defense → test coverage, build reliability
+  velocity: number; // Speed → throughput, commits, edits
+  wisdom: number; // Special → deep problem-solving, refactors
+}
+
+/** Maps Gen 1 base stats to coding stats for initial values */
+export const BASE_STAT_TO_CODING: Record<keyof BaseStats, CodingStat> = {
+  hp: "stamina",
+  attack: "debugging",
+  defense: "stability",
+  speed: "velocity",
+  special: "wisdom",
+} as const;
+
+// ── Badges (replace evolution stones) ──────────────────────
+
+export const BADGE_TYPES = [
+  "blaze", // Fire Stone → 50 bugs fixed
+  "flow", // Water Stone → 100 tests passed
+  "spark", // Thunder Stone → 200 commits
+  "lunar", // Moon Stone → 30-day streak
+  "growth", // Leaf Stone → 500 files edited
+] as const;
+
+export type BadgeType = (typeof BADGE_TYPES)[number];
+
+export interface Badge {
+  readonly type: BadgeType;
+  readonly name: string;
+  readonly description: string;
+  readonly condition: BadgeCondition;
+}
+
+export type BadgeCondition =
+  | { readonly type: "counter"; readonly counter: EventCounterKey; readonly threshold: number }
+  | { readonly type: "streak"; readonly minDays: number };
+
+// ── Owned Pokemon (user's individual Pokemon instance) ──────
+
+export interface OwnedPokemon {
+  readonly id: string; // Unique instance ID (UUID)
+  pokemonId: number;
+  nickname: string | null;
+  level: number;
+  currentXp: number;
+  totalXp: number;
+  codingStats: CodingStats;
+  happiness: number; // 0-255
+  caughtAt: string; // ISO date
+  evolvedAt: string | null;
+  isActive: boolean;
+  personality: string | null;
+  shiny: boolean; // Future: always false in v1
+  isStarter: boolean;
+}
+
+// ── Player State (single source of truth) ──────────────────
+
+export interface PlayerState {
+  readonly trainerId: string;
+  trainerName: string;
+  party: OwnedPokemon[]; // Max 6
+  pcBox: OwnedPokemon[]; // Overflow storage
+  pokedex: PokedexState;
+  badges: BadgeType[];
+  achievements: UnlockedAchievement[];
+  counters: EventCounters;
+  streak: StreakData;
+  config: BuddyConfig;
+  startedAt: string; // ISO date
+  totalXpEarned: number;
+  totalSessions: number;
+  pendingEncounter: WildEncounter | null;
+  xpSinceLastEncounter: number;
+}
+
+// ── Pokedex ────────────────────────────────────────────────
+
+export interface PokedexEntry {
+  seen: boolean;
+  caught: boolean;
+  firstSeen: string | null; // ISO date
+  firstCaught: string | null;
+}
+
+export interface PokedexState {
+  entries: Record<number, PokedexEntry>; // Keyed by Pokedex number 1-151
+  totalSeen: number;
+  totalCaught: number;
+}
+
+// ── Achievements ───────────────────────────────────────────
+
+export interface Achievement {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly category: "trainer" | "coding" | "pokemon" | "secret";
+  readonly condition: AchievementCondition;
+}
+
+export type AchievementCondition =
+  | { readonly type: "counter"; readonly counter: EventCounterKey; readonly threshold: number }
+  | { readonly type: "level"; readonly minLevel: number }
+  | { readonly type: "pokedex"; readonly minCaught: number }
+  | { readonly type: "streak"; readonly minDays: number }
+  | { readonly type: "badge"; readonly badge: BadgeType }
+  | { readonly type: "evolution" }
+  | { readonly type: "party_size"; readonly minSize: number };
+
+export interface UnlockedAchievement {
+  readonly achievementId: string;
+  readonly unlockedAt: string; // ISO date
+}
+
+// ── Event Counters ─────────────────────────────────────────
+
+export const EVENT_COUNTER_KEYS = [
+  "commits",
+  "tests_passed",
+  "tests_failed",
+  "tests_written",
+  "builds_succeeded",
+  "builds_failed",
+  "bugs_fixed",
+  "lint_fixes",
+  "files_created",
+  "files_edited",
+  "searches",
+  "large_refactors",
+  "errors_encountered",
+  "sessions",
+  "prs_merged",
+] as const;
+
+export type EventCounterKey = (typeof EVENT_COUNTER_KEYS)[number];
+
+export type EventCounters = Record<EventCounterKey, number>;
+
+// ── Streaks ────────────────────────────────────────────────
+
+export interface StreakData {
+  currentStreak: number;
+  longestStreak: number;
+  lastActiveDate: string | null; // ISO date "2026-04-13"
+  totalDaysActive: number;
+}
+
+// ── Config ─────────────────────────────────────────────────
+
+export interface BuddyConfig {
+  muted: boolean;
+  reactionCooldownMs: number; // Default 30000
+  statusLineEnabled: boolean;
+  bellEnabled: boolean; // Terminal bell on level-up/encounters
+}
+
+// ── XP Events (what triggers XP awards) ────────────────────
+
+export const XP_EVENT_TYPES = [
+  "commit",
+  "test_pass",
+  "test_written",
+  "build_success",
+  "bug_fix",
+  "lint_fix",
+  "file_create",
+  "file_edit",
+  "search",
+  "large_refactor",
+  "session_start",
+  "daily_streak",
+  "pet",
+] as const;
+
+export type XpEventType = (typeof XP_EVENT_TYPES)[number];
+
+export interface XpEvent {
+  readonly type: XpEventType;
+  readonly xp: number;
+  readonly statBoost: CodingStat | null;
+  readonly boostAmount: number;
+}
+
+// ── Encounters ─────────────────────────────────────────────
+
+export interface WildEncounter {
+  readonly pokemonId: number;
+  readonly level: number;
+  readonly catchCondition: CatchCondition;
+}
+
+export interface CatchCondition {
+  readonly requiredStat: CodingStat | null;
+  readonly minStatValue: number;
+  readonly requiredLevel: number;
+}
+
+// ── Level Up Result ────────────────────────────────────────
+
+export interface LevelUpResult {
+  readonly previousLevel: number;
+  readonly newLevel: number;
+  readonly pendingEvolution: EvolutionLink | null;
+}
+
+// ── Trainer Titles ─────────────────────────────────────────
+
+export interface TrainerTitle {
+  readonly minLevel: number;
+  readonly title: string;
+}
+
+// ── Legendary Quest ────────────────────────────────────────
+
+export interface LegendaryQuest {
+  readonly pokemonId: number;
+  readonly name: string;
+  readonly steps: readonly QuestStep[];
+}
+
+export interface QuestStep {
+  readonly description: string;
+  readonly condition: AchievementCondition;
+}

package/src/engine/xp.ts

@@ -0,0 +1,135 @@
+/**
+ * XP and leveling engine for Claudemon.
+ * Implements Gen 1 experience growth rate formulas.
+ */
+
+import type {
+  ExpGroup,
+  OwnedPokemon,
+  Pokemon,
+  LevelUpResult,
+  XpEventType,
+  XpEvent,
+} from "./types.js";
+import { MAX_LEVEL, XP_AWARDS } from "./constants.js";
+
+/**
+ * Total cumulative XP required to reach a given level.
+ * @param level - Target level (1-100)
+ * @param group - Experience growth rate group
+ * @returns Cumulative XP needed to reach that level
+ */
+export function cumulativeXpForLevel(level: number, group: ExpGroup): number {
+  const n = level;
+  const n3 = n * n * n;
+
+  switch (group) {
+    case "fast":
+      return Math.floor(0.8 * n3);
+    case "medium_fast":
+      return n3;
+    case "medium_slow": {
+      const raw = 1.2 * n3 - 15 * n * n + 100 * n - 140;
+      return Math.max(0, Math.floor(raw));
+    }
+    case "slow":
+      return Math.floor(1.25 * n3);
+  }
+}
+
+/**
+ * XP delta needed to advance from currentLevel to currentLevel + 1.
+ * @param currentLevel - The pokemon's current level (1-99)
+ * @param group - Experience growth rate group
+ * @returns XP needed for the next level, or 0 if already at MAX_LEVEL
+ */
+export function xpToNextLevel(currentLevel: number, group: ExpGroup): number {
+  if (currentLevel >= MAX_LEVEL) {
+    return 0;
+  }
+  return cumulativeXpForLevel(currentLevel + 1, group) - cumulativeXpForLevel(currentLevel, group);
+}
+
+/**
+ * Apply XP to an owned pokemon, handling level-ups (including multi-level).
+ * Mutates the pokemon's currentXp, totalXp, and level fields.
+ * @param pokemon - The owned pokemon instance to award XP to
+ * @param amount - XP amount to add
+ * @param pokemonData - The species data for this pokemon
+ * @returns Level-up result if the pokemon leveled up, or null
+ */
+export function addXp(
+  pokemon: OwnedPokemon,
+  amount: number,
+  pokemonData: Pokemon,
+): LevelUpResult | null {
+  if (amount <= 0 || pokemon.level >= MAX_LEVEL) {
+    return null;
+  }
+
+  const previousLevel = pokemon.level;
+  const group = pokemonData.expGroup;
+
+  pokemon.totalXp += amount;
+  pokemon.currentXp += amount;
+
+  // Check for level-ups (possibly multiple from large XP gains)
+  while (pokemon.level < MAX_LEVEL) {
+    const xpNeeded = xpToNextLevel(pokemon.level, group);
+    if (xpNeeded <= 0 || pokemon.currentXp < xpNeeded) {
+      break;
+    }
+    pokemon.currentXp -= xpNeeded;
+    pokemon.level += 1;
+  }
+
+  // Clamp at max level: any overflow XP is discarded
+  if (pokemon.level >= MAX_LEVEL) {
+    pokemon.currentXp = 0;
+  }
+
+  if (pokemon.level === previousLevel) {
+    return null;
+  }
+
+  // TODO(phase-2): check evolution triggers and populate pendingEvolution
+  return {
+    previousLevel,
+    newLevel: pokemon.level,
+    pendingEvolution: null,
+  };
+}
+
+/**
+ * Calculate progress percentage toward the next level.
+ * @param pokemon - The owned pokemon instance
+ * @param pokemonData - The species data for this pokemon
+ * @returns Percentage (0-100) of progress to next level
+ */
+export function xpProgressPercent(pokemon: OwnedPokemon, pokemonData: Pokemon): number {
+  if (pokemon.level >= MAX_LEVEL) {
+    return 100;
+  }
+
+  const needed = xpToNextLevel(pokemon.level, pokemonData.expGroup);
+  if (needed <= 0) {
+    return 100;
+  }
+
+  return Math.min(100, Math.floor((pokemon.currentXp / needed) * 100));
+}
+
+/**
+ * Create an XP event descriptor from an event type, using constants.
+ * @param type - The XP event type
+ * @returns A fully populated XpEvent
+ */
+export function createXpEvent(type: XpEventType): XpEvent {
+  const award = XP_AWARDS[type];
+  return {
+    type,
+    xp: award.xp,
+    statBoost: award.stat,
+    boostAmount: award.boost,
+  };
+}