coffee-cli 0.1.0__py3-none-any.whl

coffee_cli/__init__.py

@@ -0,0 +1,6 @@
+"""Coffee CLI package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

coffee_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Run Coffee CLI with ``python -m coffee_cli``."""
+
+from coffee_cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

coffee_cli/app.py

@@ -0,0 +1,344 @@
+"""Textual application for Coffee CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.reactive import reactive
+from textual.timer import Timer
+from textual.widgets import Footer, Header, Static
+
+from coffee_cli.brewing import get_brew_stage, is_brew_complete, next_brew_index
+from coffee_cli.home import HOME_MENU_ITEMS, get_menu_item, move_selection, select_menu_item
+from coffee_cli.order import (
+    CONFIRM_OPTIONS,
+    OrderDraft,
+    OrderStep,
+    apply_order_choice,
+    get_order_options,
+    move_order_selection,
+    next_order_step,
+    previous_order_step,
+)
+from coffee_cli.personal import (
+    PersonalData,
+    add_favorite,
+    add_journal_entry,
+    add_order_history,
+    draft_to_saved_drink,
+    load_personal_data,
+    make_journal_entry,
+    save_personal_data,
+)
+from coffee_cli.ui_text import (
+    STEAM_FRAMES,
+    render_brewing_panel,
+    render_brewing_summary,
+    render_favorites_panel,
+    render_hero,
+    render_journal_panel,
+    render_menu,
+    render_order_menu,
+    render_order_summary,
+    render_personal_summary,
+    render_statistics_panel,
+    render_summary,
+)
+
+
+class CoffeeApp(App[None]):
+    """The first interactive shell for Coffee CLI."""
+
+    CSS = """
+    Screen {
+        background: #101820;
+        color: #f5efe6;
+    }
+
+    #layout {
+        height: 1fr;
+    }
+
+    #left-pane {
+        width: 2fr;
+        padding: 1 2;
+    }
+
+    #right-pane {
+        width: 1fr;
+        padding: 2;
+        border: round #2bb3a3;
+        background: #17242d;
+    }
+
+    #hero {
+        margin-bottom: 1;
+    }
+
+    #menu {
+        border: round #ffbf69;
+        padding: 1 2;
+        background: #161f27;
+    }
+    """
+
+    BINDINGS = [
+        Binding("up,k", "move_up", "Up"),
+        Binding("down,j", "move_down", "Down"),
+        Binding("enter", "select_item", "Select"),
+        Binding("escape", "go_back", "Back"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    active_view = reactive("home")
+    selected_index = reactive(0)
+    order_step_index = reactive(0)
+    brew_stage_index = reactive(0)
+    steam_index = reactive(0)
+    status_message = reactive("Navigate the menu. This is Milestone 1.")
+
+    def __init__(self, personal_data_path: Path | None = None) -> None:
+        super().__init__()
+        self.order_step: OrderStep = "drink"
+        self.order_draft = OrderDraft()
+        self.brew_timer: Timer | None = None
+        self.personal_data_path = personal_data_path
+        self.personal_data: PersonalData = load_personal_data(personal_data_path)
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with Horizontal(id="layout"):
+            with Vertical(id="left-pane"):
+                yield Static(id="hero")
+                yield Static(id="menu")
+            yield Static(id="right-pane")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.set_interval(0.35, self.advance_steam)
+        self.refresh_view()
+
+    def watch_selected_index(self) -> None:
+        self.refresh_view()
+
+    def watch_order_step_index(self) -> None:
+        self.refresh_view()
+
+    def watch_brew_stage_index(self) -> None:
+        self.refresh_view()
+
+    def watch_active_view(self) -> None:
+        self.refresh_view()
+
+    def watch_status_message(self) -> None:
+        self.refresh_view()
+
+    def watch_steam_index(self) -> None:
+        self.refresh_view()
+
+    def advance_steam(self) -> None:
+        self.steam_index = (self.steam_index + 1) % len(STEAM_FRAMES)
+
+    def action_move_up(self) -> None:
+        if self.active_view == "brewing":
+            return
+        if self.active_view == "order":
+            self.order_step_index = move_order_selection(
+                self.order_step_index,
+                -1,
+                len(get_order_options(self.order_step)),
+            )
+            return
+        self.selected_index = move_selection(self.selected_index, -1)
+
+    def action_move_down(self) -> None:
+        if self.active_view == "brewing":
+            return
+        if self.active_view == "order":
+            self.order_step_index = move_order_selection(
+                self.order_step_index,
+                1,
+                len(get_order_options(self.order_step)),
+            )
+            return
+        self.selected_index = move_selection(self.selected_index, 1)
+
+    def action_select_item(self) -> None:
+        if self.active_view in {"favorites", "journal", "statistics"}:
+            return
+
+        if self.active_view == "brewing":
+            if is_brew_complete(self.brew_stage_index):
+                self.return_home_after_brew()
+            return
+
+        if self.active_view == "order":
+            self.select_order_item()
+            return
+
+        selection = select_menu_item(self.selected_index)
+        if selection.should_exit:
+            self.exit()
+            return
+        if selection.item.label == "Order Coffee":
+            self.start_order()
+            return
+        if selection.item.label == "My Favorites":
+            self.open_personal_view("favorites", "Viewing saved favorite drinks.")
+            return
+        if selection.item.label == "Coffee Journal":
+            self.open_personal_view("journal", "Viewing coffee journal entries.")
+            return
+        if selection.item.label == "Statistics":
+            self.open_personal_view("statistics", "Viewing coffee statistics.")
+            return
+        self.status_message = selection.item.status
+
+    def action_go_back(self) -> None:
+        if self.active_view in {"favorites", "journal", "statistics"}:
+            self.active_view = "home"
+            self.status_message = "Back at home."
+            return
+
+        if self.active_view == "brewing":
+            return
+
+        if self.active_view != "order":
+            return
+
+        previous_step = previous_order_step(self.order_step)
+        if previous_step is None:
+            self.active_view = "home"
+            self.status_message = "Order canceled. Back at home."
+            return
+
+        self.order_step = previous_step
+        self.order_step_index = 0
+        self.status_message = "Step back and adjust the order."
+
+    def start_order(self) -> None:
+        self.active_view = "order"
+        self.order_step = "drink"
+        self.order_step_index = 0
+        self.order_draft = OrderDraft()
+        self.status_message = "Choose a coffee to start the order."
+
+    def open_personal_view(self, view_name: str, message: str) -> None:
+        self.active_view = view_name
+        self.status_message = message
+
+    def select_order_item(self) -> None:
+        if self.order_step == "confirm":
+            selected = CONFIRM_OPTIONS[self.order_step_index]
+            if selected.label == "Confirm Order":
+                self.start_brewing()
+                return
+            if selected.label == "Start Over":
+                self.start_order()
+                return
+            self.active_view = "home"
+            self.status_message = "Order canceled. Back at home."
+            return
+
+        self.order_draft = apply_order_choice(
+            self.order_draft,
+            self.order_step,
+            self.order_step_index,
+        )
+        self.order_step = next_order_step(self.order_step)
+        self.order_step_index = 0
+        self.status_message = "Order updated. Keep going."
+
+    def start_brewing(self) -> None:
+        self.record_completed_order()
+        self.active_view = "brewing"
+        self.brew_stage_index = 0
+        self.status_message = "Brewing your order."
+        if self.brew_timer is not None:
+            self.brew_timer.stop()
+        self.brew_timer = self.set_interval(0.75, self.advance_brewing)
+
+    def advance_brewing(self) -> None:
+        if is_brew_complete(self.brew_stage_index):
+            if self.brew_timer is not None:
+                self.brew_timer.stop()
+                self.brew_timer = None
+            self.status_message = "Coffee ready. Press Enter to return home."
+            return
+
+        self.brew_stage_index = next_brew_index(self.brew_stage_index)
+        if is_brew_complete(self.brew_stage_index):
+            self.status_message = "Coffee ready. Press Enter to return home."
+
+    def return_home_after_brew(self) -> None:
+        if self.brew_timer is not None:
+            self.brew_timer.stop()
+            self.brew_timer = None
+        self.active_view = "home"
+        self.selected_index = 0
+        self.order_step = "drink"
+        self.order_step_index = 0
+        self.brew_stage_index = 0
+        self.order_draft = OrderDraft()
+        self.status_message = "Order complete. Ready for another coffee."
+
+    def record_completed_order(self) -> None:
+        drink = draft_to_saved_drink(self.order_draft)
+        self.personal_data = add_order_history(self.personal_data, drink)
+        self.personal_data = add_favorite(self.personal_data, drink)
+        self.personal_data = add_journal_entry(self.personal_data, make_journal_entry(drink))
+        save_personal_data(self.personal_data, self.personal_data_path)
+
+    def refresh_view(self) -> None:
+        steam_frame = STEAM_FRAMES[self.steam_index]
+        self.query_one("#hero", Static).update(render_hero(steam_frame))
+
+        if self.active_view == "favorites":
+            self.query_one("#menu", Static).update(render_favorites_panel(self.personal_data))
+            self.query_one("#right-pane", Static).update(
+                render_personal_summary(self.personal_data, self.status_message)
+            )
+            return
+
+        if self.active_view == "journal":
+            self.query_one("#menu", Static).update(render_journal_panel(self.personal_data))
+            self.query_one("#right-pane", Static).update(
+                render_personal_summary(self.personal_data, self.status_message)
+            )
+            return
+
+        if self.active_view == "statistics":
+            self.query_one("#menu", Static).update(render_statistics_panel(self.personal_data))
+            self.query_one("#right-pane", Static).update(
+                render_personal_summary(self.personal_data, self.status_message)
+            )
+            return
+
+        if self.active_view == "brewing":
+            stage = get_brew_stage(self.brew_stage_index)
+            self.query_one("#menu", Static).update(
+                render_brewing_panel(stage, is_brew_complete(self.brew_stage_index))
+            )
+            self.query_one("#right-pane", Static).update(
+                render_brewing_summary(self.order_draft, stage)
+            )
+            return
+
+        if self.active_view == "order":
+            options = get_order_options(self.order_step)
+            self.query_one("#menu", Static).update(
+                render_order_menu(self.order_step, options, self.order_step_index)
+            )
+            self.query_one("#right-pane", Static).update(
+                render_order_summary(self.order_draft, self.status_message)
+            )
+            return
+
+        selected_item = get_menu_item(self.selected_index)
+        self.query_one("#menu", Static).update(render_menu(HOME_MENU_ITEMS, self.selected_index))
+        self.query_one("#right-pane", Static).update(
+            render_summary(selected_item, self.status_message)
+        )

coffee_cli/brewing.py

@@ -0,0 +1,49 @@
+"""Brewing animation state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BrewStage:
+    """One visible step in the brewing animation."""
+
+    label: str
+    detail: str
+    progress: int
+
+
+BREW_STAGES = (
+    BrewStage("Grinding beans", "Breaking the beans into a clean, even grind.", 2),
+    BrewStage("Heating water", "Bringing water up to brewing temperature.", 4),
+    BrewStage("Brewing coffee", "Extracting the drink you built.", 7),
+    BrewStage("Pouring cup", "Finishing the order and settling the foam.", 9),
+    BrewStage("Ready", "Your coffee is ready. Enjoy.", 10),
+)
+
+
+def clamp_brew_index(index: int) -> int:
+    """Clamp a brewing index to the available stages."""
+    return max(0, min(index, len(BREW_STAGES) - 1))
+
+
+def get_brew_stage(index: int) -> BrewStage:
+    """Return a brewing stage by clamped index."""
+    return BREW_STAGES[clamp_brew_index(index)]
+
+
+def next_brew_index(index: int) -> int:
+    """Advance the brewing animation by one stage."""
+    return clamp_brew_index(index + 1)
+
+
+def is_brew_complete(index: int) -> bool:
+    """Return whether the brewing animation reached the final stage."""
+    return clamp_brew_index(index) == len(BREW_STAGES) - 1
+
+
+def render_progress_bar(progress: int, width: int = 10) -> str:
+    """Render a text progress bar."""
+    bounded = max(0, min(progress, width))
+    return "█" * bounded + "░" * (width - bounded)

coffee_cli/cli.py

@@ -0,0 +1,41 @@
+"""Console entry point for Coffee CLI."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol
+
+
+class RunnableApp(Protocol):
+    """Protocol for apps with a Textual-compatible run method."""
+
+    def run(self) -> None:
+        """Start the UI."""
+
+
+def load_app_class() -> type[RunnableApp]:
+    """Import the Textual app lazily so basic tests can run without UI deps."""
+    from coffee_cli.app import CoffeeApp
+
+    return CoffeeApp
+
+
+def main(app_factory: Callable[[], RunnableApp] | None = None) -> int:
+    """Launch Coffee CLI."""
+    factory = app_factory
+    if factory is None:
+        try:
+            factory = load_app_class()
+        except ModuleNotFoundError as exc:
+            if exc.name == "textual":
+                print(
+                    "Coffee CLI requires the 'textual' package. "
+                    "Install project dependencies with: python -m pip install -e '.[dev]'"
+                )
+                return 1
+            raise
+
+    app = factory()
+    app.run()
+    return 0
+

coffee_cli/home.py

@@ -0,0 +1,89 @@
+"""Home screen state and menu behavior."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MenuItem:
+    """A selectable item on the Coffee CLI home screen."""
+
+    label: str
+    detail: str
+    status: str
+
+
+@dataclass(frozen=True)
+class MenuSelection:
+    """Result of selecting a home menu item."""
+
+    item: MenuItem
+    should_exit: bool = False
+
+
+HOME_MENU_ITEMS = (
+    MenuItem(
+        "Order Coffee",
+        "Start a guided coffee order with drink, size, milk, and summary.",
+        "Opening the guided order flow.",
+    ),
+    MenuItem(
+        "Today's Special",
+        "Preview the daily recommendation and what makes it worth trying.",
+        "Daily specials are planned after ordering works.",
+    ),
+    MenuItem(
+        "My Favorites",
+        "Keep repeat orders close for fast access.",
+        "Favorites arrive once local storage is introduced.",
+    ),
+    MenuItem(
+        "Coffee Journal",
+        "Track what you brewed, what you liked, and what to improve.",
+        "Journal entries are planned for a later milestone.",
+    ),
+    MenuItem(
+        "Brewing Guide",
+        "Learn simple brew methods and ratios from inside the terminal.",
+        "Guides will expand after the first order flow.",
+    ),
+    MenuItem(
+        "Statistics",
+        "Review drink history, favorite styles, and usage patterns.",
+        "Stats need persisted order history first.",
+    ),
+    MenuItem(
+        "Settings",
+        "Tune themes, preferences, and future app behavior.",
+        "Settings are planned after the playable core is stable.",
+    ),
+    MenuItem(
+        "Exit",
+        "Close Coffee CLI and return to the shell.",
+        "Closing Coffee CLI.",
+    ),
+)
+
+
+def clamp_menu_index(index: int, item_count: int = len(HOME_MENU_ITEMS)) -> int:
+    """Wrap a menu index into the valid range."""
+    if item_count < 1:
+        raise ValueError("menu must contain at least one item")
+    return index % item_count
+
+
+def move_selection(current_index: int, step: int) -> int:
+    """Move the home menu selection by one or more positions."""
+    return clamp_menu_index(current_index + step)
+
+
+def get_menu_item(index: int) -> MenuItem:
+    """Return the menu item at a wrapped index."""
+    return HOME_MENU_ITEMS[clamp_menu_index(index)]
+
+
+def select_menu_item(index: int) -> MenuSelection:
+    """Return the selection result for the current menu item."""
+    item = get_menu_item(index)
+    return MenuSelection(item=item, should_exit=item.label == "Exit")

coffee_cli/order.py

@@ -0,0 +1,136 @@
+"""Coffee ordering state and pricing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Literal
+
+OrderStep = Literal["drink", "size", "milk", "confirm"]
+
+
+@dataclass(frozen=True)
+class OrderOption:
+    """A selectable option in the guided order flow."""
+
+    label: str
+    detail: str
+    price_delta: int = 0
+
+
+@dataclass(frozen=True)
+class OrderDraft:
+    """A partially completed coffee order."""
+
+    drink: OrderOption | None = None
+    size: OrderOption | None = None
+    milk: OrderOption | None = None
+
+
+DRINK_OPTIONS = (
+    OrderOption("Espresso", "Short, focused, and direct.", 350),
+    OrderOption("Latte", "Smooth espresso with steamed milk.", 450),
+    OrderOption("Cappuccino", "Balanced espresso, milk, and foam.", 425),
+    OrderOption("Mocha", "Espresso with chocolate and milk.", 500),
+    OrderOption("Americano", "Espresso stretched with hot water.", 375),
+)
+
+SIZE_OPTIONS = (
+    OrderOption("Small", "A quick cup for a short session.", 0),
+    OrderOption("Medium", "The default developer serving.", 75),
+    OrderOption("Large", "For long debugging sessions.", 125),
+)
+
+MILK_OPTIONS = (
+    OrderOption("Whole", "Classic dairy texture.", 0),
+    OrderOption("Oat", "Creamy non-dairy option.", 65),
+    OrderOption("Almond", "Nutty and light.", 55),
+    OrderOption("Soy", "Soft, steady, and familiar.", 45),
+    OrderOption("None", "Keep the drink black.", 0),
+)
+
+CONFIRM_OPTIONS = (
+    OrderOption("Confirm Order", "Finish this order and show the total."),
+    OrderOption("Start Over", "Clear the current order and choose again."),
+    OrderOption("Cancel", "Return to the home screen."),
+)
+
+ORDER_STEP_TITLES: dict[OrderStep, str] = {
+    "drink": "Choose Coffee",
+    "size": "Choose Size",
+    "milk": "Choose Milk",
+    "confirm": "Review Order",
+}
+
+
+def format_price(cents: int) -> str:
+    """Format cents as a simple dollar amount."""
+    dollars, cents_remainder = divmod(cents, 100)
+    return f"${dollars}.{cents_remainder:02d}"
+
+
+def calculate_total(draft: OrderDraft) -> int:
+    """Calculate the current order total in cents."""
+    return sum(
+        option.price_delta
+        for option in (draft.drink, draft.size, draft.milk)
+        if option is not None
+    )
+
+
+def get_order_options(step: OrderStep) -> tuple[OrderOption, ...]:
+    """Return selectable options for the current order step."""
+    match step:
+        case "drink":
+            return DRINK_OPTIONS
+        case "size":
+            return SIZE_OPTIONS
+        case "milk":
+            return MILK_OPTIONS
+        case "confirm":
+            return CONFIRM_OPTIONS
+
+
+def move_order_selection(current_index: int, step: int, option_count: int) -> int:
+    """Move through the current order step options."""
+    if option_count < 1:
+        raise ValueError("order step must contain at least one option")
+    return (current_index + step) % option_count
+
+
+def apply_order_choice(draft: OrderDraft, step: OrderStep, option_index: int) -> OrderDraft:
+    """Apply the selected option to the draft order."""
+    option = get_order_options(step)[option_index]
+    match step:
+        case "drink":
+            return replace(draft, drink=option)
+        case "size":
+            return replace(draft, size=option)
+        case "milk":
+            return replace(draft, milk=option)
+        case "confirm":
+            return draft
+
+
+def next_order_step(step: OrderStep) -> OrderStep:
+    """Advance the guided order flow."""
+    match step:
+        case "drink":
+            return "size"
+        case "size":
+            return "milk"
+        case "milk" | "confirm":
+            return "confirm"
+
+
+def previous_order_step(step: OrderStep) -> OrderStep | None:
+    """Move backward through the guided order flow."""
+    match step:
+        case "drink":
+            return None
+        case "size":
+            return "drink"
+        case "milk":
+            return "size"
+        case "confirm":
+            return "milk"
+

coffee_cli/personal.py

@@ -0,0 +1,166 @@
+"""Personal coffee data stored on disk."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from coffee_cli.order import OrderDraft, calculate_total
+
+APP_DIR_NAME = "coffee-for-devs"
+DATA_FILE_NAME = "personal.json"
+
+
+@dataclass(frozen=True)
+class SavedDrink:
+    """A favorite drink saved from an order."""
+
+    drink: str
+    size: str
+    milk: str
+    total: int
+
+
+@dataclass(frozen=True)
+class JournalEntry:
+    """A small journal entry created after an order."""
+
+    title: str
+    note: str
+
+
+@dataclass(frozen=True)
+class PersonalData:
+    """Local personal data for Coffee CLI."""
+
+    favorites: tuple[SavedDrink, ...] = ()
+    journal: tuple[JournalEntry, ...] = ()
+    order_history: tuple[SavedDrink, ...] = ()
+
+
+def default_data_path() -> Path:
+    """Return the default local data file path."""
+    base_dir = os.environ.get("XDG_DATA_HOME")
+    if base_dir:
+        return Path(base_dir) / APP_DIR_NAME / DATA_FILE_NAME
+    return Path.home() / ".local" / "share" / APP_DIR_NAME / DATA_FILE_NAME
+
+
+def draft_to_saved_drink(draft: OrderDraft) -> SavedDrink:
+    """Convert a completed order draft into persisted drink data."""
+    return SavedDrink(
+        drink=draft.drink.label if draft.drink else "Coffee",
+        size=draft.size.label if draft.size else "Standard",
+        milk=draft.milk.label if draft.milk else "None",
+        total=calculate_total(draft),
+    )
+
+
+def add_favorite(data: PersonalData, drink: SavedDrink) -> PersonalData:
+    """Add a favorite drink if it is not already saved."""
+    if drink in data.favorites:
+        return data
+    return PersonalData(
+        favorites=(*data.favorites, drink),
+        journal=data.journal,
+        order_history=data.order_history,
+    )
+
+
+def add_order_history(data: PersonalData, drink: SavedDrink) -> PersonalData:
+    """Add a completed drink to order history."""
+    return PersonalData(
+        favorites=data.favorites,
+        journal=data.journal,
+        order_history=(*data.order_history, drink),
+    )
+
+
+def add_journal_entry(data: PersonalData, entry: JournalEntry) -> PersonalData:
+    """Add a journal entry."""
+    return PersonalData(
+        favorites=data.favorites,
+        journal=(*data.journal, entry),
+        order_history=data.order_history,
+    )
+
+
+def make_journal_entry(drink: SavedDrink) -> JournalEntry:
+    """Create a simple automatic journal entry for a completed order."""
+    return JournalEntry(
+        title=f"{drink.size} {drink.drink}",
+        note=f"Ordered with {drink.milk} milk for {format_cents(drink.total)}.",
+    )
+
+
+def favorite_labels(data: PersonalData) -> tuple[str, ...]:
+    """Return display labels for saved favorites."""
+    return tuple(
+        f"{drink.size} {drink.drink} with {drink.milk} ({format_cents(drink.total)})"
+        for drink in data.favorites
+    )
+
+
+def journal_labels(data: PersonalData) -> tuple[str, ...]:
+    """Return display labels for journal entries."""
+    return tuple(f"{entry.title}: {entry.note}" for entry in data.journal)
+
+
+def stats_summary(data: PersonalData) -> dict[str, int | str]:
+    """Return simple statistics for personal coffee data."""
+    total_orders = len(data.order_history)
+    total_spent = sum(drink.total for drink in data.order_history)
+    favorite_count = len(data.favorites)
+    most_recent = data.order_history[-1].drink if data.order_history else "None"
+    return {
+        "total_orders": total_orders,
+        "total_spent": total_spent,
+        "favorite_count": favorite_count,
+        "most_recent": most_recent,
+    }
+
+
+def load_personal_data(path: Path | None = None) -> PersonalData:
+    """Load personal data from disk."""
+    data_path = path or default_data_path()
+    if not data_path.exists():
+        return PersonalData()
+
+    with data_path.open("r", encoding="utf-8") as file:
+        payload = json.load(file)
+    return personal_data_from_dict(payload)
+
+
+def save_personal_data(data: PersonalData, path: Path | None = None) -> None:
+    """Save personal data to disk."""
+    data_path = path or default_data_path()
+    data_path.parent.mkdir(parents=True, exist_ok=True)
+    with data_path.open("w", encoding="utf-8") as file:
+        json.dump(personal_data_to_dict(data), file, indent=2)
+
+
+def personal_data_to_dict(data: PersonalData) -> dict[str, list[dict[str, Any]]]:
+    """Convert personal data into JSON-safe structures."""
+    return {
+        "favorites": [asdict(drink) for drink in data.favorites],
+        "journal": [asdict(entry) for entry in data.journal],
+        "order_history": [asdict(drink) for drink in data.order_history],
+    }
+
+
+def personal_data_from_dict(payload: dict[str, Any]) -> PersonalData:
+    """Create personal data from JSON-loaded structures."""
+    return PersonalData(
+        favorites=tuple(SavedDrink(**item) for item in payload.get("favorites", [])),
+        journal=tuple(JournalEntry(**item) for item in payload.get("journal", [])),
+        order_history=tuple(SavedDrink(**item) for item in payload.get("order_history", [])),
+    )
+
+
+def format_cents(cents: int) -> str:
+    """Format cents as a simple dollar amount."""
+    dollars, cents_remainder = divmod(cents, 100)
+    return f"${dollars}.{cents_remainder:02d}"

coffee_cli/ui_text.py

@@ -0,0 +1,215 @@
+"""Pure text rendering helpers for the Coffee CLI UI."""
+
+from __future__ import annotations
+
+from coffee_cli.brewing import BrewStage, render_progress_bar
+from coffee_cli.home import HOME_MENU_ITEMS, MenuItem
+from coffee_cli.order import (
+    ORDER_STEP_TITLES,
+    OrderDraft,
+    OrderOption,
+    OrderStep,
+    calculate_total,
+    format_price,
+)
+from coffee_cli.personal import PersonalData, favorite_labels, journal_labels, stats_summary
+
+STEAM_FRAMES = (
+    "\n".join(
+        (
+            "                         *",
+            "                         %",
+            "                        %#",
+            "                      %###   #",
+            "                    %####   %#",
+        )
+    ),
+    "\n".join(
+        (
+            "                         %",
+            "                        %#",
+            "                      %###   #",
+            "                   %#####  %#%",
+            "                    ####  ###",
+        )
+    ),
+    "\n".join(
+        (
+            "                         *",
+            "                        %#",
+            "                     %####   #",
+            "                   #####   %#%",
+            "                      #%%",
+        )
+    ),
+)
+
+
+def render_hero(steam_frame: str) -> str:
+    """Render the opening banner."""
+    return (
+        "╔════════════════════════════════════════════════╗\n"
+        "║                COFFEE FOR DEVS                ║\n"
+        "╚════════════════════════════════════════════════╝\n\n"
+        f"{steam_frame}\n"
+        "        ####################################\n"
+        "        ####################################%\n"
+        "  ################################################\n"
+        " ######    #######################################\n"
+        " ####%     ######################################\n"
+        " ####      ######################################\n"
+        " #####      #####################################\n"
+        " ######     *###################################%\n"
+        "  #######    ###################################\n"
+        "    ########% ###############################%\n"
+        "       #####################################\n"
+        "          #%%############################\n"
+        "              #########################\n"
+        "                #####################%\n"
+        "                   %###############%\n\n"
+        "          (@)   (@)     (@)   (@)\n"
+        "          coffee beans for focused work\n\n"
+        "          Brew Better. Code Better."
+    )
+
+
+def render_menu(items: tuple[MenuItem, ...], selected_index: int) -> str:
+    """Render the home menu with a single active item."""
+    lines = ["Home", ""]
+    for index, item in enumerate(items):
+        prefix = "►" if index == selected_index else " "
+        lines.append(f"{prefix} {item.label}")
+    lines.extend(("", "↑/k Up   ↓/j Down   Enter Select   q Quit"))
+    return "\n".join(lines)
+
+
+def render_summary(selected_item: MenuItem, message: str) -> str:
+    """Render the right-hand summary panel."""
+    return (
+        "Selected\n"
+        f"{selected_item.label}\n\n"
+        "What this does\n"
+        f"{selected_item.detail}\n\n"
+        "Sprint focus\n"
+        "Playable home screen with visible navigation.\n\n"
+        f"Status: {message}"
+    )
+
+
+def render_personal_panel(title: str, lines: tuple[str, ...], empty_message: str) -> str:
+    """Render a personal tools panel."""
+    body = lines if lines else (empty_message,)
+    return "\n".join((title, "", *body, "", "Esc Back   q Quit"))
+
+
+def render_personal_summary(data: PersonalData, message: str) -> str:
+    """Render a summary for personal coffee data."""
+    stats = stats_summary(data)
+    return (
+        "Personal Coffee\n\n"
+        f"Favorites: {stats['favorite_count']}\n"
+        f"Orders:    {stats['total_orders']}\n"
+        f"Spent:     {format_price(int(stats['total_spent']))}\n"
+        f"Recent:    {stats['most_recent']}\n\n"
+        f"Status: {message}"
+    )
+
+
+def render_favorites_panel(data: PersonalData) -> str:
+    """Render saved favorite drinks."""
+    return render_personal_panel(
+        "My Favorites",
+        favorite_labels(data),
+        "No favorites saved yet. Confirm an order to save one.",
+    )
+
+
+def render_journal_panel(data: PersonalData) -> str:
+    """Render coffee journal entries."""
+    return render_personal_panel(
+        "Coffee Journal",
+        journal_labels(data),
+        "No journal entries yet. Completed orders create entries.",
+    )
+
+
+def render_statistics_panel(data: PersonalData) -> str:
+    """Render simple statistics."""
+    stats = stats_summary(data)
+    lines = (
+        f"Total orders: {stats['total_orders']}",
+        f"Total spent:  {format_price(int(stats['total_spent']))}",
+        f"Favorites:    {stats['favorite_count']}",
+        f"Most recent:  {stats['most_recent']}",
+    )
+    return render_personal_panel("Statistics", lines, "No statistics yet.")
+
+
+def render_home_screen(steam_frame: str, selected_index: int, message: str) -> str:
+    """Render the complete home screen as plain text for tests and snapshots."""
+    selected_item = HOME_MENU_ITEMS[selected_index]
+    return "\n\n".join(
+        (
+            render_hero(steam_frame),
+            render_menu(HOME_MENU_ITEMS, selected_index),
+            render_summary(selected_item, message),
+        )
+    )
+
+
+def render_order_menu(
+    step: OrderStep,
+    options: tuple[OrderOption, ...],
+    selected_index: int,
+) -> str:
+    """Render the current order step options."""
+    lines = [f"Order > {ORDER_STEP_TITLES[step]}", ""]
+    for index, option in enumerate(options):
+        prefix = "►" if index == selected_index else " "
+        price = f"  {format_price(option.price_delta)}" if option.price_delta else ""
+        lines.append(f"{prefix} {option.label}{price}")
+        lines.append(f"  {option.detail}")
+    lines.extend(("", "↑/k Up   ↓/j Down   Enter Select   Esc Back   q Quit"))
+    return "\n".join(lines)
+
+
+def render_order_summary(draft: OrderDraft, message: str) -> str:
+    """Render the live order summary."""
+    drink = draft.drink.label if draft.drink else "Not selected"
+    size = draft.size.label if draft.size else "Not selected"
+    milk = draft.milk.label if draft.milk else "Not selected"
+    return (
+        "Order Summary\n\n"
+        f"Coffee: {drink}\n"
+        f"Size:   {size}\n"
+        f"Milk:   {milk}\n\n"
+        f"Total:  {format_price(calculate_total(draft))}\n\n"
+        f"Status: {message}"
+    )
+
+
+def render_brewing_panel(stage: BrewStage, is_complete: bool) -> str:
+    """Render the brewing animation panel."""
+    footer = "Enter Return Home   q Quit" if is_complete else "Brewing in progress..."
+    return (
+        "Brewing\n\n"
+        f"{stage.label}...\n"
+        f"{render_progress_bar(stage.progress)}\n\n"
+        f"{stage.detail}\n\n"
+        f"{footer}"
+    )
+
+
+def render_brewing_summary(draft: OrderDraft, stage: BrewStage) -> str:
+    """Render order details while brewing."""
+    drink = draft.drink.label if draft.drink else "Coffee"
+    size = draft.size.label if draft.size else "Standard"
+    milk = draft.milk.label if draft.milk else "None"
+    return (
+        "Final Order\n\n"
+        f"{size} {drink}\n"
+        f"Milk: {milk}\n"
+        f"Total: {format_price(calculate_total(draft))}\n\n"
+        f"Now: {stage.label}\n\n"
+        "Milestone 3 turns confirmation into a visible brewing moment."
+    )

coffee_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: coffee-cli
+Version: 0.1.0
+Summary: A polished Python terminal UI for coffee-themed developer workflows.
+Project-URL: Homepage, https://github.com/josephforson285/coffee-for-devs
+Project-URL: Issues, https://github.com/josephforson285/coffee-for-devs/issues
+Author: Coffee CLI Contributors
+License: MIT
+Keywords: cli,coffee,terminal,textual,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.12
+Requires-Dist: textual<1.0,>=0.68
+Provides-Extra: dev
+Requires-Dist: anyio>=4.4; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Coffee CLI
+
+Coffee CLI is a Python terminal UI application for developers who want a polished, installable `coffee` command with personality. The app is built as a modern Python package and is intended to grow into a showcase project for terminal UX, testing, CI/CD, and professional packaging.
+
+## Project goals
+
+- Launch with `coffee` after installation.
+- Use `Textual` for a polished TUI.
+- Keep the codebase educational and production-leaning.
+- Validate every change with tests, linting, and CI.
+
+## Local environment
+
+This project is being developed inside:
+
+- project root: `/home/redsteam/Desktop/bear/ML/coffee-for-devs`
+- virtual environment: `/home/redsteam/Desktop/bear/ML/MLprojs`
+
+Activate the environment:
+
+```bash
+source /home/redsteam/Desktop/bear/ML/MLprojs/bin/activate
+```
+
+## First-time setup
+
+Install the project and developer tools into the virtual environment:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Run the quality checks:
+
+```bash
+ruff check .
+pytest
+python -m build
+```
+
+Start the app:
+
+```bash
+coffee
+```
+
+## Install from a wheel
+
+Build the package:
+
+```bash
+python -m build
+```
+
+Install the generated wheel into a fresh environment:
+
+```bash
+python -m pip install dist/coffee_cli-0.1.0-py3-none-any.whl
+coffee
+```
+
+This is the local release-candidate check before publishing to PyPI.
+
+## Release publishing
+
+Publishing is handled by the manual GitHub Actions workflow in `.github/workflows/publish.yml`.
+Use `target=testpypi` first, verify the package, then publish to PyPI from a version tag such as
+`v0.1.0`.
+
+## Current scope
+
+Coffee CLI currently includes:
+
+- modern `pyproject.toml` packaging
+- `src/` layout
+- `coffee` console script entry point
+- first Textual app skeleton with animated ASCII steam
+- order flow, brewing flow, personal favorites, journal, and statistics
+- tested package structure
+- GitHub Actions CI workflow
+
+See [docs/roadmap.md](docs/roadmap.md) for the planned sprint breakdown, [docs/milestones.md](docs/milestones.md) for runnable milestones, [docs/release-checklist.md](docs/release-checklist.md) for release steps, and [CONTRIBUTING.md](CONTRIBUTING.md) for the Git workflow.

coffee_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+coffee_cli/__init__.py,sha256=7tcb4C1Zo7GNcknR5YW1JtKdmwQPk_YH1h0gbmgoz4A,77
+coffee_cli/__main__.py,sha256=Ym6aA8IYkC_fshum4ZmaneNPIOj7emPtcD4HTtPGCFE,143
+coffee_cli/app.py,sha256=Ce0UlOQAklZ1mdhNZaXsfX9PMMKaKuaofMO0AHwQfKg,11413
+coffee_cli/brewing.py,sha256=9_zUzl1YBgYddeyGmgVmZibhlJyyCrPS5lfc3xRJR3o,1452
+coffee_cli/cli.py,sha256=OpIqw6iaMQjx-7Co-m4WbQH88QxAwQIFyhjsXeiZO84,1060
+coffee_cli/home.py,sha256=jKaHpjnxcWJeoJC8PMn_-ZBzgBFDypF-a87zwS79f5A,2547
+coffee_cli/order.py,sha256=ujhxMXcGDhtiytrIo0EViVrU5YTWZkZV7KcQ0zIpsvc,3984
+coffee_cli/personal.py,sha256=OLK4cfvOAPgqmd2eBJiz9Y7vsvSaBUE_1dGsWdrcA1s,5293
+coffee_cli/ui_text.py,sha256=v_QH9pjW1L1ZJrPCOr4epkpP4PcC9l-bXc83_3OGJ4s,7718
+coffee_cli-0.1.0.dist-info/METADATA,sha256=Cv0Q9u6ZXqoBNUwGnHksddK8IuKjaDeV5Ccp4ULvAXg,3152
+coffee_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+coffee_cli-0.1.0.dist-info/entry_points.txt,sha256=no4mEcbp7mbPtKxKPlpe4Cj3r-uZwe1C3kfy_jZIXF8,47
+coffee_cli-0.1.0.dist-info/RECORD,,

coffee_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

coffee_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+coffee = coffee_cli.cli:main