milo-cli 0.1.0__py3-none-any.whl

milo/_types.py

@@ -0,0 +1,234 @@
+"""Frozen dataclasses, enums, and type aliases — no internal imports."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Keys
+# ---------------------------------------------------------------------------
+
+
+class SpecialKey(Enum):
+    ENTER = auto()
+    TAB = auto()
+    BACKSPACE = auto()
+    DELETE = auto()
+    ESCAPE = auto()
+    UP = auto()
+    DOWN = auto()
+    LEFT = auto()
+    RIGHT = auto()
+    HOME = auto()
+    END = auto()
+    PAGE_UP = auto()
+    PAGE_DOWN = auto()
+    INSERT = auto()
+    F1 = auto()
+    F2 = auto()
+    F3 = auto()
+    F4 = auto()
+    F5 = auto()
+    F6 = auto()
+    F7 = auto()
+    F8 = auto()
+    F9 = auto()
+    F10 = auto()
+    F11 = auto()
+    F12 = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Key:
+    """Single keypress."""
+
+    char: str = ""
+    name: SpecialKey | None = None
+    ctrl: bool = False
+    alt: bool = False
+    shift: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Actions
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Action:
+    """Event dispatched to a reducer."""
+
+    type: str
+    payload: Any = None
+
+
+BUILTIN_ACTIONS: frozenset[str] = frozenset(
+    {
+        "@@INIT",
+        "@@KEY",
+        "@@TICK",
+        "@@RESIZE",
+        "@@EFFECT_RESULT",
+        "@@QUIT",
+        "@@NAVIGATE",
+        "@@HOT_RELOAD",
+        "@@PIPELINE_START",
+        "@@PIPELINE_COMPLETE",
+        "@@PHASE_START",
+        "@@PHASE_COMPLETE",
+        "@@PHASE_FAILED",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# App
+# ---------------------------------------------------------------------------
+
+
+class AppStatus(Enum):
+    IDLE = auto()
+    RUNNING = auto()
+    PAUSED = auto()
+    STOPPED = auto()
+
+
+class RenderTarget(Enum):
+    TERMINAL = auto()
+    HTML = auto()
+
+
+# ---------------------------------------------------------------------------
+# Screens / Flows
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Screen:
+    """Named screen config: template name + reducer reference."""
+
+    name: str
+    template: str
+    reducer: Callable  # Reducer protocol
+
+
+@dataclass(frozen=True, slots=True)
+class Transition:
+    """Flow edge between screens."""
+
+    from_screen: str
+    to_screen: str
+    on_action: str
+
+
+# ---------------------------------------------------------------------------
+# Fields / Forms
+# ---------------------------------------------------------------------------
+
+
+class FieldType(Enum):
+    TEXT = auto()
+    SELECT = auto()
+    CONFIRM = auto()
+    PASSWORD = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class FieldSpec:
+    """Declarative field configuration."""
+
+    name: str
+    label: str
+    field_type: FieldType = FieldType.TEXT
+    choices: tuple[str, ...] = ()
+    default: Any = None
+    validator: Callable | None = None
+    placeholder: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class FieldState:
+    """Runtime state for a single field."""
+
+    value: Any = ""
+    cursor: int = 0
+    error: str = ""
+    focused: bool = False
+    selected_index: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class FormState:
+    """Full form state."""
+
+    fields: tuple[FieldState, ...] = ()
+    specs: tuple[FieldSpec, ...] = ()
+    active_index: int = 0
+    submitted: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Effects (sagas)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Call:
+    """Call a function, resume saga with its return value."""
+
+    fn: Callable
+    args: tuple = ()
+    kwargs: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Put:
+    """Dispatch an action back to the store."""
+
+    action: Action
+
+
+@dataclass(frozen=True, slots=True)
+class Select:
+    """Read current state, resume saga with it."""
+
+    selector: Callable | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Fork:
+    """Run another saga concurrently."""
+
+    saga: Callable | Generator
+
+
+@dataclass(frozen=True, slots=True)
+class Delay:
+    """Sleep for N seconds."""
+
+    seconds: float
+
+
+# ---------------------------------------------------------------------------
+# Reducer result (state + optional sagas)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ReducerResult:
+    """Reducer can return this to trigger side effects."""
+
+    state: Any
+    sagas: tuple[Callable, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class Quit:
+    """Signal the app to exit. Return from a reducer to stop the event loop."""
+
+    state: Any
+    code: int = 0
+    sagas: tuple[Callable, ...] = ()

milo/app.py

@@ -0,0 +1,353 @@
+"""App event loop and terminal rendering."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+import signal
+import sys
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from milo._errors import AppError, ErrorCode, format_render_error
+from milo._types import Action, AppStatus, RenderTarget
+from milo.flow import Flow, FlowState
+from milo.input._platform import is_tty
+from milo.input._reader import KeyReader
+from milo.state import Store
+
+
+class _TerminalRenderer:
+    """In-place terminal renderer using alternate screen buffer.
+
+    Uses cursor-home redraws with line clearing to avoid flicker
+    and prevent frame stacking.
+    """
+
+    def __init__(self) -> None:
+        self._prev_lines = 0
+        self._started = False
+
+    def start(self) -> None:
+        """Enter alternate screen buffer and hide cursor."""
+        sys.stdout.write("\033[?1049h")  # Enter alternate screen
+        sys.stdout.write("\033[?25l")  # Hide cursor
+        sys.stdout.flush()
+        self._started = True
+
+    def update(self, output: str) -> None:
+        """Redraw the screen with new output."""
+        if not self._started:
+            return
+        cols = shutil.get_terminal_size().columns
+        lines = output.split("\n")
+
+        # Move cursor to home position
+        sys.stdout.write("\033[H")
+
+        # Write each line, clearing to end of line
+        for line in lines:
+            # Truncate to terminal width to avoid wrapping artifacts
+            sys.stdout.write(line[:cols])
+            sys.stdout.write("\033[K\n")  # Clear to end of line
+
+        # Clear any leftover lines from previous frame
+        if self._prev_lines > len(lines):
+            for _ in range(self._prev_lines - len(lines)):
+                sys.stdout.write("\033[K\n")
+
+        self._prev_lines = len(lines)
+        sys.stdout.flush()
+
+    def stop(self) -> None:
+        """Show cursor and leave alternate screen buffer."""
+        if not self._started:
+            return
+        self._started = False
+        sys.stdout.write("\033[?25h")  # Show cursor
+        sys.stdout.write("\033[?1049l")  # Leave alternate screen
+        sys.stdout.flush()
+
+
+class App:
+    """Main application event loop.
+
+    Integrates the Store, KeyReader, and kida LiveRenderer
+    into a unified event loop.
+    """
+
+    def __init__(
+        self,
+        *,
+        template: str | Any = "",
+        reducer: Callable | None = None,
+        initial_state: Any = None,
+        middleware: tuple[Callable, ...] = (),
+        tick_rate: float = 0.0,
+        transient: bool = False,
+        target: RenderTarget = RenderTarget.TERMINAL,
+        record: bool | str | Path = False,
+        env: Any = None,
+        flow: Flow | None = None,
+        exit_template: str = "",
+    ) -> None:
+        self._target = target
+        self._tick_rate = tick_rate
+        self._transient = transient
+        self._env = env
+        self._flow = flow
+        self._template_name = template
+        self._exit_template = exit_template
+        self._status = AppStatus.IDLE
+        self._stop = threading.Event()
+
+        # Flow mode: build reducer from flow
+        if flow is not None:
+            self._reducer = flow.build_reducer()
+            self._initial_state = None
+            self._template_map = flow.template_map
+        else:
+            if reducer is None:
+                raise AppError(ErrorCode.APP_LIFECYCLE, "Either reducer or flow is required")
+            self._reducer = reducer
+            self._initial_state = initial_state
+            self._template_map = None
+
+        self._middleware = middleware
+        self._record = record
+
+    @classmethod
+    def from_flow(cls, flow: Flow, **kwargs: Any) -> App:
+        """Create App from a declarative Flow."""
+        return cls(flow=flow, **kwargs)
+
+    @classmethod
+    def render(cls, template: str, state: Any = None, *, env: Any = None) -> str:
+        """One-shot render of a template with state. Returns the rendered string."""
+        if env is None:
+            from milo.templates import get_env
+
+            env = get_env()
+        tmpl = env.get_template(template)
+        return tmpl.render(state=state)
+
+    def run(self) -> Any:
+        """Run the event loop. Returns final state."""
+        store = Store(
+            self._reducer,
+            self._initial_state,
+            self._middleware,
+            record=self._record,
+        )
+
+        if self._target == RenderTarget.HTML or not is_tty():
+            # Single render pass, no input
+            self._render_once(store.state)
+            if self._exit_template:
+                env = self._get_env()
+                try:
+                    self._render_exit(store.state, env)
+                except Exception as e:
+                    msg = format_render_error(e, template_name=self._exit_template, env=env)
+                    sys.stderr.write(f"[milo] {msg}\n")
+            return store.state
+
+        self._status = AppStatus.RUNNING
+        self._stop.clear()
+
+        # Set up signal handler for resize
+        original_sigwinch = None
+        if hasattr(signal, "SIGWINCH"):
+
+            def _on_resize(signum: int, frame: Any) -> None:
+                try:
+                    cols, rows = os.get_terminal_size()
+                    store.dispatch(Action("@@RESIZE", payload=(cols, rows)))
+                except OSError:
+                    pass
+
+            original_sigwinch = signal.getsignal(signal.SIGWINCH)
+            signal.signal(signal.SIGWINCH, _on_resize)
+
+        # Set up tick timer
+        tick_thread = None
+        if self._tick_rate > 0:
+            stop_tick = threading.Event()
+
+            def _tick_loop() -> None:
+                while not stop_tick.is_set():
+                    stop_tick.wait(self._tick_rate)
+                    if not stop_tick.is_set() and not self._stop.is_set():
+                        store.dispatch(Action("@@TICK"))
+
+            tick_thread = threading.Thread(target=_tick_loop, daemon=True)
+            tick_thread.start()
+
+        env = self._get_env()
+        renderer = _TerminalRenderer()
+        quit_dispatched = False
+
+        try:
+            renderer.start()
+
+            # Subscribe to state changes for re-rendering
+            def _on_state_change() -> None:
+                self._render_state(store.state, env, renderer)
+
+            unsubscribe = store.subscribe(_on_state_change)
+
+            # Initial render
+            self._render_state(store.state, env, renderer)
+
+            # Input loop
+            with KeyReader() as keys:
+                for key in keys:
+                    if self._stop.is_set() or store.quit_requested:
+                        break
+
+                    # Ctrl+C: first dispatches @@QUIT, second force-exits
+                    if key.ctrl and key.char == "c":
+                        if quit_dispatched:
+                            break
+                        quit_dispatched = True
+                        store.dispatch(Action("@@QUIT"))
+                        if store.quit_requested:
+                            break
+                        continue
+
+                    store.dispatch(Action("@@KEY", payload=key))
+
+                    if store.quit_requested:
+                        break
+
+            self._status = AppStatus.STOPPED
+            self._stop.set()
+            unsubscribe()
+
+        finally:
+            if tick_thread is not None:
+                stop_tick.set()
+            with contextlib.suppress(Exception):
+                renderer.stop()
+            if original_sigwinch is not None:
+                signal.signal(signal.SIGWINCH, original_sigwinch)
+            store.shutdown()
+
+        final_state = store.state
+
+        # Render exit template if provided
+        if self._exit_template:
+            try:
+                self._render_exit(final_state, env)
+            except Exception as e:
+                msg = format_render_error(e, template_name=self._exit_template, env=env)
+                sys.stderr.write(f"[milo] {msg}\n")
+
+        return final_state
+
+    def _get_env(self) -> Any:
+        """Get or create the kida Environment."""
+        if self._env is not None:
+            return self._env
+        from milo.templates import get_env
+
+        return get_env()
+
+    def _get_template_name(self, state: Any) -> str:
+        """Get the template name for the current state."""
+        if self._template_map and isinstance(state, FlowState):
+            return self._template_map.get(state.current_screen, self._template_name)
+        return self._template_name
+
+    def _render_state(self, state: Any, env: Any, renderer: _TerminalRenderer) -> None:
+        """Render current state through the template."""
+        try:
+            template_name = self._get_template_name(state)
+            template = env.get_template(template_name)
+
+            # For flow state, pass the current screen's state
+            render_state = state
+            if isinstance(state, FlowState):
+                render_state = state.screen_states.get(state.current_screen, state)
+
+            output = template.render(state=render_state)
+            renderer.update(output)
+        except Exception as e:
+            template_name = self._get_template_name(state)
+            msg = format_render_error(e, template_name=template_name, env=env)
+            sys.stderr.write(f"[milo] {msg}\n")
+
+    def _render_exit(self, state: Any, env: Any) -> None:
+        """Render the exit template once to stdout."""
+        template = env.get_template(self._exit_template)
+        render_state = state
+        if isinstance(state, FlowState):
+            # For flows, pass all screen states so exit template can reference any data
+            render_state = state.screen_states
+        output = template.render(state=render_state)
+        sys.stdout.write(output + "\n")
+        sys.stdout.flush()
+
+    def _render_once(self, state: Any) -> None:
+        """Single render pass (non-TTY or HTML mode)."""
+        try:
+            env = self._get_env()
+            template_name = self._get_template_name(state)
+            template = env.get_template(template_name)
+
+            render_state = state
+            if isinstance(state, FlowState):
+                render_state = state.screen_states.get(state.current_screen, state)
+
+            output = template.render(state=render_state)
+            sys.stdout.write(output + "\n")
+            sys.stdout.flush()
+        except Exception as e:
+            template_name = self._get_template_name(state)
+            msg = format_render_error(e, template_name=template_name)
+            sys.stderr.write(f"[milo] {msg}\n")
+
+
+def run(*, template: str, reducer: Callable, initial_state: Any, **kwargs: Any) -> Any:
+    """Shorthand: App(...).run()"""
+    return App(template=template, reducer=reducer, initial_state=initial_state, **kwargs).run()
+
+
+def render_html(
+    state: Any,
+    template: str | Any,
+    *,
+    title: str = "",
+    css: str = "",
+    env: Any = None,
+) -> str:
+    """One-shot HTML render of state through template."""
+    if env is None:
+        from milo.templates import get_env
+
+        env = get_env(autoescape=True)
+
+    tmpl = env.get_template(template) if isinstance(template, str) else template
+
+    body = tmpl.render(state=state)
+
+    default_css = """
+body { background: #1e1e1e; color: #d4d4d4; font-family: monospace; padding: 2em; }
+.dim { opacity: 0.6; }
+strong { font-weight: bold; }
+"""
+
+    return f"""<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>{title}</title>
+<style>{css or default_css}</style>
+</head>
+<body>
+<pre>{body}</pre>
+</body>
+</html>"""