@pennyfarthing/core 10.1.0 → 10.3.0

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/brownfield/__init__.py

@@ -6,17 +6,17 @@ Analyzes existing codebases and generates AI-ready documentation.
 
 from pennyfarthing_scripts.brownfield.discover import (
     DepthLevel,
-    ProjectType,
     DiscoveryResult,
+    ProjectType,
+    detect_architecture_patterns,
     detect_project_type,
     detect_tech_stack,
-    scan_directory_structure,
-    detect_architecture_patterns,
+    discover,
+    generate_ai_guidance_doc,
     generate_project_overview,
-    generate_tech_stack_doc,
     generate_source_tree_doc,
-    generate_ai_guidance_doc,
-    discover,
+    generate_tech_stack_doc,
+    scan_directory_structure,
 )
 
 __all__ = [

package/pennyfarthing_scripts/brownfield/__main__.py

@@ -1,6 +1,7 @@
 """Entry point for python -m pennyfarthing_scripts.brownfield."""
 
 import sys
+
 from pennyfarthing_scripts.brownfield.cli import cli
 
 if __name__ == "__main__":

package/pennyfarthing_scripts/brownfield/cli.py

@@ -12,7 +12,6 @@ import argparse
 import asyncio
 import sys
 from pathlib import Path
-from typing import Any
 
 from pennyfarthing_scripts.brownfield.discover import (
     DepthLevel,

package/pennyfarthing_scripts/brownfield/discover.py

@@ -11,7 +11,6 @@ import re
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Literal
 
 # Try to import tomllib (Python 3.11+) or fall back to tomli
 try:
@@ -642,7 +641,7 @@ def generate_ai_guidance_doc(result: DiscoveryResult) -> str:
 
     if result.tech_stack:
         # Get unique tech names
-        tech_names = sorted(set(item.name.lower() for item in result.tech_stack))[:10]
+        tech_names = sorted({item.name.lower() for item in result.tech_stack})[:10]
         lines.extend([
             "## Key Technologies",
             "",

package/pennyfarthing_scripts/cli.py

@@ -31,35 +31,45 @@ def cli():
 
 
 # Import and register sprint group (lazy registration preserves startup time)
-from pennyfarthing_scripts.sprint.cli import sprint
+from pennyfarthing_scripts.sprint.cli import sprint  # noqa: E402
 
 cli.add_command(sprint)
 
 # Import and register hotspots group
-from pennyfarthing_scripts.hotspots.cli import hotspots
+from pennyfarthing_scripts.hotspots.cli import hotspots  # noqa: E402
 
 cli.add_command(hotspots)
 
 # Import and register jira group
-from pennyfarthing_scripts.jira.cli import jira
+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
+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
+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
+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
+
+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/codemarkers/__init__.py

@@ -2,18 +2,22 @@
 Code marker analysis — TODO, FIXME, HACK, XXX detection with git blame.
 
 Story 80-1: Python codemarkers module.
+Story 80-2: @deprecated detection and caller cross-reference.
 """
 
+from pennyfarthing_scripts.codemarkers.analyze import analyze_deprecations, analyze_repo
 from pennyfarthing_scripts.codemarkers.models import (
     CodeMarker,
     CodeMarkersResult,
+    DeprecationMarker,
     MarkerSummary,
 )
-from pennyfarthing_scripts.codemarkers.analyze import analyze_repo
 
 __all__ = [
     "CodeMarker",
     "CodeMarkersResult",
+    "DeprecationMarker",
     "MarkerSummary",
+    "analyze_deprecations",
     "analyze_repo",
 ]

package/pennyfarthing_scripts/codemarkers/analyze.py

@@ -12,12 +12,13 @@ import fnmatch
 import re
 import time
 from collections import defaultdict
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
 from pennyfarthing_scripts.codemarkers.models import (
     CodeMarker,
     CodeMarkersResult,
+    DeprecationMarker,
     MarkerSummary,
 )
 
@@ -286,7 +287,7 @@ async def analyze_repo(
             if author_time > 0:
                 age_days = (now - author_time) / 86400
                 date_str = datetime.fromtimestamp(
-                    author_time, tz=timezone.utc
+                    author_time, tz=UTC
                 ).isoformat()
             else:
                 age_days = 0.0
@@ -324,3 +325,177 @@ async def analyze_repo(
         markers=markers,
         summary=summary,
     )
+
+
+# =============================================================================
+# @deprecated detection (Story 80-2)
+# =============================================================================
+
+# File extensions to scan for @deprecated JSDoc tags
+_DEPRECATION_EXTENSIONS = frozenset({".ts", ".tsx", ".js"})
+
+# Pattern to find @deprecated in JSDoc comments
+_DEPRECATED_PATTERN = re.compile(r"@deprecated\b(.*)")
+
+# Pattern to extract symbol name from export declarations
+_SYMBOL_PATTERN = re.compile(
+    r"export\s+(?:default\s+)?(?:function|class|const|let|var|interface|type|enum)\s+(\w+)"
+)
+
+
+def _grep_deprecations(root: Path, excludes: list[str]) -> list[dict]:
+    """Scan TypeScript/JS files for @deprecated JSDoc tags.
+
+    For each @deprecated tag found, extracts the symbol name from the
+    next export declaration line following the JSDoc block.
+
+    Args:
+        root: Directory to scan recursively
+        excludes: Glob patterns for files/dirs to skip
+
+    Returns:
+        List of dicts: {path, line, symbol, text}
+    """
+    results: list[dict] = []
+
+    for file_path in sorted(root.rglob("*")):
+        if not file_path.is_file():
+            continue
+
+        if file_path.suffix.lower() not in _DEPRECATION_EXTENSIONS:
+            continue
+
+        rel_path = str(file_path.relative_to(root))
+
+        if _should_exclude(rel_path, excludes):
+            continue
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="strict")
+        except (UnicodeDecodeError, OSError):
+            continue
+
+        lines = content.split("\n")
+        for line_num, line_text in enumerate(lines, start=1):
+            match = _DEPRECATED_PATTERN.search(line_text)
+            if not match:
+                continue
+
+            # Extract the @deprecated text
+            deprecated_text = line_text.strip()
+
+            # Look ahead for the symbol declaration
+            symbol = ""
+            for ahead in lines[line_num:]:  # line_num is already 1-indexed, so lines[line_num:] starts after current
+                sym_match = _SYMBOL_PATTERN.search(ahead)
+                if sym_match:
+                    symbol = sym_match.group(1)
+                    break
+                # Stop looking if we hit another JSDoc or a blank line after the block closes
+                stripped = ahead.strip()
+                if stripped and not stripped.startswith("*") and not stripped.startswith("/") and not stripped == "":
+                    break
+
+            if symbol:
+                results.append({
+                    "path": rel_path,
+                    "line": line_num,
+                    "symbol": symbol,
+                    "text": deprecated_text,
+                })
+
+    return results
+
+
+def _count_callers(
+    symbol: str, root: Path, defining_file: str
+) -> tuple[int, list[str]]:
+    """Count files that import/reference a deprecated symbol.
+
+    Greps all TypeScript/JS files for the symbol name, excluding
+    the file that defines it.
+
+    Args:
+        symbol: The deprecated symbol name to search for
+        root: Directory to scan
+        defining_file: Relative path of the file defining the symbol (excluded)
+
+    Returns:
+        (caller_count, list_of_caller_paths)
+    """
+    callers: list[str] = []
+
+    for file_path in sorted(root.rglob("*")):
+        if not file_path.is_file():
+            continue
+
+        if file_path.suffix.lower() not in _DEPRECATION_EXTENSIONS:
+            continue
+
+        rel_path = str(file_path.relative_to(root))
+
+        if rel_path == defining_file:
+            continue
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="strict")
+        except (UnicodeDecodeError, OSError):
+            continue
+
+        if symbol in content:
+            callers.append(rel_path)
+
+    return len(callers), callers
+
+
+async def analyze_deprecations(
+    path: Path,
+    excludes: list[str] | None = None,
+) -> dict:
+    """Analyze a directory for @deprecated symbols and their callers.
+
+    Args:
+        path: Directory to scan
+        excludes: Additional file patterns to exclude
+
+    Returns:
+        Dict with success, deprecations (list of DeprecationMarker),
+        summary (total_deprecations, deprecations_with_callers), and
+        optionally error.
+    """
+    resolved = Path(path).resolve()
+
+    if not resolved.exists():
+        return {
+            "success": False,
+            "error": f"Path not found: {resolved}",
+        }
+
+    all_excludes = DEFAULT_EXCLUDES + (excludes or [])
+
+    raw = _grep_deprecations(resolved, all_excludes)
+
+    markers: list[DeprecationMarker] = []
+    for item in raw:
+        count, caller_list = _count_callers(
+            item["symbol"], resolved, item["path"]
+        )
+        markers.append(DeprecationMarker(
+            path=item["path"],
+            line=item["line"],
+            symbol=item["symbol"],
+            text=item["text"],
+            caller_count=count,
+            callers=caller_list,
+        ))
+
+    with_callers = sum(1 for m in markers if m.caller_count > 0)
+
+    return {
+        "success": True,
+        "deprecations": markers,
+        "summary": {
+            "total_deprecations": len(markers),
+            "deprecations_with_callers": with_callers,
+        },
+    }

package/pennyfarthing_scripts/codemarkers/cli.py

@@ -127,3 +127,53 @@ def summary(repo, repo_path, days, top, fmt, output_file, exclude):
     else:
         from pennyfarthing_scripts.codemarkers.formatters import format_summary
         format_summary(result, file=click.get_text_stream("stdout"))
+
+
+def _run_deprecation_analysis(repo_path, exclude):
+    """Run deprecation analysis and return result dict."""
+    from pennyfarthing_scripts.codemarkers.analyze import analyze_deprecations
+
+    excludes = list(exclude) if exclude else None
+    if repo_path:
+        p = Path(repo_path).resolve()
+    else:
+        from pennyfarthing_scripts.common.config import get_project_root
+        p = get_project_root()
+
+    return asyncio.run(analyze_deprecations(p, excludes))
+
+
+@codemarkers.command()
+@_common_options
+def deprecations(repo, repo_path, days, top, fmt, output_file, exclude):
+    """Scan for @deprecated symbols and cross-reference callers."""
+    result = _run_deprecation_analysis(repo_path, exclude)
+
+    if fmt == "json":
+        import json
+        from dataclasses import asdict
+
+        output = {
+            "success": result["success"],
+            "deprecations": [asdict(m) for m in result.get("deprecations", [])],
+            "summary": result.get("summary", {}),
+        }
+        text = json.dumps(output, indent=2)
+    else:
+        lines = []
+        deps = result.get("deprecations", [])
+        summary = result.get("summary", {})
+        lines.append(f"Total deprecations: {summary.get('total_deprecations', 0)}")
+        lines.append(f"With active callers: {summary.get('deprecations_with_callers', 0)}")
+        lines.append("")
+        for m in deps[:top]:
+            callers_str = f" ({m.caller_count} callers)" if m.caller_count else ""
+            lines.append(f"  {m.symbol} @ {m.path}:{m.line}{callers_str}")
+            lines.append(f"    {m.text}")
+        text = "\n".join(lines)
+
+    if output_file:
+        Path(output_file).write_text(text)
+        click.echo(f"Output written to {output_file}", err=True)
+    else:
+        click.echo(text)

package/pennyfarthing_scripts/codemarkers/formatters.py

@@ -16,7 +16,6 @@ from typing import TextIO
 from pennyfarthing_scripts.codemarkers.models import (
     CodeMarker,
     CodeMarkersResult,
-    MarkerSummary,
 )
 
 

package/pennyfarthing_scripts/codemarkers/models.py

@@ -43,3 +43,18 @@ class CodeMarkersResult:
     markers: list[CodeMarker] = field(default_factory=list)
     summary: MarkerSummary | None = None
     error: str | None = None
+
+
+@dataclass
+class DeprecationMarker:
+    """A deprecated symbol with caller cross-reference data (Story 80-2).
+
+    Stub: Dev will implement full functionality.
+    """
+
+    path: str
+    line: int
+    symbol: str
+    text: str
+    caller_count: int = 0
+    callers: list[str] = field(default_factory=list)

package/pennyfarthing_scripts/common/__init__.py

@@ -5,8 +5,16 @@ This package provides shared utilities used across all CLI tools:
 - config: Project configuration loading
 """
 
+from pennyfarthing_scripts.common.config import (
+    find_project_root,
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+)
 from pennyfarthing_scripts.common.output import (
     Colors,
+    _colorize,
+    _supports_color,
     bold,
     debug,
     dim,
@@ -16,15 +24,6 @@ from pennyfarthing_scripts.common.output import (
     info,
     success,
     warn,
-    _colorize,
-    _supports_color,
-)
-
-from pennyfarthing_scripts.common.config import (
-    find_project_root,
-    get_project_root,
-    load_pennyfarthing_config,
-    load_yaml_config,
 )
 
 __all__ = [

package/pennyfarthing_scripts/common/config.py

@@ -78,7 +78,7 @@ def load_yaml_config(path: Path) -> dict[str, Any] | None:
     if not path.exists():
         return None
 
-    with open(path, "r") as f:
+    with open(path) as f:
         return yaml.safe_load(f)
 
 

package/pennyfarthing_scripts/complexity/__init__.py

@@ -5,8 +5,8 @@ Wraps eslint with complexity rules to extract per-file metrics:
 cyclomatic complexity, function length, nesting depth, and line counts.
 """
 
-from pennyfarthing_scripts.complexity.models import FileComplexity, ComplexityResult
 from pennyfarthing_scripts.complexity.analyze import analyze_complexity
+from pennyfarthing_scripts.complexity.models import ComplexityResult, FileComplexity
 
 __all__ = [
     "FileComplexity",