@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing_scripts/bikerack/ws_client.py

@@ -0,0 +1,176 @@
+"""WheelHub WebSocket client with auto-reconnect.
+
+Story 103-2: Python WebSocket client that connects to WheelHub,
+subscribes to panel channels, receives JSON payloads, dispatches
+to handlers, and auto-reconnects on disconnect with backoff.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import websockets
+
+
+class ConnectionState(Enum):
+    """WebSocket connection states."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+
+
+# Default port for BikeRack mode
+DEFAULT_PORT = 2898
+
+# Reconnect delay in seconds (matches React hook pattern)
+RECONNECT_DELAY = 2.0
+
+# Type alias for message handlers
+MessageHandler = Callable[[dict[str, Any]], None]
+StateChangeCallback = Callable[[ConnectionState], None]
+
+
+class WheelHubClient:
+    """WebSocket client for WheelHub server.
+
+    Connects to WheelHub, subscribes to channels, dispatches
+    JSON messages to registered handlers, auto-reconnects on disconnect.
+    """
+
+    def __init__(
+        self,
+        port: int | None = None,
+        project_dir: Path | None = None,
+    ) -> None:
+        self._port = port
+        self._project_dir = project_dir
+        self._state = ConnectionState.DISCONNECTED
+        self._handlers: dict[str, list[MessageHandler]] = {}
+        self._state_callbacks: list[StateChangeCallback] = []
+        self._connections: dict[str, Any] = {}
+        self._tasks: list[asyncio.Task] = []
+        self._stopped = False
+
+    @property
+    def state(self) -> ConnectionState:
+        """Current connection state."""
+        return self._state
+
+    @property
+    def port(self) -> int | None:
+        """Configured port, if any."""
+        return self._port
+
+    def _set_state(self, new_state: ConnectionState) -> None:
+        """Transition to a new state and notify callbacks."""
+        self._state = new_state
+        for cb in self._state_callbacks:
+            cb(new_state)
+
+    def discover_port(self) -> int:
+        """Read port from .bikerack-port file, fallback to DEFAULT_PORT.
+
+        Priority: explicit port > port file > DEFAULT_PORT.
+        """
+        if self._port is not None:
+            return self._port
+        if self._project_dir is not None:
+            port_file = self._project_dir / ".bikerack-port"
+            if port_file.exists():
+                try:
+                    return int(port_file.read_text().strip())
+                except (ValueError, OSError):
+                    pass
+        return DEFAULT_PORT
+
+    def subscribe(self, channel: str, handler: MessageHandler) -> None:
+        """Register a handler for messages on a channel."""
+        if channel not in self._handlers:
+            self._handlers[channel] = []
+        self._handlers[channel].append(handler)
+
+    def on_state_change(self, callback: StateChangeCallback) -> None:
+        """Register a callback for connection state changes."""
+        self._state_callbacks.append(callback)
+
+    async def connect(self) -> None:
+        """Connect to WheelHub and start receiving messages.
+
+        Blocks while channel recv loops are running. Returns when all
+        loops complete (via CancelledError or disconnect).
+        """
+        self._stopped = False
+        port = self.discover_port()
+
+        if not self._handlers:
+            self._set_state(ConnectionState.CONNECTED)
+            return
+
+        async def channel_loop(
+            channel: str, handlers: list[MessageHandler]
+        ) -> None:
+            while not self._stopped:
+                try:
+                    url = f"ws://localhost:{port}/ws/{channel}"
+                    ws = await websockets.connect(url)
+                    self._connections[channel] = ws
+                    self._set_state(ConnectionState.CONNECTED)
+                    while True:
+                        raw = await ws.recv()
+                        try:
+                            msg = json.loads(raw)
+                            for h in handlers:
+                                h(msg)
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                except asyncio.CancelledError:
+                    raise
+                except Exception:
+                    if self._stopped:
+                        break
+                    self._set_state(ConnectionState.RECONNECTING)
+                    _sleep = asyncio.create_task(
+                        asyncio.sleep(RECONNECT_DELAY)
+                    )
+                    try:
+                        await _sleep
+                    except asyncio.CancelledError:
+                        _sleep.cancel()
+                        raise
+
+        self._tasks = [
+            asyncio.create_task(channel_loop(ch, hs))
+            for ch, hs in self._handlers.items()
+        ]
+
+        results = await asyncio.gather(*self._tasks, return_exceptions=True)
+        for r in results:
+            if isinstance(r, asyncio.CancelledError):
+                raise r
+
+    async def disconnect(self) -> None:
+        """Disconnect from WheelHub and cancel reconnect timers."""
+        self._stopped = True
+
+        for task in self._tasks:
+            task.cancel()
+
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks = []
+
+        for ws in self._connections.values():
+            try:
+                await ws.close()
+            except Exception:
+                pass
+        self._connections = {}
+
+        self._set_state(ConnectionState.DISCONNECTED)

package/pennyfarthing_scripts/cli.py

@@ -26,6 +26,16 @@ def cli():
     workflow  - Workflow state and phase management
     agent     - Agent session management
     sprint    - Sprint status and story operations
+    debug     - Analysis tools (hotspots, deadcode, healthscore)
+
+    \b
+    Shortcuts (sugar for common operations):
+      status   - Show sprint status (= sprint status)
+      backlog  - Show available stories (= sprint backlog)
+      work     - Start work on a story (= sprint work)
+      story    - Story operations (= sprint story)
+      gui      - Open BikeRack dashboard (= launch gui)
+      tui      - Launch terminal UI (= launch tui)
     """
     pass
 
@@ -35,31 +45,53 @@ from pennyfarthing_scripts.sprint.cli import sprint  # noqa: E402
 
 cli.add_command(sprint)
 
-# Import and register hotspots group
+# Top-level sugar shortcuts for common sprint operations
+cli.add_command(sprint.commands["status"], "status")
+cli.add_command(sprint.commands["backlog"], "backlog")
+cli.add_command(sprint.commands["work"], "work")
+cli.add_command(sprint.commands["story"], "story")
+
+# Import analysis groups
+from pennyfarthing_scripts.deadcode.cli import deadcode  # noqa: E402
+from pennyfarthing_scripts.healthscore.cli import healthscore  # noqa: E402
 from pennyfarthing_scripts.hotspots.cli import hotspots  # noqa: E402
 
-cli.add_command(hotspots)
+
+@cli.group()
+def debug():
+    """Debug and analysis tools.
+
+    \b
+    Subcommands:
+      hotspots     - Git history hotspot detection
+      deadcode     - Dead code detection tools
+      healthscore  - Composite codebase health score
+    """
+    pass
+
+
+debug.add_command(hotspots)
+debug.add_command(deadcode)
+debug.add_command(healthscore)
+
+# Hidden backward-compat aliases
+cli.add_command(hotspots, "hotspots")
+cli.commands["hotspots"].hidden = True
+cli.add_command(deadcode, "deadcode")
+cli.commands["deadcode"].hidden = True
+cli.add_command(healthscore, "healthscore")
+cli.commands["healthscore"].hidden = True
 
 # Import and register jira group
 from pennyfarthing_scripts.jira.cli import jira  # noqa: E402
 
 cli.add_command(jira)
 
-# Import and register deadcode group
-from pennyfarthing_scripts.deadcode.cli import deadcode  # noqa: E402
-
-cli.add_command(deadcode)
-
 # Import and register theme group
 from pennyfarthing_scripts.theme.cli import theme  # noqa: E402
 
 cli.add_command(theme)
 
-# Import and register healthscore group
-from pennyfarthing_scripts.healthscore.cli import healthscore  # noqa: E402
-
-cli.add_command(healthscore)
-
 # Import and register validate group
 from pennyfarthing_scripts.validate.cli import validate  # noqa: E402
 
@@ -70,6 +102,18 @@ from pennyfarthing_scripts.bikerack.cli import bikerack  # noqa: E402
 
 cli.add_command(bikerack)
 
+# Import and register launch group + top-level sugar aliases
+from pennyfarthing_scripts.launch.cli import launch  # noqa: E402
+
+cli.add_command(launch)
+cli.add_command(launch.commands["gui"], "gui")
+cli.add_command(launch.commands["tui"], "tui")
+
+# Import and register bc group
+from pennyfarthing_scripts.bc.cli import bc  # noqa: E402
+
+cli.add_command(bc)
+
 
 @cli.group()
 def agent():
@@ -86,16 +130,16 @@ def agent():
 @click.argument("name")
 @click.option("--session-id", help="Use explicit session ID")
 @click.option("--no-persona", is_flag=True, help="Skip persona loading")
-@click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
 @click.option("--minimal", is_flag=True, help="Skip all context (fastest)")
 @click.option("--full", is_flag=True, help="Include domain docs")
 @click.option("--quiet", is_flag=True, help="Suppress section headers")
-@click.option("--tier", type=click.Choice(["FULL", "REFRESH", "HANDOFF", "MINIMAL"], case_sensitive=False), help="Context tier level")
+@click.option("--tier", type=click.Choice(["full", "refresh", "handoff", "minimal"], case_sensitive=False), help="Context tier level")
 def agent_start(
     name: str,
     session_id: str | None,
     no_persona: bool,
-    json_output: bool,
+    output_json: bool,
     minimal: bool,
     full: bool,
     quiet: bool,
@@ -117,7 +161,7 @@ def agent_start(
         agent_name=name,
         session_id=session_id,
         no_persona=no_persona,
-        json_output=json_output,
+        json_output=output_json,
         minimal=minimal,
         full=full,
         quiet=quiet,

package/pennyfarthing_scripts/healthscore/analyze.py

@@ -557,10 +557,24 @@ def compute_composite_score(
     return weighted_sum / total_weight
 
 
+def _find_project_root(start: Path) -> Path | None:
+    """Find project root by walking up to find .pennyfarthing with config."""
+    current = start
+    while current != current.parent:
+        pf_dir = current / ".pennyfarthing"
+        if pf_dir.is_dir() and (pf_dir / "config.local.yaml").exists():
+            return current
+        current = current.parent
+    return None
+
+
 def get_cache_path(target_path: Path) -> Path:
     """Return the cache directory for a given target path."""
     path_hash = hashlib.md5(str(target_path).encode()).hexdigest()[:12]
-    return target_path / ".pennyfarthing" / ".cache" / "healthscore" / path_hash
+    project_root = _find_project_root(target_path) or _find_project_root(Path.cwd())
+    if project_root:
+        return project_root / ".pennyfarthing" / ".cache" / "healthscore" / path_hash
+    return Path.home() / ".cache" / "pennyfarthing" / "healthscore" / path_hash
 
 
 def read_cached_score(cache_dir: Path, dimension: str, ttl: int) -> float | None:

package/pennyfarthing_scripts/jira/cli.py

@@ -61,8 +61,12 @@ def check(key):
 
 @jira.command()
 @click.argument("key")
-def claim(key):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def claim(key, dry_run):
     """Claim a story (assign to self + move to In Progress)."""
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would claim {key} (assign to self + move to In Progress)")
+        return
     from pennyfarthing_scripts.jira.claim import main as claim_main
 
     raise SystemExit(claim_main([key, "--claim"]))
@@ -320,8 +324,12 @@ def jira_sprint():
 @jira_sprint.command("add")
 @click.argument("sprint_id")
 @click.argument("issue_key")
-def sprint_add(sprint_id, issue_key):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def sprint_add(sprint_id, issue_key, dry_run):
     """Add an issue to a sprint."""
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would add {issue_key} to sprint {sprint_id}")
+        return
     from pennyfarthing_scripts.jira.client import get_client
 
     client = get_client()

package/pennyfarthing_scripts/launch/__init__.py

@@ -0,0 +1 @@
+"""Launch module — mid-session GUI/TUI launcher commands."""

package/pennyfarthing_scripts/launch/cli.py

@@ -0,0 +1,231 @@
+"""Launch CLI — mid-session GUI/TUI launcher commands.
+
+Usage:
+    pf gui                 # Ensure WheelHub, open browser
+    pf tui                 # Start TUI (auto-detects interactivity)
+    pf launch gui          # Full path
+    pf launch tui          # Full path
+    pf launch status       # Is WheelHub running?
+    pf launch stop         # Kill WheelHub
+"""
+
+from __future__ import annotations
+
+import sys
+import webbrowser
+from pathlib import Path
+
+import click
+
+
+def _ensure_wheelhub(project_dir: Path) -> tuple[int, int, bool]:
+    """Ensure WheelHub is running. Returns (port, pid, was_already_running).
+
+    If already running, reuses existing instance.
+    If not, starts a new one and prints a mid-session OTEL note.
+    """
+    from pennyfarthing_scripts.bikerack.launcher import (
+        is_already_running,
+        poll_for_port_file,
+        start_wheelhub,
+        write_pid_file,
+    )
+
+    running, pid, port = is_already_running(project_dir)
+    if running:
+        return port, pid, True
+
+    click.echo("Starting WheelHub server...")
+    proc = start_wheelhub(project_dir)
+    write_pid_file(project_dir, proc.pid)
+    port = poll_for_port_file(project_dir)
+    click.echo(f"WheelHub listening on http://localhost:{port}")
+    click.echo(
+        "Note: OTEL telemetry requires Claude to be started with BikeRack env vars. "
+        "File-based panels (sprint, git, diffs) work independently."
+    )
+    return port, proc.pid, False
+
+
+@click.group()
+def launch():
+    """Mid-session GUI/TUI launcher.
+
+    \b
+    Commands:
+      gui     - Open BikeRack dashboard in browser
+      tui     - Launch terminal UI
+      status  - Show WheelHub running state
+      stop    - Stop WheelHub server
+    """
+    pass
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+@click.option("--no-open", is_flag=True, help="Print URL only, don't open browser.")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def gui(project_dir, no_open, dry_run):
+    """Open BikeRack dashboard in browser.
+
+    Ensures WheelHub is running (starts it if needed), then opens
+    the dashboard URL. Safe to call multiple times — reuses existing server.
+    """
+    from pennyfarthing_scripts.bikerack.launcher import resolve_project_dir
+
+    project_dir = resolve_project_dir(project_dir)
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would launch BikeRack GUI")
+        click.echo(f"  Project: {project_dir}")
+        click.echo("  Actions: ensure WheelHub running, open browser to dashboard")
+        return
+
+    try:
+        port, pid, reused = _ensure_wheelhub(project_dir)
+    except TimeoutError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    url = f"http://localhost:{port}/bikerack"
+
+    if no_open:
+        click.echo(f"Dashboard: {url}")
+    else:
+        click.echo(f"Opening {url}")
+        webbrowser.open(url)
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+@click.option("--foreground", "mode", flag_value="foreground", help="Force TUI in current terminal.")
+@click.option("--detach", "mode", flag_value="detach", help="Force TUI in new Terminal.app window.")
+@click.option("--port", type=int, default=None, help="WheelHub port (skip auto-start).")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def tui(project_dir, mode, port, dry_run):
+    """Launch BikeRack TUI.
+
+    Auto-detects terminal interactivity:
+    - Interactive terminal → runs TUI in foreground
+    - Non-interactive (e.g. Claude's Bash tool) → opens new Terminal.app window
+
+    Use --foreground or --detach to override auto-detection.
+    """
+    from pennyfarthing_scripts.bikerack.launcher import resolve_project_dir
+
+    project_dir = resolve_project_dir(project_dir)
+
+    # Auto-detect mode if not specified
+    if mode is None:
+        mode = "foreground" if sys.stdin.isatty() else "detach"
+
+    if dry_run:
+        click.echo("[DRY-RUN] Would launch BikeRack TUI")
+        click.echo(f"  Project: {project_dir}")
+        click.echo(f"  Mode: {mode}")
+        if port:
+            click.echo(f"  Port: {port} (user-specified, skip WheelHub start)")
+        else:
+            click.echo("  Actions: ensure WheelHub running, launch TUI")
+        return
+
+    # Resolve port — either user-specified or ensure WheelHub is running
+    if port is None:
+        try:
+            port, _pid, _reused = _ensure_wheelhub(project_dir)
+        except TimeoutError as e:
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(1)
+
+    if mode == "foreground":
+        from pennyfarthing_scripts.bikerack.tui import main as tui_main
+
+        tui_main(port=port, project_dir=project_dir)
+    else:
+        _launch_tui_detached(project_dir, port)
+
+
+def _launch_tui_detached(project_dir: Path, port: int) -> None:
+    """Launch TUI in a new Terminal.app window via osascript."""
+    import subprocess
+
+    python = sys.executable
+    cmd = f"{python} -m pennyfarthing_scripts.bikerack.tui --port {port} --project-dir {project_dir}"
+
+    applescript = f'''
+    tell application "Terminal"
+        activate
+        do script "{cmd}"
+    end tell
+    '''
+
+    try:
+        subprocess.run(["osascript", "-e", applescript], check=True, capture_output=True)
+        click.echo(f"TUI launched in new Terminal.app window (port {port})")
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error launching Terminal.app: {e.stderr.decode().strip()}", err=True)
+        click.echo(f"Run manually: {cmd}")
+        sys.exit(1)
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+def status(project_dir):
+    """Show WheelHub running state."""
+    from pennyfarthing_scripts.bikerack.launcher import get_status, resolve_project_dir
+
+    project_dir = resolve_project_dir(project_dir)
+    result = get_status(project_dir)
+
+    if result["running"]:
+        click.echo("WheelHub is running")
+        click.echo(f"  PID: {result['pid']}")
+        click.echo(f"  Port: {result['port']}")
+        click.echo(f"  Dashboard: {result['dashboard']}")
+        if result.get("tui_pid"):
+            click.echo(f"  TUI PID: {result['tui_pid']}")
+    else:
+        click.echo("WheelHub is not running")
+
+
+@launch.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory. Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes.")
+def stop(project_dir, dry_run):
+    """Stop WheelHub server."""
+    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 WheelHub server")
+        click.echo(f"  Project: {project_dir}")
+        return
+
+    result = stop_bikerack(project_dir)
+
+    if result["success"]:
+        click.echo(result["message"])
+    else:
+        click.echo(result["message"], err=True)
+        sys.exit(1)

package/pennyfarthing_scripts/prime/version_sentinel.py

@@ -11,7 +11,6 @@ import json
 from dataclasses import dataclass
 from pathlib import Path
 
-
 SENTINEL_FILENAME = ".installed-version"