@pennyfarthing/core 10.3.1 → 11.0.0-alpha.0

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

@@ -0,0 +1,103 @@
+"""Version sentinel detection for auto-update in prime.
+
+MSSCI-14698: Reads .pennyfarthing/.installed-version sentinel and compares
+against current package version. On mismatch, signals that auto-update
+is needed.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+SENTINEL_FILENAME = ".installed-version"
+
+
+@dataclass
+class VersionCheckResult:
+    """Result of version mismatch check."""
+
+    needs_update: bool
+    installed_version: str | None
+    package_version: str
+
+
+def read_sentinel_version(project_root: Path) -> str | None:
+    """Read version from .pennyfarthing/.installed-version sentinel.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Version string, or None if sentinel doesn't exist or is empty
+    """
+    sentinel_path = project_root / ".pennyfarthing" / SENTINEL_FILENAME
+
+    if not sentinel_path.exists():
+        return None
+
+    content = sentinel_path.read_text().strip()
+    return content or None
+
+
+def get_package_version(project_root: Path) -> str:
+    """Get the current package version from VERSION file or package.json.
+
+    Checks VERSION file first (plain text), then falls back to package.json.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Version string
+
+    Raises:
+        FileNotFoundError: If no version source found
+    """
+    # Try VERSION file first
+    version_file = project_root / "VERSION"
+    if version_file.exists():
+        version = version_file.read_text().strip()
+        if version:
+            return version
+
+    # Fall back to package.json
+    package_json = project_root / "package.json"
+    if package_json.exists():
+        data = json.loads(package_json.read_text())
+        version = data.get("version", "")
+        if version:
+            return version
+
+    raise FileNotFoundError(
+        f"No VERSION file or package.json found in {project_root}"
+    )
+
+
+def check_version_mismatch(
+    project_root: Path,
+    *,
+    package_version: str | None = None,
+) -> VersionCheckResult:
+    """Compare sentinel version against package version.
+
+    Args:
+        project_root: Project root directory
+        package_version: Override package version (for testing).
+            If None, reads from VERSION file.
+
+    Returns:
+        VersionCheckResult with needs_update flag
+    """
+    if package_version is None:
+        package_version = get_package_version(project_root)
+
+    installed = read_sentinel_version(project_root)
+    needs_update = installed != package_version
+
+    return VersionCheckResult(
+        needs_update=needs_update,
+        installed_version=installed,
+        package_version=package_version,
+    )

package/pennyfarthing_scripts/session_start_hook.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Session start hook — initialize environment for Claude Code session.
+
+Handles:
+1. Session directory setup and logging
+2. Checkpoint validation (cross-session drift detection)
+3. WheelHub auto-start (ensure BikeRack server is running)
+4. OTEL auto-configuration via CLAUDE_ENV_FILE
+
+Called by Claude Code SessionStart hook via shell wrapper.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _read_input() -> dict:
+    """Read JSON from stdin (hook protocol)."""
+    raw = sys.stdin.read()
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+def _setup_session_dir(project_dir: Path, session_id: str, source_type: str) -> None:
+    """Ensure .session directory exists and log session start."""
+    session_dir = project_dir / ".session"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    (session_dir / "agents").mkdir(exist_ok=True)
+
+    from datetime import datetime, timezone
+
+    timestamp = datetime.now(timezone.utc).isoformat()
+    log_file = session_dir / "session-log.txt"
+    with open(log_file, "a") as f:
+        f.write(f"{timestamp} | Session {source_type}: {session_id}\n")
+
+
+def _validate_checkpoint(project_dir: Path) -> None:
+    """Validate previous session checkpoint for cross-session drift detection."""
+    try:
+        import subprocess
+
+        script_dir = Path(__file__).resolve().parent.parent
+        checkpoint_lib = script_dir / "pennyfarthing-dist" / "scripts" / "lib" / "checkpoint.sh"
+
+        if not checkpoint_lib.exists():
+            return
+
+        result = subprocess.run(
+            ["bash", "-c", f'source "{checkpoint_lib}" && checkpoint_restore session_state'],
+            capture_output=True,
+            text=True,
+            cwd=str(project_dir),
+            timeout=5,
+        )
+
+        prev_state = result.stdout.strip()
+        if not prev_state:
+            return
+
+        # Parse checkpoint data
+        fields = {}
+        for part in prev_state.split(";"):
+            if "=" in part:
+                k, v = part.split("=", 1)
+                fields[k] = v
+
+        prev_sha = fields.get("sha", "")
+        if not prev_sha:
+            return
+
+        # Get current git SHA
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=str(project_dir),
+            timeout=5,
+        )
+        current_sha = result.stdout.strip()
+        if not current_sha or current_sha == prev_sha:
+            return
+
+        # Log drift
+        from datetime import datetime, timezone
+
+        timestamp = datetime.now(timezone.utc).isoformat()
+        session_dir = project_dir / ".session"
+
+        warning = f"CROSS_SESSION_DRIFT: Git changed (was: {prev_sha}, now: {current_sha})"
+        if fields.get("story"):
+            warning += f" | Story: {fields['story']}"
+        if fields.get("agent"):
+            warning += f" | Agent: {fields['agent']}"
+
+        with open(session_dir / "session-log.txt", "a") as f:
+            f.write(f"{timestamp} | {warning}\n")
+
+        drift_entry = f"{timestamp} | prev_sha={prev_sha} | current_sha={current_sha}"
+        for key in ("story", "agent", "phase"):
+            if fields.get(key):
+                drift_entry += f" | {key}={fields[key]}"
+        with open(session_dir / "drift-log.txt", "a") as f:
+            f.write(drift_entry + "\n")
+
+    except Exception:
+        pass
+
+
+def _ensure_wheelhub(project_dir: Path) -> int | None:
+    """Auto-start WheelHub if not already running. Returns port or None."""
+    from pennyfarthing_scripts.bikerack.launcher import (
+        is_already_running,
+        poll_for_port_file,
+        start_wheelhub,
+        write_pid_file,
+    )
+
+    # Skip if full Cyclist is running
+    cyclist_port_file = project_dir / ".cyclist-port"
+    if cyclist_port_file.exists():
+        try:
+            return int(cyclist_port_file.read_text().strip())
+        except (ValueError, OSError):
+            return None
+
+    # Check if BikeRack WheelHub is already running
+    running, _pid, port = is_already_running(project_dir)
+    if running:
+        return port
+
+    # Start WheelHub
+    try:
+        proc = start_wheelhub(project_dir)
+        write_pid_file(project_dir, proc.pid)
+        return poll_for_port_file(project_dir)
+    except Exception:
+        return None
+
+
+def _write_env_file(project_dir: Path, session_id: str, otel_port: int | None) -> None:
+    """Write environment variables to CLAUDE_ENV_FILE."""
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    if not env_file:
+        return
+
+    lines = [
+        "# Pennyfarthing core environment",
+        f'export PROJECT_ROOT="{project_dir}"',
+        f'export SESSION_ID="{session_id}"',
+    ]
+
+    if otel_port is not None:
+        lines.extend([
+            "# OTEL auto-configuration for Cyclist/WheelHub",
+            'export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"',
+            f'export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:{otel_port}"',
+        ])
+
+    with open(env_file, "a") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def main() -> None:
+    """Entry point for SessionStart hook."""
+    try:
+        input_data = _read_input()
+        session_id = input_data.get("session_id", "unknown")
+        source_type = input_data.get("source", "unknown")
+
+        project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+
+        _setup_session_dir(project_dir, session_id, source_type)
+        _validate_checkpoint(project_dir)
+
+        otel_port = _ensure_wheelhub(project_dir)
+        _write_env_file(project_dir, session_id, otel_port)
+
+    except Exception:
+        pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()