@pennyfarthing/core 11.0.0-alpha.0 → 11.1.0

package/pennyfarthing_scripts/bikerack/debug_panel.py

@@ -0,0 +1,218 @@
+"""DebugPanel — Context usage and token stats for BikeRack TUI.
+
+Story 103-17: Port of the React DebugPanel. Subscribes to /ws/context
+and /ws/token-stats, renders context usage (tokens, percent, tier) and
+token consumption stats (input, output, cache, cost).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+
+# Tier → Rich style mapping
+_TIER_STYLES: dict[str, str] = {
+    "FULL": "bold green",
+    "REFRESH": "bold yellow",
+    "HANDOFF": "bold cyan",
+    "MINIMAL": "bold red",
+}
+
+
+def _safe_int(value: Any) -> int | None:
+    """Safely convert a value to int, returning None on failure."""
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _safe_float(value: Any) -> float | None:
+    """Safely convert a value to float, returning None on failure."""
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _format_tokens(value: Any) -> str:
+    """Format a token count with comma separators."""
+    n = _safe_int(value)
+    if n is None:
+        return "—"
+    return f"{n:,}"
+
+
+class DebugPanel(BasePanel):
+    """Context usage and token stats panel.
+
+    Subscribes to both ``context`` and ``token-stats`` WebSocket channels.
+    Renders context usage (tokens, percentage, tier) and token consumption
+    stats (input, output, cache read/write, cost).
+    """
+
+    channel: str = "context"
+    panel_name: str = "Debug"
+    icon: str = PANEL_ICONS["debug"][0]
+
+    def __init__(self, client: Any = None, **kwargs: Any) -> None:
+        super().__init__(client=client, **kwargs)
+        self._context_data: dict[str, Any] | None = None
+        self._token_stats: dict[str, Any] | None = None
+
+    def on_mount(self) -> None:
+        """Subscribe to both context and token-stats channels."""
+        self._mounted = True
+        if self._client is not None:
+            self._client.subscribe("context", self._handle_context_message)
+            self._client.subscribe("token-stats", self._handle_token_stats_message)
+
+    def _handle_context_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming context channel message."""
+        if message is None:
+            return
+        ctx = message.get("context")
+        if isinstance(ctx, dict):
+            self._context_data = ctx
+        else:
+            self._context_data = {}
+        self._rerender()
+
+    def _handle_token_stats_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming token-stats channel message."""
+        if message is None:
+            return
+        self._token_stats = message
+        self._rerender()
+
+    def _rerender(self) -> None:
+        """Re-render with the latest data from both channels."""
+        rendered = self.render_panel(self._context_data or {})
+        try:
+            self.update(rendered)
+        except Exception:
+            pass
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render combined context usage and token stats."""
+        parts: list[Any] = []
+
+        # --- Context Usage Section ---
+        ctx = self._context_data
+        if ctx:
+            parts.append(_render_context(ctx))
+        elif not self._token_stats:
+            return Text("No context data", style="dim italic")
+
+        # --- Token Stats Section ---
+        if self._token_stats:
+            if parts:
+                parts.append(Text(""))  # spacer
+            parts.append(_render_token_stats(self._token_stats))
+
+        if not parts:
+            return Text("No context data", style="dim italic")
+
+        return Group(*parts)
+
+
+def _render_context(ctx: dict[str, Any]) -> Any:
+    """Render context usage section."""
+    parts: list[Any] = []
+
+    # Tier badge
+    tier = ctx.get("tier")
+    if tier and isinstance(tier, str):
+        style = _TIER_STYLES.get(tier, "bold")
+        tier_text = Text()
+        tier_text.append(tier, style=style)
+        savings = _tier_savings(tier)
+        if savings > 0:
+            tier_text.append(f" {savings}% savings", style="dim")
+        parts.append(tier_text)
+
+    # Token usage
+    tokens = _safe_int(ctx.get("tokens"))
+    percent = _safe_int(ctx.get("percent"))
+    baseline = _safe_int(ctx.get("baseline"))
+    available = _safe_int(ctx.get("available"))
+
+    if tokens is not None:
+        usage_text = Text()
+        usage_text.append(f"{tokens:,}", style="bold")
+        if baseline is not None and available is not None:
+            total = baseline + available
+            usage_text.append(f" / {total:,}")
+        usage_text.append(" tokens")
+        if percent is not None:
+            usage_text.append(f" ({percent}%)")
+        parts.append(usage_text)
+
+    # Breakdown: baseline / conversation / available
+    if baseline is not None:
+        breakdown = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
+        breakdown.add_column("Label", style="dim")
+        breakdown.add_column("Value", justify="right")
+        breakdown.add_row("System Prompt", _format_tokens(baseline))
+        usable = _safe_int(ctx.get("usableTokens"))
+        if usable is not None:
+            breakdown.add_row("Conversation", _format_tokens(usable))
+        if available is not None:
+            breakdown.add_row("Available", _format_tokens(available))
+        parts.append(breakdown)
+
+    if not parts:
+        return Text("No context data", style="dim italic")
+
+    return Group(*parts)
+
+
+def _render_token_stats(stats: dict[str, Any]) -> Any:
+    """Render token stats section."""
+    table = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
+    table.add_column("Stat", style="dim")
+    table.add_column("Value", justify="right")
+
+    rows: list[tuple[str, str]] = []
+
+    input_t = _safe_int(stats.get("inputTokens"))
+    if input_t is not None:
+        rows.append(("Input", f"{input_t:,}"))
+
+    output_t = _safe_int(stats.get("outputTokens"))
+    if output_t is not None:
+        rows.append(("Output", f"{output_t:,}"))
+
+    cache_read = _safe_int(stats.get("cacheReadTokens"))
+    if cache_read is not None:
+        rows.append(("Cache Read", f"{cache_read:,}"))
+
+    cache_write = _safe_int(stats.get("cacheCreationTokens"))
+    if cache_write is not None:
+        rows.append(("Cache Write", f"{cache_write:,}"))
+
+    cost = _safe_float(stats.get("totalCostUsd"))
+    if cost is not None and cost > 0:
+        rows.append(("Cost", f"${cost:.4f}"))
+
+    if not rows:
+        return Text("No token stats", style="dim italic")
+
+    for label, value in rows:
+        table.add_row(label, value)
+
+    return table
+
+
+def _tier_savings(tier: str) -> int:
+    """Calculate token savings percentage for a tier vs FULL."""
+    return {"FULL": 0, "REFRESH": 85, "HANDOFF": 82, "MINIMAL": 95}.get(tier, 0)

package/pennyfarthing_scripts/bikerack/diffs_panel.py

@@ -2,12 +2,16 @@
 
 Story 103-18: Subscribes to /ws/diffs, renders file diffs with syntax
 highlighting using Rich. File headers, added/removed line coloring, line numbers.
+
+Story 103-19: Large diff handling — truncation at 1000 lines, pagination,
+temp file storage for very large diffs (>5000 lines), non-blocking rendering.
 """
 
 from __future__ import annotations
 
 import os
 import re
+import tempfile
 from typing import Any
 
 from rich.console import Group
@@ -16,6 +20,16 @@ from rich.text import Text
 
 from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
 
+#: Default max content lines rendered per page before truncation kicks in.
+DEFAULT_LINE_LIMIT = 1000
+
+#: Diffs with more raw lines than this threshold are written to temp files.
+TEMP_FILE_THRESHOLD = 5000
+
+#: Skip syntax highlighting for diffs larger than this to maintain rendering performance.
+#: At 5000+ lines, syntax highlighting cost becomes prohibitive for <100ms frame time.
+HIGHLIGHT_THRESHOLD = 5000
+
 
 class DiffsPanel(BasePanel):
     """Diff rendering panel with syntax highlighting.
@@ -23,25 +37,99 @@ class DiffsPanel(BasePanel):
     Subscribes to the ``diffs`` WebSocket channel and renders
     file diffs with syntax highlighting, colored added/removed lines,
     file headers, and line numbers.
+
+    Large diffs (>1000 content lines) are truncated with a text indicator
+    and support pagination via ``next_page()`` / ``prev_page()``.
+    Very large diffs (>5000 lines) use temp file storage for memory efficiency.
     """
 
     channel: str = "diffs"
     panel_name: str = "Diffs"
     icon: str = PANEL_ICONS["diffs"][0]
 
+    def __init__(self, client=None, **kwargs):
+        super().__init__(client=client, **kwargs)
+        self._current_page: int = 0
+        self._max_page: int = 0
+        self._temp_files: list[str] = []
+
+    def next_page(self) -> None:
+        """Advance to the next page of truncated diff content."""
+        if self._current_page < self._max_page:
+            self._current_page += 1
+
+    def prev_page(self) -> None:
+        """Go back to the previous page of truncated diff content."""
+        if self._current_page > 0:
+            self._current_page -= 1
+
+    def handle_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming WebSocket message with pagination reset and temp management."""
+        if not self._mounted or message is None:
+            return
+        self._current_page = 0
+        self._cleanup_temp_files()
+        self._store_large_diffs(message)
+        super().handle_message(message)
+
+    def on_unmount(self) -> None:
+        """Clean up temp files and mark panel as unmounted."""
+        self._cleanup_temp_files()
+        super().on_unmount()
+
     def render_panel(self, payload: dict[str, Any]) -> Any:
-        """Render diff data from WebSocket payload."""
+        """Render diff data from WebSocket payload with truncation/pagination."""
         diffs = payload.get("diffs", [])
         if not diffs:
             return Text("No diffs yet", style="dim italic")
 
         parts: list[Any] = []
+        max_total = 0
         for diff_entry in diffs:
-            parts.extend(_render_file_diff(diff_entry))
+            # Skip syntax highlighting for very large diffs (>2000 lines) for performance
+            raw_diff = diff_entry.get("diff", "")
+            skip_highlight = raw_diff.count("\n") > HIGHLIGHT_THRESHOLD
+
+            file_parts, total_lines = _render_file_diff(
+                diff_entry,
+                page=self._current_page,
+                page_size=DEFAULT_LINE_LIMIT,
+                skip_highlight=skip_highlight,
+            )
+            parts.extend(file_parts)
             parts.append(Text(""))  # separator between files
+            max_total = max(max_total, total_lines)
+
+        # Track max page for pagination bounds
+        if max_total > DEFAULT_LINE_LIMIT:
+            self._max_page = -(-max_total // DEFAULT_LINE_LIMIT) - 1
+        else:
+            self._max_page = 0
 
         return Group(*parts)
 
+    def _store_large_diffs(self, message: dict[str, Any]) -> None:
+        """Write very large diffs to temp files for memory-efficient access."""
+        diffs = message.get("diffs", [])
+        for diff_entry in diffs:
+            raw_diff = diff_entry.get("diff", "")
+            if raw_diff.count("\n") > TEMP_FILE_THRESHOLD:
+                fd, path = tempfile.mkstemp(
+                    prefix="bikerack_diff_", suffix=".diff"
+                )
+                with os.fdopen(fd, "w") as f:
+                    f.write(raw_diff)
+                self._temp_files.append(path)
+
+    def _cleanup_temp_files(self) -> None:
+        """Remove any temp files created for large diff storage."""
+        for path in self._temp_files:
+            try:
+                os.unlink(path)
+            except OSError:
+                pass
+        self._temp_files.clear()
+
 
 _LANG_MAP: dict[str, str] = {
     ".py": "python", ".ts": "typescript", ".tsx": "tsx",
@@ -74,8 +162,23 @@ def _highlight_code(code: str, language: str) -> Text:
         return Text(code)
 
 
-def _render_file_diff(diff_entry: dict[str, Any]) -> list[Any]:
-    """Render a single file's diff as a list of Rich renderables."""
+def _render_file_diff(
+    diff_entry: dict[str, Any],
+    page: int = 0,
+    page_size: int = DEFAULT_LINE_LIMIT,
+    skip_highlight: bool = False,
+) -> tuple[list[Any], int]:
+    """Render a single file's diff as a list of Rich renderables.
+
+    Args:
+        diff_entry: Diff data from WebSocket payload
+        page: Current page number for pagination
+        page_size: Lines per page for truncation
+        skip_highlight: Skip syntax highlighting for performance on large diffs
+
+    Returns:
+        Tuple of (renderable_parts, total_content_line_count).
+    """
     path = diff_entry.get("path", "unknown")
     status = diff_entry.get("status", "")
     additions = diff_entry.get("additions")
@@ -92,19 +195,70 @@ def _render_file_diff(diff_entry: dict[str, Any]) -> list[Any]:
 
     language = _detect_language(path)
     parts: list[Any] = [header]
-    parts.extend(_parse_diff_lines(raw_diff, language))
-    return parts
+    rendered_lines, total_lines = _parse_diff_lines(
+        raw_diff, language, page=page, page_size=page_size, skip_highlight=skip_highlight,
+    )
+    parts.extend(rendered_lines)
+
+    # Add truncation/pagination indicator if content was truncated
+    if total_lines > page_size:
+        total_pages = -(-total_lines // page_size)  # ceil division
+        current_page_display = page + 1
+        visible_end = min((page + 1) * page_size, total_lines)
+
+        if page == 0:
+            indicator = (
+                f"Showing first {visible_end} of {total_lines} lines"
+                f" — Page {current_page_display} / {total_pages}"
+            )
+        else:
+            visible_start = page * page_size + 1
+            indicator = (
+                f"Showing lines {visible_start}-{visible_end}"
+                f" of {total_lines} lines"
+                f" — Page {current_page_display} / {total_pages}"
+            )
+        parts.append(Text(indicator, style="dim yellow"))
 
+    return parts, total_lines
 
-def _parse_diff_lines(raw_diff: str, language: str = "text") -> list[Any]:
-    """Parse unified diff output into styled Rich Text lines with syntax highlighting."""
+
+def _parse_diff_lines(
+    raw_diff: str,
+    language: str = "text",
+    page: int = 0,
+    page_size: int = DEFAULT_LINE_LIMIT,
+    skip_highlight: bool = False,
+) -> tuple[list[Any], int]:
+    """Parse unified diff output into styled Rich Text lines with syntax highlighting.
+
+    Optimized single-pass streaming:
+    - Only highlight lines within current page range (unless skip_highlight=True)
+    - Count total lines without building objects for them
+    - Scan entire diff to get accurate total for pagination
+
+    Args:
+        raw_diff: Raw unified diff string
+        language: Programming language for syntax highlighting
+        page: Current page number for pagination
+        page_size: Lines per page
+        skip_highlight: Skip syntax highlighting for performance on large diffs
+
+    Returns:
+        Tuple of (rendered_lines, total_content_line_count).
+    """
     if not raw_diff or not raw_diff.strip():
-        return []
+        return [], 0
 
     result: list[Any] = []
     line_num = 0
+    content_idx = 0
+    start = page * page_size
+    end = start + page_size
+    current_hunk_header = None
 
     for line in raw_diff.split("\n"):
+        # Skip diff metadata lines (not counted as content)
         if line.startswith("diff --git") or line.startswith("index "):
             continue
         if line.startswith("---") or line.startswith("+++"):
@@ -113,34 +267,56 @@ def _parse_diff_lines(raw_diff: str, language: str = "text") -> list[Any]:
             continue
         if line.startswith("rename "):
             continue
+        if line == "":
+            continue
 
         if line.startswith("Binary files"):
-            result.append(Text(line, style="dim italic"))
+            if start <= content_idx < end:
+                result.append(Text(line, style="dim italic"))
+            content_idx += 1
         elif line.startswith("@@"):
+            # @@ line is metadata, extract line number but don't count as content
+            current_hunk_header = line
             match = re.match(r"@@ -\d+(?:,\d+)? \+(\d+)", line)
             if match:
                 line_num = int(match.group(1)) - 1
-            result.append(Text(line, style="cyan"))
+            if start <= content_idx < end:
+                result.append(Text(current_hunk_header, style="cyan"))
         elif line.startswith("+"):
             line_num += 1
-            t = Text()
-            t.append(f"{line_num:4d} ", style="dim green")
-            t.append_text(_highlight_code(line[1:], language))
-            result.append(t)
+            if start <= content_idx < end:
+                t = Text()
+                t.append(f"{line_num:4d} ", style="dim green")
+                if not skip_highlight:
+                    t.append_text(_highlight_code(line[1:], language))
+                else:
+                    t.append(line[1:])
+                result.append(t)
+            content_idx += 1
         elif line.startswith("-"):
-            t = Text()
-            t.append("   - ", style="red")
-            t.append_text(_highlight_code(line[1:], language))
-            result.append(t)
+            if start <= content_idx < end:
+                t = Text()
+                t.append("   - ", style="red")
+                if not skip_highlight:
+                    t.append_text(_highlight_code(line[1:], language))
+                else:
+                    t.append(line[1:])
+                result.append(t)
+            content_idx += 1
         elif line.startswith(" "):
             line_num += 1
-            t = Text()
-            t.append(f"{line_num:4d} ", style="dim")
-            t.append_text(_highlight_code(line[1:], language))
-            result.append(t)
-        elif line == "":
-            continue
+            if start <= content_idx < end:
+                t = Text()
+                t.append(f"{line_num:4d} ", style="dim")
+                if not skip_highlight:
+                    t.append_text(_highlight_code(line[1:], language))
+                else:
+                    t.append(line[1:])
+                result.append(t)
+            content_idx += 1
         else:
-            result.append(Text(line, style="dim"))
+            if start <= content_idx < end:
+                result.append(Text(line, style="dim"))
+            content_idx += 1
 
-    return result
+    return result, content_idx

package/pennyfarthing_scripts/cli.py

@@ -26,6 +26,9 @@ def cli():
     workflow  - Workflow state and phase management
     agent     - Agent session management
     sprint    - Sprint status and story operations
+    git       - Repository operations (status, cleanup, branches, release)
+    session   - Session lifecycle (new, continue, parallel)
+    epic      - Epic lifecycle (start, close)
     debug     - Analysis tools (hotspots, deadcode, healthscore)
 
     \b
@@ -114,6 +117,26 @@ from pennyfarthing_scripts.bc.cli import bc  # noqa: E402
 
 cli.add_command(bc)
 
+# Import and register handoff group
+from pennyfarthing_scripts.handoff.cli import handoff  # noqa: E402
+
+cli.add_command(handoff)
+
+# Import and register git group
+from pennyfarthing_scripts.git_group.cli import git  # noqa: E402
+
+cli.add_command(git)
+
+# Import and register session group
+from pennyfarthing_scripts.session.cli import session  # noqa: E402
+
+cli.add_command(session)
+
+# Import and register epic group
+from pennyfarthing_scripts.epic.cli import epic  # noqa: E402
+
+cli.add_command(epic)
+
 
 @cli.group()
 def agent():
@@ -244,6 +267,97 @@ def workflow_handoff(next_agent: str):
     click.echo("---")
 
 
+@cli.command("help")
+@click.argument("group", required=False)
+def help_cmd(group: str | None):
+    """Context-aware help for Pennyfarthing commands.
+
+    \b
+    Arguments:
+      GROUP  - Optional command group name (sprint, git, session, epic, jira, theme, workflow, etc.)
+    """
+
+    import yaml
+
+    from pennyfarthing_scripts.common.config import get_project_root
+
+    root = get_project_root()
+    registry_path = root / "pennyfarthing-dist" / "command-registry.yaml"
+
+    if not registry_path.is_file():
+        click.echo("Command registry not found. Run /pf-health-check.", err=True)
+        raise SystemExit(1)
+
+    registry = yaml.safe_load(registry_path.read_text())
+
+    if group is None:
+        # Show overview
+        click.echo("Pennyfarthing CLI — Command Reference")
+        click.echo("=" * 45)
+        click.echo("")
+        click.echo("Resource Groups:")
+        for name, grp in registry.get("groups", {}).items():
+            cli_cmd = grp.get("cli", "")
+            slash = grp.get("slash", "")
+            desc = grp.get("description", "")
+            parts = []
+            if slash:
+                parts.append(slash)
+            if cli_cmd:
+                parts.append(cli_cmd)
+            ref = ", ".join(parts)
+            click.echo(f"  {name:<12} {desc:<45} ({ref})")
+        click.echo("")
+        click.echo("Standalone:")
+        for name, cmd in registry.get("standalone", {}).items():
+            slash = cmd.get("slash", "")
+            desc = cmd.get("description", "")
+            click.echo(f"  {name:<12} {desc:<45} ({slash})")
+        click.echo("")
+        click.echo("Use 'pf help <group>' for detailed commands.")
+        return
+
+    # Show specific group
+    groups = registry.get("groups", {})
+    if group not in groups:
+        click.echo(f"Unknown group: {group}", err=True)
+        click.echo(f"Available groups: {', '.join(groups.keys())}", err=True)
+        raise SystemExit(1)
+
+    grp = groups[group]
+    click.echo(f"{group} — {grp.get('description', '')}")
+    click.echo("-" * 45)
+    if grp.get("cli"):
+        click.echo(f"CLI:   {grp['cli']}")
+    if grp.get("slash"):
+        click.echo(f"Slash: {grp['slash']}")
+    if grp.get("skill"):
+        click.echo(f"Skill: {grp['skill']}")
+    click.echo("")
+
+    commands = grp.get("commands", {})
+    if commands:
+        click.echo("Commands:")
+        for cmd_name, cmd in commands.items():
+            args = cmd.get("args", "")
+            desc = cmd.get("description", "")
+            if args:
+                click.echo(f"  {cmd_name} {args:<20} {desc}")
+            else:
+                click.echo(f"  {cmd_name:<25} {desc}")
+
+    subgroups = grp.get("subgroups", {})
+    for sg_name, sg in subgroups.items():
+        click.echo(f"\n  {sg_name} — {sg.get('description', '')}")
+        for cmd_name, cmd in sg.get("commands", {}).items():
+            args = cmd.get("args", "")
+            desc = cmd.get("description", "")
+            if args:
+                click.echo(f"    {cmd_name} {args:<18} {desc}")
+            else:
+                click.echo(f"    {cmd_name:<23} {desc}")
+
+
 def main():
     """Entry point for the CLI."""
     cli()