@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/pf/bikerack/launcher.py

@@ -0,0 +1,240 @@
+"""BikeRack launcher — core lifecycle functions.
+
+Story 101-5: BikeRack launcher CLI (pf bikerack start/stop/status)
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+from typing import NoReturn
+
+
+def is_process_alive(pid: int) -> bool:
+    """Check if a process with given PID is alive."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def cleanup_files(project_dir: Path) -> None:
+    """Clean up .bikerack-port, .wheelhub-pid, and .wheelhub-gui-pid files."""
+    for name in (".bikerack-port", ".wheelhub-pid", ".wheelhub-gui-pid"):
+        try:
+            (project_dir / name).unlink()
+        except FileNotFoundError:
+            pass
+
+
+def read_port_file(project_dir: Path) -> int | None:
+    """Read port from .bikerack-port file. Returns None if not found."""
+    try:
+        return int((project_dir / ".bikerack-port").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def read_pid_file(project_dir: Path) -> int | None:
+    """Read PID from .wheelhub-pid file. Returns None if not found."""
+    try:
+        return int((project_dir / ".wheelhub-pid").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def write_pid_file(project_dir: Path, pid: int) -> None:
+    """Write .wheelhub-pid file."""
+    (project_dir / ".wheelhub-pid").write_text(str(pid))
+
+
+def build_otel_env(port: int) -> dict[str, str]:
+    """Build the 5 OTEL environment variables from discovered port (Rule 5)."""
+    return {
+        "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
+        "OTEL_LOGS_EXPORTER": "otlp",
+        "OTEL_METRICS_EXPORTER": "otlp",
+        "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
+        "OTEL_EXPORTER_OTLP_ENDPOINT": f"http://localhost:{port}",
+    }
+
+
+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."""
+    # pf/bikerack/launcher.py -> pennyfarthing/
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def start_wheelhub(project_dir: Path) -> subprocess.Popen:
+    """Start WheelHub server in background with IS_BIKERACK=1."""
+    framework_dir = _find_framework_dir()
+    bikerack_entry = framework_dir / "packages" / "cyclist" / "dist" / "bikerack.js"
+
+    env = os.environ.copy()
+    env["IS_BIKERACK"] = "1"
+    env["CYCLIST_PROJECT_DIR"] = str(project_dir)
+
+    return subprocess.Popen(
+        ["node", str(bikerack_entry)],
+        env=env,
+        cwd=str(project_dir),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+
+def poll_for_port_file(
+    project_dir: Path, timeout: float = 5.0, interval: float = 0.1
+) -> int:
+    """Poll for .bikerack-port file, return port number."""
+    port_file = project_dir / ".bikerack-port"
+    deadline = time.monotonic() + timeout
+
+    while True:
+        if port_file.exists():
+            return int(port_file.read_text().strip())
+        if time.monotonic() >= deadline:
+            raise TimeoutError(
+                f"Timed out waiting for {port_file} after {timeout}s"
+            )
+        time.sleep(interval)
+
+
+def register_cleanup(project_dir: Path, pid: int) -> None:
+    """Register atexit handler to kill WheelHub and clean up files (Rule 8)."""
+
+    def _cleanup(project_dir: Path, pid: int) -> None:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except (ProcessLookupError, OSError):
+            pass
+        cleanup_files(project_dir)
+
+    atexit.register(_cleanup, project_dir, pid)
+
+
+def exec_claude(otel_env: dict[str, str], project_dir: Path | None = None) -> NoReturn:
+    """Replace current process with Claude CLI using os.execvpe (CE-4)."""
+    env = os.environ.copy()
+    env.update(otel_env)
+    if project_dir:
+        os.chdir(project_dir)
+    os.execvpe("claude", ["claude"], env)
+
+
+def is_already_running(project_dir: Path) -> tuple[bool, int | None, int | None]:
+    """Check if BikeRack is already running.
+
+    Returns (is_running, pid_or_none, port_or_none).
+    Cleans up stale files if PID is dead.
+    """
+    pid = read_pid_file(project_dir)
+    port = read_port_file(project_dir)
+
+    if pid is None or port is None:
+        return (False, None, None)
+
+    if is_process_alive(pid):
+        return (True, pid, port)
+
+    cleanup_files(project_dir)
+    return (False, None, None)
+
+
+def stop_bikerack(project_dir: Path) -> dict:
+    """Stop running BikeRack instance and TUI. Returns {success, pid, message}."""
+    pid = read_pid_file(project_dir)
+
+    if pid is None:
+        return {"success": False, "message": "BikeRack is not running"}
+
+    if not is_process_alive(pid):
+        cleanup_files(project_dir)
+        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})"}
+
+
+def get_status(project_dir: Path) -> dict:
+    """Get BikeRack running status. Returns {running, pid, port, dashboard}."""
+    pid = read_pid_file(project_dir)
+    port = read_port_file(project_dir)
+
+    if pid is None or port is None:
+        return {"running": False}
+
+    if not is_process_alive(pid):
+        return {"running": False}
+
+    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 .wheelhub-gui-pid file. Returns None if not found."""
+    try:
+        return int((project_dir / ".wheelhub-gui-pid").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def write_tui_pid_file(project_dir: Path, pid: int) -> None:
+    """Write .wheelhub-gui-pid file."""
+    (project_dir / ".wheelhub-gui-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 .wheelhub-gui-pid for lifecycle tracking.
+    """
+    import sys
+
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "pf.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-dist/pf/bikerack/portrait_resolver.py

@@ -0,0 +1,139 @@
+"""Portrait path resolution for BikeRack TUI.
+
+Resolves persona portrait image paths using the canonical theme discovery
+from ``pf.common.themes``.  Each theme directory that
+contains ``themes/{name}.yaml`` has a sibling ``portraits/{name}/`` with
+size-bucketed portrait images.
+
+Story 110-3: Portrait image header with textual-image.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+
+def _to_slug(name: str) -> str:
+    """Convert a name to URL-safe slug (lowercase kebab-case)."""
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def _extract_agent_slug(theme_yaml: Path, agent: str) -> str | None:
+    """Extract portrait slug (shortName-OCEAN) from a theme YAML file."""
+    if not theme_yaml.exists():
+        return None
+    try:
+        data = yaml.safe_load(theme_yaml.read_text())
+        agent_data = (data or {}).get("agents", {}).get(agent)
+        if not agent_data:
+            return None
+        short_name = agent_data.get("shortName") or (
+            agent_data.get("character", "").split()[0] if agent_data.get("character") else None
+        )
+        ocean = agent_data.get("ocean", {})
+        if short_name and all(k in ocean for k in "OCEAN"):
+            return f"{_to_slug(short_name)}-{ocean['O']}{ocean['C']}{ocean['E']}{ocean['A']}{ocean['N']}"
+    except Exception:
+        pass
+    return None
+
+
+def _find_portrait(portraits_theme_dir: Path, slug: str) -> Path | None:
+    """Find a portrait file matching the slug in a theme's portrait directory."""
+    if not portraits_theme_dir.is_dir():
+        return None
+    for size in ["medium", "large", "small", "original"]:
+        size_dir = portraits_theme_dir / size
+        if size_dir.is_dir():
+            for f in size_dir.iterdir():
+                if f.name.lower().startswith(slug.lower()) and f.suffix in (".png", ".jpg"):
+                    return f
+    # Fallback to root of theme dir
+    for f in portraits_theme_dir.iterdir():
+        if f.is_file() and f.name.lower().startswith(slug.lower()) and f.suffix in (".png", ".jpg"):
+            return f
+    return None
+
+
+def resolve_portrait_path(
+    theme: str, agent: str, project_root: Path | None = None
+) -> Path | None:
+    """Resolve the full path to a portrait image.
+
+    Uses ``discover_all_theme_dirs`` from ``common.themes`` to search core
+    themes, installed theme packages, monorepo workspace packages, and
+    custom themes — in canonical priority order.
+
+    For each theme directory the portrait sibling is derived:
+    - ``.pennyfarthing/personas/themes/`` → ``.pennyfarthing/personas/portraits/``
+    - ``themes-*/themes/`` → ``themes-*/portraits/``
+
+    Args:
+        theme: Theme name (e.g., 'hogans-heroes', 'monty-python')
+        agent: Agent role (e.g., 'sm', 'tea', 'dev')
+        project_root: Project root for path resolution. Defaults to cwd.
+
+    Returns:
+        Path to portrait file, or None if not found.
+    """
+    from pf.common.themes import discover_all_theme_dirs
+
+    theme_dirs = discover_all_theme_dirs(project_root)
+
+    # Resolve slug from the first theme dir that has this theme's YAML
+    slug: str | None = None
+    for themes_dir in theme_dirs:
+        theme_yaml = themes_dir / f"{theme}.yaml"
+        slug = _extract_agent_slug(theme_yaml, agent)
+        if slug:
+            break
+
+    if not slug:
+        return None
+
+    # Search portrait directories (sibling of each themes dir)
+    for themes_dir in theme_dirs:
+        portraits_dir = themes_dir.parent / "portraits" / theme
+        result = _find_portrait(portraits_dir, slug)
+        if result:
+            return result
+
+    return None
+
+
+def detect_image_protocol() -> str | None:
+    """Detect the best available terminal image protocol.
+
+    Uses environment variables for reliable detection since subprocess
+    stdout may not be a TTY (e.g., when launched via Claude Code).
+
+    Returns:
+        Protocol name ('kitty', 'sixel', 'halfcell', None for unsupported).
+    """
+    import os
+
+    # Kitty: TERM=xterm-kitty or KITTY_WINDOW_ID present
+    term = os.environ.get("TERM", "")
+    if "kitty" in term or os.environ.get("KITTY_WINDOW_ID"):
+        return "kitty"
+
+    # Sixel: some terminals advertise via TERM or COLORTERM
+    # WezTerm, foot, mlterm support sixel
+    term_program = os.environ.get("TERM_PROGRAM", "")
+    if term_program.lower() in ("wezterm", "foot", "mlterm"):
+        return "sixel"
+
+    # Fallback: try textual-image's cell size probe for halfcell baseline
+    try:
+        from textual_image._terminal import get_cell_size
+
+        cell_size = get_cell_size()
+        if cell_size and cell_size.width > 0:
+            return "halfcell"
+    except Exception:
+        pass
+
+    return None

package/pennyfarthing-dist/pf/bikerack/progress_panel.py

@@ -0,0 +1,314 @@
+"""ProgressPanel — Unified story progress view for BikeRack TUI.
+
+Combines story context, workflow phase, acceptance criteria, todos, and
+git status into a single at-a-glance panel. Subscribes to 4 WS channels:
+/ws/story, /ws/todos, /ws/git, /ws/sprint.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Group
+from rich.text import Text
+
+from pf.bikerack.base_panel import (
+    PANEL_ICONS,
+    BasePanel,
+    render_progress_bar,
+)
+
+
+class ProgressPanel(BasePanel):
+    """Unified story progress panel.
+
+    Subscribes to ``story``, ``todos``, ``git``, and ``sprint`` channels.
+    Renders a compact overview combining story header, workflow phase,
+    AC progress, todo progress, and git summary.
+    """
+
+    channel: str = "story"  # primary channel
+    panel_name: str = "Progress"
+    icon: str = PANEL_ICONS.get("progress", ("\uf200", "P"))[0]
+
+    def __init__(self, client: Any = None, **kwargs: Any) -> None:
+        super().__init__(client=client, **kwargs)
+        self._story_data: dict[str, Any] | None = None
+        self._todos_data: dict[str, Any] | None = None
+        self._git_data: dict[str, Any] | None = None
+        self._sprint_data: dict[str, Any] | None = None
+
+    def on_mount(self) -> None:
+        """Subscribe to all 4 channels."""
+        self._mounted = True
+        if self._client is not None:
+            self._client.subscribe("story", self._handle_story)
+            self._client.subscribe("todos", self._handle_todos)
+            self._client.subscribe("git", self._handle_git)
+            self._client.subscribe("sprint", self._handle_sprint)
+
+    def _handle_story(self, message: dict[str, Any] | None) -> None:
+        if message is None:
+            return
+        self._story_data = message
+        self._rerender()
+
+    def _handle_todos(self, message: dict[str, Any] | None) -> None:
+        if message is None:
+            return
+        self._todos_data = message
+        self._rerender()
+
+    def _handle_git(self, message: dict[str, Any] | None) -> None:
+        if message is None:
+            return
+        self._git_data = message
+        self._rerender()
+
+    def _handle_sprint(self, message: dict[str, Any] | None) -> None:
+        if message is None:
+            return
+        self._sprint_data = message
+        self._rerender()
+
+    def _rerender(self) -> None:
+        """Re-render with latest data from all channels."""
+        rendered = self.render_panel({})
+        try:
+            self.update(rendered)
+        except Exception:
+            pass
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render unified progress view."""
+        parts: list[Any] = []
+
+        # --- Story Header ---
+        story_header = self._render_story_header()
+        if story_header is None:
+            return Text(
+                "No active story \u2014 start with /sprint work",
+                style="dim italic",
+            )
+        parts.append(story_header)
+        parts.append(Text("\u2500" * 35, style="dim"))
+
+        # --- Workflow Phase ---
+        workflow = self._render_workflow()
+        if workflow is not None:
+            parts.append(workflow)
+            parts.append(Text("\u2500" * 35, style="dim"))
+
+        # --- Acceptance Criteria ---
+        ac = self._render_ac()
+        if ac is not None:
+            parts.append(ac)
+            parts.append(Text("\u2500" * 35, style="dim"))
+
+        # --- Todos ---
+        todos = self._render_todos()
+        if todos is not None:
+            parts.append(todos)
+            parts.append(Text("\u2500" * 35, style="dim"))
+
+        # --- Git Summary ---
+        git = self._render_git()
+        if git is not None:
+            parts.append(git)
+
+        return Group(*parts)
+
+    def _render_story_header(self) -> Text | None:
+        """Render story ID, title, points, epic, assignee."""
+        story = self._story_data or {}
+        sprint = self._sprint_data or {}
+
+        # Try sprint data for current story context
+        current = sprint.get("sprint", {}).get("currentStory")
+        if isinstance(current, str) and current:
+            story_id = current
+        else:
+            story_id = story.get("id", "")
+
+        title = story.get("title", "")
+        points = story.get("points", "")
+        epic = story.get("epic", "")
+        assignee = story.get("assignee", "")
+
+        # Also try to extract from sprint epics
+        if not title and sprint:
+            for ep in sprint.get("epics", []):
+                for s in ep.get("stories", []):
+                    if s.get("id") == story_id:
+                        title = s.get("title", "")
+                        points = s.get("points", "")
+                        epic = ep.get("id", "")
+                        break
+
+        if not story_id and not title:
+            return None
+
+        header = Text()
+        if story_id:
+            header.append(story_id, style="bold cyan")
+            header.append("  ")
+        if title:
+            header.append(title, style="bold")
+        if points:
+            header.append(f"  {points}pt", style="dim")
+
+        # Second line: epic + assignee
+        meta_parts: list[str] = []
+        if epic:
+            meta_parts.append(f"Epic {epic}")
+        if assignee:
+            meta_parts.append(assignee)
+        if meta_parts:
+            header.append("\n")
+            header.append(" \u00b7 ".join(meta_parts), style="dim")
+
+        return header
+
+    def _render_workflow(self) -> Text | None:
+        """Render workflow type badge and phase dots."""
+        story = self._story_data or {}
+        workflow = story.get("workflow", "")
+        phases = story.get("workflowPhases", [])
+        current_phase = story.get("phase", "")
+
+        if not phases:
+            return None
+
+        line = Text()
+
+        # Workflow type badge
+        if workflow:
+            line.append(f"[{workflow}]", style="bold")
+            line.append("  ")
+
+        # Phase dots
+        for i, phase in enumerate(phases):
+            phase_name = phase if isinstance(phase, str) else phase.get("name", "")
+            phase_status = ""
+            if isinstance(phase, dict):
+                phase_status = phase.get("status", "")
+
+            # Determine phase state
+            if phase_status == "done" or (current_phase and phase_name != current_phase and _phase_before(phase_name, current_phase, phases)):
+                line.append("\u2713", style="green")
+            elif phase_name == current_phase:
+                line.append("\u25cf", style="bold yellow")
+            else:
+                line.append("\u25cb", style="dim")
+
+            line.append(f" {phase_name}", style="bold" if phase_name == current_phase else "dim")
+
+            if i < len(phases) - 1:
+                line.append(" \u2192 ", style="dim")
+
+        return line
+
+    def _render_ac(self) -> Text | None:
+        """Render acceptance criteria progress bar."""
+        story = self._story_data or {}
+        criteria = story.get("criteria", [])
+        if not criteria:
+            return None
+
+        total = len(criteria)
+        done = sum(1 for c in criteria if isinstance(c, dict) and c.get("met"))
+
+        if total == 0:
+            return None
+
+        pct = int(done / total * 100)
+        line = Text()
+        line.append("AC   ", style="bold")
+        line.append_text(render_progress_bar(pct, width=10))
+        line.append(f"  {done}/{total}")
+        return line
+
+    def _render_todos(self) -> Text | None:
+        """Render todo progress bar with active task."""
+        data = self._todos_data or {}
+        todos = data.get("todos", [])
+        if not todos:
+            return None
+
+        total = len(todos)
+        done = sum(1 for t in todos if isinstance(t, dict) and t.get("status") == "done")
+        active = None
+        for t in todos:
+            if isinstance(t, dict) and t.get("status") in ("in-progress", "active", "running"):
+                active = t.get("description", t.get("title", ""))
+                break
+
+        if total == 0:
+            return None
+
+        pct = int(done / total * 100)
+        line = Text()
+        line.append("Todo ", style="bold")
+        line.append_text(render_progress_bar(pct, width=10))
+        line.append(f"  {done}/{total}")
+        if active:
+            line.append(f"  \u25cf {active}", style="yellow")
+        return line
+
+    def _render_git(self) -> Text | None:
+        """Render git summary: branch, dirty counts, ahead/behind."""
+        data = self._git_data or {}
+        repos = data.get("repos", [])
+        if not repos:
+            return None
+
+        line = Text()
+        line.append("Git  ", style="bold")
+
+        for repo in repos:
+            if not isinstance(repo, dict):
+                continue
+            branch = repo.get("branch", "")
+            dirty_files = repo.get("dirtyFiles", [])
+            ahead = repo.get("ahead", 0)
+            behind = repo.get("behind", 0)
+
+            # Count file types
+            modified = 0
+            untracked = 0
+            for f in dirty_files:
+                if not isinstance(f, dict):
+                    continue
+                status = f.get("status", "  ")
+                if status.startswith("?"):
+                    untracked += 1
+                else:
+                    modified += 1
+
+            part = Text()
+            if branch:
+                part.append(branch, style="cyan")
+            part.append(f"  {modified}M", style="yellow" if modified else "dim")
+            part.append(f" {untracked}U", style="dim")
+            part.append(f"  \u2191{ahead}", style="green" if ahead else "dim")
+            part.append(f" \u2193{behind}", style="red" if behind else "dim")
+
+            line.append_text(part)
+
+            # Only show first repo on main line, rest on separate lines
+            break
+
+        return line
+
+
+def _phase_before(phase: str, current: str, phases: list) -> bool:
+    """Check if phase comes before current in the phases list."""
+    phase_idx = -1
+    current_idx = -1
+    for i, p in enumerate(phases):
+        name = p if isinstance(p, str) else p.get("name", "")
+        if name == phase:
+            phase_idx = i
+        if name == current:
+            current_idx = i
+    return phase_idx >= 0 and current_idx >= 0 and phase_idx < current_idx