code-muse 0.0.1__py3-none-any.whl

code_muse/hook_engine/validator.py

@@ -0,0 +1,144 @@
+"""
+Configuration validation for hooks.
+
+Validates hook configuration dictionaries and provides actionable error messages.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+VALID_EVENT_TYPES = [
+    "PreToolUse",
+    "PostToolUse",
+    "SessionStart",
+    "SessionEnd",
+    "PreCompact",
+    "UserPromptSubmit",
+    "Notification",
+    "Stop",
+    "SubagentStop",
+]
+
+VALID_HOOK_TYPES = ["command", "prompt"]
+
+
+def validate_hooks_config(config: dict[str, Any]) -> tuple[bool, list[str]]:
+    """
+    Validate a hooks configuration dictionary.
+
+    Returns:
+        Tuple of (is_valid, list_of_error_messages)
+    """
+    errors: list[str] = []
+
+    if not isinstance(config, dict):
+        return False, ["Configuration must be a dictionary"]
+
+    for event_type, hook_groups in config.items():
+        if event_type.startswith("_"):
+            continue  # skip comment keys
+
+        if event_type not in VALID_EVENT_TYPES:
+            errors.append(
+                f"Unknown event type '{event_type}'. "
+                f"Valid types: {', '.join(VALID_EVENT_TYPES)}"
+            )
+            continue
+
+        if not isinstance(hook_groups, list):
+            errors.append(f"'{event_type}' must be a list of hook groups")
+            continue
+
+        for i, group in enumerate(hook_groups):
+            if not isinstance(group, dict):
+                errors.append(
+                    f"'{event_type}[{i}]' must be a dict with 'matcher' and 'hooks'"
+                )
+                continue
+
+            if "matcher" not in group:
+                errors.append(f"'{event_type}[{i}]' missing required field 'matcher'")
+
+            if "hooks" not in group:
+                errors.append(f"'{event_type}[{i}]' missing required field 'hooks'")
+                continue
+
+            if not isinstance(group["hooks"], list):
+                errors.append(f"'{event_type}[{i}].hooks' must be a list")
+                continue
+
+            for j, hook in enumerate(group["hooks"]):
+                hook_errors = _validate_hook(event_type, i, j, hook)
+                errors.extend(hook_errors)
+
+    return len(errors) == 0, errors
+
+
+def _validate_hook(
+    event_type: str, group_idx: int, hook_idx: int, hook: Any
+) -> list[str]:
+    errors: list[str] = []
+    prefix = f"'{event_type}[{group_idx}].hooks[{hook_idx}]'"
+
+    if not isinstance(hook, dict):
+        return [f"{prefix} must be a dict"]
+
+    hook_type = hook.get("type")
+    if not hook_type:
+        errors.append(f"{prefix} missing required field 'type'")
+    elif hook_type not in VALID_HOOK_TYPES:
+        errors.append(
+            f"{prefix} invalid type '{hook_type}'. Must be one of: {', '.join(VALID_HOOK_TYPES)}"
+        )
+
+    if hook_type == "command" and not hook.get("command"):
+        errors.append(f"{prefix} missing required field 'command' for type 'command'")
+    elif hook_type == "prompt" and not hook.get("prompt") and not hook.get("command"):
+        errors.append(
+            f"{prefix} missing required field 'prompt' (or 'command') for type 'prompt'"
+        )
+
+    timeout = hook.get("timeout")
+    if timeout is not None:
+        if not isinstance(timeout, (int, float)) or timeout < 100:
+            errors.append(f"{prefix} 'timeout' must be >= 100ms, got: {timeout}")
+
+    return errors
+
+
+def format_validation_report(
+    is_valid: bool, errors: list[str], suggestions: list[str | None] = None
+) -> str:
+    lines = []
+    if is_valid:
+        lines.append("✓ Configuration is valid")
+    else:
+        lines.append(f"✗ Configuration has {len(errors)} error(s):")
+        for error in errors:
+            lines.append(f"  • {error}")
+
+    if suggestions:
+        lines.append("\nSuggestions:")
+        for suggestion in suggestions:
+            lines.append(f"  → {suggestion}")
+
+    return "\n".join(lines)
+
+
+def get_config_suggestions(config: dict[str, Any], errors: list[str]) -> list[str]:
+    suggestions: list[str] = []
+
+    for error in errors:
+        if "Unknown event type" in error:
+            suggestions.append("Valid event types are: " + ", ".join(VALID_EVENT_TYPES))
+            break
+
+    if any("missing required field 'command'" in e for e in errors):
+        suggestions.append(
+            "Hook commands should be shell commands like: "
+            "'bash .claude/hooks/my-hook.sh'"
+        )
+
+    return suggestions

code_muse/http_utils.py

@@ -0,0 +1,360 @@
+"""
+HTTP utilities module for Muse.
+
+This module provides functions for creating properly configured HTTP clients.
+"""
+
+import asyncio
+import os
+import socket
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from code_muse.config import get_http2
+
+
+@dataclass
+class ProxyConfig:
+    """Configuration for proxy and SSL settings."""
+
+    verify: bool | str | None
+    trust_env: bool
+    proxy_url: str | None
+    disable_retry: bool
+    http2_enabled: bool
+
+
+def _detect_proxy_url() -> str | None:
+    """Return the first proxy URL found in environment variables."""
+    return (
+        os.environ.get("HTTPS_PROXY")
+        or os.environ.get("https_proxy")
+        or os.environ.get("HTTP_PROXY")
+        or os.environ.get("http_proxy")
+        or None
+    )
+
+
+def _resolve_proxy_config(verify: bool | str | None = None) -> ProxyConfig:
+    """Resolve proxy, SSL, and retry settings from environment.
+
+    This centralizes the logic for detecting proxies, determining SSL verification,
+    and checking if retry transport should be disabled.
+    """
+    if verify is None:
+        verify = get_cert_bundle_path()
+
+    http2_enabled = get_http2()
+
+    disable_retry = os.environ.get(
+        "MUSE_DISABLE_RETRY_TRANSPORT", ""
+    ).lower() in ("1", "true", "yes")
+
+    # When retry transport is disabled and no cert bundle is configured,
+    # also disable TLS verification (legacy compatibility). If a cert
+    # bundle is available, keep it — only bare disable_retry sets False.
+    if disable_retry and verify is None:
+        verify = False
+
+    # Explicit TLS disable — independent from retry logic
+    disable_tls_verify = os.environ.get(
+        "MUSE_DISABLE_TLS_VERIFY", ""
+    ).lower() in ("1", "true", "yes")
+    if disable_tls_verify:
+        verify = False
+
+    proxy_url = _detect_proxy_url()
+    has_proxy = proxy_url is not None
+
+    # trust_env lets httpx read proxy settings from the environment.
+    # It should not affect SSL verification.
+    trust_env = has_proxy
+
+    return ProxyConfig(
+        verify=verify,
+        trust_env=trust_env,
+        proxy_url=proxy_url,
+        disable_retry=disable_retry,
+        http2_enabled=http2_enabled,
+    )
+
+
+try:
+    from .reopenable_async_client import ReopenableAsyncClient
+except ImportError:
+    ReopenableAsyncClient = None
+
+try:
+    from .messaging import emit_info, emit_warning
+except ImportError:
+    # Fallback if messaging system is not available
+    def emit_info(content: str, **metadata):
+        pass  # No-op if messaging system is not available
+
+    def emit_warning(content: str, **metadata):
+        pass
+
+
+class RetryingAsyncClient(httpx.AsyncClient):
+    """AsyncClient with built-in rate limit handling (429) and retries.
+
+    This replaces the Tenacity transport with a more direct subclass implementation,
+    which plays nicer with proxies and custom transports.
+
+    Special handling for Cerebras: Their Retry-After headers are absurdly aggressive
+    (often 60s), so we ignore them and use a 3s base backoff instead.
+    """
+
+    def __init__(
+        self,
+        retry_status_codes: tuple = (429, 502, 503, 504),
+        max_retries: int = 5,
+        model_name: str = "",
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.retry_status_codes = retry_status_codes
+        self.max_retries = max_retries
+        self.model_name = model_name.lower() if model_name else ""
+        # Cerebras sends crazy aggressive Retry-After headers (60s), ignore them
+        self._ignore_retry_headers = "cerebras" in self.model_name
+
+    async def send(self, request: httpx.Request, **kwargs: Any) -> httpx.Response:
+        """Send request with automatic retries for rate limits and server errors."""
+        last_response = None
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await super().send(request, **kwargs)
+                last_response = response
+
+                # Check for retryable status
+                if response.status_code not in self.retry_status_codes:
+                    return response
+
+                # Close response if we're going to retry
+                await response.aclose()
+
+                # Determine wait time - Cerebras gets special treatment
+                if self._ignore_retry_headers:
+                    # Cerebras: 3s base with exponential backoff (3s, 6s, 12s...)
+                    wait_time = 3.0 * (2**attempt)
+                else:
+                    # Default exponential backoff: 1s, 2s, 4s...
+                    wait_time = 1.0 * (2**attempt)
+
+                    # Check Retry-After header (only for non-Cerebras)
+                    retry_after = response.headers.get("Retry-After")
+                    if retry_after:
+                        try:
+                            wait_time = float(retry_after)
+                        except ValueError:
+                            # Try parsing http-date
+                            from email.utils import parsedate_to_datetime
+
+                            try:
+                                date = parsedate_to_datetime(retry_after)
+                                wait_time = date.timestamp() - time.time()
+                            except Exception:
+                                pass
+
+                # Cap wait time
+                wait_time = max(0.5, min(wait_time, 60.0))
+
+                if attempt < self.max_retries:
+                    provider_note = (
+                        " (ignoring header)" if self._ignore_retry_headers else ""
+                    )
+                    emit_info(
+                        f"HTTP retry: {response.status_code} received{provider_note}. "
+                        f"Waiting {wait_time:.1f}s (attempt {attempt + 1}/{self.max_retries})"
+                    )
+                    await asyncio.sleep(wait_time)
+
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.PoolTimeout) as e:
+                last_exception = e
+                wait_time = 1.0 * (2**attempt)
+                if attempt < self.max_retries:
+                    emit_warning(
+                        f"HTTP connection error: {e}. Retrying in {wait_time}s..."
+                    )
+                    await asyncio.sleep(wait_time)
+                else:
+                    raise
+            except Exception:
+                raise
+
+        # Return last response (even if it's an error status)
+        if last_response:
+            return last_response
+
+        # Should catch this in loop, but just in case
+        if last_exception:
+            raise last_exception
+
+        return last_response
+
+
+def get_cert_bundle_path() -> str | None:
+    # First check if SSL_CERT_FILE environment variable is set
+    ssl_cert_file = os.environ.get("SSL_CERT_FILE")
+    if ssl_cert_file and Path(ssl_cert_file).exists():
+        return ssl_cert_file
+
+
+def create_client(
+    timeout: int = 180,
+    verify: bool | str = None,
+    headers: dict[str, str | None] = None,
+    retry_status_codes: tuple = (429, 502, 503, 504),
+) -> httpx.Client:
+    if verify is None:
+        verify = get_cert_bundle_path()
+
+    # Check if HTTP/2 is enabled in config
+    http2_enabled = get_http2()
+
+    # If retry components are available, create a client with retry transport
+    # Note: TenacityTransport was removed. For now we just return a standard client.
+    # Future TODO: Implement RetryingClient(httpx.Client) if needed.
+    return httpx.Client(
+        verify=verify,
+        headers=headers or {},
+        timeout=timeout,
+        http2=http2_enabled,
+    )
+
+
+def create_async_client(
+    timeout: int = 180,
+    verify: bool | str = None,
+    headers: dict[str, str | None] = None,
+    retry_status_codes: tuple = (429, 502, 503, 504),
+    model_name: str = "",
+) -> httpx.AsyncClient:
+    config = _resolve_proxy_config(verify)
+
+    if not config.disable_retry:
+        return RetryingAsyncClient(
+            retry_status_codes=retry_status_codes,
+            model_name=model_name,
+            proxy=config.proxy_url,
+            verify=config.verify,
+            headers=headers or {},
+            timeout=timeout,
+            http2=config.http2_enabled,
+            trust_env=config.trust_env,
+        )
+    else:
+        return httpx.AsyncClient(
+            proxy=config.proxy_url,
+            verify=config.verify,
+            headers=headers or {},
+            timeout=timeout,
+            http2=config.http2_enabled,
+            trust_env=config.trust_env,
+        )
+
+
+def create_httpx_client(
+    timeout: float = 5.0,
+    verify: bool | str = None,
+    headers: dict[str, str | None] = None,
+) -> httpx.Client:
+    if verify is None:
+        verify = get_cert_bundle_path()
+
+    client = httpx.Client(verify=verify)
+
+    if headers:
+        client.headers.update(headers or {})
+
+    return client
+
+
+def create_auth_headers(
+    api_key: str, header_name: str = "Authorization"
+) -> dict[str, str]:
+    return {header_name: f"Bearer {api_key}"}
+
+
+def resolve_env_var_in_header(headers: dict[str, str]) -> dict[str, str]:
+    resolved_headers = {}
+
+    for key, value in headers.items():
+        if isinstance(value, str):
+            try:
+                expanded = os.path.expandvars(value)
+                resolved_headers[key] = expanded
+            except Exception:
+                resolved_headers[key] = value
+        else:
+            resolved_headers[key] = value
+
+    return resolved_headers
+
+
+def create_reopenable_async_client(
+    timeout: int = 180,
+    verify: bool | str = None,
+    headers: dict[str, str | None] = None,
+    retry_status_codes: tuple = (429, 502, 503, 504),
+    model_name: str = "",
+) -> ReopenableAsyncClient | httpx.AsyncClient:
+    config = _resolve_proxy_config(verify)
+
+    base_kwargs = {
+        "proxy": config.proxy_url,
+        "verify": config.verify,
+        "headers": headers or {},
+        "timeout": timeout,
+        "http2": config.http2_enabled,
+        "trust_env": config.trust_env,
+    }
+
+    if ReopenableAsyncClient is not None:
+        client_class = (
+            RetryingAsyncClient if not config.disable_retry else httpx.AsyncClient
+        )
+        kwargs = {**base_kwargs, "client_class": client_class}
+        if not config.disable_retry:
+            kwargs["retry_status_codes"] = retry_status_codes
+            kwargs["model_name"] = model_name
+        return ReopenableAsyncClient(**kwargs)
+    else:
+        # Fallback to RetryingAsyncClient or plain AsyncClient
+        if not config.disable_retry:
+            return RetryingAsyncClient(
+                retry_status_codes=retry_status_codes,
+                model_name=model_name,
+                **base_kwargs,
+            )
+        else:
+            return httpx.AsyncClient(**base_kwargs)
+
+
+def is_cert_bundle_available() -> bool:
+    cert_path = get_cert_bundle_path()
+    if cert_path is None:
+        return False
+    return Path(cert_path).exists() and Path(cert_path).is_file()
+
+
+def find_available_port(start_port=8090, end_port=9010, host="127.0.0.1"):
+    for port in range(start_port, end_port + 1):
+        try:
+            # Try to bind to the port to check if it's available.
+            # Do NOT set SO_REUSEADDR here — it would allow binding to
+            # ports already in use, defeating the availability check.
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                sock.bind((host, port))
+                return port
+        except OSError:
+            # Port is in use, try the next one
+            continue
+    return None

code_muse/keymap.py

@@ -0,0 +1,128 @@
+"""Keymap configuration for Muse.
+
+This module handles configurable keyboard shortcuts, starting with the
+cancel_agent_key feature that allows users to override Ctrl+C with a
+different key for cancelling agent tasks.
+"""
+
+# Character codes for Ctrl+letter combinations (Ctrl+A = 0x01, Ctrl+Z = 0x1A)
+KEY_CODES: dict[str, str] = {
+    "ctrl+a": "\x01",
+    "ctrl+b": "\x02",
+    "ctrl+c": "\x03",
+    "ctrl+d": "\x04",
+    "ctrl+e": "\x05",
+    "ctrl+f": "\x06",
+    "ctrl+g": "\x07",
+    "ctrl+h": "\x08",
+    "ctrl+i": "\x09",
+    "ctrl+j": "\x0a",
+    "ctrl+k": "\x0b",
+    "ctrl+l": "\x0c",
+    "ctrl+m": "\x0d",
+    "ctrl+n": "\x0e",
+    "ctrl+o": "\x0f",
+    "ctrl+p": "\x10",
+    "ctrl+q": "\x11",
+    "ctrl+r": "\x12",
+    "ctrl+s": "\x13",
+    "ctrl+t": "\x14",
+    "ctrl+u": "\x15",
+    "ctrl+v": "\x16",
+    "ctrl+w": "\x17",
+    "ctrl+x": "\x18",
+    "ctrl+y": "\x19",
+    "ctrl+z": "\x1a",
+    "escape": "\x1b",
+}
+
+# Valid keys for cancel_agent_key configuration
+# NOTE: "escape" is excluded because it conflicts with ANSI escape sequences
+# (arrow keys, F-keys, etc. all start with \x1b)
+VALID_CANCEL_KEYS: set[str] = {
+    "ctrl+c",
+    "ctrl+k",
+    "ctrl+q",
+}
+
+DEFAULT_CANCEL_AGENT_KEY: str = "ctrl+c"
+
+
+class KeymapError(Exception):
+    """Exception raised for keymap configuration errors."""
+
+
+def get_cancel_agent_key() -> str:
+    """Get the configured cancel agent key from config.
+
+    On Windows when launched via uvx, this automatically returns "ctrl+k"
+    to work around uvx capturing Ctrl+C before it reaches Python.
+
+    Returns:
+        The key name (e.g., "ctrl+c", "ctrl+k") from config,
+        or the default if not configured.
+    """
+    from code_muse.config import get_value
+    from code_muse.uvx_detection import should_use_alternate_cancel_key
+
+    # On Windows + uvx, force ctrl+k to bypass uvx's SIGINT capture
+    if should_use_alternate_cancel_key():
+        return "ctrl+k"
+
+    key = get_value("cancel_agent_key")
+    if key is None or key.strip() == "":
+        return DEFAULT_CANCEL_AGENT_KEY
+    return key.strip().lower()
+
+
+def validate_cancel_agent_key() -> None:
+    """Validate the configured cancel agent key.
+
+    Raises:
+        KeymapError: If the configured key is invalid.
+    """
+    key = get_cancel_agent_key()
+    if key not in VALID_CANCEL_KEYS:
+        valid_keys_str = ", ".join(sorted(VALID_CANCEL_KEYS))
+        raise KeymapError(
+            f"Invalid cancel_agent_key '{key}' in muse.cfg. "
+            f"Valid options are: {valid_keys_str}"
+        )
+
+
+def cancel_agent_uses_signal() -> bool:
+    """Check if the cancel agent key uses SIGINT (Ctrl+C).
+
+    Returns:
+        True if the cancel key is ctrl+c (uses SIGINT handler),
+        False if it uses keyboard listener approach.
+    """
+    return get_cancel_agent_key() == "ctrl+c"
+
+
+def get_cancel_agent_char_code() -> str:
+    """Get the character code for the cancel agent key.
+
+    Returns:
+        The character code (e.g., "\x0b" for ctrl+k).
+
+    Raises:
+        KeymapError: If the key is not found in KEY_CODES.
+    """
+    key = get_cancel_agent_key()
+    if key not in KEY_CODES:
+        raise KeymapError(f"Unknown key '{key}' - no character code mapping found.")
+    return KEY_CODES[key]
+
+
+def get_cancel_agent_display_name() -> str:
+    """Get a human-readable display name for the cancel agent key.
+
+    Returns:
+        A formatted display name like "Ctrl+K".
+    """
+    key = get_cancel_agent_key()
+    if key.startswith("ctrl+"):
+        letter = key.split("+")[1].upper()
+        return f"Ctrl+{letter}"
+    return key.upper()

code_muse/list_filtering.py

@@ -0,0 +1,26 @@
+"""Helpers for lightweight case-insensitive list filtering in TUIs."""
+
+import re
+
+_NON_ALNUM_RE = re.compile(r"[^0-9a-z]+")
+
+
+def normalize_filter_text(text: str) -> str:
+    """Normalize text for forgiving case-insensitive substring matching."""
+    normalized = _NON_ALNUM_RE.sub(" ", str(text).casefold()).strip()
+    return " ".join(normalized.split())
+
+
+def query_matches_text(query: str, *candidates: str) -> bool:
+    """Return True when every query term appears in the candidate text."""
+    terms = normalize_filter_text(query).split()
+    if not terms:
+        return True
+
+    haystack = " ".join(
+        normalize_filter_text(candidate) for candidate in candidates if candidate
+    ).strip()
+    if not haystack:
+        return False
+
+    return all(term in haystack for term in terms)

code_muse/main.py

@@ -0,0 +1,10 @@
+"""Main entry point for Muse CLI.
+
+This module re-exports the main_entry function from cli_runner for backwards compatibility.
+All the actual logic lives in cli_runner.py.
+"""
+
+from code_muse.cli_runner import main_entry
+
+if __name__ == "__main__":
+    main_entry()