@pennyfarthing/core 9.2.0 → 9.3.0

package/pennyfarthing_scripts/hooks.py

@@ -1,455 +0,0 @@
-"""
-Shared utilities for Pennyfarthing Claude Code hooks.
-
-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 hooks should import from this module for consistency.
-
-Story: MSSCI-12409 - Hook consistency and relay mode compatibility
-"""
-
-import json
-import os
-import sys
-import urllib.request
-import urllib.error
-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).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.
-
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
-
-    Returns:
-        True if Cyclist is responding to health checks
-    """
-    port = get_cyclist_port(project_root)
-    url = f"http://127.0.0.1:{port}/health"
-
-    try:
-        with urllib.request.urlopen(url, timeout=2) as response:
-            return response.status == 200
-    except (urllib.error.URLError, OSError):
-        return False
-
-
-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

package/pennyfarthing_scripts/jira/__init__.py

@@ -1,93 +0,0 @@
-"""
-Jira integration package for Pennyfarthing scripts.
-
-This package provides:
-- client: JiraClient REST API wrapper and helper functions
-- sync: Epic sync to Jira
-- bidirectional: Bidirectional sync between YAML and Jira
-- epic: Epic creation
-- story: Single story sync
-- claim: Story claiming
-
-Usage:
-    # Use the client module
-    from pennyfarthing_scripts.jira import JiraClient
-    client = JiraClient()
-    issue = client.get_issue_sync("MSSCI-12345")
-
-    # Use CLI
-    python -m pennyfarthing_scripts.jira <subcommand> [args]
-"""
-
-# Re-export from client for backwards compatibility
-from pennyfarthing_scripts.jira.client import (
-    # Constants
-    GITHUB_TO_JIRA_MAP,
-    JIRA_PROJECT,
-    JIRA_TO_STATUS,
-    JIRA_URL,
-    STATUS_TO_JIRA,
-    # Classes
-    JiraClient,
-    # Functions
-    add_comment,
-    check_dependencies,
-    extract_jira_key,
-    get_client,
-    get_issue,
-    get_jira_field,
-    get_story_points,
-    is_jira_cli_available,
-    map_github_to_jira,
-    map_jira_to_status,
-    map_status_to_jira,
-    update_issue_status,
-)
-
-# Import submodules to make them accessible
-from pennyfarthing_scripts.jira import (
-    bidirectional,
-    claim,
-    client,
-    epic,
-    story,
-    sync,
-)
-
-# CLI entry point - import module, not function, so "from jira import cli" gets the module
-from pennyfarthing_scripts.jira import cli
-from pennyfarthing_scripts.jira.cli import main
-
-__all__ = [
-    # Constants
-    "GITHUB_TO_JIRA_MAP",
-    "JIRA_PROJECT",
-    "JIRA_TO_STATUS",
-    "JIRA_URL",
-    "STATUS_TO_JIRA",
-    # Classes
-    "JiraClient",
-    # Functions
-    "add_comment",
-    "check_dependencies",
-    "extract_jira_key",
-    "get_client",
-    "get_issue",
-    "get_jira_field",
-    "get_story_points",
-    "is_jira_cli_available",
-    "map_github_to_jira",
-    "map_jira_to_status",
-    "map_status_to_jira",
-    "update_issue_status",
-    # Submodules
-    "bidirectional",
-    "claim",
-    "client",
-    "epic",
-    "story",
-    "sync",
-    # CLI
-    "cli",
-    "main",
-]

package/pennyfarthing_scripts/jira/__main__.py

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