@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/pf/patch_mode.py

@@ -0,0 +1,449 @@
+"""Patch Mode - Interrupt-Driven Bug Fix Workflow.
+
+Story: 74-1 - Implement Patch Mode
+Epic: epic-74 (Patch Mode Workflow)
+
+This module provides the core functionality for Patch Mode, allowing developers
+to interrupt their current workflow to fix blocking bugs and then resume work
+with full context preserved.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pf.common.config import get_project_root
+
+
+@dataclass
+class PatchState:
+    """State preserved when entering patch mode."""
+
+    story_id: str
+    workflow: str
+    phase: str
+    agent: str
+    feature_branch: str
+
+    def to_yaml(self) -> str:
+        """Serialize state to YAML string."""
+        return yaml.dump(asdict(self), default_flow_style=False)
+
+    @classmethod
+    def from_yaml(cls, yaml_str: str) -> PatchState:
+        """Deserialize state from YAML string."""
+        data = yaml.safe_load(yaml_str)
+        return cls(**data)
+
+
+class PatchStack:
+    """Stack of patch states for nested patch support."""
+
+    def __init__(self, stack_file: Path | None = None) -> None:
+        """Initialize patch stack.
+
+        Args:
+            stack_file: Path to patch-stack.yaml file
+        """
+        if stack_file is None:
+            root = get_project_root()
+            stack_file = root / ".session" / "patch-stack.yaml"
+
+        self.stack_file = stack_file
+        self._stack: list[PatchState] = []
+
+        # Load existing stack from file if it exists
+        if self.stack_file.exists():
+            self._load()
+
+    def _load(self) -> None:
+        """Load stack from file."""
+        content = yaml.safe_load(self.stack_file.read_text())
+        if content and "stack" in content:
+            self._stack = [
+                PatchState(**item) for item in content["stack"]
+            ]
+
+    def _save(self) -> None:
+        """Save stack to file."""
+        # Ensure parent directory exists
+        self.stack_file.parent.mkdir(parents=True, exist_ok=True)
+
+        content = {
+            "stack": [asdict(state) for state in self._stack]
+        }
+        self.stack_file.write_text(yaml.dump(content, default_flow_style=False))
+
+    def push(self, state: PatchState) -> None:
+        """Push state onto stack."""
+        self._stack.append(state)
+        self._save()
+
+    def pop(self) -> PatchState:
+        """Pop state from stack."""
+        if not self._stack:
+            raise IndexError("Cannot pop from empty patch stack")
+        state = self._stack.pop()
+        self._save()
+        return state
+
+    def depth(self) -> int:
+        """Return current stack depth."""
+        return len(self._stack)
+
+    def peek(self) -> PatchState | None:
+        """Peek at top of stack without popping."""
+        return self._stack[-1] if self._stack else None
+
+
+def get_patch_stack(stack_file: Path | None = None) -> PatchStack:
+    """Get the patch stack instance.
+
+    Args:
+        stack_file: Optional path to stack file
+
+    Returns:
+        PatchStack instance
+    """
+    return PatchStack(stack_file=stack_file)
+
+
+def _sanitize_branch_name(description: str) -> str:
+    """Sanitize description for use in branch name.
+
+    Args:
+        description: Raw description string
+
+    Returns:
+        Sanitized string safe for git branch names
+    """
+    # Replace special characters with dashes
+    sanitized = re.sub(r'[^a-zA-Z0-9\s-]', '', description)
+    # Replace spaces with dashes
+    sanitized = re.sub(r'\s+', '-', sanitized)
+    # Remove multiple consecutive dashes
+    sanitized = re.sub(r'-+', '-', sanitized)
+    # Lowercase and strip
+    sanitized = sanitized.lower().strip('-')
+    # Truncate if too long
+    return sanitized[:50]
+
+
+def create_patch_branch(
+    description: str,
+    feature_branch: str,
+    repo_path: Path | None = None,
+) -> str:
+    """Create a patch branch from the current feature branch.
+
+    Args:
+        description: Description for branch name
+        feature_branch: Current feature branch
+        repo_path: Path to git repository
+
+    Returns:
+        Name of created patch branch
+
+    Raises:
+        ValueError: If description is empty or produces empty branch name
+    """
+    if not description or not description.strip():
+        raise ValueError("Patch description cannot be empty")
+
+    timestamp = int(time.time())
+    sanitized_desc = _sanitize_branch_name(description)
+
+    if not sanitized_desc:
+        raise ValueError(
+            f"Patch description '{description}' produces empty branch name after sanitization"
+        )
+
+    branch_name = f"patch/{sanitized_desc}-{timestamp}"
+
+    cwd = str(repo_path) if repo_path else None
+
+    # Create and checkout the new branch from current HEAD (feature branch)
+    result = subprocess.run(
+        ["git", "checkout", "-b", branch_name],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(f"Git branch creation failed: {result.stderr}")
+
+    return branch_name
+
+
+def merge_patch_branch(
+    patch_branch: str,
+    feature_branch: str,
+    repo_path: Path | None = None,
+) -> None:
+    """Merge patch branch back to feature branch and delete it.
+
+    Args:
+        patch_branch: Name of patch branch
+        feature_branch: Target feature branch
+        repo_path: Path to git repository
+    """
+    cwd = str(repo_path) if repo_path else None
+
+    # Checkout feature branch
+    result = subprocess.run(
+        ["git", "checkout", feature_branch],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Git checkout failed: {result.stderr}")
+
+    # Merge patch branch
+    result = subprocess.run(
+        ["git", "merge", patch_branch],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Git merge failed: {result.stderr}")
+
+    # Delete patch branch
+    result = subprocess.run(
+        ["git", "branch", "-d", patch_branch],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Git branch delete failed: {result.stderr}")
+
+
+def enter_patch_mode(
+    description: str,
+    story_id: str,
+    workflow: str,
+    phase: str,
+    agent: str,
+    feature_branch: str,
+    repo_path: Path | None = None,
+    stack_file: Path | None = None,
+) -> dict[str, Any]:
+    """Enter patch mode by saving state and creating patch branch.
+
+    Args:
+        description: Description of the patch/fix
+        story_id: Current story ID
+        workflow: Current workflow type
+        phase: Current workflow phase
+        agent: Current agent
+        feature_branch: Current feature branch name
+        repo_path: Path to git repository
+        stack_file: Path to patch-stack.yaml
+
+    Returns:
+        Dict with patch_branch and other metadata
+    """
+    # Save current state to stack
+    state = PatchState(
+        story_id=story_id,
+        workflow=workflow,
+        phase=phase,
+        agent=agent,
+        feature_branch=feature_branch,
+    )
+
+    stack = get_patch_stack(stack_file)
+    stack.push(state)
+
+    # Create patch branch
+    try:
+        patch_branch = create_patch_branch(
+            description=description,
+            feature_branch=feature_branch,
+            repo_path=repo_path,
+        )
+    except Exception as e:
+        # Rollback stack on failure
+        stack.pop()
+        raise RuntimeError(f"Git error: {e}") from e
+
+    return {
+        "patch_branch": patch_branch,
+        "agent": "dev",  # Patch mode is always dev
+        "story_id": story_id,
+        "description": description,
+    }
+
+
+def exit_patch_mode(
+    patch_branch: str | None = None,
+    repo_path: Path | None = None,
+    stack_file: Path | None = None,
+) -> dict[str, Any]:
+    """Exit patch mode by merging and restoring state.
+
+    Args:
+        patch_branch: Name of patch branch to merge
+        repo_path: Path to git repository
+        stack_file: Path to patch-stack.yaml
+
+    Returns:
+        Dict with restored state and handoff_marker
+    """
+    stack = get_patch_stack(stack_file)
+
+    # Peek at state first - don't pop until operations succeed
+    state = stack.peek()
+    if state is None:
+        raise RuntimeError("Cannot exit patch mode: stack is empty")
+
+    # Merge patch branch back to feature branch if provided
+    # Do this BEFORE popping state so we can recover on failure
+    if patch_branch:
+        merge_patch_branch(
+            patch_branch=patch_branch,
+            feature_branch=state.feature_branch,
+            repo_path=repo_path,
+        )
+
+    # Only pop after successful merge
+    stack.pop()
+
+    # Build handoff marker for original agent
+    handoff_marker = f"<!-- CYCLIST:HANDOFF:/{state.agent} -->"
+
+    return {
+        "story_id": state.story_id,
+        "workflow": state.workflow,
+        "phase": state.phase,
+        "agent": state.agent,
+        "feature_branch": state.feature_branch,
+        "handoff_marker": handoff_marker,
+        "relay_mode_disabled": False,
+    }
+
+
+def restore_workflow_state(
+    repo_path: Path | None = None,
+    stack_file: Path | None = None,
+) -> dict[str, Any]:
+    """Restore workflow state from patch stack.
+
+    Args:
+        repo_path: Path to git repository
+        stack_file: Path to patch-stack.yaml
+
+    Returns:
+        Dict with restored state
+    """
+    stack = get_patch_stack(stack_file)
+
+    # Peek at state first - don't pop until checkout succeeds
+    state = stack.peek()
+    if state is None:
+        raise RuntimeError("Cannot restore workflow state: stack is empty")
+
+    cwd = str(repo_path) if repo_path else None
+
+    # Checkout the original feature branch
+    result = subprocess.run(
+        ["git", "checkout", state.feature_branch],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(f"Git checkout failed: {result.stderr}")
+
+    # Only pop after successful checkout
+    stack.pop()
+
+    return {
+        "story_id": state.story_id,
+        "workflow": state.workflow,
+        "phase": state.phase,
+        "agent": state.agent,
+        "feature_branch": state.feature_branch,
+    }
+
+
+def log_patch_to_session(
+    session_file: Path,
+    description: str,
+    commit_sha: str,
+) -> None:
+    """Log completed patch to session file.
+
+    Args:
+        session_file: Path to session markdown file
+        description: Patch description
+        commit_sha: Git commit SHA
+    """
+    content = session_file.read_text()
+
+    # Find the Patches section and add entry
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    patch_entry = f"- **{timestamp}**: {description} (`{commit_sha}`)\n"
+
+    # Look for the marker comment or Patches header
+    if "<!-- Patches applied during this story will be logged here -->" in content:
+        content = content.replace(
+            "<!-- Patches applied during this story will be logged here -->",
+            f"<!-- Patches applied during this story will be logged here -->\n{patch_entry}"
+        )
+    elif "## Patches" in content:
+        # Insert after the Patches header
+        idx = content.find("## Patches")
+        next_newline = content.find("\n", idx)
+        content = content[:next_newline + 1] + "\n" + patch_entry + content[next_newline + 1:]
+    else:
+        # Append at end
+        content += f"\n## Patches\n\n{patch_entry}"
+
+    session_file.write_text(content)
+
+
+def generate_patch_commit_message(
+    description: str,
+    story_id: str,
+) -> str:
+    """Generate commit message for patch.
+
+    Format: fix(patch): description [from:STORY-ID]
+
+    Args:
+        description: Patch description
+        story_id: Story ID the patch is from
+
+    Returns:
+        Formatted commit message
+    """
+    return f"""fix(patch): {description} [from:{story_id}]
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+"""
+
+
+def is_in_patch_mode(stack_file: Path | None = None) -> bool:
+    """Check if currently in patch mode.
+
+    Args:
+        stack_file: Path to patch-stack.yaml
+
+    Returns:
+        True if patch stack is non-empty
+    """
+    stack = get_patch_stack(stack_file)
+    return stack.depth() > 0

package/pennyfarthing-dist/pf/preflight/__init__.py

@@ -0,0 +1,17 @@
+"""Preflight checks for Pennyfarthing workflows.
+
+This package provides async preflight checks that run in parallel
+to validate story completion before finishing.
+"""
+
+from pf.preflight.finish import (
+    PreflightIssue,
+    PreflightResult,
+    run_finish_preflight,
+)
+
+__all__ = [
+    "PreflightResult",
+    "PreflightIssue",
+    "run_finish_preflight",
+]

package/pennyfarthing-dist/pf/preflight/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for python -m pf.preflight
+"""
+
+import sys
+
+from pf.preflight.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())

package/pennyfarthing-dist/pf/preflight/cli.py

@@ -0,0 +1,141 @@
+"""
+Preflight CLI - Fan-out CLI for preflight checks.
+
+Usage:
+    python -m pf.preflight <subcommand> [args]
+
+Subcommands:
+    finish      Run finish preflight checks
+"""
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from pf.preflight.finish import run_finish_preflight
+
+
+def finish(args: list[str]) -> int:
+    """Run finish preflight checks."""
+    parser = argparse.ArgumentParser(
+        prog="preflight finish",
+        description="Run finish preflight checks in parallel",
+    )
+    parser.add_argument(
+        "story_id",
+        help="Story identifier (e.g., 31-10)",
+    )
+    parser.add_argument(
+        "--branch", "-b",
+        required=True,
+        help="Feature branch name",
+    )
+    parser.add_argument(
+        "--jira", "-j",
+        help="Jira issue key (optional, skips Jira checks if absent)",
+    )
+    parser.add_argument(
+        "--repo", "-r",
+        help="Repository name for PR lookup (optional)",
+    )
+    parser.add_argument(
+        "--project-root", "-p",
+        type=Path,
+        help="Project root path (defaults to cwd)",
+    )
+    parser.add_argument(
+        "--format", "-f",
+        choices=["json", "yaml"],
+        default="json",
+        help="Output format (default: json)",
+    )
+
+    parsed = parser.parse_args(args)
+
+    # Run async preflight
+    result = asyncio.run(run_finish_preflight(
+        story_id=parsed.story_id,
+        branch=parsed.branch,
+        jira_key=parsed.jira,
+        repo=parsed.repo,
+        project_root=parsed.project_root,
+    ))
+
+    # Output result
+    result_dict = result.to_dict()
+
+    if parsed.format == "yaml":
+        try:
+            import yaml
+            print(yaml.dump(result_dict, default_flow_style=False, sort_keys=False))
+        except ImportError:
+            print("YAML output requires PyYAML. Falling back to JSON.", file=sys.stderr)
+            print(json.dumps(result_dict, indent=2))
+    else:
+        print(json.dumps(result_dict, indent=2))
+
+    # Return non-zero if not ready to finish
+    return 0 if result.ready_to_finish else 1
+
+
+# Subcommand registry
+SUBCOMMANDS = {
+    "finish": finish,
+}
+
+
+def cli(args: list[str] | None = None) -> int:
+    """Main CLI entry point."""
+    if args is None:
+        args = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="preflight",
+        description="Preflight checks for Pennyfarthing workflows",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+    finish <story_id> --branch <branch> [--jira <key>]
+        Run finish preflight checks in parallel
+
+Examples:
+    preflight finish 31-10 --branch feat/31-10-feature --jira MSSCI-12345
+    preflight finish 63-9 -b feat/63-9-fanout -j MSSCI-12413 -f yaml
+""",
+    )
+
+    parser.add_argument(
+        "subcommand",
+        nargs="?",
+        choices=list(SUBCOMMANDS.keys()),
+        help="Subcommand to run",
+    )
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments for subcommand",
+    )
+
+    parsed = parser.parse_args(args)
+
+    if not parsed.subcommand:
+        parser.print_help()
+        return 0
+
+    handler = SUBCOMMANDS.get(parsed.subcommand)
+    if handler:
+        return handler(parsed.args)
+    else:
+        print(f"Unknown subcommand: {parsed.subcommand}", file=sys.stderr)
+        return 1
+
+
+def main(args: list[str] | None = None) -> int:
+    """Alias for cli()."""
+    return cli(args)
+
+
+if __name__ == "__main__":
+    sys.exit(cli())

package/pennyfarthing-dist/pf/pretooluse_hook.py

@@ -0,0 +1,10 @@
+"""
+Backward-compatibility shim — pretooluse hook moved to hooks/cyclist_pretooluse.py.
+
+This file will be removed in a future version.
+"""
+
+from pf.hooks.cyclist_pretooluse import main  # noqa: F401
+
+if __name__ == "__main__":
+    main()