@pennyfarthing/core 10.3.1 → 11.0.0-alpha.0

package/pennyfarthing_scripts/bc/focus.py

@@ -0,0 +1,333 @@
+"""Panel focus management — read/write focus key in config.local.yaml.
+
+Story 104-1: pf bc CLI command + /bc user skill
+Story 104-4: Save and clear named layouts via /bc
+Epic: 104 — /bc CLI Panel Focus
+"""
+
+from __future__ import annotations
+
+import io
+import re
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+
+def _get_root() -> Path:
+    """Get project root, falling back to cwd."""
+    try:
+        from pennyfarthing_scripts.common.config import get_project_root
+
+        return get_project_root()
+    except Exception:
+        return Path.cwd()
+
+VALID_PANELS = [
+    "sprint",
+    "git",
+    "diffs",
+    "todo",
+    "workflow",
+    "background",
+    "audit-log",
+    "changed",
+    "ac",
+    "debug",
+    "settings",
+    "tty",
+]
+
+
+def set_panel_focus(panel_name: str, project_dir: Path | None = None) -> dict:
+    """Set focus panel in config.local.yaml.
+
+    Args:
+        panel_name: Panel to focus on (must be in VALID_PANELS)
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, data?: str, error?: str}
+    """
+    if panel_name not in VALID_PANELS:
+        return {
+            "success": False,
+            "error": f"Invalid panel '{panel_name}'. Valid panels: {', '.join(VALID_PANELS)}",
+        }
+
+    try:
+        config_path, config = _read_config(project_dir)
+        if config is None:
+            return {"success": False, "error": "Config is not a YAML mapping"}
+        config["focus"] = panel_name
+        _write_config(config_path, config)
+        return {"success": True, "data": panel_name}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def clear_panel_focus(project_dir: Path | None = None) -> dict:
+    """Clear focus setting from config.local.yaml.
+
+    Args:
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, message?: str, error?: str}
+    """
+    try:
+        root = project_dir or _get_root()
+        config_path = root / ".pennyfarthing" / "config.local.yaml"
+
+        if not config_path.exists():
+            return {"success": True, "message": "No focus setting to clear"}
+
+        config_path, config = _read_config(project_dir)
+        if config is None:
+            config = _make_yaml().load("{}")
+        if "focus" in config:
+            del config["focus"]
+        _write_config(config_path, config)
+
+        return {"success": True, "message": "focus cleared"}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+LAYOUT_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_]+$")
+
+
+def _make_yaml() -> YAML:
+    """Create a configured ruamel.yaml instance that preserves formatting."""
+    yml = YAML()
+    yml.preserve_quotes = True
+    yml.default_flow_style = False
+    yml.width = 4096
+    yml.indent(mapping=2, sequence=4, offset=2)
+    return yml
+
+
+def _read_config(project_dir: Path | None = None):
+    """Read config.local.yaml using ruamel.yaml to preserve formatting.
+
+    Returns:
+        (config_path, config) where config is a CommentedMap or None if invalid.
+    """
+    root = project_dir or _get_root()
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+    yml = _make_yaml()
+    if config_path.exists():
+        config = yml.load(config_path.read_text())
+        if config is None:
+            config = yml.load("{}")
+        return config_path, config
+    return config_path, yml.load("{}")
+
+
+def _write_config(config_path: Path, config) -> None:
+    """Write config to YAML file, preserving formatting via ruamel.yaml."""
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    yml = _make_yaml()
+    stream = io.StringIO()
+    yml.dump(config, stream)
+    config_path.write_text(stream.getvalue())
+
+
+def validate_layout_name(name: str) -> bool:
+    """Validate a layout name (alphanumeric + underscore only).
+
+    Args:
+        name: Layout name to validate
+
+    Returns:
+        True if valid, False otherwise
+    """
+    return bool(LAYOUT_NAME_PATTERN.match(name))
+
+
+def save_named_layout(
+    name: str, layout_data: dict, project_dir: Path | None = None
+) -> dict:
+    """Save a named layout to config.local.yaml.
+
+    Args:
+        name: Layout name (must match LAYOUT_NAME_PATTERN)
+        layout_data: Serialized dockview layout
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, data?: str, error?: str}
+    """
+    if not validate_layout_name(name):
+        return {"success": False, "error": f"Invalid layout name '{name}'"}
+    try:
+        config_path, config = _read_config(project_dir)
+        if "layouts" not in config or not isinstance(config.get("layouts"), dict):
+            config["layouts"] = {}
+        config["layouts"][name] = layout_data
+        _write_config(config_path, config)
+        return {"success": True, "data": name}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def load_named_layout(name: str, project_dir: Path | None = None) -> dict:
+    """Load a named layout from config.local.yaml.
+
+    Args:
+        name: Layout name to load
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, data?: dict, error?: str}
+    """
+    if not validate_layout_name(name):
+        return {"success": False, "error": f"Invalid layout name '{name}'"}
+    try:
+        _, config = _read_config(project_dir)
+        layouts = config.get("layouts")
+        if not isinstance(layouts, dict) or name not in layouts:
+            return {"success": False, "error": f"Layout '{name}' not found"}
+        return {"success": True, "data": layouts[name]}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def list_named_layouts(project_dir: Path | None = None) -> dict:
+    """List all saved named layouts.
+
+    Args:
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, data?: list[str], error?: str}
+    """
+    try:
+        _, config = _read_config(project_dir)
+        layouts = config.get("layouts")
+        if not isinstance(layouts, dict):
+            return {"success": True, "data": []}
+        return {"success": True, "data": list(layouts.keys())}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def clear_named_layout(name: str, project_dir: Path | None = None) -> dict:
+    """Delete a specific named layout from config.local.yaml.
+
+    Args:
+        name: Layout name to delete
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, message?: str, error?: str}
+    """
+    if not validate_layout_name(name):
+        return {"success": False, "error": f"Invalid layout name '{name}'"}
+    try:
+        config_path, config = _read_config(project_dir)
+        layouts = config.get("layouts")
+        if not isinstance(layouts, dict) or name not in layouts:
+            return {"success": False, "error": f"Layout '{name}' not found"}
+        del config["layouts"][name]
+        _write_config(config_path, config)
+        return {"success": True, "message": f"Layout '{name}' cleared"}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def clear_all_named_layouts(project_dir: Path | None = None) -> dict:
+    """Delete all named layouts from config.local.yaml.
+
+    Args:
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, message?: str, error?: str}
+    """
+    try:
+        config_path, config = _read_config(project_dir)
+        config.pop("layouts", None)
+        _write_config(config_path, config)
+        return {"success": True, "message": "All layouts cleared"}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def get_last_panel(project_dir: Path | None = None) -> dict:
+    """Read last_panel from config.local.yaml.
+
+    Story 103-8: Panel persistence — single source of truth for last-viewed
+    panel, shared between ERB and TUI.
+
+    Args:
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, last_panel?: str|None, error?: str}
+    """
+    try:
+        _, config = _read_config(project_dir)
+        last_panel = config.get("last_panel") if config else None
+        if last_panel is not None and last_panel not in VALID_PANELS:
+            return {"success": True, "last_panel": None}
+        return {"success": True, "last_panel": last_panel}
+    except Exception:
+        return {"success": True, "last_panel": None}
+
+
+def save_last_panel(panel_name: str, project_dir: Path | None = None) -> dict:
+    """Save last_panel to config.local.yaml.
+
+    Story 103-8: Panel persistence — persists the active panel so it can
+    be restored on next launch. Shared between ERB and TUI.
+
+    Args:
+        panel_name: Panel ID to persist (must be in VALID_PANELS)
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, data?: str, error?: str}
+    """
+    if panel_name not in VALID_PANELS:
+        return {
+            "success": False,
+            "error": f"Invalid panel '{panel_name}'. Valid panels: {', '.join(VALID_PANELS)}",
+        }
+
+    try:
+        config_path, config = _read_config(project_dir)
+        if config is None:
+            config = _make_yaml().load("{}")
+        config["last_panel"] = panel_name
+        _write_config(config_path, config)
+        return {"success": True, "data": panel_name}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def get_panel_focus(project_dir: Path | None = None) -> dict:
+    """Read current focus setting from config.local.yaml.
+
+    Args:
+        project_dir: Override project root (for testing)
+
+    Returns:
+        {success: bool, focus?: str|None, error?: str}
+    """
+    try:
+        root = project_dir or _get_root()
+        config_path = root / ".pennyfarthing" / "config.local.yaml"
+
+        if not config_path.exists():
+            return {"success": True, "focus": None}
+
+        try:
+            _, config = _read_config(project_dir)
+            if config is not None:
+                return {"success": True, "focus": config.get("focus")}
+            return {"success": True, "focus": None}
+        except Exception:
+            return {"success": True, "focus": None}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}

package/pennyfarthing_scripts/bikerack/__init__.py

@@ -13,10 +13,14 @@ from pennyfarthing_scripts.bikerack.launcher import (
     poll_for_port_file,
     read_pid_file,
     read_port_file,
+    read_tui_pid_file,
     register_cleanup,
+    resolve_project_dir,
+    start_tui,
     start_wheelhub,
     stop_bikerack,
     write_pid_file,
+    write_tui_pid_file,
 )
 
 __all__ = [
@@ -29,8 +33,12 @@ __all__ = [
     "poll_for_port_file",
     "read_pid_file",
     "read_port_file",
+    "read_tui_pid_file",
     "register_cleanup",
+    "resolve_project_dir",
+    "start_tui",
     "start_wheelhub",
     "stop_bikerack",
     "write_pid_file",
+    "write_tui_pid_file",
 ]

package/pennyfarthing_scripts/bikerack/background_panel.py

@@ -0,0 +1,81 @@
+"""BackgroundPanel — Background task status display for BikeRack TUI.
+
+Story 103-16: Subscribes to /ws/background-tasks, renders background task
+list with status indicators (running, completed, failed).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Group
+from rich.text import Text
+
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+
+
+class BackgroundPanel(BasePanel):
+    """Background task status panel.
+
+    Subscribes to the ``background-tasks`` WebSocket channel and renders
+    a list of background tasks with status indicators.
+    """
+
+    channel: str = "background-tasks"
+    panel_name: str = "Background"
+    icon: str = PANEL_ICONS["background"][0]
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render background task data from WebSocket payload."""
+        tasks = payload.get("tasks", [])
+        if not isinstance(tasks, list) or not tasks:
+            return Text("No background tasks", style="dim italic")
+
+        parts: list[Any] = []
+        for task in tasks:
+            if not isinstance(task, dict):
+                continue
+            parts.append(_render_task(task))
+
+        if not parts:
+            return Text("No background tasks", style="dim italic")
+
+        return Group(*parts)
+
+
+def _render_task(task: dict[str, Any]) -> Text:
+    """Render a single background task as a styled Text line."""
+    description = task.get("description", "Unknown task")
+    subagent_type = task.get("subagentType", "")
+    completed_at = task.get("completedAt")
+    success = task.get("success")
+    result = task.get("result", "")
+    error = task.get("error", "")
+
+    line = Text()
+
+    if completed_at is not None:
+        if success:
+            line.append("✓ ", style="bold green")
+            line.append(description)
+            if subagent_type:
+                line.append(f" [{subagent_type}]", style="dim")
+            line.append(" — done", style="green")
+            if result:
+                line.append(f" ({result})", style="dim green")
+        else:
+            line.append("✗ ", style="bold red")
+            line.append(description)
+            if subagent_type:
+                line.append(f" [{subagent_type}]", style="dim")
+            line.append(" — failed", style="red")
+            if error:
+                line.append(f"\n  {error}", style="red")
+    else:
+        line.append("⟳ ", style="bold yellow")
+        line.append(description)
+        if subagent_type:
+            line.append(f" [{subagent_type}]", style="dim")
+        line.append(" — running", style="yellow")
+
+    return line

package/pennyfarthing_scripts/bikerack/base_panel.py

@@ -0,0 +1,100 @@
+"""Base panel abstraction for BikeRack TUI.
+
+Story 103-5: Base panel class that panels inherit from. Handles:
+subscribe to WebSocket channel by key, receive JSON payload, call
+render method, display Rich output in main content area.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from textual.widgets import Static
+
+# Nerd Font icon registry: panel_name → (nerd_font_icon, ascii_fallback)
+PANEL_ICONS: dict[str, tuple[str, str]] = {
+    "sprint": ("\uf0e7", "#"),       # nf-fa-bolt
+    "git": ("\ue725", "G"),          # nf-dev-git_branch
+    "diffs": ("\uf440", "D"),        # nf-oct-diff
+    "todo": ("\uf046", "T"),         # nf-fa-check_square_o
+    "workflow": ("\uf126", "W"),     # nf-fa-code_fork
+    "background": ("\uf110", "B"),   # nf-fa-spinner
+    "audit-log": ("\uf15c", "L"),    # nf-fa-file_text
+    "changed": ("\uf044", "C"),      # nf-fa-pencil_square_o
+    "ac": ("\uf00c", "A"),           # nf-fa-check
+    "debug": ("\uf188", "d"),        # nf-fa-bug
+    "settings": ("\uf013", "S"),     # nf-fa-gear
+    "tty": ("\uf120", ">"),          # nf-fa-terminal
+}
+
+
+def get_panel_icon(panel_name: str, use_nerd_font: bool = True) -> str:
+    """Return icon for a panel name.
+
+    Args:
+        panel_name: Panel identifier (e.g. "sprint", "git").
+        use_nerd_font: If True, return Nerd Font glyph; otherwise ASCII fallback.
+
+    Returns:
+        Icon string, or empty string if panel_name is unknown.
+    """
+    entry = PANEL_ICONS.get(panel_name)
+    if entry is None:
+        return ""
+    return entry[0] if use_nerd_font else entry[1]
+
+
+class BasePanel(Static):
+    """Base class for BikeRack TUI panels.
+
+    Subclasses set ``channel`` as a class attribute and implement
+    ``render_panel(payload)`` to return a Rich renderable.
+    """
+
+    #: WebSocket channel this panel subscribes to (override in subclass)
+    channel: str = ""
+
+    #: Human-readable panel name shown in header chrome
+    panel_name: str = ""
+
+    #: Nerd Font icon for this panel type (with ASCII fallback)
+    icon: str = ""
+
+    def __init__(self, client=None, **kwargs):
+        super().__init__(**kwargs)
+        self._client = client
+        self._last_payload: dict[str, Any] | None = None
+        self._mounted = False
+
+    def on_mount(self) -> None:
+        """Subscribe to channel via client on mount."""
+        self._mounted = True
+        if self._client is not None and self.channel:
+            self._client.subscribe(self.channel, self.handle_message)
+
+    def on_unmount(self) -> None:
+        """Mark panel as unmounted — messages ignored after this."""
+        self._mounted = False
+
+    def handle_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming WebSocket message.
+
+        Stores payload, calls render_panel, updates widget display.
+        No-op after unmount or if message is None.
+        """
+        if not self._mounted or message is None:
+            return
+        self._last_payload = message
+        rendered = self.render_panel(message)
+        try:
+            self.update(rendered)
+        except Exception:
+            pass
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render panel content from payload.
+
+        Subclasses override this to return Rich renderables
+        (Table, Tree, Text, etc.).
+        """
+        raise NotImplementedError("Subclasses must implement render_panel()")

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"]: