@pennyfarthing/core 10.3.1 → 11.0.0-alpha.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."""