@pennyfarthing/core 11.1.1 → 11.2.1

package/pennyfarthing_scripts/hooks.py

@@ -1,451 +1,32 @@
 """
-Shared utilities for Pennyfarthing Claude Code hooks.
+Backward-compatibility shim — hooks utilities moved to hooks/ subpackage.
 
-Provides common functionality for all hooks:
-- Project root detection
-- Port file discovery
-- Settings loading (relay_mode, permission_mode)
-- Context state checking
-- HTTP communication with Cyclist
+All exports are re-imported from pennyfarthing_scripts.hooks (the package).
+Existing code that does `from hooks import ...` or
+`from pennyfarthing_scripts.hooks import ...` continues to work.
 
-All hooks should import from this module for consistency.
-
-Story: MSSCI-12409 - Hook consistency and relay mode compatibility
+This file will be removed in a future version.
 """
 
-import json
-import os
-import sys
-import urllib.error
-import urllib.request
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-import yaml
-
-# =============================================================================
-# Port File Constants
-# =============================================================================
-
-# WheelHub port file - central coordination server for all communication
-# Per ADR-0004: "the hub where all communication converges"
-CYCLIST_PORT_FILE = ".cyclist-port"
-
-# Legacy approval port file (deprecated, for backwards compatibility during migration)
-CYCLIST_APPROVAL_PORT_FILE_LEGACY = ".cyclist-approval-port"
-
-# Default port if file not found
-DEFAULT_CYCLIST_PORT = 7431
-
-# HTTP timeout for Cyclist communication
-HTTP_TIMEOUT_SECONDS = 120
-
-
-# =============================================================================
-# Project Root Detection
-# =============================================================================
-
-
-def find_project_root(start_dir: Path | None = None) -> Path | None:
-    """Find the project root by looking for marker files.
-
-    Searches for (in order):
-    1. .cyclist-port or .cyclist-approval-port (Cyclist is running)
-    2. .pennyfarthing directory
-    3. .claude directory
-
-    Args:
-        start_dir: Directory to start search from (defaults to cwd)
-
-    Returns:
-        Path to project root, or None if not found
-    """
-    current = Path(start_dir) if start_dir else Path.cwd()
-    current = current.resolve()
-
-    while current != current.parent:
-        # Check for Cyclist port files first (indicates Cyclist is running)
-        if (current / CYCLIST_PORT_FILE).exists():
-            return current
-        if (current / CYCLIST_APPROVAL_PORT_FILE_LEGACY).exists():
-            return current
-        # Fall back to directory markers
-        if (current / ".pennyfarthing").is_dir():
-            return current
-        if (current / ".claude").is_dir():
-            return current
-        current = current.parent
-
-    return None
-
-
-# =============================================================================
-# Port File Reading
-# =============================================================================
-
-
-def read_port_file(file_name: str, project_root: Path | None = None) -> int | None:
-    """Read a port number from a Cyclist port file.
-
-    Args:
-        file_name: Name of the port file (.cyclist-port or .cyclist-approval-port)
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        Port number, or None if file not found or invalid
-    """
-    root = project_root or find_project_root()
-    if not root:
-        return None
-
-    port_file = root / file_name
-    if not port_file.exists():
-        return None
-
-    try:
-        content = port_file.read_text().strip()
-        port = int(content)
-        if 0 < port < 65536:
-            return port
-    except (ValueError, OSError):
-        pass
-
-    return None
-
-
-def get_cyclist_port(project_root: Path | None = None) -> int:
-    """Get the WheelHub server port.
-
-    WheelHub is the central coordination server for all Cyclist communication,
-    including hook requests, OTEL, REST APIs, and WebSocket.
-
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        Port number (default if file not found)
-    """
-    port = read_port_file(CYCLIST_PORT_FILE, project_root)
-    if port:
-        return port
-
-    # Fallback to legacy approval port file during migration
-    legacy_port = read_port_file(CYCLIST_APPROVAL_PORT_FILE_LEGACY, project_root)
-    if legacy_port:
-        return legacy_port
-
-    return DEFAULT_CYCLIST_PORT
-
-
-# Alias for backwards compatibility
-get_approval_port = get_cyclist_port
-
-
-# =============================================================================
-# Settings Loading
-# =============================================================================
-
-
-@dataclass
-class CyclistSettings:
-    """Cyclist workflow settings from config.local.yaml."""
-
-    permission_mode: str = "manual"  # plan, manual, accept
-    relay_mode: bool = False
-    bell_mode: bool = False
-    theme: str | None = None
-
-
-def load_settings(project_root: Path | None = None) -> CyclistSettings:
-    """Load Cyclist settings from .pennyfarthing/config.local.yaml.
-
-    Handles legacy setting migrations:
-    - permission_mode: 'turbo' -> 'accept' + relay_mode: True
-    - handoff_mode: 'auto' -> relay_mode: True
-    - auto_handoff: True -> relay_mode: True
-
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        CyclistSettings with current configuration
-    """
-    settings = CyclistSettings()
-
-    root = project_root or find_project_root()
-    if not root:
-        return settings
-
-    config_path = root / ".pennyfarthing" / "config.local.yaml"
-    if not config_path.exists():
-        return settings
-
-    try:
-        with open(config_path) as f:
-            config = yaml.safe_load(f) or {}
-    except (OSError, yaml.YAMLError):
-        return settings
-
-    # Extract theme
-    settings.theme = config.get("theme")
-
-    # Extract workflow settings
-    workflow = config.get("workflow", {})
-    if not isinstance(workflow, dict):
-        return settings
-
-    # Handle permission_mode
-    mode = workflow.get("permission_mode", "manual")
-    if mode == "turbo":
-        # Migrate turbo -> accept + relay_mode
-        settings.permission_mode = "accept"
-        settings.relay_mode = True
-    elif mode in ("plan", "manual", "accept"):
-        settings.permission_mode = mode
-    else:
-        settings.permission_mode = "manual"
-
-    # Handle explicit relay_mode (overrides migration)
-    if "relay_mode" in workflow and isinstance(workflow["relay_mode"], bool):
-        settings.relay_mode = workflow["relay_mode"]
-    elif not settings.relay_mode:
-        # Check legacy settings
-        if workflow.get("handoff_mode") == "auto":
-            settings.relay_mode = True
-        elif workflow.get("auto_handoff") is True:
-            settings.relay_mode = True
-
-    # Handle bell_mode
-    if "bell_mode" in workflow and isinstance(workflow["bell_mode"], bool):
-        settings.bell_mode = workflow["bell_mode"]
-
-    return settings
-
-
-def is_relay_mode_enabled(project_root: Path | None = None) -> bool:
-    """Check if relay mode (auto-handoff) is enabled.
-
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        True if relay mode is enabled
-    """
-    return load_settings(project_root).relay_mode
-
-
-def is_bell_mode_enabled(project_root: Path | None = None) -> bool:
-    """Check if bell mode is enabled.
-
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        True if bell mode is enabled
-    """
-    return load_settings(project_root).bell_mode
-
-
-# =============================================================================
-# Context State
-# =============================================================================
-
-
-@dataclass
-class ContextState:
-    """Current context usage state."""
-
-    used_tokens: int = 0
-    max_tokens: int = 200000
-    percentage: float = 0.0
-    is_high: bool = False  # > 60%
-    is_critical: bool = False  # > 80%
-
-
-def get_context_state(project_root: Path | None = None) -> ContextState:
-    """Get current context usage from Cyclist API.
-
-    Calls Cyclist's /api/context endpoint which runs check-context.sh.
-
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        ContextState with current usage (defaults if Cyclist not running)
-    """
-    state = ContextState()
-
-    port = get_cyclist_port(project_root)
-    url = f"http://127.0.0.1:{port}/api/context"
-
-    try:
-        with urllib.request.urlopen(url, timeout=5) as response:
-            data = json.loads(response.read().decode())
-            state.used_tokens = data.get("used_tokens", 0)
-            state.max_tokens = data.get("max_tokens", 200000)
-            if state.max_tokens > 0:
-                state.percentage = (state.used_tokens / state.max_tokens) * 100
-            state.is_high = state.percentage > 60
-            state.is_critical = state.percentage > 80
-    except (urllib.error.URLError, json.JSONDecodeError, OSError):
-        # Cyclist not running or error - return defaults
-        pass
-
-    return state
-
-
-# =============================================================================
-# Cyclist HTTP Communication
-# =============================================================================
-
-
-def send_to_cyclist(
-    endpoint: str,
-    data: dict[str, Any],
-    port: int | None = None,
-    project_root: Path | None = None,
-    timeout: int = HTTP_TIMEOUT_SECONDS,
-) -> dict[str, Any] | None:
-    """Send a POST request to WheelHub (Cyclist's central coordination server).
-
-    All endpoints go through WheelHub per ADR-0004.
-
-    Args:
-        endpoint: API endpoint path (e.g., "/api/hook-request")
-        data: JSON data to send
-        port: Port to use (auto-detected if not provided)
-        project_root: Project root for port discovery
-        timeout: Request timeout in seconds
-
-    Returns:
-        Response JSON as dict, or None on error
-    """
-    if port is None:
-        port = get_cyclist_port(project_root)
-
-    url = f"http://127.0.0.1:{port}{endpoint}"
-    json_data = json.dumps(data).encode("utf-8")
-
-    request = urllib.request.Request(
-        url,
-        data=json_data,
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
-
-    try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:
-            return json.loads(response.read().decode())
-    except urllib.error.URLError as e:
-        # Connection refused means Cyclist isn't running
-        if "Connection refused" in str(e):
-            return None
-        raise
-    except (json.JSONDecodeError, OSError):
-        return None
-
-
-# =============================================================================
-# Hook Response Formatting
-# =============================================================================
-
-
-@dataclass
-class HookResponse:
-    """Standard hook response for Claude Code."""
-
-    event_name: str
-    decision: str | None = None  # allow, deny, ask (for PreToolUse)
-    reason: str | None = None
-    updated_input: dict[str, Any] | None = None
-    additional_context: str | None = None  # For PostToolUse context injection
-
-    def to_json(self) -> str:
-        """Format as Claude Code hook JSON output."""
-        output: dict[str, Any] = {
-            "hookSpecificOutput": {
-                "hookEventName": self.event_name,
-            }
-        }
-
-        hook_output = output["hookSpecificOutput"]
-
-        if self.decision:
-            hook_output["permissionDecision"] = self.decision
-        if self.reason:
-            hook_output["permissionDecisionReason"] = self.reason
-        if self.updated_input:
-            hook_output["updatedInput"] = self.updated_input
-        if self.additional_context:
-            hook_output["additionalContext"] = self.additional_context
-
-        return json.dumps(output)
-
-
-def output_hook_response(response: HookResponse) -> None:
-    """Output hook response to stdout for Claude Code."""
-    print(response.to_json())
-
-
-def read_stdin_json() -> dict[str, Any]:
-    """Read JSON from stdin (hook input from Claude Code).
-
-    Returns:
-        Parsed JSON as dict
-
-    Raises:
-        ValueError: If input is not valid JSON
-    """
-    data = sys.stdin.read()
-    try:
-        return json.loads(data)
-    except json.JSONDecodeError as e:
-        raise ValueError(f"Invalid JSON input: {e}") from e
-
-
-# =============================================================================
-# Hook Execution Utilities
-# =============================================================================
-
-
-def is_cyclist_running(project_root: Path | None = None) -> bool:
-    """Check if Cyclist server is running.
-
-    Checks the CYCLIST environment variable set by ClaudeService when
-    spawning Claude inside Cyclist. No file I/O, no HTTP, no signals —
-    this runs on every tool invocation and must be instant.
-
-    The project_root parameter is kept for backward compatibility but
-    is no longer used.
-
-    Returns:
-        True if running inside a Cyclist-spawned Claude process
-    """
-    return os.environ.get("CYCLIST") == "1"
-
-
-def should_auto_approve(settings: CyclistSettings) -> bool:
-    """Check if requests should be auto-approved based on settings.
-
-    Auto-approve when permission_mode is 'accept' (formerly turbo).
-
-    Args:
-        settings: Current Cyclist settings
-
-    Returns:
-        True if auto-approval is enabled
-    """
-    return settings.permission_mode == "accept"
-
-
-def should_auto_handoff(settings: CyclistSettings) -> bool:
-    """Check if handoffs should be automatic based on settings.
-
-    Args:
-        settings: Current Cyclist settings
-
-    Returns:
-        True if relay_mode is enabled
-    """
-    return settings.relay_mode
+# Re-export everything from the hooks package
+from pennyfarthing_scripts.hooks import (  # noqa: F401
+    CYCLIST_PORT_FILE,
+    DEFAULT_CYCLIST_PORT,
+    HTTP_TIMEOUT_SECONDS,
+    ContextState,
+    CyclistSettings,
+    HookResponse,
+    find_project_root,
+    get_context_state,
+    get_cyclist_port,
+    is_bell_mode_enabled,
+    is_cyclist_running,
+    is_relay_mode_enabled,
+    load_settings,
+    output_hook_response,
+    read_port_file,
+    read_stdin_json,
+    send_to_cyclist,
+    should_auto_approve,
+    should_auto_handoff,
+)