empire-cli 0.1.0

package/README.md

@@ -0,0 +1,137 @@
+# ⚔️ Empire CLI 👑
+
+> **Status: Early MVP** — Core gameplay works. AI game master (Gemini/Ollama/Claude) coming soon.
+
+A CLI turn-based strategy RPG where you build armies, expand your empire, and conquer the world. Open source, runs in any terminal.
+
+## Screenshot
+
+```
+  ╔════════════════════════════╗
+  ║  ⚔️  E M P I R E  CLI  👑  ║
+  ╚════════════════════════════╝
+
+  👑 Iron Legion  —  Turn 1
+  💰 20  🍖 10  🪵 5  🪨 15
+  ⚔️  Armies: 5  |  🚩 Territories: 2/8
+
+  World Map:
+  🏰 Northkeep      Iron Legion ⚔️  3 ★
+     ↔ Iron Hills, Greenwood
+  ⛰️  Iron Hills     Iron Legion ⚔️  2 ★
+     ↔ Northkeep, Crossroads
+  🌲 Greenwood      Green Pact ⚔️  2
+     ↔ Northkeep, Crossroads, Silver Bay
+  🌾 Crossroads     Unclaimed
+     ↔ Iron Hills, Greenwood, Desert Gate, Stonehaven
+  🏰 Silver Bay     Green Pact ⚔️  3
+     ↔ Greenwood, Stonehaven
+  ⛰️  Dragon Peak    Void Covenant ⚔️  4
+     ↔ Stonehaven
+
+  Turn 1 [3/3 actions] > recruit northkeep 2
+  🛡️  Recruited 2 units in Northkeep. (💰-6 🍖-4)
+
+  Turn 1 [2/3 actions] > attack iron crossroads
+  🔥 Battle: Iron Hills (5) → Crossroads (0)
+  Decisive victory! The defenders are routed!
+  🚩 You captured Crossroads!
+
+  --- End of Turn 1 ---
+  🔥 Enemy Actions:
+  Green Pact recruited 3 units in Greenwood
+  Sand Empire attacks Stonehaven from Desert Gate!
+```
+
+## Quick Start
+
+```bash
+# Play instantly (no install needed)
+npx empire-cli
+
+# Or clone for development
+git clone https://github.com/lppduy/empire-cli.git
+cd empire-cli
+npm install
+npm start
+```
+
+## Quick Tutorial
+
+```
+1. Start a new game → pick a faction (e.g. Iron Legion)
+2. "look" — see the world map
+3. "info northkeep" — inspect a territory
+4. "recruit northkeep 3" — train 3 units (costs 3💰 + 2🍖 each)
+5. "move northkeep greenwood 3" — march 3 units to Greenwood
+6. "attack greenwood silver" — attack Silver Bay from Greenwood
+7. "next" — end your turn (or use all 3 actions, auto-advances)
+8. Watch enemy factions react — then plan your next move!
+```
+
+**Goal:** Conquer all 8 territories to win.
+
+## Commands
+
+You get **3 actions per turn**. `look`, `info`, `status`, `help`, `save` are free (don't cost actions).
+
+| Command | Description |
+|---------|-------------|
+| `look` | Show world map |
+| `info <territory>` | Show territory details & neighbors |
+| `status` | Show your resources and army count |
+| `move <from> <to> [n]` | Move n units between territories (all if omitted) |
+| `recruit <territory> <n>` | Recruit n units at a territory |
+| `attack <from> <to>` | Attack enemy territory from yours |
+| `next` | End turn early |
+| `save [slot]` | Save game |
+| `help` | Show commands |
+| `quit` | Exit |
+
+## Factions
+
+| Faction | Personality | Strengths |
+|---------|-------------|-----------|
+| 🔴 Iron Legion | Aggressive | High stone, strong start |
+| 🟢 Green Pact | Defensive | High food & wood |
+| 🟡 Sand Empire | Mercantile | High gold reserves |
+| 🟣 Void Covenant | Diplomatic | Mountain fortress |
+
+## Resources
+
+- 💰 **Gold** — Recruit armies (3 per unit)
+- 🍖 **Food** — Recruit + army upkeep (2 per unit)
+- 🪵 **Wood** — Future: buildings
+- 🪨 **Stone** — Future: fortifications
+
+## Roadmap
+
+- [x] Core game loop with turn-based strategy
+- [x] 4 factions with AI personalities
+- [x] 8-territory map with adjacency
+- [x] Combat system with terrain bonuses
+- [x] Save/load game
+- [x] Action limit per turn (3 actions)
+- [ ] AI Game Master (Gemini free tier / Ollama / Claude) — dynamic narration
+- [ ] Diplomacy system (alliances, trade, peace)
+- [ ] Buildings (walls, barracks, markets)
+- [ ] More maps & factions
+- [ ] npm package (`npx empire-cli`)
+
+## Tech Stack
+
+- TypeScript + Node.js 18+
+- chalk (terminal colors)
+- readline (input)
+- JSON saves (`~/.empire-cli/saves/`)
+
+## Development
+
+```bash
+npm start      # Play the game
+npm run build  # Compile TypeScript
+```
+
+## License
+
+MIT

package/assets/gameplay-output.txt

@@ -0,0 +1,117 @@
+
+  ╔════════════════════════════╗
+  ║  ⚔️  E M P I R E  CLI  👑  ║
+  ╚════════════════════════════╝
+
+  1. New Game
+  2. Load Game
+  3. Quit
+
+  Choose: 
+Choose your faction:
+  1. 🔴 Iron Legion (aggressive)
+  2. 🟢 Green Pact (defensive)
+  3. 🟡 Sand Empire (mercantile)
+  4. 🟣 Void Covenant (diplomatic)
+
+  Choose: 
+  👑 Welcome to Empire CLI ⚔️ 
+
+
+  Commands:
+  look                        — show world map
+  info <territory>            — show territory details
+  status                      — show your resources
+  move <from> <to> [n]        — move n units between territories (all if omitted)
+  recruit <territory> <n>     — recruit n units (3💰 + 2🍖 each)
+  attack <from> <to>          — attack enemy territory from yours
+  next                        — end turn (enemies act after this)
+  save [slot]                 — save game
+  quit                        — exit game
+  help                        — show this help
+
+────────────────────────────────────────────────────────────
+  👑 Iron Legion  —  Turn 1
+  💰 20  🍖 10  🪵 5  🪨 15
+  ⚔️  Armies: 5  |  🚩 Territories: 2/8
+────────────────────────────────────────────────────────────
+  Turn 1 [3/3 actions] > 
+  World Map:
+
+  🏰 Northkeep      Iron Legion ⚔️  3 ★
+     ↔ Iron Hills, Greenwood
+  ⛰️  Iron Hills     Iron Legion ⚔️  2 ★
+     ↔ Northkeep, Crossroads
+  🌲 Greenwood      Green Pact ⚔️  2
+     ↔ Northkeep, Crossroads, Silver Bay
+  🌾 Crossroads     Unclaimed
+     ↔ Iron Hills, Greenwood, Desert Gate, Stonehaven
+  🌾 Desert Gate    Sand Empire ⚔️  2
+     ↔ Crossroads
+  🏰 Silver Bay     Green Pact ⚔️  3
+     ↔ Greenwood, Stonehaven
+  ⛰️  Stonehaven     Sand Empire ⚔️  2
+     ↔ Crossroads, Silver Bay, Dragon Peak
+  ⛰️  Dragon Peak    Void Covenant ⚔️  4
+     ↔ Stonehaven
+
+  Turn 1 [3/3 actions] > 
+  🏰 Northkeep (city)
+  Owner: Iron Legion
+  ⚔️  Armies: 3
+  Resources/turn: 💰4 🍖2 🪵1 🪨2
+  Neighbors:
+    → ⛰️  Iron Hills — Iron Legion ★
+    → 🌲 Greenwood — Green Pact ⚔️ 2
+
+  Turn 1 [3/3 actions] > 🛡️  Recruited 2 units in Northkeep. (💰-6 🍖-4)
+  Turn 1 [2/3 actions] > ⚔️  Moved 3 units: Northkeep → Iron Hills (2 garrison Northkeep)
+  Turn 1 [1/3 actions] > 
+  🔥 Battle: Iron Hills (5) → Crossroads (0)
+  Attack power: 4.0 vs Defense power: 0.0
+  Terrain (plains) gives defender x1 bonus
+  Decisive victory! The defenders are routed!
+  Attacker losses: 0 units
+  Defender losses: 0 units
+
+  🚩 You captured Crossroads!
+
+  ⏰ No actions remaining — turn ends automatically.
+
+────────────────────────────────────────────────────────────
+  --- End of Turn 1 ---
+
+  Iron Legion collected: +8g +5f +2w +7s
+
+  🔥 Enemy Actions:
+  Green Pact recruited 3 units in Greenwood
+  Green Pact attacks Northkeep from Greenwood!
+    → Green Pact captured Northkeep! 🔥
+
+────────────────────────────────────────────────────────────
+────────────────────────────────────────────────────────────
+  👑 Iron Legion  —  Turn 2
+  💰 22  🍖 4  🪵 7  🪨 22
+  ⚔️  Armies: 6  |  🚩 Territories: 2/8
+────────────────────────────────────────────────────────────
+  Turn 2 [3/3 actions] > 
+  World Map:
+
+  🏰 Northkeep      Green Pact ⚔️  4
+     ↔ Iron Hills, Greenwood
+  ⛰️  Iron Hills     Iron Legion ⚔️  5 ★
+     ↔ Northkeep, Crossroads
+  🌲 Greenwood      Green Pact ⚔️  4
+     ↔ Northkeep, Crossroads, Silver Bay
+  🌾 Crossroads     Iron Legion ⚔️  5 ★
+     ↔ Iron Hills, Greenwood, Desert Gate, Stonehaven
+  🌾 Desert Gate    Sand Empire ⚔️  2
+     ↔ Crossroads
+  🏰 Silver Bay     Green Pact ⚔️  3
+     ↔ Greenwood, Stonehaven
+  ⛰️  Stonehaven     Sand Empire ⚔️  2
+     ↔ Crossroads, Silver Bay, Dragon Peak
+  ⛰️  Dragon Peak    Void Covenant ⚔️  4
+     ↔ Stonehaven
+
+  Turn 2 [3/3 actions] > Farewell, Emperor.

package/dist/data/default-world-map.d.ts

@@ -0,0 +1,3 @@
+import type { Territory, Faction } from '../game-types.js';
+export declare const DEFAULT_TERRITORIES: Territory[];
+export declare const DEFAULT_FACTIONS: Faction[];

package/dist/data/default-world-map.js

@@ -0,0 +1,133 @@
+// Default world map data: 8 territories, 4 starting factions
+// Map layout:
+//   [Northkeep] --- [Iron Hills]
+//        |              |
+//   [Greenwood] --- [Crossroads] --- [Desert Gate]
+//        |              |
+//   [Silver Bay] --- [Stonehaven]
+//                       |
+//                  [Dragon Peak]
+export const DEFAULT_TERRITORIES = [
+    {
+        id: 'northkeep',
+        name: 'Northkeep',
+        type: 'city',
+        owner: 'iron_legion',
+        armies: 3,
+        resources: { gold: 4, food: 2, wood: 1, stone: 2 },
+        adjacentTo: ['iron_hills', 'greenwood'],
+    },
+    {
+        id: 'iron_hills',
+        name: 'Iron Hills',
+        type: 'mountain',
+        owner: 'iron_legion',
+        armies: 2,
+        resources: { gold: 2, food: 1, wood: 0, stone: 4 },
+        adjacentTo: ['northkeep', 'crossroads'],
+    },
+    {
+        id: 'greenwood',
+        name: 'Greenwood',
+        type: 'forest',
+        owner: 'green_pact',
+        armies: 2,
+        resources: { gold: 1, food: 3, wood: 4, stone: 0 },
+        adjacentTo: ['northkeep', 'crossroads', 'silver_bay'],
+    },
+    {
+        id: 'crossroads',
+        name: 'Crossroads',
+        type: 'plains',
+        owner: null,
+        armies: 0,
+        resources: { gold: 2, food: 2, wood: 1, stone: 1 },
+        adjacentTo: ['iron_hills', 'greenwood', 'desert_gate', 'stonehaven'],
+    },
+    {
+        id: 'desert_gate',
+        name: 'Desert Gate',
+        type: 'plains',
+        owner: 'sand_empire',
+        armies: 2,
+        resources: { gold: 3, food: 1, wood: 0, stone: 2 },
+        adjacentTo: ['crossroads'],
+    },
+    {
+        id: 'silver_bay',
+        name: 'Silver Bay',
+        type: 'city',
+        owner: 'green_pact',
+        armies: 3,
+        resources: { gold: 5, food: 2, wood: 1, stone: 1 },
+        adjacentTo: ['greenwood', 'stonehaven'],
+    },
+    {
+        id: 'stonehaven',
+        name: 'Stonehaven',
+        type: 'mountain',
+        owner: 'sand_empire',
+        armies: 2,
+        resources: { gold: 2, food: 1, wood: 0, stone: 5 },
+        adjacentTo: ['crossroads', 'silver_bay', 'dragon_peak'],
+    },
+    {
+        id: 'dragon_peak',
+        name: 'Dragon Peak',
+        type: 'mountain',
+        owner: 'void_covenant',
+        armies: 4,
+        resources: { gold: 1, food: 0, wood: 0, stone: 6 },
+        adjacentTo: ['stonehaven'],
+    },
+];
+export const DEFAULT_FACTIONS = [
+    {
+        id: 'iron_legion',
+        name: 'Iron Legion',
+        personality: 'aggressive',
+        color: 'red',
+        territories: ['northkeep', 'iron_hills'],
+        gold: 20,
+        food: 10,
+        wood: 5,
+        stone: 15,
+        totalArmies: 5,
+    },
+    {
+        id: 'green_pact',
+        name: 'Green Pact',
+        personality: 'defensive',
+        color: 'green',
+        territories: ['greenwood', 'silver_bay'],
+        gold: 15,
+        food: 20,
+        wood: 25,
+        stone: 5,
+        totalArmies: 5,
+    },
+    {
+        id: 'sand_empire',
+        name: 'Sand Empire',
+        personality: 'mercantile',
+        color: 'yellow',
+        territories: ['desert_gate', 'stonehaven'],
+        gold: 30,
+        food: 8,
+        wood: 2,
+        stone: 10,
+        totalArmies: 4,
+    },
+    {
+        id: 'void_covenant',
+        name: 'Void Covenant',
+        personality: 'diplomatic',
+        color: 'magenta',
+        territories: ['dragon_peak'],
+        gold: 10,
+        food: 5,
+        wood: 2,
+        stone: 20,
+        totalArmies: 4,
+    },
+];

package/dist/engine/ai-turn-processor.d.ts

@@ -0,0 +1,2 @@
+import type { GameState } from '../game-types.js';
+export declare function runAiTurns(state: GameState): string[];

package/dist/engine/ai-turn-processor.js

@@ -0,0 +1,75 @@
+import { resolveCombat } from './combat-resolver.js';
+import { findArmyInTerritory, getUnitsInTerritory, applyCasualties } from './army-manager.js';
+export function runAiTurns(state) {
+    const log = [];
+    for (const faction of state.factions.values()) {
+        if (faction.id === state.playerFactionId)
+            continue;
+        if (faction.territories.length === 0)
+            continue;
+        // Simple AI: recruit if has resources, then try to expand
+        // Recruit in first territory if affordable
+        if (faction.gold >= 6 && faction.food >= 4) {
+            const recruitTerrId = faction.territories[0];
+            const recruitTerr = state.territories.get(recruitTerrId);
+            if (recruitTerr) {
+                const units = Math.min(Math.floor(faction.gold / 3), Math.floor(faction.food / 2), 3);
+                if (units > 0) {
+                    faction.gold -= units * 3;
+                    faction.food -= units * 2;
+                    faction.totalArmies += units;
+                    recruitTerr.armies += units;
+                    // Create/merge army record
+                    const existing = findArmyInTerritory(faction.id, recruitTerrId, state.armies);
+                    if (existing) {
+                        existing.units += units;
+                    }
+                    else {
+                        const id = `ai_army_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+                        state.armies.set(id, { id, factionId: faction.id, units, morale: 80, territoryId: recruitTerrId });
+                    }
+                    log.push(`${faction.name} recruited ${units} units in ${recruitTerr.name}`);
+                }
+            }
+        }
+        // Try to attack one adjacent weak territory
+        for (const territoryId of [...faction.territories]) {
+            const territory = state.territories.get(territoryId);
+            for (const adjId of territory.adjacentTo) {
+                const adj = state.territories.get(adjId);
+                if (adj.owner === faction.id)
+                    continue;
+                const attackerUnits = getUnitsInTerritory(faction.id, territoryId, state.armies);
+                const defenderUnits = adj.armies;
+                if (attackerUnits < 2)
+                    continue;
+                if (attackerUnits < defenderUnits && faction.personality !== 'aggressive')
+                    continue;
+                const result = resolveCombat(attackerUnits, 80, defenderUnits, 80, adj.type);
+                log.push(`${faction.name} attacks ${adj.name} from ${territory.name}!`);
+                const attackerArmy = findArmyInTerritory(faction.id, territoryId, state.armies);
+                if (attackerArmy)
+                    applyCasualties(attackerArmy, result.attackerCasualties, faction, state.armies, territory);
+                if (result.captured) {
+                    const oldOwner = adj.owner ? state.factions.get(adj.owner) : null;
+                    if (oldOwner) {
+                        oldOwner.territories = oldOwner.territories.filter((id) => id !== adjId);
+                        const defArmy = findArmyInTerritory(adj.owner, adjId, state.armies);
+                        if (defArmy)
+                            applyCasualties(defArmy, result.defenderCasualties, oldOwner, state.armies, adj);
+                    }
+                    adj.owner = faction.id;
+                    adj.armies = attackerArmy?.units ?? 0;
+                    faction.territories.push(adjId);
+                    log.push(`  → ${faction.name} captured ${adj.name}! ${ICONS_FIRE}`);
+                }
+                else {
+                    log.push(`  → Attack on ${adj.name} failed`);
+                }
+                return log; // one attack per faction per turn
+            }
+        }
+    }
+    return log;
+}
+const ICONS_FIRE = '🔥';

package/dist/engine/army-manager.d.ts

@@ -0,0 +1,28 @@
+import type { Army, Faction, Territory } from '../game-types.js';
+/**
+ * Recruit new army units in a territory owned by the faction.
+ * Returns error message or null on success.
+ */
+export declare function recruitArmy(faction: Faction, territory: Territory, units: number, armies: Map<string, Army>): string | null;
+/**
+ * Move an army from one territory to an adjacent territory.
+ * Returns error message or null on success.
+ */
+export declare function moveArmy(army: Army, fromTerritory: Territory, toTerritory: Territory): string | null;
+/**
+ * Find any army belonging to a faction in a specific territory.
+ */
+export declare function findArmyInTerritory(factionId: string, territoryId: string, armies: Map<string, Army>): Army | undefined;
+/**
+ * Get total units a faction has in a given territory.
+ */
+export declare function getUnitsInTerritory(factionId: string, territoryId: string, armies: Map<string, Army>): number;
+/**
+ * Remove casualties from army after combat. Destroys army if no units remain.
+ */
+export declare function applyCasualties(army: Army, casualties: number, faction: Faction, armies: Map<string, Army>, territory: Territory): void;
+/**
+ * Ensure an Army record exists for a faction in a territory.
+ * Fixes desync where territory.armies > 0 but no Army object exists.
+ */
+export declare function ensureArmyRecord(factionId: string, territory: Territory, armies: Map<string, Army>): void;

package/dist/engine/army-manager.js

@@ -0,0 +1,111 @@
+// Army recruitment, movement, and validation logic
+import { canAfford, deductResources } from './resource-calculator.js';
+const RECRUIT_COST_PER_UNIT = { gold: 3, food: 2, wood: 0, stone: 0 };
+const DEFAULT_MORALE = 80;
+let armyIdCounter = 1;
+function generateArmyId() {
+    return `army_${Date.now()}_${armyIdCounter++}`;
+}
+/**
+ * Recruit new army units in a territory owned by the faction.
+ * Returns error message or null on success.
+ */
+export function recruitArmy(faction, territory, units, armies) {
+    if (territory.owner !== faction.id) {
+        return `${territory.name} is not owned by ${faction.name}.`;
+    }
+    if (units < 1) {
+        return 'Must recruit at least 1 unit.';
+    }
+    const totalCost = {
+        gold: RECRUIT_COST_PER_UNIT.gold * units,
+        food: RECRUIT_COST_PER_UNIT.food * units,
+    };
+    if (!canAfford(faction, totalCost)) {
+        return `Not enough resources. Need ${totalCost.gold} gold and ${totalCost.food} food.`;
+    }
+    deductResources(faction, totalCost);
+    faction.totalArmies += units;
+    territory.armies += units;
+    // Create or merge army in territory
+    const existingArmy = findArmyInTerritory(faction.id, territory.id, armies);
+    if (existingArmy) {
+        existingArmy.units += units;
+    }
+    else {
+        const newArmy = {
+            id: generateArmyId(),
+            factionId: faction.id,
+            units,
+            morale: DEFAULT_MORALE,
+            territoryId: territory.id,
+        };
+        armies.set(newArmy.id, newArmy);
+    }
+    return null;
+}
+/**
+ * Move an army from one territory to an adjacent territory.
+ * Returns error message or null on success.
+ */
+export function moveArmy(army, fromTerritory, toTerritory) {
+    if (army.territoryId !== fromTerritory.id) {
+        return 'Army is not in the specified territory.';
+    }
+    if (!fromTerritory.adjacentTo.includes(toTerritory.id)) {
+        return `${toTerritory.name} is not adjacent to ${fromTerritory.name}.`;
+    }
+    // Move the army
+    fromTerritory.armies -= army.units;
+    toTerritory.armies += army.units;
+    army.territoryId = toTerritory.id;
+    return null;
+}
+/**
+ * Find any army belonging to a faction in a specific territory.
+ */
+export function findArmyInTerritory(factionId, territoryId, armies) {
+    for (const army of armies.values()) {
+        if (army.factionId === factionId && army.territoryId === territoryId) {
+            return army;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get total units a faction has in a given territory.
+ */
+export function getUnitsInTerritory(factionId, territoryId, armies) {
+    let total = 0;
+    for (const army of armies.values()) {
+        if (army.factionId === factionId && army.territoryId === territoryId) {
+            total += army.units;
+        }
+    }
+    return total;
+}
+/**
+ * Remove casualties from army after combat. Destroys army if no units remain.
+ */
+export function applyCasualties(army, casualties, faction, armies, territory) {
+    const actual = Math.min(casualties, army.units);
+    army.units -= actual;
+    faction.totalArmies -= actual;
+    territory.armies -= actual;
+    if (army.units <= 0) {
+        armies.delete(army.id);
+    }
+}
+/**
+ * Ensure an Army record exists for a faction in a territory.
+ * Fixes desync where territory.armies > 0 but no Army object exists.
+ */
+export function ensureArmyRecord(factionId, territory, armies) {
+    if (territory.armies > 0 && territory.owner === factionId) {
+        const existing = findArmyInTerritory(factionId, territory.id, armies);
+        if (!existing) {
+            const id = `army_fix_${Date.now()}`;
+            armies.set(id, { id, factionId, units: territory.armies, morale: 80, territoryId: territory.id });
+        }
+    }
+}

package/dist/engine/combat-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { CombatResult, TerritoryType } from '../game-types.js';
+/**
+ * Resolve combat between attacker and defender armies.
+ * Uses a power ratio formula to determine outcome and casualties.
+ */
+export declare function resolveCombat(attackerUnits: number, attackerMorale: number, defenderUnits: number, defenderMorale: number, terrain: TerritoryType): CombatResult;
+/**
+ * Simulate AI faction auto-attack decision: returns true if AI should attack.
+ */
+export declare function shouldAiAttack(personality: string, attackerUnits: number, defenderUnits: number): boolean;