@pennyfarthing/core 7.9.5 → 8.0.1

package/pennyfarthing_scripts/bellmode_hook.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Bell Mode PostToolUse Hook (Python)
+
+This hook is called by Claude Code after each tool execution.
+When bell mode is enabled and there are queued messages, it returns
+the first queued message as additionalContext to be injected into
+Claude's next API call.
+
+Configuration files:
+  .pennyfarthing/config.local.yaml - workflow.bell_mode: true/false
+  .pennyfarthing/bell-queue.json - [{"text": "...", "images": [...]}, ...]
+
+Output format (when injecting):
+  {
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "User feedback: <message>"
+    }
+  }
+
+Output when disabled or queue empty: (nothing - exit 0)
+
+Story: MSSCI-12409 - Hook consistency and WheelHub consolidation
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from hooks import (
+    find_project_root,
+    get_cyclist_port,
+    send_to_cyclist,
+    output_hook_response,
+    HookResponse,
+    is_bell_mode_enabled,
+)
+
+
+def read_bell_queue(project_root: Path) -> list[dict]:
+    """Read the bell message queue.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        List of queued messages, or empty list if none
+    """
+    queue_path = project_root / ".pennyfarthing" / "bell-queue.json"
+    if not queue_path.exists():
+        return []
+
+    try:
+        with open(queue_path) as f:
+            queue = json.load(f)
+            if isinstance(queue, list):
+                return queue
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    return []
+
+
+def dequeue_message(project_root: Path) -> None:
+    """Remove the first message from the queue.
+
+    Args:
+        project_root: Project root directory
+    """
+    queue_path = project_root / ".pennyfarthing" / "bell-queue.json"
+    if not queue_path.exists():
+        return
+
+    try:
+        with open(queue_path) as f:
+            queue = json.load(f)
+
+        if isinstance(queue, list) and len(queue) > 0:
+            queue = queue[1:]  # Remove first item
+            with open(queue_path, "w") as f:
+                json.dump(queue, f)
+    except (json.JSONDecodeError, OSError):
+        pass
+
+
+def notify_cyclist(project_root: Path, message_text: str) -> None:
+    """Notify Cyclist browser that a queued message was consumed.
+
+    Args:
+        project_root: Project root directory
+        message_text: The message text that was consumed
+    """
+    try:
+        send_to_cyclist(
+            endpoint="/api/bell-consumed",
+            data={"text": message_text},
+            project_root=project_root,
+            timeout=5,
+        )
+    except Exception:
+        # Ignore errors - don't block hook
+        pass
+
+
+def main() -> None:
+    """Main entry point for PostToolUse bell mode hook."""
+    try:
+        # Read and discard stdin (required by hook protocol)
+        sys.stdin.read()
+
+        # Find project root
+        project_root = find_project_root()
+        if not project_root:
+            sys.exit(0)
+
+        # Check if bell mode is enabled
+        if not is_bell_mode_enabled(project_root):
+            sys.exit(0)
+
+        # Read queue
+        queue = read_bell_queue(project_root)
+        if not queue:
+            sys.exit(0)
+
+        # Get first message
+        first_message = queue[0]
+        message_text = first_message.get("text", "")
+        if not message_text:
+            sys.exit(0)
+
+        # Output hook response with additionalContext
+        output_hook_response(HookResponse(
+            event_name="PostToolUse",
+            additional_context=f"User feedback: {message_text}",
+        ))
+
+        # Dequeue message and notify Cyclist (in background-ish - after output)
+        dequeue_message(project_root)
+        notify_cyclist(project_root, message_text)
+
+        sys.exit(0)
+
+    except Exception as e:
+        # On error, exit silently
+        print(f"[bellmode-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing_scripts/brownfield/__init__.py

@@ -0,0 +1,35 @@
+"""
+Brownfield discovery module for Pennyfarthing.
+
+Analyzes existing codebases and generates AI-ready documentation.
+"""
+
+from pennyfarthing_scripts.brownfield.discover import (
+    DepthLevel,
+    ProjectType,
+    DiscoveryResult,
+    detect_project_type,
+    detect_tech_stack,
+    scan_directory_structure,
+    detect_architecture_patterns,
+    generate_project_overview,
+    generate_tech_stack_doc,
+    generate_source_tree_doc,
+    generate_ai_guidance_doc,
+    discover,
+)
+
+__all__ = [
+    "DepthLevel",
+    "ProjectType",
+    "DiscoveryResult",
+    "detect_project_type",
+    "detect_tech_stack",
+    "scan_directory_structure",
+    "detect_architecture_patterns",
+    "generate_project_overview",
+    "generate_tech_stack_doc",
+    "generate_source_tree_doc",
+    "generate_ai_guidance_doc",
+    "discover",
+]

package/pennyfarthing_scripts/brownfield/__main__.py

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

package/pennyfarthing_scripts/brownfield/cli.py

@@ -0,0 +1,131 @@
+"""
+Brownfield CLI - Analyze existing codebases.
+
+Usage:
+    python -m pennyfarthing_scripts.brownfield <subcommand> [args]
+
+Subcommands:
+    scan        Scan codebase and generate documentation
+"""
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+from typing import Any
+
+from pennyfarthing_scripts.brownfield.discover import (
+    DepthLevel,
+    discover,
+)
+
+
+def scan(args: list[str]) -> int:
+    """Scan codebase and generate documentation."""
+    parser = argparse.ArgumentParser(
+        prog="brownfield scan",
+        description="Scan codebase and generate AI-ready documentation",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--depth",
+        choices=["quick", "standard", "deep"],
+        default="standard",
+        help="Scan depth level",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        help="Output directory for generated docs",
+    )
+
+    parsed = parser.parse_args(args)
+
+    path = Path(parsed.path).resolve()
+    depth = DepthLevel(parsed.depth)
+    output_dir = Path(parsed.output) if parsed.output else None
+
+    result = asyncio.run(discover(path, depth, output_dir))
+
+    if not result.success:
+        print(f"Error: {result.error}", file=sys.stderr)
+        return 1
+
+    print(f"Discovery complete: {result.project_name}")
+    print(f"Type: {result.project_type.value}")
+    print(f"Tech stack: {len(result.tech_stack)} items detected")
+
+    return 0
+
+
+# Subcommand registry
+SUBCOMMANDS = {
+    "scan": scan,
+}
+
+
+def cli(args: list[str] | None = None) -> int:
+    """Main CLI entry point.
+
+    Args:
+        args: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code
+    """
+    if args is None:
+        args = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="brownfield",
+        description="Brownfield codebase discovery for Pennyfarthing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+    scan [path] [opts]      Scan codebase and generate docs
+
+Examples:
+    brownfield scan
+    brownfield scan /path/to/project
+    brownfield scan --depth deep
+    brownfield scan . --output docs/brownfield
+""",
+    )
+
+    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())