@pennyfarthing/core 10.2.0 → 10.3.0

package/pennyfarthing_scripts/bikerack/cli.py

@@ -0,0 +1,148 @@
+"""BikeRack CLI — Click-based CLI for bikerack operations.
+
+Usage:
+    pf bikerack [COMMAND]
+
+Commands:
+    start   Start BikeRack mode (default)
+    stop    Stop running BikeRack instance
+    status  Show running state
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def bikerack(ctx):
+    """BikeRack Mode — Decoupled WheelHub dashboard launcher.
+
+    \b
+    Commands:
+      start   - Start WheelHub + Claude CLI (default)
+      stop    - Stop running BikeRack instance
+      status  - Show running state (PID, port, uptime)
+    """
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(start)
+
+
+@bikerack.command()
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    default=None,
+    help="Project directory (where .pennyfarthing/ lives). Falls back to CYCLIST_PROJECT_DIR env var, then cwd.",
+)
+def start(project_dir):
+    """Start BikeRack mode.
+
+    Starts WheelHub in background, waits for readiness,
+    sets OTEL env vars, and execs Claude CLI.
+    """
+    from pennyfarthing_scripts.bikerack.launcher import (
+        build_otel_env,
+        exec_claude,
+        is_already_running,
+        poll_for_port_file,
+        register_cleanup,
+        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()
+
+    running, pid, port = is_already_running(project_dir)
+    if running:
+        click.echo(
+            f"Error: BikeRack is already running (PID {pid}, port {port})",
+            err=True,
+        )
+        click.echo("Use 'pf bikerack stop' to stop it.", err=True)
+        sys.exit(2)
+
+    click.echo("Starting BikeRack mode...")
+    try:
+        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}")
+
+        otel_env = build_otel_env(port)
+        click.echo("Setting OTEL environment variables...")
+
+        register_cleanup(project_dir, proc.pid)
+
+        click.echo(f"Dashboard: http://localhost:{port}/bikerack")
+        click.echo("Starting Claude CLI...")
+        exec_claude(otel_env, project_dir)
+    except TimeoutError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@bikerack.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 stop(project_dir):
+    """Stop running BikeRack instance."""
+    from pennyfarthing_scripts.bikerack.launcher import stop_bikerack
+
+    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"]:
+        click.echo(result["message"])
+    else:
+        click.echo(result["message"], err=True)
+        sys.exit(1)
+
+
+@bikerack.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 BikeRack running state."""
+    from pennyfarthing_scripts.bikerack.launcher import get_status
+
+    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 = get_status(project_dir)
+
+    if result["running"]:
+        click.echo("BikeRack is running")
+        click.echo(f"  PID: {result['pid']}")
+        click.echo(f"  Port: {result['port']}")
+        click.echo(f"  Dashboard: {result['dashboard']}")
+    else:
+        click.echo("BikeRack is not running")

package/pennyfarthing_scripts/bikerack/launcher.py

@@ -0,0 +1,181 @@
+"""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 and .bikerack-pid files."""
+    for name in (".bikerack-port", ".bikerack-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 .bikerack-pid file. Returns None if not found."""
+    try:
+        return int((project_dir / ".bikerack-pid").read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def write_pid_file(project_dir: Path, pid: int) -> None:
+    """Write .bikerack-pid file."""
+    (project_dir / ".bikerack-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 _find_framework_dir() -> Path:
+    """Locate the pennyfarthing framework root from this package's location."""
+    # pennyfarthing_scripts/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. 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)
+    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}
+
+    return {
+        "running": True,
+        "pid": pid,
+        "port": port,
+        "dashboard": f"http://localhost:{port}/bikerack",
+    }

package/pennyfarthing_scripts/cli.py

@@ -65,6 +65,11 @@ from pennyfarthing_scripts.validate.cli import validate  # noqa: E402
 
 cli.add_command(validate)
 
+# Import and register bikerack group
+from pennyfarthing_scripts.bikerack.cli import bikerack  # noqa: E402
+
+cli.add_command(bikerack)
+
 
 @cli.group()
 def agent():

package/pennyfarthing_scripts/healthscore/analyze.py

@@ -490,7 +490,8 @@ async def _probe_agent_context_efficiency(target_path: Path) -> float | None:
     from pennyfarthing_scripts.prime.tiers import ContextTier, load_tier_components
 
     agents = ["sm", "tea", "dev", "reviewer", "architect",
-              "pm", "tech-writer", "ux-designer", "devops", "orchestrator"]
+              "pm", "tech-writer", "ux-designer", "devops", "orchestrator",
+              "ba"]
 
     target_budget = 4000
     scores: list[float] = []

package/pennyfarthing_scripts/prime/__init__.py

@@ -47,6 +47,7 @@ from pennyfarthing_scripts.prime.loader import (
     load_agent_definition,
     load_behavior_guide,
     load_domain_docs,
+    load_repos_topology,
     load_session_context,
     load_sidecars,
     load_sprint_context,
@@ -94,6 +95,7 @@ __all__ = [
     "load_session_context",
     "load_sidecars",
     "load_domain_docs",
+    "load_repos_topology",
     # Workflow detection
     "detect_workflow_state",
     "check_redirect",

package/pennyfarthing_scripts/prime/cli.py

@@ -102,6 +102,7 @@ def _component_header(name: str, agent_name: str | None) -> str:
         "persona_compressed": f"Persona: {agent_name} (compressed)",
         "behavior_guide": "Agent Behavior Guide",
         "sprint_context": "Sprint Context",
+        "repos_topology": "Repos Topology",
         "session_header": "Active Session",
         "session_assessment": "Session Assessment",
         "sidecars": f"Agent Sidecar: {agent_name}",
@@ -118,6 +119,7 @@ def _component_source(name: str, agent_name: str | None, root: Path) -> str | No
         "persona_compressed": None,
         "behavior_guide": ".pennyfarthing/guides/agent-behavior.md",
         "sprint_context": "sprint/current-sprint.yaml",
+        "repos_topology": ".pennyfarthing/repos.yaml",
         "session_header": None,
         "session_assessment": None,
         "sidecars": f".pennyfarthing/sidecars/{agent_name}/",
@@ -474,6 +476,17 @@ def prime(
             _print_header("Sprint Context", quiet)
             print(sprint_content)
 
+    # ==========================================================================
+    # PRIORITY 5.5: Repos Topology
+    # ==========================================================================
+    if not json_output:
+        from pennyfarthing_scripts.prime.loader import load_repos_topology
+
+        topology_content = load_repos_topology(root)
+        if topology_content:
+            _print_header("Repos Topology", quiet)
+            print(topology_content)
+
     # ==========================================================================
     # PRIORITY 6: Session context
     # ==========================================================================