Phase 04: Rich Terminal CLI¶

src/theact/cli/
    __init__.py          # Public API: main() entry point
    app.py               # Top-level application loop (menu → game session)
    menu.py              # Game management: list, create, load, delete
    session.py           # Gameplay loop: input → turn engine → display
    commands.py          # Slash command parser and handlers
    renderer.py          # Rich-based rendering: streaming, styling, layout
    styles.py            # Color/style constants

main.py                  # asyncio.run(main()) — the script the player runs

+-----------------------------------------------------------+
|  main.py                                                  |
|  asyncio.run(cli.main())                                  |
+-----------------------------------------------------------+
        |
        v
+-----------------------------------------------------------+
|  app.py — Application                                     |
|  Main menu loop: games/saves management                   |
|  Transitions to Session when player loads a save           |
+-----------------------------------------------------------+
        |                           |
        v                           v
+-------------------+   +---------------------------+
|  menu.py          |   |  session.py — GameSession  |
|  list_games()     |   |  Gameplay loop:            |
|  create_save()    |   |  input → turn engine →     |
|  list_saves()     |   |  stream display → repeat   |
|  delete_save()    |   +---------------------------+
+-------------------+          |            |
                               v            v
                    +---------------+  +----------------+
                    | commands.py   |  | renderer.py    |
                    | parse /cmd    |  | stream tokens  |
                    | dispatch      |  | style text     |
                    +---------------+  +----------------+
                                            |
                                            v
                                    +---------------+
                                    | styles.py     |
                                    | color consts  |
                                    +---------------+

# Phase 03's actual interface:
StreamCallback = Callable[[str, str, str], Awaitable[None]]
# (source: "narrator"|"character", character_name: str, token: str)

async def run_turn(
    game: LoadedGame,
    player_input: str,
    llm_config: LLMConfig,
    on_token: StreamCallback | None = None,
) -> TurnResult

class TurnEngine:
    """Thin adapter: wraps run_turn's StreamCallback into an AsyncIterator[TurnEvent]."""

    def __init__(self, game: LoadedGame, llm_config: LLMConfig):
        self.game = game
        self.llm_config = llm_config

    async def play_turn(self, player_input: str) -> AsyncIterator[TurnEvent]:
        """
        Yields TurnEvent objects as the turn progresses:
        - NarratorThinking(chunk: str)
        - NarratorContent(chunk: str)
        - NarratorDone(full_text: str, metadata: dict)
        - CharacterThinking(character: str, chunk: str)
        - CharacterContent(character: str, chunk: str)
        - CharacterDone(character: str, full_text: str)
        - PostProcessingStart()
        - PostProcessingDone(state: GameState)
        - TurnComplete(turn: int)

        Internally calls engine.run_turn() with an on_token callback that
        pushes TurnEvent objects into an asyncio.Queue, which this method
        yields from.
        """
        ...

uv run python main.py

╭─────────────────────────────────╮
│         T H E   A C T           │
│     an AI text-based RPG        │
╰─────────────────────────────────╯

  1. New Game
  2. Continue Game
  3. Delete Save
  4. Quit

>

1. Display turn header (Turn N, Chapter title)
2. If turn 0: run an initial narrator turn with no player input (opening narration)
3. Show prompt: player name >
4. Read input
5. If input starts with "/": parse and execute slash command
6. Otherwise: pass input to turn_engine.play_turn()
7. Iterate over TurnEvents, rendering each via renderer
8. After TurnComplete: loop back to step 1

Game saved at turn 7. See you next time.

def parse_command(raw_input: str) -> tuple[str, list[str]] | None:
    """
    If input starts with '/', parse it as a command.
    Returns (command_name, args) or None if not a command.

    Examples:
        "/undo"       → ("undo", [])
        "/undo 3"     → ("undo", ["3"])
        "/memory maya" → ("memory", ["maya"])
        "hello"       → None
    """

from rich.style import Style

# --- Narrative styles ---
NARRATOR_STYLE = Style(color="white", italic=True)
NARRATOR_LABEL_STYLE = Style(color="bright_white", bold=True, italic=True)

# --- Character styles ---
# Characters get assigned colors from this palette in order of appearance.
CHARACTER_COLORS = [
    "bright_cyan",
    "bright_magenta",
    "bright_yellow",
    "bright_green",
    "bright_red",
    "bright_blue",
]
CHARACTER_NAME_STYLE = Style(bold=True)  # combined with character color

# --- Player styles ---
PLAYER_STYLE = Style(color="bright_white", bold=True)
PLAYER_PROMPT_STYLE = Style(color="bright_white", bold=True)

# --- Thinking styles ---
THINKING_STYLE = Style(color="bright_black", dim=True)  # gray, dimmed
THINKING_LABEL_STYLE = Style(color="bright_black", bold=True, dim=True)

# --- UI styles ---
STATUS_STYLE = Style(color="bright_black")
ERROR_STYLE = Style(color="red", bold=True)
TURN_HEADER_STYLE = Style(color="bright_black", bold=True)
COMMAND_OUTPUT_STYLE = Style(color="bright_black")

# --- Separators ---
TURN_SEPARATOR = "dim"  # Rich Rule style

def get_character_color(character_name: str, character_list: list[str]) -> str:
    """Return the color for a character based on their position in the roster."""
    try:
        idx = character_list.index(character_name)
    except ValueError:
        idx = hash(character_name)  # fallback for unknown characters
    return CHARACTER_COLORS[idx % len(CHARACTER_COLORS)]

─── Turn 3 · The Crash ────────────────────────────────────────

  ⠿ thinking...
  The model is reasoning about the player's action and the
  current state of the story...

  The tide has pulled back, exposing the reef like broken teeth.
  You can see the tail section now — half-submerged, tilted at
  an unnatural angle. Something moves in the tree line beyond
  the beach. Not wind. Something deliberate.

  Maya Chen
  She drops the piece of fuselage she was examining and looks
  where you're pointing. "I saw it too. About ten minutes ago."
  She pauses. "We should move camp inland before dark."

  ⠿ updating world state...

─────────────────────────────────────────────────────────────

you >

  ⠿ thinking...
  i need to consider what the player is doing. they want to
  explore the wreckage. the chapter beat says they should
  discover a body. i should narrate them approaching the
  tail section and finding something disturbing...

# Simplified rendering pseudocode
from rich.text import Text

console = Console()

async for event in turn_engine.play_turn(player_input):
    match event:
        case NarratorThinking(chunk=text):
            if show_thinking:
                console.print(Text(text, style=THINKING_STYLE), end="")
        case NarratorContent(chunk=text):
            console.print(Text(text, style=NARRATOR_STYLE), end="")
        case CharacterContent(character=name, chunk=text):
            color = get_character_color(name, characters)
            console.print(Text(text, style=Style(color=color)), end="")
        ...

NarratorThinking("i need to")     ← 0+ thinking chunks
NarratorThinking(" consider...")
NarratorContent("The tide has")   ← narrator prose chunks
NarratorContent(" pulled back,")
NarratorContent(" exposing...")
NarratorDone(full_text, metadata) ← signals end of narrator
CharacterThinking("maya would")   ← 0+ per-character thinking
CharacterContent("maya", "She")   ← character prose chunks
CharacterContent("maya", " drops")
CharacterDone("maya", full_text)  ← signals end of character
PostProcessingStart()             ← spinner begins
PostProcessingDone(state)         ← spinner ends
TurnComplete(turn=3)              ← turn fully committed

class RenderState:
    IDLE = "idle"
    THINKING = "thinking"
    NARRATOR = "narrator"
    CHARACTER = "character"
    POST_PROCESSING = "post_processing"

  ⠿ updating world state...

from rich.console import Console

class Application:
    """Top-level CLI application."""

    def __init__(self):
        self.console = Console()
        self.llm_config = None  # loaded on start

    async def run(self):
        """Main entry point. Shows banner, then main menu loop."""
        self._print_banner()
        self.llm_config = self._load_config()

        while True:
            choice = await self._main_menu()
            if choice == "new":
                await self._new_game()
            elif choice == "continue":
                await self._continue_game()
            elif choice == "delete":
                await self._delete_save()
            elif choice == "quit":
                self._farewell()
                break

    def _print_banner(self):
        """Print the title card."""
        ...

    def _load_config(self) -> LLMConfig:
        """Load LLM config from env. Print error and exit if missing."""
        ...

    async def _main_menu(self) -> str:
        """Display menu, return choice string."""
        ...

    async def _new_game(self):
        """Game selection → save creation → enter session."""
        ...

    async def _continue_game(self):
        """Save selection → load → enter session."""
        ...

    async def _delete_save(self):
        """Save selection → confirm → delete."""
        ...

    async def _enter_session(self, game: LoadedGame):
        """Create TurnEngine and GameSession, run session loop."""
        engine = TurnEngine(game, self.llm_config)
        session = GameSession(self.console, engine, game)
        await session.run()

    def _farewell(self):
        self.console.print("\nUntil next time.\n", style=STATUS_STYLE)

from rich.console import Console
from rich.table import Table

def show_game_list(console: Console) -> list[GameMeta]:
    """Display available games as a numbered table. Returns the list."""
    games = save_manager.list_games()
    if not games:
        console.print("No games found in games/.", style=ERROR_STYLE)
        return []
    table = Table(title="Available Games")
    table.add_column("#", style="bold")
    table.add_column("Title")
    table.add_column("Description")
    for i, game in enumerate(games, 1):
        table.add_row(str(i), game.title, game.description)
    console.print(table)
    return games

def show_save_list(console: Console) -> list[dict]:
    """Display existing saves as a numbered table. Returns the list."""
    saves = save_manager.list_saves()
    if not saves:
        console.print("No saves found.", style=STATUS_STYLE)
        return []
    table = Table(title="Saved Games")
    table.add_column("#", style="bold")
    table.add_column("Save ID")
    table.add_column("Game")
    table.add_column("Turn")
    table.add_column("Last Played")
    for i, save in enumerate(saves, 1):
        table.add_row(str(i), save["id"], save["game"], str(save["turn"]), save["modified"])
    console.print(table)
    return saves

def prompt_choice(console: Console, items: list, prompt: str = "Select") -> int | None:
    """Prompt user to pick a numbered item. Returns 0-based index or None on cancel."""
    ...

def prompt_text(console: Console, prompt: str, default: str = "") -> str:
    """Prompt for free-form text input. Returns stripped string."""
    ...

def confirm(console: Console, message: str) -> bool:
    """Yes/no confirmation. Returns True if yes."""
    ...

def slugify(text: str) -> str:
    """Convert a free-form name to a URL-safe slug."""
    # lowercase, replace spaces/special chars with hyphens, strip leading/trailing hyphens
    ...

class GameSession:
    """Manages a single gameplay session from load to quit."""

    def __init__(self, console: Console, engine: TurnEngine, game: LoadedGame):
        self.console = console
        self.engine = engine
        self.game = game
        self.renderer = Renderer(console, game)
        self.show_thinking = True

    async def run(self):
        """Main gameplay loop."""
        if self.game.state.turn == 0:
            # Fresh game — run the opening narration automatically
            await self._play_turn("[game start]")
        else:
            # Resuming a saved game — show recent context so the player
            # knows where they left off
            self._show_recap()

        while True:
            player_input = self._get_input()

            if player_input is None:
                # EOF (Ctrl+D) — treat as quit
                break

            if not player_input.strip():
                continue

            command = parse_command(player_input)
            if command:
                cmd_name, args = command
                should_quit = await self._handle_command(cmd_name, args)
                if should_quit:
                    break
                continue

            await self._play_turn(player_input)

        self._print_exit_message()

    async def _play_turn(self, player_input: str):
        """Run a turn through the engine, streaming results to the renderer."""
        self.renderer.begin_turn(self.game.state.turn + 1, self._current_chapter_title())

        try:
            async for event in self.engine.play_turn(player_input):
                self.renderer.handle_event(event, show_thinking=self.show_thinking)
        except Exception as e:
            self.renderer.show_error(f"Error during turn: {e}")
            # Reload from disk to discard any partial in-memory state mutations
            self.game = save_manager.load_save(self.game.save_path)
            return

        self.renderer.end_turn()
        # Reload game state after turn (the engine has committed changes)
        self.game = save_manager.load_save(self.game.save_path)

    def _get_input(self) -> str | None:
        """Prompt for player input. Returns None on EOF."""
        try:
            return self.console.input(
                f"[bold bright_white]{self.game.state.player_name} > [/]"
            )
        except EOFError:
            return None

    async def _handle_command(self, cmd: str, args: list[str]) -> bool:
        """Execute a slash command. Returns True if session should end."""
        ...  # delegates to commands.py functions

    def _show_recap(self):
        """Show the last few conversation entries so the player has context."""
        entries = self.game.conversation[-5:]  # last 5 entries
        if not entries:
            return
        self.console.print()
        self.console.print("  Previously...", style=Style(dim=True, italic=True))
        self.console.print()
        for entry in entries:
            if entry.role == "narrator":
                # Show truncated narrator text
                text = entry.content[:200] + ("..." if len(entry.content) > 200 else "")
                self.console.print(Text(f"  {text}", style=NARRATOR_STYLE))
            elif entry.role == "player":
                line = Text(f"  {self.game.state.player_name}: ", style=PLAYER_STYLE)
                line.append(entry.content)
                self.console.print(line)
            elif entry.role == "character":
                name = entry.character or "?"
                color = get_character_color(name, list(self.game.characters.keys()))
                self.console.print(Text(f"  {name}: ", style=Style(color=color, bold=True)), end="")
                text = entry.content[:200] + ("..." if len(entry.content) > 200 else "")
                self.console.print(Text(text, style=Style(color=color)))
        self.console.print()

    def _current_chapter_title(self) -> str:
        chapter_id = self.game.state.current_chapter
        return self.game.chapters[chapter_id].title

    def _print_exit_message(self):
        turn = self.game.state.turn
        self.console.print(
            f"\nGame saved at turn {turn}. See you next time.\n",
            style=STATUS_STYLE,
        )

from rich.console import Console
from rich.table import Table

COMMANDS = {
    "help":    {"args": "",               "desc": "Show this help message"},
    "quit":    {"args": "",               "desc": "Exit to main menu"},
    "undo":    {"args": "[N]",            "desc": "Undo last N turns (default: 1)"},
    "history": {"args": "",               "desc": "Show turn history"},
    "save":    {"args": "",               "desc": "Show current save info"},
    "status":  {"args": "",               "desc": "Show game status"},
    "memory":  {"args": "[character]",    "desc": "Show character memory"},
    "think":   {"args": "[on|off]",       "desc": "Toggle thinking display"},
    "retry":   {"args": "",               "desc": "Undo last turn and replay same input"},
    "conversation": {"args": "[N]",       "desc": "Show last N conversation entries"},
}

def parse_command(raw_input: str) -> tuple[str, list[str]] | None:
    """Parse a slash command. Returns (name, args) or None."""
    stripped = raw_input.strip()
    if not stripped.startswith("/"):
        return None
    parts = stripped[1:].split()
    if not parts:
        return None
    return parts[0].lower(), parts[1:]

def cmd_help(console: Console):
    """Display command reference."""
    table = Table(title="Commands", show_header=True)
    table.add_column("Command", style="bold")
    table.add_column("Args")
    table.add_column("Description")
    for name, info in COMMANDS.items():
        table.add_row(f"/{name}", info["args"], info["desc"])
    console.print(table)

def cmd_undo(console: Console, game: LoadedGame, args: list[str]) -> LoadedGame:
    """
    Undo N turns. Returns the reloaded game.
    Raises ValueError for invalid args or over-undo.
    """
    steps = 1
    if args:
        try:
            steps = int(args[0])
            if steps < 1:
                raise ValueError
        except ValueError:
            console.print("Usage: /undo [N] where N is a positive integer.", style=ERROR_STYLE)
            return game

    try:
        new_turn = git_save.undo(Path(game.save_path), steps)
        game = save_manager.load_save(game.save_path)
        console.print(f"Undone {steps} turn(s). Now at turn {new_turn}.", style=STATUS_STYLE)
        return game
    except ValueError as e:
        console.print(f"Cannot undo: {e}", style=ERROR_STYLE)
        return game

def cmd_history(console: Console, game: LoadedGame):
    """Display turn history."""
    history = git_save.get_history(Path(game.save_path))
    if not history:
        console.print("No turn history yet.", style=STATUS_STYLE)
        return
    table = Table(title="Turn History")
    table.add_column("Turn", style="bold")
    table.add_column("Summary")
    table.add_column("Time")
    for entry in history:
        table.add_row(str(entry.turn), entry.message, entry.timestamp)
    console.print(table)

def cmd_save(console: Console, game: LoadedGame):
    """Display save info."""
    console.print(f"  Save:    {game.meta.id}", style=COMMAND_OUTPUT_STYLE)
    console.print(f"  Game:    {game.meta.title}", style=COMMAND_OUTPUT_STYLE)
    console.print(f"  Player:  {game.state.player_name}", style=COMMAND_OUTPUT_STYLE)
    console.print(f"  Path:    {game.save_path}", style=COMMAND_OUTPUT_STYLE)

def cmd_status(console: Console, game: LoadedGame):
    """Display game status."""
    chapter = game.chapters[game.state.current_chapter]
    beats_total = len(chapter.beats)
    beats_done = len(game.state.beats_hit)

    console.print(f"  Chapter: {chapter.title} ({chapter.id})", style=COMMAND_OUTPUT_STYLE)
    console.print(f"  Turn:    {game.state.turn}", style=COMMAND_OUTPUT_STYLE)
    console.print(f"  Beats:   {beats_done}/{beats_total}", style=COMMAND_OUTPUT_STYLE)
    if game.state.flags:
        console.print(f"  Flags:   {game.state.flags}", style=COMMAND_OUTPUT_STYLE)

def cmd_memory(console: Console, game: LoadedGame, args: list[str]):
    """Display character memory."""
    if not args:
        # List characters
        console.print("Characters:", style=COMMAND_OUTPUT_STYLE)
        for name in game.characters:
            char = game.characters[name]
            has_memory = name in game.memories
            marker = " (has memory)" if has_memory else ""
            console.print(f"  - {char.name}{marker}", style=COMMAND_OUTPUT_STYLE)
        return

    # Find character by fuzzy match
    query = " ".join(args).lower()
    match = None
    for key, char in game.characters.items():
        if query in char.name.lower() or query in key.lower():
            match = key
            break

    if match is None:
        names = [game.characters[k].name for k in game.characters]
        console.print(f"Unknown character. Available: {', '.join(names)}", style=ERROR_STYLE)
        return

    if match not in game.memories:
        console.print(f"{game.characters[match].name} has no memories yet.", style=STATUS_STYLE)
        return

    memory = game.memories[match]
    console.print(f"\n  {memory.character} — Memory", style=Style(bold=True))
    console.print(f"\n  Summary: {memory.summary}", style=COMMAND_OUTPUT_STYLE)
    if memory.key_facts:
        console.print("  Key facts:", style=COMMAND_OUTPUT_STYLE)
        for fact in memory.key_facts:
            console.print(f"    - {fact}", style=COMMAND_OUTPUT_STYLE)
    console.print()

def cmd_think(console: Console, args: list[str], current: bool) -> bool:
    """Toggle or set thinking display. Returns new state."""
    if not args:
        state = "on" if current else "off"
        console.print(f"Thinking display is {state}.", style=STATUS_STYLE)
        return current

    arg = args[0].lower()
    if arg == "on":
        console.print("Thinking display enabled.", style=STATUS_STYLE)
        return True
    elif arg == "off":
        console.print("Thinking display disabled.", style=STATUS_STYLE)
        return False
    else:
        console.print("Usage: /think [on|off]", style=ERROR_STYLE)
        return current

from rich.console import Console
from rich.rule import Rule
from rich.text import Text

class Renderer:
    """Handles all visual output during gameplay."""

    def __init__(self, console: Console, game: LoadedGame):
        self.console = console
        self.game = game
        self.character_list = list(game.characters.keys())
        self._section = RenderState.IDLE
        self._current_character = None

    def begin_turn(self, turn_number: int, chapter_title: str):
        """Print the turn header."""
        self.console.print()
        self.console.print(
            Rule(f" Turn {turn_number} · {chapter_title} ", style=TURN_SEPARATOR)
        )
        self.console.print()
        self._section = RenderState.IDLE

    def end_turn(self):
        """Print the turn footer."""
        self.console.print()
        self.console.print(Rule(style=TURN_SEPARATOR))
        self.console.print()
        self._section = RenderState.IDLE

    def handle_event(self, event, show_thinking: bool = True):
        """Route a TurnEvent to the appropriate rendering method."""
        match event:
            case NarratorThinking(chunk=text):
                self._render_thinking(text, show_thinking, label="thinking")
            case NarratorContent(chunk=text):
                self._transition_to(RenderState.NARRATOR)
                self.console.print(Text(text, style=NARRATOR_STYLE), end="")
            case NarratorDone():
                self.console.print()  # newline after narrator block
            case CharacterThinking(character=name, chunk=text):
                self._render_thinking(text, show_thinking, label=f"{name} thinking")
            case CharacterContent(character=name, chunk=text):
                self._transition_to_character(name)
                color = get_character_color(name, self.character_list)
                self.console.print(Text(text, style=Style(color=color)), end="")
            case CharacterDone():
                self.console.print()  # newline after character block
            case PostProcessingStart():
                self._transition_to(RenderState.POST_PROCESSING)
                self._start_spinner()
            case PostProcessingDone():
                self._stop_spinner()
            case TurnComplete():
                pass  # end_turn handles footer

    def _render_thinking(self, text: str, show: bool, label: str):
        """Render thinking tokens if enabled."""
        if not show:
            return
        if self._section != RenderState.THINKING:
            self._transition_to(RenderState.THINKING)
            self.console.print(f"  ⠿ {label}...", style=THINKING_LABEL_STYLE)
        self.console.print(Text(text, style=THINKING_STYLE), end="")

    def _transition_to(self, new_section: str):
        """Handle section transitions with appropriate spacing."""
        if self._section == new_section:
            return
        if self._section != RenderState.IDLE:
            self.console.print()  # end current inline stream
            self.console.print()  # blank line between sections
        self._section = new_section

    def _transition_to_character(self, name: str):
        """Handle transition into a character section, printing name label."""
        if self._section == RenderState.CHARACTER and self._current_character == name:
            return  # still same character, keep streaming
        self._transition_to(RenderState.CHARACTER)
        self._current_character = name
        color = get_character_color(name, self.character_list)
        display_name = self.game.characters.get(name, None)
        label = display_name.name if display_name else name
        self.console.print(f"  {label}", style=Style(color=color, bold=True))

    def _start_spinner(self):
        """Show a post-processing spinner. Uses console.status()."""
        # Note: console.status() is a context manager. We store it so _stop_spinner can exit.
        self._status_ctx = self.console.status(
            "  updating world state...", spinner="dots", style=STATUS_STYLE
        )
        self._status_ctx.__enter__()

    def _stop_spinner(self):
        """Stop the post-processing spinner."""
        if hasattr(self, "_status_ctx"):
            self._status_ctx.__exit__(None, None, None)
            del self._status_ctx
        self._section = RenderState.IDLE

    def show_error(self, message: str):
        """Display an error message. Also stops the spinner if it's running."""
        self._stop_spinner()  # safe to call even if spinner isn't active
        self.console.print()
        self.console.print(f"  Error: {message}", style=ERROR_STYLE)
        self.console.print()

dependencies = [
    "openai>=2.29.0",
    "python-dotenv>=1.2.2",
    "pydantic>=2.10.0",
    "pyyaml>=6.0",
    "gitpython>=3.1.0",
    "rich>=13.0.0",
]