@pennyfarthing/core 11.4.0 → 12.0.0

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

@@ -1,248 +0,0 @@
-"""DebugPanel — Context usage and token stats for BikeRack TUI.
-
-Story 103-17: Port of the React DebugPanel. Subscribes to /ws/context
-and /ws/token-stats, renders context usage (tokens, percent, tier) and
-token consumption stats (input, output, cache, cost).
-"""
-
-from __future__ import annotations
-
-from collections import deque
-from typing import Any
-
-from rich.console import Group
-from rich.table import Table
-from rich.text import Text
-
-from pf.bikerack.base_panel import PANEL_ICONS, BasePanel, render_progress_bar
-
-# Tier → Rich style mapping
-_TIER_STYLES: dict[str, str] = {
-    "FULL": "bold green",
-    "REFRESH": "bold yellow",
-    "HANDOFF": "bold cyan",
-    "MINIMAL": "bold red",
-}
-
-
-def _safe_int(value: Any) -> int | None:
-    """Safely convert a value to int, returning None on failure."""
-    if value is None:
-        return None
-    try:
-        return int(value)
-    except (ValueError, TypeError):
-        return None
-
-
-def _safe_float(value: Any) -> float | None:
-    """Safely convert a value to float, returning None on failure."""
-    if value is None:
-        return None
-    try:
-        return float(value)
-    except (ValueError, TypeError):
-        return None
-
-
-def _format_tokens(value: Any) -> str:
-    """Format a token count with comma separators."""
-    n = _safe_int(value)
-    if n is None:
-        return "—"
-    return f"{n:,}"
-
-
-class DebugPanel(BasePanel):
-    """Context usage and token stats panel.
-
-    Subscribes to both ``context`` and ``token-stats`` WebSocket channels.
-    Renders context usage (tokens, percentage, tier) and token consumption
-    stats (input, output, cache read/write, cost).
-    """
-
-    channel: str = "context"
-    panel_name: str = "Debug"
-    icon: str = PANEL_ICONS["debug"][0]
-
-    def __init__(self, client: Any = None, **kwargs: Any) -> None:
-        super().__init__(client=client, **kwargs)
-        self._context_data: dict[str, Any] | None = None
-        self._token_stats: dict[str, Any] | None = None
-        self._sparkline_history: deque[int] = deque(maxlen=20)
-
-    def on_mount(self) -> None:
-        """Subscribe to both context and token-stats channels."""
-        self._mounted = True
-        if self._client is not None:
-            self._client.subscribe("context", self._handle_context_message)
-            self._client.subscribe("token-stats", self._handle_token_stats_message)
-
-    def _handle_context_message(self, message: dict[str, Any] | None) -> None:
-        """Handle incoming context channel message."""
-        if message is None:
-            return
-        ctx = message.get("context")
-        if isinstance(ctx, dict):
-            self._context_data = ctx
-            pct = _safe_int(ctx.get("percent"))
-            if pct is not None:
-                self._sparkline_history.append(pct)
-        else:
-            self._context_data = {}
-        self._rerender()
-
-    def _handle_token_stats_message(self, message: dict[str, Any] | None) -> None:
-        """Handle incoming token-stats channel message."""
-        if message is None:
-            return
-        self._token_stats = message
-        self._rerender()
-
-    def _rerender(self) -> None:
-        """Re-render with the latest data from both channels."""
-        rendered = self.render_panel(self._context_data or {})
-        try:
-            self._thread_safe_update(rendered)
-        except Exception:
-            pass
-
-    def render_panel(self, payload: dict[str, Any]) -> Any:
-        """Render combined context usage and token stats."""
-        parts: list[Any] = []
-
-        # --- Context Usage Section ---
-        ctx = self._context_data
-        if ctx:
-            parts.append(_render_context(ctx))
-            if len(self._sparkline_history) >= 2:
-                parts.append(_render_sparkline(self._sparkline_history))
-        elif not self._token_stats:
-            return Text("No context data", style="dim italic")
-
-        # --- Token Stats Section ---
-        if self._token_stats:
-            if parts:
-                parts.append(Text(""))  # spacer
-            parts.append(_render_token_stats(self._token_stats))
-
-        if not parts:
-            return Text("No context data", style="dim italic")
-
-        return Group(*parts)
-
-
-def _render_context(ctx: dict[str, Any]) -> Any:
-    """Render context usage section."""
-    parts: list[Any] = []
-
-    # Tier badge
-    tier = ctx.get("tier")
-    if tier and isinstance(tier, str):
-        style = _TIER_STYLES.get(tier, "bold")
-        tier_text = Text()
-        tier_text.append(tier, style=style)
-        savings = _tier_savings(tier)
-        if savings > 0:
-            tier_text.append(f" {savings}% savings", style="dim")
-        parts.append(tier_text)
-
-    # Token usage
-    tokens = _safe_int(ctx.get("tokens"))
-    percent = _safe_int(ctx.get("percent"))
-    baseline = _safe_int(ctx.get("baseline"))
-    available = _safe_int(ctx.get("available"))
-
-    if tokens is not None:
-        usage_text = Text()
-        usage_text.append(f"{tokens:,}", style="bold")
-        if baseline is not None and available is not None:
-            total = baseline + available
-            usage_text.append(f" / {total:,}")
-        usage_text.append(" tokens")
-        if percent is not None:
-            usage_text.append(f" ({percent}%)")
-        parts.append(usage_text)
-
-    # Context usage progress bar
-    if percent is not None:
-        parts.append(render_progress_bar(percent, warn_high=True))
-
-    # Breakdown: baseline / conversation / available
-    if baseline is not None:
-        breakdown = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
-        breakdown.add_column("Label", style="dim")
-        breakdown.add_column("Value", justify="right")
-        breakdown.add_row("System Prompt", _format_tokens(baseline))
-        usable = _safe_int(ctx.get("usableTokens"))
-        if usable is not None:
-            breakdown.add_row("Conversation", _format_tokens(usable))
-        if available is not None:
-            breakdown.add_row("Available", _format_tokens(available))
-        parts.append(breakdown)
-
-    if not parts:
-        return Text("No context data", style="dim italic")
-
-    return Group(*parts)
-
-
-_SPARKLINE_CHARS = "▁▂▃▄▅▆▇█"
-
-
-def _render_sparkline(history: deque[int]) -> Text:
-    """Render a Unicode sparkline from context usage history."""
-    text = Text()
-    text.append("Context trend: ", style="dim")
-    for pct in history:
-        level = min(7, max(0, int(pct / 100 * 7.99)))
-        if pct < 50:
-            style = "green"
-        elif pct <= 80:
-            style = "yellow"
-        else:
-            style = "red"
-        text.append(_SPARKLINE_CHARS[level], style=style)
-    return text
-
-
-def _render_token_stats(stats: dict[str, Any]) -> Any:
-    """Render token stats section."""
-    table = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
-    table.add_column("Stat", style="dim")
-    table.add_column("Value", justify="right")
-
-    rows: list[tuple[str, str]] = []
-
-    input_t = _safe_int(stats.get("inputTokens"))
-    if input_t is not None:
-        rows.append(("Input", f"{input_t:,}"))
-
-    output_t = _safe_int(stats.get("outputTokens"))
-    if output_t is not None:
-        rows.append(("Output", f"{output_t:,}"))
-
-    cache_read = _safe_int(stats.get("cacheReadTokens"))
-    if cache_read is not None:
-        rows.append(("Cache Read", f"{cache_read:,}"))
-
-    cache_write = _safe_int(stats.get("cacheCreationTokens"))
-    if cache_write is not None:
-        rows.append(("Cache Write", f"{cache_write:,}"))
-
-    cost = _safe_float(stats.get("totalCostUsd"))
-    if cost is not None and cost > 0:
-        rows.append(("Cost", f"${cost:.4f}"))
-
-    if not rows:
-        return Text("No token stats", style="dim italic")
-
-    for label, value in rows:
-        table.add_row(label, value)
-
-    return table
-
-
-def _tier_savings(tier: str) -> int:
-    """Calculate token savings percentage for a tier vs FULL."""
-    return {"FULL": 0, "REFRESH": 85, "HANDOFF": 82, "MINIMAL": 95}.get(tier, 0)

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

@@ -1,240 +0,0 @@
-"""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

@@ -1,160 +0,0 @@
-"""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
-
-    # Fallback: search Cyclist package portrait directories
-    # Portraits are bundled in @pennyfarthing/cyclist, not alongside theme YAMLs
-    root = project_root or Path.cwd()
-    cyclist_portrait_dirs = [
-        root / "packages" / "cyclist" / "portraits" / theme,  # monorepo dev
-        root / "node_modules" / "@pennyfarthing" / "cyclist" / "portraits" / theme,  # npm
-    ]
-    # pnpm: resolve through .pennyfarthing symlink chain
-    pnpm_cyclist = root / "node_modules" / ".pnpm"
-    if pnpm_cyclist.is_dir():
-        for entry in pnpm_cyclist.iterdir():
-            if entry.name.startswith("@pennyfarthing+cyclist@"):
-                candidate = entry / "node_modules" / "@pennyfarthing" / "cyclist" / "portraits" / theme
-                cyclist_portrait_dirs.append(candidate)
-                break
-
-    for portraits_dir in cyclist_portrait_dirs:
-        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