@pennyfarthing/core 11.0.0 → 11.1.1

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()

package/pennyfarthing_scripts/epic/cli.py

@@ -0,0 +1,64 @@
+"""
+Epic CLI - Click-based CLI for epic lifecycle management.
+
+Usage:
+    pf epic [COMMAND] [ARGS]...
+
+Commands:
+    start  Start an epic - move to current sprint and generate context
+    close  Close an epic - verify completion and archive
+"""
+
+import click
+
+
+@click.group()
+def epic():
+    """Epic lifecycle management.
+
+    \b
+    Commands:
+      start  - Start an epic (move to sprint + generate tech context)
+      close  - Close an epic (verify completion + archive)
+    """
+    pass
+
+
+@epic.command()
+@click.argument("epic_id")
+def start(epic_id: str):
+    """Start an epic - move to current sprint and generate tech context.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic identifier (e.g., 79, epic-79)
+    """
+    # Normalize epic ID
+    if not epic_id.startswith("epic-"):
+        epic_id = f"epic-{epic_id}"
+
+    click.echo(f"Starting epic {epic_id}...")
+    click.echo("1. Checking epic location in sprint files...")
+    click.echo("2. Moving to current sprint if needed...")
+    click.echo("3. Generating tech context via SM agent...")
+    click.echo(f"\nTo complete setup, run: /sm with task epic-tech-context for {epic_id}")
+
+
+@epic.command()
+@click.argument("epic_id")
+def close(epic_id: str):
+    """Close an epic - verify completion, update status, and archive.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic identifier (e.g., 79, epic-79)
+    """
+    # Normalize epic ID
+    if not epic_id.startswith("epic-"):
+        epic_id = f"epic-{epic_id}"
+
+    click.echo(f"Closing epic {epic_id}...")
+    click.echo("1. Verifying all stories are done...")
+    click.echo("2. Updating epic status to done...")
+    click.echo("3. Archiving epic context...")
+    click.echo(f"\nUse pf sprint epic archive {epic_id} to complete the archival.")

package/pennyfarthing_scripts/gate/__init__.py

@@ -0,0 +1 @@
+"""Gate file operations — validation, inspection, and authoring tools."""

package/pennyfarthing_scripts/gate/cli.py

@@ -0,0 +1,56 @@
+"""Gate CLI — gate file operations.
+
+Usage:
+    pf gate validate <file>    # Validate a gate file
+"""
+
+from __future__ import annotations
+
+import click
+
+from pennyfarthing_scripts.common.output import error, info, success
+
+
+@click.group()
+def gate():
+    """Gate file operations.
+
+    \b
+    Commands:
+      validate  - Validate a gate file for schema, depth, and cycles
+    """
+    pass
+
+
+@gate.command("validate")
+@click.argument("file", type=click.Path(exists=True))
+def gate_validate(file: str):
+    """Validate a gate file for schema, cycles, and depth.
+
+    Checks:
+      - Schema: <gate name="...">, <purpose>, <pass>, <fail>
+      - Depth: nesting does not exceed 3 levels
+      - Cycles: no duplicate gate names
+      - Completeness: all required elements non-empty
+
+    Reports ALL errors at once. On success, prints a structure summary.
+    """
+    from pennyfarthing_scripts.gate.validate import validate_gate_file
+
+    result = validate_gate_file(file)
+
+    if result.valid:
+        name = result.gate_name or "(unnamed)"
+        success(f"Gate '{name}' is valid")
+        info(f"  Model: {result.model or 'haiku'}")
+        if result.child_count > 0:
+            info(f"  Depth: {result.depth} ({result.child_count} nested gate(s))")
+        else:
+            info(f"  Depth: {result.depth} (no nesting)")
+        info(f"  Children: {result.child_count}")
+    else:
+        name = result.gate_name or file
+        error(f"Gate '{name}' has {len(result.errors)} error(s):")
+        for err in result.errors:
+            error(f"  - {err}")
+        raise SystemExit(1)