empire-cli 0.1.0

package/src/engine/combat-resolver.ts

@@ -0,0 +1,92 @@
+// Combat resolution engine: calculates battle outcomes based on units, morale, terrain
+
+import type { CombatResult, TerritoryType } from '../game-types.js';
+
+// Terrain defense bonuses (multiplier on defender power)
+const TERRAIN_BONUS: Record<TerritoryType, number> = {
+  plains: 1.0,
+  forest: 1.2,
+  mountain: 1.5,
+  city: 1.3,
+};
+
+/**
+ * Resolve combat between attacker and defender armies.
+ * Uses a power ratio formula to determine outcome and casualties.
+ */
+export function resolveCombat(
+  attackerUnits: number,
+  attackerMorale: number,
+  defenderUnits: number,
+  defenderMorale: number,
+  terrain: TerritoryType
+): CombatResult {
+  const log: string[] = [];
+
+  const terrainBonus = TERRAIN_BONUS[terrain];
+  const attackPower = attackerUnits * (attackerMorale / 100);
+  const defensePower = defenderUnits * (defenderMorale / 100) * terrainBonus;
+
+  log.push(`Attack power: ${attackPower.toFixed(1)} vs Defense power: ${defensePower.toFixed(1)}`);
+  log.push(`Terrain (${terrain}) gives defender x${terrainBonus} bonus`);
+
+  const ratio = attackPower / (defensePower || 1);
+
+  let outcome: CombatResult['outcome'];
+  let attackerCasualties: number;
+  let defenderCasualties: number;
+  let captured = false;
+
+  if (ratio >= 2.0) {
+    // Decisive victory — attacker dominates
+    outcome = 'decisive_victory';
+    attackerCasualties = Math.max(0, Math.floor(attackerUnits * 0.1));
+    defenderCasualties = defenderUnits; // all defenders lost
+    captured = true;
+    log.push('Decisive victory! The defenders are routed!');
+  } else if (ratio >= 1.2) {
+    // Regular victory
+    outcome = 'victory';
+    attackerCasualties = Math.max(0, Math.floor(attackerUnits * 0.25));
+    defenderCasualties = Math.max(0, Math.floor(defenderUnits * 0.6));
+    captured = true;
+    log.push('Victory! The territory has been captured.');
+  } else if (ratio >= 0.8) {
+    // Pyrrhic — costly win or stalemate resolved as attacker loss
+    outcome = 'pyrrhic_victory';
+    attackerCasualties = Math.max(0, Math.floor(attackerUnits * 0.5));
+    defenderCasualties = Math.max(0, Math.floor(defenderUnits * 0.4));
+    captured = ratio >= 1.0; // only capture if slightly above even
+    log.push(captured ? 'Pyrrhic victory — heavy losses on both sides.' : 'Stalemate — attackers withdraw.');
+  } else {
+    // Defeat
+    outcome = 'defeat';
+    attackerCasualties = Math.max(0, Math.floor(attackerUnits * 0.6));
+    defenderCasualties = Math.max(0, Math.floor(defenderUnits * 0.15));
+    captured = false;
+    log.push('Defeat! The attack has failed.');
+  }
+
+  log.push(`Attacker losses: ${attackerCasualties} units`);
+  log.push(`Defender losses: ${defenderCasualties} units`);
+
+  return { attackerCasualties, defenderCasualties, outcome, captured, log };
+}
+
+/**
+ * Simulate AI faction auto-attack decision: returns true if AI should attack.
+ */
+export function shouldAiAttack(
+  personality: string,
+  attackerUnits: number,
+  defenderUnits: number
+): boolean {
+  const ratio = attackerUnits / (defenderUnits || 1);
+  switch (personality) {
+    case 'aggressive': return ratio >= 1.0;
+    case 'defensive':  return ratio >= 2.0;
+    case 'mercantile': return ratio >= 1.5;
+    case 'diplomatic': return ratio >= 2.5;
+    default:           return ratio >= 1.5;
+  }
+}

package/src/engine/resource-calculator.ts

@@ -0,0 +1,95 @@
+// Resource collection and upkeep calculations for each faction per turn
+
+import type { Faction, Territory, Resources } from '../game-types.js';
+
+const ARMY_FOOD_UPKEEP = 1; // food per army unit per turn
+const ARMY_GOLD_UPKEEP = 0; // gold per army unit (free for now)
+
+/**
+ * Calculate total resource income for a faction based on owned territories.
+ */
+export function collectResources(
+  faction: Faction,
+  territories: Map<string, Territory>
+): Resources {
+  const income: Resources = { gold: 0, food: 0, wood: 0, stone: 0 };
+
+  for (const territoryId of faction.territories) {
+    const territory = territories.get(territoryId);
+    if (!territory) continue;
+
+    income.gold += territory.resources.gold;
+    income.food += territory.resources.food;
+    income.wood += territory.resources.wood;
+    income.stone += territory.resources.stone;
+  }
+
+  return income;
+}
+
+/**
+ * Calculate food upkeep cost for all armies in a faction.
+ */
+export function calculateUpkeep(faction: Faction): Resources {
+  return {
+    gold: faction.totalArmies * ARMY_GOLD_UPKEEP,
+    food: faction.totalArmies * ARMY_FOOD_UPKEEP,
+    wood: 0,
+    stone: 0,
+  };
+}
+
+/**
+ * Apply income and deduct upkeep from faction. Mutates faction in place.
+ * Returns net change log messages.
+ */
+export function processTurnResources(
+  faction: Faction,
+  territories: Map<string, Territory>
+): string[] {
+  const income = collectResources(faction, territories);
+  const upkeep = calculateUpkeep(faction);
+  const log: string[] = [];
+
+  faction.gold += income.gold - upkeep.gold;
+  faction.food += income.food - upkeep.food;
+  faction.wood += income.wood - upkeep.wood;
+  faction.stone += income.stone - upkeep.stone;
+
+  // Clamp negatives — starvation means morale hit (handled elsewhere)
+  if (faction.food < 0) {
+    log.push(`${faction.name} is starving! Food deficit: ${faction.food}`);
+    faction.food = 0;
+  }
+  if (faction.gold < 0) {
+    log.push(`${faction.name} is bankrupt! Gold deficit: ${faction.gold}`);
+    faction.gold = 0;
+  }
+
+  log.push(
+    `${faction.name} collected: +${income.gold}g +${income.food}f +${income.wood}w +${income.stone}s`
+  );
+
+  return log;
+}
+
+/**
+ * Check if a faction can afford a given resource cost.
+ */
+export function canAfford(faction: Faction, cost: Partial<Resources>): boolean {
+  if (cost.gold !== undefined && faction.gold < cost.gold) return false;
+  if (cost.food !== undefined && faction.food < cost.food) return false;
+  if (cost.wood !== undefined && faction.wood < cost.wood) return false;
+  if (cost.stone !== undefined && faction.stone < cost.stone) return false;
+  return true;
+}
+
+/**
+ * Deduct resources from faction. Assumes canAfford check done first.
+ */
+export function deductResources(faction: Faction, cost: Partial<Resources>): void {
+  if (cost.gold) faction.gold -= cost.gold;
+  if (cost.food) faction.food -= cost.food;
+  if (cost.wood) faction.wood -= cost.wood;
+  if (cost.stone) faction.stone -= cost.stone;
+}

package/src/game-types.ts

@@ -0,0 +1,80 @@
+// Core game type definitions for Empire CLI strategy RPG
+
+export type TerritoryType = 'plains' | 'forest' | 'mountain' | 'city';
+
+export type FactionPersonality = 'aggressive' | 'defensive' | 'diplomatic' | 'mercantile';
+
+export interface Resources {
+  gold: number;
+  food: number;
+  wood: number;
+  stone: number;
+}
+
+export interface Territory {
+  id: string;
+  name: string;
+  type: TerritoryType;
+  owner: string | null; // faction id or null for unclaimed
+  armies: number;
+  resources: Resources; // base income per turn
+  adjacentTo: string[]; // territory ids
+}
+
+export interface Faction {
+  id: string;
+  name: string;
+  personality: FactionPersonality;
+  color: string; // chalk color name
+  territories: string[]; // territory ids
+  gold: number;
+  food: number;
+  wood: number;
+  stone: number;
+  totalArmies: number;
+}
+
+export interface Army {
+  id: string;
+  factionId: string;
+  units: number;
+  morale: number; // 0-100
+  territoryId: string;
+}
+
+export interface CombatResult {
+  attackerCasualties: number;
+  defenderCasualties: number;
+  outcome: 'decisive_victory' | 'victory' | 'pyrrhic_victory' | 'defeat';
+  captured: boolean;
+  log: string[];
+}
+
+export interface GameState {
+  turn: number;
+  territories: Map<string, Territory>;
+  factions: Map<string, Faction>;
+  armies: Map<string, Army>;
+  playerFactionId: string;
+  gameLog: string[];
+  isOver: boolean;
+  winner: string | null;
+}
+
+export interface Command {
+  type: string;
+  args: string[];
+}
+
+// Serializable version for JSON save files
+export interface SaveData {
+  turn: number;
+  territories: Record<string, Territory>;
+  factions: Record<string, Faction>;
+  armies: Record<string, Army>;
+  playerFactionId: string;
+  gameLog: string[];
+  isOver: boolean;
+  winner: string | null;
+  savedAt: string;
+}

package/src/index.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// Empire CLI — main entry point: menu, game loop, command dispatch
+// General (👑) commands armies from above — no player cursor
+
+import readline from 'readline';
+import chalk from 'chalk';
+import type { GameState, Territory, Faction } from './game-types.js';
+import { newGame, saveGame, loadGame, listSaves, checkWinCondition } from './state/game-state-manager.js';
+import { processTurnResources } from './engine/resource-calculator.js';
+import { resolveCombat } from './engine/combat-resolver.js';
+import { recruitArmy, findArmyInTerritory, applyCasualties, getUnitsInTerritory, ensureArmyRecord } from './engine/army-manager.js';
+import { printLine, printSeparator, printStatus, printHelp, printMap, printTerritoryInfo, ICONS } from './ui/display-helpers.js';
+import { runAiTurns } from './engine/ai-turn-processor.js';
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+function ask(prompt: string): Promise<string> {
+  return new Promise((resolve) => rl.question(prompt, resolve));
+}
+
+// ─── Territory finder helper ─────────────────────────────────────────────────
+
+function findTerritory(state: GameState, name: string): Territory | undefined {
+  return [...state.territories.values()].find(
+    (t) => t.name.toLowerCase().includes(name.toLowerCase())
+  );
+}
+
+// ─── Command processing ─────────────────────────────────────────────────────
+
+async function processCommand(input: string, state: GameState): Promise<boolean> {
+  const parts = input.trim().split(/\s+/);
+  const cmd = parts[0]?.toLowerCase() ?? '';
+  const args = parts.slice(1);
+  const player = state.factions.get(state.playerFactionId)!;
+
+  switch (cmd) {
+    case 'look': printMap(state); break;
+    case 'status': printStatus(state); break;
+    case 'help': printHelp(); break;
+
+    case 'info': {
+      if (!args[0]) { printLine('Usage: info <territory>'); break; }
+      printTerritoryInfo(state, args.join(' '));
+      break;
+    }
+
+    case 'move': {
+      // move <from> <to> [n]
+      if (args.length < 2) { printLine('Usage: move <from> <to> [units]'); break; }
+      const lastArg = args[args.length - 1];
+      const unitCount = /^\d+$/.test(lastArg) ? parseInt(lastArg, 10) : 0;
+      // Split args: try to find two territory names, optional number at end
+      const nameArgs = unitCount > 0 ? args.slice(0, -1) : args;
+      const { from, to } = parseTwoTerritories(state, nameArgs);
+      if (!from || !to) { printLine(chalk.red('Could not find those territories. Try: move northkeep greenwood 3')); break; }
+      if (!from.adjacentTo.includes(to.id)) { printLine(chalk.red(`${to.name} is not adjacent to ${from.name}.`)); break; }
+      if (from.owner !== player.id) { printLine(chalk.red(`You don't own ${from.name}.`)); break; }
+
+      ensureArmyRecord(player.id, from, state.armies);
+      const army = findArmyInTerritory(player.id, from.id, state.armies);
+      if (!army || army.units === 0) { printLine(chalk.red(`No army in ${from.name}.`)); break; }
+
+      const toMove = unitCount > 0 ? Math.min(unitCount, army.units) : army.units;
+      const remaining = army.units - toMove;
+      if (toMove === 0) { printLine(chalk.red('Must move at least 1 unit.')); break; }
+
+      // Update source
+      if (remaining > 0) { army.units = remaining; from.armies = remaining; }
+      else { from.armies -= toMove; state.armies.delete(army.id); }
+
+      // Update destination — merge if friendly army exists
+      const destArmy = findArmyInTerritory(player.id, to.id, state.armies);
+      if (destArmy) { destArmy.units += toMove; }
+      else { state.armies.set(`army_${Date.now()}`, { id: `army_${Date.now()}`, factionId: player.id, units: toMove, morale: army.morale, territoryId: to.id }); }
+      to.armies += toMove;
+
+      const leftMsg = remaining > 0 ? chalk.gray(` (${remaining} garrison ${from.name})`) : '';
+      printLine(chalk.green(`${ICONS.army} Moved ${toMove} units: ${from.name} → ${to.name}${leftMsg}`));
+      break;
+    }
+
+    case 'recruit': {
+      // recruit <territory> <n>
+      if (args.length < 2) { printLine('Usage: recruit <territory> <n>'); break; }
+      const n = parseInt(args[args.length - 1], 10);
+      if (!n || n < 1) { printLine('Usage: recruit <territory> <n>'); break; }
+      const terrName = args.slice(0, -1).join(' ');
+      const terr = findTerritory(state, terrName);
+      if (!terr) { printLine(chalk.red(`Territory "${terrName}" not found.`)); break; }
+      if (terr.owner !== player.id) { printLine(chalk.red(`You don't own ${terr.name}.`)); break; }
+
+      const err = recruitArmy(player, terr, n, state.armies);
+      if (err) { printLine(chalk.red(err)); break; }
+      printLine(chalk.green(`${ICONS.shield} Recruited ${n} units in ${terr.name}. (${ICONS.gold}-${n * 3} ${ICONS.food}-${n * 2})`));
+      break;
+    }
+
+    case 'attack': {
+      // attack <from> <to>
+      if (args.length < 2) { printLine('Usage: attack <from> <to>'); break; }
+      const { from, to } = parseTwoTerritories(state, args);
+      if (!from || !to) { printLine(chalk.red('Could not find those territories.')); break; }
+      if (from.owner !== player.id) { printLine(chalk.red(`You don't own ${from.name}.`)); break; }
+      if (to.owner === player.id) { printLine(chalk.red(`You already own ${to.name}.`)); break; }
+      if (!from.adjacentTo.includes(to.id)) { printLine(chalk.red(`${to.name} is not adjacent to ${from.name}.`)); break; }
+
+      ensureArmyRecord(player.id, from, state.armies);
+      const attackerArmy = findArmyInTerritory(player.id, from.id, state.armies);
+      if (!attackerArmy || attackerArmy.units === 0) { printLine(chalk.red(`No army in ${from.name}.`)); break; }
+
+      printLine(chalk.yellow(`\n  ${ICONS.fire} Battle: ${from.name} (${attackerArmy.units}) → ${to.name} (${to.armies})`));
+      const result = resolveCombat(attackerArmy.units, attackerArmy.morale, to.armies, 80, to.type);
+      result.log.forEach((l) => printLine(`  ${l}`));
+
+      applyCasualties(attackerArmy, result.attackerCasualties, player, state.armies, from);
+      if (result.captured) {
+        const oldOwner = to.owner ? state.factions.get(to.owner) : null;
+        if (oldOwner) {
+          const defArmy = findArmyInTerritory(to.owner!, to.id, state.armies);
+          if (defArmy) applyCasualties(defArmy, result.defenderCasualties, oldOwner, state.armies, to);
+          oldOwner.territories = oldOwner.territories.filter((id) => id !== to.id);
+        }
+        to.owner = player.id;
+        to.armies = attackerArmy?.units ?? 0;
+        player.territories.push(to.id);
+        printLine(chalk.green(`\n  ${ICONS.flag} You captured ${to.name}!`));
+        state.gameLog.push(`Turn ${state.turn}: Captured ${to.name}`);
+      } else {
+        printLine(chalk.red(`\n  ${ICONS.skull} The attack failed.`));
+      }
+      break;
+    }
+
+    case 'save': {
+      saveGame(state, args[0] ?? 'autosave');
+      printLine(chalk.green(`Game saved to "${args[0] ?? 'autosave'}".`));
+      break;
+    }
+
+    case 'next': return true;
+
+    case 'quit': case 'exit':
+      printLine(chalk.gray('Farewell, Emperor.'));
+      rl.close(); process.exit(0); break;
+
+    default:
+      printLine(chalk.red(`Unknown command: "${cmd}". Type help.`));
+  }
+  return false;
+}
+
+// ─── Parse two territory names from args ─────────────────────────────────────
+// Tries to match territory names greedily from left, then right
+function parseTwoTerritories(state: GameState, args: string[]): { from: Territory | undefined; to: Territory | undefined } {
+  // Try splitting at each position
+  for (let i = 1; i < args.length; i++) {
+    const fromName = args.slice(0, i).join(' ');
+    const toName = args.slice(i).join(' ');
+    const from = findTerritory(state, fromName);
+    const to = findTerritory(state, toName);
+    if (from && to && from.id !== to.id) return { from, to };
+  }
+  return { from: undefined, to: undefined };
+}
+
+// ─── Game loop ───────────────────────────────────────────────────────────────
+
+async function runGameLoop(state: GameState): Promise<void> {
+  printLine(chalk.bold.cyan(`\n  ${ICONS.crown} Welcome to Empire CLI ${ICONS.army}\n`));
+  printHelp();
+
+  const MAX_ACTIONS = 3; // actions per turn (look/info/status/help don't count)
+  const FREE_CMDS = new Set(['look', 'info', 'status', 'help', 'where', 'save']);
+
+  while (!state.isOver) {
+    printStatus(state);
+    let turnEnded = false;
+    let actionsUsed = 0;
+    while (!turnEnded) {
+      const remaining = MAX_ACTIONS - actionsUsed;
+      const input = await ask(chalk.cyan(`  Turn ${state.turn} [${remaining}/${MAX_ACTIONS} actions] > `));
+      const cmd = input.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
+
+      // Free commands don't consume actions
+      if (FREE_CMDS.has(cmd)) {
+        turnEnded = await processCommand(input, state);
+        continue;
+      }
+      if (cmd === 'next') { turnEnded = true; continue; }
+      if (cmd === 'quit' || cmd === 'exit') { await processCommand(input, state); continue; }
+
+      // Action commands consume 1 action
+      turnEnded = await processCommand(input, state);
+      if (!turnEnded) actionsUsed++;
+
+      // Auto-end turn when actions exhausted
+      if (actionsUsed >= MAX_ACTIONS && !turnEnded) {
+        printLine(chalk.yellow(`\n  ⏰ No actions remaining — turn ends automatically.`));
+        turnEnded = true;
+      }
+    }
+
+    // === End of Turn ===
+    printLine(''); printSeparator();
+    printLine(chalk.bold.yellow(`  --- End of Turn ${state.turn} ---`));
+    printLine('');
+
+    const resLogs: string[] = [];
+    for (const f of state.factions.values()) resLogs.push(...processTurnResources(f, state.territories));
+    const playerResLogs = resLogs.filter((l) => l.includes(state.factions.get(state.playerFactionId)!.name));
+    playerResLogs.forEach((l) => printLine(chalk.gray(`  ${l}`)));
+
+    const aiLogs = runAiTurns(state);
+    if (aiLogs.length > 0) {
+      printLine(''); printLine(chalk.bold.red(`  ${ICONS.fire} Enemy Actions:`));
+      aiLogs.forEach((l) => printLine(chalk.red(`  ${l}`)));
+    } else {
+      printLine(chalk.gray('  The other factions bide their time...'));
+    }
+
+    [...resLogs, ...aiLogs].forEach((l) => state.gameLog.push(l));
+    printLine(''); printSeparator();
+    state.turn++;
+
+    const winner = checkWinCondition(state);
+    if (winner) {
+      state.isOver = true; state.winner = winner;
+      printLine(chalk.bold.yellow(`\n  ${ICONS.crown} ${state.factions.get(winner)!.name} has conquered the world! Game over.\n`));
+    }
+  }
+}
+
+// ─── Main menu ───────────────────────────────────────────────────────────────
+
+async function mainMenu(): Promise<void> {
+  printLine(chalk.bold.cyan('\n  ╔════════════════════════════╗'));
+  printLine(chalk.bold.cyan('  ║  ⚔️  E M P I R E  CLI  👑  ║'));
+  printLine(chalk.bold.cyan('  ╚════════════════════════════╝\n'));
+  printLine('  1. New Game');
+  printLine('  2. Load Game');
+  printLine('  3. Quit\n');
+
+  const choice = await ask('  Choose: ');
+  if (choice.trim() === '1') {
+    printLine('\nChoose your faction:');
+    printLine('  1. 🔴 Iron Legion (aggressive)');
+    printLine('  2. 🟢 Green Pact (defensive)');
+    printLine('  3. 🟡 Sand Empire (mercantile)');
+    printLine('  4. 🟣 Void Covenant (diplomatic)\n');
+    const fc = await ask('  Choose: ');
+    const fm: Record<string, string> = { '1': 'iron_legion', '2': 'green_pact', '3': 'sand_empire', '4': 'void_covenant' };
+    await runGameLoop(newGame(fm[fc.trim()] ?? 'iron_legion'));
+  } else if (choice.trim() === '2') {
+    const saves = listSaves();
+    if (saves.length === 0) { printLine(chalk.red('No saves found.')); return mainMenu(); }
+    saves.forEach((s, i) => printLine(`  ${i + 1}. ${s}`));
+    const slot = await ask('  Slot name: ');
+    const state = loadGame(slot.trim());
+    if (!state) { printLine(chalk.red('Save not found.')); return mainMenu(); }
+    await runGameLoop(state);
+  } else { rl.close(); process.exit(0); }
+}
+
+mainMenu().catch((err) => { console.error(chalk.red('Fatal:'), err); process.exit(1); });

package/src/state/game-state-manager.ts

@@ -0,0 +1,134 @@
+// Game state creation, serialization, save/load to ~/.empire-cli/saves/
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import type { GameState, SaveData, Army } from '../game-types.js';
+import { DEFAULT_TERRITORIES, DEFAULT_FACTIONS } from '../data/default-world-map.js';
+
+const SAVES_DIR = join(homedir(), '.empire-cli', 'saves');
+
+function ensureSavesDir(): void {
+  if (!existsSync(SAVES_DIR)) {
+    mkdirSync(SAVES_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Create a fresh game state with default map and factions.
+ */
+export function newGame(playerFactionId: string): GameState {
+  const territories = new Map(DEFAULT_TERRITORIES.map((t) => [t.id, { ...t }]));
+  const factions = new Map(DEFAULT_FACTIONS.map((f) => [f.id, { ...f, territories: [...f.territories] }]));
+
+  // Build initial armies from territory data
+  const armies = new Map<string, Army>();
+  let armyCounter = 1;
+  for (const territory of territories.values()) {
+    if (territory.owner && territory.armies > 0) {
+      const armyId = `army_start_${armyCounter++}`;
+      armies.set(armyId, {
+        id: armyId,
+        factionId: territory.owner,
+        units: territory.armies,
+        morale: 80,
+        territoryId: territory.id,
+      });
+    }
+  }
+
+  return {
+    turn: 1,
+    territories,
+    factions,
+    armies,
+    playerFactionId,
+    gameLog: ['A new empire rises. Your destiny awaits.'],
+    isOver: false,
+    winner: null,
+  };
+}
+
+/**
+ * Serialize GameState to JSON-compatible SaveData.
+ */
+export function toSaveData(state: GameState): SaveData {
+  return {
+    turn: state.turn,
+    territories: Object.fromEntries(state.territories),
+    factions: Object.fromEntries(state.factions),
+    armies: Object.fromEntries(state.armies),
+    playerFactionId: state.playerFactionId,
+    gameLog: state.gameLog.slice(-50), // keep last 50 entries
+    isOver: state.isOver,
+    winner: state.winner,
+    savedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Deserialize SaveData back into a live GameState.
+ */
+export function fromSaveData(data: SaveData): GameState {
+  return {
+    turn: data.turn,
+    territories: new Map(Object.entries(data.territories)),
+    factions: new Map(Object.entries(data.factions)),
+    armies: new Map(Object.entries(data.armies)),
+    playerFactionId: data.playerFactionId,
+    gameLog: data.gameLog,
+    isOver: data.isOver,
+    winner: data.winner,
+  };
+}
+
+/**
+ * Save game to ~/.empire-cli/saves/<slot>.json
+ */
+export function saveGame(state: GameState, slot: string = 'autosave'): void {
+  ensureSavesDir();
+  const filePath = join(SAVES_DIR, `${slot}.json`);
+  const data = toSaveData(state);
+  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Load game from ~/.empire-cli/saves/<slot>.json
+ * Returns null if save not found.
+ */
+export function loadGame(slot: string = 'autosave'): GameState | null {
+  ensureSavesDir();
+  const filePath = join(SAVES_DIR, `${slot}.json`);
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data: SaveData = JSON.parse(raw);
+    return fromSaveData(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List available save slots.
+ */
+export function listSaves(): string[] {
+  ensureSavesDir();
+  return readdirSync(SAVES_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace('.json', ''));
+}
+
+/**
+ * Check win condition: a faction owns all territories.
+ */
+export function checkWinCondition(state: GameState): string | null {
+  const totalTerritories = state.territories.size;
+  for (const faction of state.factions.values()) {
+    if (faction.territories.length >= totalTerritories) {
+      return faction.id;
+    }
+  }
+  return null;
+}