@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing_scripts/bikerack/cli.py

@@ -9,9 +9,7 @@ Commands:
     status  Show running state
 """
 
-import os
 import sys
-from pathlib import Path
 
 import click
 
@@ -38,7 +36,8 @@ def bikerack(ctx):
     default=None,
     help="Project directory (where .pennyfarthing/ lives). Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
 )
-def start(project_dir):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def start(project_dir, dry_run):
     """Start BikeRack mode.
 
     Starts WheelHub in background, waits for readiness,
@@ -50,16 +49,18 @@ def start(project_dir):
         is_already_running,
         poll_for_port_file,
         register_cleanup,
+        resolve_project_dir,
         start_wheelhub,
         write_pid_file,
     )
 
-    if project_dir:
-        project_dir = Path(project_dir)
-    elif os.environ.get("CYCLIST_PROJECT_DIR"):
-        project_dir = Path(os.environ["CYCLIST_PROJECT_DIR"])
-    else:
-        project_dir = Path.cwd()
+    project_dir = resolve_project_dir(project_dir)
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would start BikeRack mode")
+        click.echo(f"  Project: {project_dir}")
+        click.echo("  Actions: start WheelHub, set OTEL env, exec Claude CLI")
+        return
 
     running, pid, port = is_already_running(project_dir)
     if running:
@@ -101,16 +102,18 @@ def start(project_dir):
     default=None,
     help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
 )
-def stop(project_dir):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def stop(project_dir, dry_run):
     """Stop running BikeRack instance."""
-    from pennyfarthing_scripts.bikerack.launcher import stop_bikerack
+    from pennyfarthing_scripts.bikerack.launcher import resolve_project_dir, stop_bikerack
+
+    project_dir = resolve_project_dir(project_dir)
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would stop BikeRack instance")
+        click.echo(f"  Project: {project_dir}")
+        return
 
-    if project_dir:
-        project_dir = Path(project_dir)
-    elif os.environ.get("CYCLIST_PROJECT_DIR"):
-        project_dir = Path(os.environ["CYCLIST_PROJECT_DIR"])
-    else:
-        project_dir = Path.cwd()
     result = stop_bikerack(project_dir)
 
     if result["success"]:
@@ -129,14 +132,9 @@ def stop(project_dir):
 )
 def status(project_dir):
     """Show BikeRack running state."""
-    from pennyfarthing_scripts.bikerack.launcher import get_status
+    from pennyfarthing_scripts.bikerack.launcher import get_status, resolve_project_dir
 
-    if project_dir:
-        project_dir = Path(project_dir)
-    elif os.environ.get("CYCLIST_PROJECT_DIR"):
-        project_dir = Path(os.environ["CYCLIST_PROJECT_DIR"])
-    else:
-        project_dir = Path.cwd()
+    project_dir = resolve_project_dir(project_dir)
     result = get_status(project_dir)
 
     if result["running"]:

package/pennyfarthing_scripts/bikerack/diffs_panel.py

@@ -0,0 +1,146 @@
+"""DiffsPanel — Rich diff rendering with syntax highlighting for BikeRack TUI.
+
+Story 103-18: Subscribes to /ws/diffs, renders file diffs with syntax
+highlighting using Rich. File headers, added/removed line coloring, line numbers.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+from rich.console import Group
+from rich.syntax import Syntax
+from rich.text import Text
+
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+
+
+class DiffsPanel(BasePanel):
+    """Diff rendering panel with syntax highlighting.
+
+    Subscribes to the ``diffs`` WebSocket channel and renders
+    file diffs with syntax highlighting, colored added/removed lines,
+    file headers, and line numbers.
+    """
+
+    channel: str = "diffs"
+    panel_name: str = "Diffs"
+    icon: str = PANEL_ICONS["diffs"][0]
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render diff data from WebSocket payload."""
+        diffs = payload.get("diffs", [])
+        if not diffs:
+            return Text("No diffs yet", style="dim italic")
+
+        parts: list[Any] = []
+        for diff_entry in diffs:
+            parts.extend(_render_file_diff(diff_entry))
+            parts.append(Text(""))  # separator between files
+
+        return Group(*parts)
+
+
+_LANG_MAP: dict[str, str] = {
+    ".py": "python", ".ts": "typescript", ".tsx": "tsx",
+    ".js": "javascript", ".jsx": "jsx", ".go": "go",
+    ".rs": "rust", ".rb": "ruby", ".java": "java",
+    ".css": "css", ".html": "html", ".json": "json",
+    ".yaml": "yaml", ".yml": "yaml", ".md": "markdown",
+    ".sh": "bash", ".zsh": "bash", ".toml": "toml",
+    ".xml": "xml", ".sql": "sql", ".c": "c", ".cpp": "cpp",
+    ".h": "c", ".hpp": "cpp",
+}
+
+
+def _detect_language(path: str) -> str:
+    """Detect programming language from file path for syntax highlighting."""
+    ext = os.path.splitext(path)[1].lower()
+    return _LANG_MAP.get(ext, "text")
+
+
+def _highlight_code(code: str, language: str) -> Text:
+    """Apply syntax highlighting to a single line using rich.syntax.Syntax."""
+    if not code or not code.strip():
+        return Text(code)
+    try:
+        syntax = Syntax(code, language, theme="monokai", background_color="default")
+        highlighted = syntax.highlight(code)
+        highlighted.rstrip()
+        return highlighted
+    except Exception:
+        return Text(code)
+
+
+def _render_file_diff(diff_entry: dict[str, Any]) -> list[Any]:
+    """Render a single file's diff as a list of Rich renderables."""
+    path = diff_entry.get("path", "unknown")
+    status = diff_entry.get("status", "")
+    additions = diff_entry.get("additions")
+    deletions = diff_entry.get("deletions")
+    raw_diff = diff_entry.get("diff", "")
+
+    # File header line: path [status] +N -N
+    header = Text()
+    header.append(path, style="bold cyan")
+    if status:
+        header.append(f"  {status}", style="dim")
+    if additions is not None and deletions is not None:
+        header.append(f"  +{additions} -{deletions}", style="dim")
+
+    language = _detect_language(path)
+    parts: list[Any] = [header]
+    parts.extend(_parse_diff_lines(raw_diff, language))
+    return parts
+
+
+def _parse_diff_lines(raw_diff: str, language: str = "text") -> list[Any]:
+    """Parse unified diff output into styled Rich Text lines with syntax highlighting."""
+    if not raw_diff or not raw_diff.strip():
+        return []
+
+    result: list[Any] = []
+    line_num = 0
+
+    for line in raw_diff.split("\n"):
+        if line.startswith("diff --git") or line.startswith("index "):
+            continue
+        if line.startswith("---") or line.startswith("+++"):
+            continue
+        if line.startswith("new file") or line.startswith("deleted file"):
+            continue
+        if line.startswith("rename "):
+            continue
+
+        if line.startswith("Binary files"):
+            result.append(Text(line, style="dim italic"))
+        elif line.startswith("@@"):
+            match = re.match(r"@@ -\d+(?:,\d+)? \+(\d+)", line)
+            if match:
+                line_num = int(match.group(1)) - 1
+            result.append(Text(line, style="cyan"))
+        elif line.startswith("+"):
+            line_num += 1
+            t = Text()
+            t.append(f"{line_num:4d} ", style="dim green")
+            t.append_text(_highlight_code(line[1:], language))
+            result.append(t)
+        elif line.startswith("-"):
+            t = Text()
+            t.append("   - ", style="red")
+            t.append_text(_highlight_code(line[1:], language))
+            result.append(t)
+        elif line.startswith(" "):
+            line_num += 1
+            t = Text()
+            t.append(f"{line_num:4d} ", style="dim")
+            t.append_text(_highlight_code(line[1:], language))
+            result.append(t)
+        elif line == "":
+            continue
+        else:
+            result.append(Text(line, style="dim"))
+
+    return result

package/pennyfarthing_scripts/bikerack/git_panel.py

@@ -0,0 +1,69 @@
+"""GitPanel — Multi-repo git status panel for BikeRack TUI.
+
+Story 103-10: Subscribes to /ws/git, renders multi-repo git status
+as Rich table with Nerd Font glyphs for branch and status indicators.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.table import Table
+
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+
+
+class GitPanel(BasePanel):
+    """Multi-repo git status panel.
+
+    Subscribes to the ``git`` WebSocket channel and renders
+    git status for all configured repos as a Rich table with
+    columns: Repository, Branch, Commits, Changes, Status.
+    """
+
+    channel: str = "git"
+    panel_name: str = "Git"
+    icon: str = PANEL_ICONS["git"][0]
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render git status as Rich table with Nerd Font glyphs."""
+        table = Table()
+        table.add_column("Repository", style="cyan")
+        table.add_column("Branch")
+        table.add_column("Commits")
+        table.add_column("Changes", justify="right")
+        table.add_column("Status")
+
+        for repo in payload.get("repos", []):
+            branch = repo.get("branch", "")
+            ahead = repo.get("ahead", 0)
+            behind = repo.get("behind", 0)
+            clean = repo.get("clean", True)
+            dirty_files = repo.get("dirtyFiles", [])
+
+            # Branch with Nerd Font glyph
+            branch_col = f"\ue0a0 {branch}"
+
+            # Commits: ahead/behind with arrow glyphs
+            parts = []
+            if ahead:
+                parts.append(f"\u2b06{ahead}")
+            if behind:
+                parts.append(f"\u2b07{behind}")
+            commits_col = " ".join(parts) if parts else "—"
+
+            # Changes: count of dirty files
+            changes_col = str(len(dirty_files))
+
+            # Status: checkmark or cross
+            status_col = "\u2713" if clean else "\u2717"
+
+            table.add_row(
+                repo.get("name", ""),
+                branch_col,
+                commits_col,
+                changes_col,
+                status_col,
+            )
+
+        return table

package/pennyfarthing_scripts/bikerack/launcher.py

@@ -24,8 +24,8 @@ def is_process_alive(pid: int) -> bool:
 
 
 def cleanup_files(project_dir: Path) -> None:
-    """Clean up .bikerack-port and .bikerack-pid files."""
-    for name in (".bikerack-port", ".bikerack-pid"):
+    """Clean up .bikerack-port, .bikerack-pid, and .bikerack-tui-pid files."""
+    for name in (".bikerack-port", ".bikerack-pid", ".bikerack-tui-pid"):
         try:
             (project_dir / name).unlink()
         except FileNotFoundError:
@@ -64,6 +64,19 @@ def build_otel_env(port: int) -> dict[str, str]:
     }
 
 
+def resolve_project_dir(project_dir: str | None) -> Path:
+    """Resolve project directory from option → env var → cwd.
+
+    Used by bikerack and launch CLI commands.
+    """
+    if project_dir:
+        return Path(project_dir)
+    env = os.environ.get("CYCLIST_PROJECT_DIR")
+    if env:
+        return Path(env)
+    return Path.cwd()
+
+
 def _find_framework_dir() -> Path:
     """Locate the pennyfarthing framework root from this package's location."""
     # pennyfarthing_scripts/bikerack/launcher.py -> pennyfarthing/
@@ -147,7 +160,7 @@ def is_already_running(project_dir: Path) -> tuple[bool, int | None, int | None]
 
 
 def stop_bikerack(project_dir: Path) -> dict:
-    """Stop running BikeRack instance. Returns {success, pid, message}."""
+    """Stop running BikeRack instance and TUI. Returns {success, pid, message}."""
     pid = read_pid_file(project_dir)
 
     if pid is None:
@@ -158,6 +171,15 @@ def stop_bikerack(project_dir: Path) -> dict:
         return {"success": False, "message": "BikeRack is not running (stale PID)"}
 
     os.kill(pid, signal.SIGTERM)
+
+    # Also kill TUI process if running
+    tui_pid = read_tui_pid_file(project_dir)
+    if tui_pid is not None:
+        try:
+            os.kill(tui_pid, signal.SIGTERM)
+        except (ProcessLookupError, OSError):
+            pass
+
     cleanup_files(project_dir)
     return {"success": True, "pid": pid, "message": f"Stopped BikeRack (PID {pid})"}
 
@@ -173,9 +195,46 @@ def get_status(project_dir: Path) -> dict:
     if not is_process_alive(pid):
         return {"running": False}
 
-    return {
+    result = {
         "running": True,
         "pid": pid,
         "port": port,
         "dashboard": f"http://localhost:{port}/bikerack",
+        "tui_pid": read_tui_pid_file(project_dir),
     }
+    return result
+
+
+# --- Story 103-3: TUI launcher functions ---
+
+
+def read_tui_pid_file(project_dir: Path) -> int | None:
+    """Read TUI PID from .bikerack-tui-pid file. Returns None if not found."""
+    try:
+        return int((project_dir / ".bikerack-tui-pid").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def write_tui_pid_file(project_dir: Path, pid: int) -> None:
+    """Write .bikerack-tui-pid file."""
+    (project_dir / ".bikerack-tui-pid").write_text(str(pid))
+
+
+def start_tui(project_dir: Path, port: int) -> subprocess.Popen:
+    """Start TUI as independent subprocess.
+
+    Uses start_new_session=True so TUI survives parent exit.
+    Writes .bikerack-tui-pid for lifecycle tracking.
+    """
+    import sys
+
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "pennyfarthing_scripts.bikerack.tui", "--port", str(port)],
+        cwd=str(project_dir),
+        start_new_session=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    write_tui_pid_file(project_dir, proc.pid)
+    return proc

package/pennyfarthing_scripts/bikerack/sprint_panel.py

@@ -0,0 +1,72 @@
+"""SprintPanel — Sprint status panel for BikeRack TUI.
+
+Story 103-6: First panel implementation proving the BasePanel vertical slice.
+Subscribes to /ws/sprint, renders sprint status as Rich table.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+
+
+class SprintPanel(BasePanel):
+    """Sprint status panel.
+
+    Subscribes to the ``sprint`` WebSocket channel and renders
+    sprint status as a Rich table with story list, points, and velocity.
+    """
+
+    channel: str = "sprint"
+    panel_name: str = "Sprint"
+    icon: str = PANEL_ICONS["sprint"][0]
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render sprint data as Rich renderable.
+
+        Returns a Group containing a sprint metrics header and a
+        story table with columns: ID, Title, Status, Pts, Jira.
+        """
+        sprint = payload.get("sprint", {})
+        metrics = payload.get("metrics", {})
+        epics = payload.get("epics", [])
+
+        # Sprint metrics header
+        sprint_num = sprint.get("number", "")
+        done = sprint.get("done", 0)
+        remaining = sprint.get("remaining", 0)
+        in_progress = sprint.get("inProgress", 0)
+        velocity = metrics.get("velocity", 0)
+
+        header = Text.from_markup(
+            f"Sprint {sprint_num}  "
+            f"[green]Done: {done}[/green] | "
+            f"Remaining: {remaining} | "
+            f"In Progress: {in_progress} | "
+            f"Velocity: {velocity}"
+        )
+
+        # Story table
+        table = Table(title=sprint.get("name", "Sprint"))
+        table.add_column("ID", style="cyan")
+        table.add_column("Title")
+        table.add_column("Status")
+        table.add_column("Pts", justify="right")
+        table.add_column("Jira", style="dim")
+
+        for epic in epics:
+            for story in epic.get("stories", []):
+                table.add_row(
+                    story.get("id", ""),
+                    story.get("title", ""),
+                    story.get("status", ""),
+                    str(story.get("points", "")),
+                    story.get("jiraKey") or "—",
+                )
+
+        return Group(header, table)

package/pennyfarthing_scripts/bikerack/tui.py

@@ -0,0 +1,193 @@
+"""BikeRack TUI — Terminal-native dashboard built on Textual.
+
+Story 103-1: Textual app scaffold with basic layout.
+Story 103-4: Connection status indicator in TUI header.
+Story 103-6: SprintPanel as default panel on launch.
+Story 103-7: /bc TUI panel focus — subscribe to /ws/focus, switch panels.
+Story 103-9: Panel header chrome — icon + name indicator for active panel.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.reactive import reactive
+from textual.widgets import Footer, Header, Static
+
+from pennyfarthing_scripts.bc.focus import get_last_panel, save_last_panel
+from pennyfarthing_scripts.bikerack.base_panel import get_panel_icon
+from pennyfarthing_scripts.bikerack.sprint_panel import SprintPanel
+from pennyfarthing_scripts.bikerack.ws_client import ConnectionState, WheelHubClient
+
+STATE_DISPLAY: dict[ConnectionState, str] = {
+    ConnectionState.CONNECTED: "[green]● Connected[/green]",
+    ConnectionState.DISCONNECTED: "[red]● Disconnected[/red]",
+    ConnectionState.RECONNECTING: "[yellow]● Reconnecting…[/yellow]",
+    ConnectionState.CONNECTING: "[yellow]● Connecting…[/yellow]",
+}
+
+# Human-readable display names for panels
+PANEL_DISPLAY_NAMES: dict[str, str] = {
+    "sprint": "Sprint",
+    "git": "Git",
+    "diffs": "Diffs",
+    "todo": "Todo",
+    "workflow": "Workflow",
+    "background": "Background",
+    "audit-log": "Audit Log",
+    "changed": "Changed",
+    "ac": "Acceptance Criteria",
+    "debug": "Debug",
+    "settings": "Settings",
+    "tty": "TTY",
+}
+
+
+class PanelIndicator(Static):
+    """Displays the active panel's Nerd Font icon and name."""
+
+    panel_key: reactive[str] = reactive("sprint")
+
+    def watch_panel_key(self, key: str) -> None:
+        """Update display when the active panel changes."""
+        icon = get_panel_icon(key)
+        name = PANEL_DISPLAY_NAMES.get(key, key.title())
+        if icon:
+            self.update(f"[bold]{icon} {name}[/bold]")
+        else:
+            self.update(f"[bold]{name}[/bold]")
+
+
+class ConnectionStatus(Static):
+    """Displays WheelHub connection state with colored indicator."""
+
+    connection_state: reactive[ConnectionState] = reactive(
+        ConnectionState.DISCONNECTED
+    )
+
+    def watch_connection_state(self, state: ConnectionState) -> None:
+        """Update display when connection state changes."""
+        self.update(STATE_DISPLAY.get(state, "● Unknown"))
+
+
+class BikeRackApp(App):
+    """BikeRack TUI application shell."""
+
+    TITLE = "BikeRack"
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, client=None, **kwargs):
+        super().__init__(**kwargs)
+        self._client = client
+        self._focused_panel: str | None = None
+        self._previous_panel: str | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield PanelIndicator(id="panel-indicator")
+        yield ConnectionStatus(
+            STATE_DISPLAY[ConnectionState.DISCONNECTED],
+            id="connection-status",
+        )
+        with VerticalScroll(id="main-content"):
+            yield SprintPanel(client=self._client, id="sprint-panel")
+        yield Footer()
+
+    async def on_mount(self) -> None:
+        result = get_last_panel()
+        if result.get("success") and result.get("last_panel"):
+            self._focused_panel = result["last_panel"]
+
+        # Set initial panel indicator
+        self._update_panel_indicator(self._focused_panel or "sprint")
+
+        if self._client is not None:
+            self._client.on_state_change(self._on_ws_state_change)
+            self._client.subscribe("focus", self._handle_focus_message)
+            self.run_worker(self._client.connect(), exclusive=True, name="ws-client")
+
+    def _update_panel_indicator(self, panel_key: str) -> None:
+        """Update the panel indicator widget with the given panel key."""
+        try:
+            indicator = self.query_one("#panel-indicator", PanelIndicator)
+            indicator.panel_key = panel_key
+        except Exception:
+            pass
+
+    def _handle_focus_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming focus channel messages.
+
+        Expected format: {type: 'init'|'update', focus: '<panel>'|null}
+        Only 'update' messages trigger panel switches (matching React hook).
+        """
+        if message is None or not isinstance(message, dict):
+            return
+        if message.get("type") != "update":
+            return
+        if "focus" not in message:
+            return
+
+        focus = message["focus"]
+        if focus is not None:
+            self._previous_panel = self._focused_panel
+            self._focused_panel = focus
+            save_last_panel(focus, project_dir=None)
+            self._update_panel_indicator(focus)
+        else:
+            self._focused_panel = None
+            self._previous_panel = None
+
+    def _on_ws_state_change(self, state: ConnectionState) -> None:
+        """Handle WheelHub connection state changes."""
+        try:
+            widget = self.query_one("#connection-status", ConnectionStatus)
+            widget.connection_state = state
+        except Exception:
+            pass
+
+
+DEFAULT_PORT = 2898
+
+
+def main(port: int | None = None, project_dir: Path | None = None) -> None:
+    """Launch BikeRack TUI as a standalone application.
+
+    Args:
+        port: Explicit WheelHub port. If None, reads from .bikerack-port file.
+        project_dir: Project directory for port file discovery. Defaults to cwd.
+    """
+    if port is None:
+        if project_dir is not None:
+            port_file = project_dir / ".bikerack-port"
+            if port_file.exists():
+                try:
+                    port = int(port_file.read_text().strip())
+                except (ValueError, OSError):
+                    port = DEFAULT_PORT
+            else:
+                port = DEFAULT_PORT
+        else:
+            port = DEFAULT_PORT
+
+    client = WheelHubClient(port=port)
+    app = BikeRackApp(client=client)
+    app.run()
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="BikeRack TUI")
+    parser.add_argument("--port", type=int, default=None, help="WheelHub port")
+    parser.add_argument("--project-dir", type=str, default=None, help="Project directory")
+    args = parser.parse_args()
+
+    project_dir = Path(args.project_dir) if args.project_dir else None
+    main(port=args.port, project_dir=project_dir)