multi-forge 0.2.0__py3-none-any.whl

forge/install/tracking.py

@@ -0,0 +1,238 @@
+"""Tracking store for ~/.forge/installed.json.
+
+Manages the persistent record of what Forge has installed, enabling
+reversible update and uninstall operations.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+import dacite
+
+from forge.core.paths import get_forge_home
+from forge.core.state import atomic_write_json, file_lock_for_target
+
+from .exceptions import TrackingCorruptedError
+from .models import (
+    TRACKING_VERSION,
+    Installation,
+    InstalledManifest,
+    make_installation_key,
+    parse_installation_key,
+)
+
+# Constants
+TRACKING_FILENAME = "installed.json"
+
+
+def get_tracking_path() -> Path:
+    """Get path to tracking file (~/.forge/installed.json)."""
+    return get_forge_home() / TRACKING_FILENAME
+
+
+def compute_checksum(path: Path) -> str:
+    """Compute SHA256 checksum of a file.
+
+    Args:
+        path: Path to the file to checksum.
+
+    Returns:
+        Hex-encoded SHA256 hash of file contents.
+    """
+    sha256 = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+class TrackingStore:
+    """Manage the tracking manifest at ~/.forge/installed.json.
+
+    The tracking manifest records what Forge has installed so that:
+    - `forge update` updates only tracked items
+    - `forge uninstall` removes only tracked files and settings entries
+
+    Error handling:
+    - Missing file: Return empty manifest (not an error)
+    - Corrupted JSON: Raise TrackingCorruptedError (fail loudly to preserve safety)
+    """
+
+    def __init__(self, tracking_path: Path | None = None) -> None:
+        """Initialize store.
+
+        Args:
+            tracking_path: Override path to tracking file (for testing).
+        """
+        self._path = tracking_path or get_tracking_path()
+
+    @property
+    def path(self) -> Path:
+        """Return the full path to the tracking file."""
+        return self._path
+
+    def exists(self) -> bool:
+        """Check if tracking file exists."""
+        return self._path.is_file()
+
+    def read(self) -> InstalledManifest:
+        """Read tracking manifest.
+
+        Returns empty manifest if file doesn't exist.
+        Raises TrackingCorruptedError if file exists but is invalid.
+
+        Returns:
+            The tracking manifest.
+
+        Raises:
+            TrackingCorruptedError: If file is corrupted or has invalid schema.
+        """
+        if not self.exists():
+            return InstalledManifest()
+
+        try:
+            with open(self._path, encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise TrackingCorruptedError(str(self._path), f"invalid JSON: {e}")
+        except OSError as e:
+            raise TrackingCorruptedError(str(self._path), f"read error: {e}")
+
+        # Version check (no migration support)
+        version = data.get("version", 1)
+        if version != TRACKING_VERSION:
+            raise TrackingCorruptedError(
+                str(self._path),
+                f"incompatible version {version} (this Forge expects {TRACKING_VERSION}). "
+                f"Delete this file and run 'forge extension enable' again.",
+            )
+
+        # Guard: reject manifests from pre-OSS patching builds.
+        # patched_files was removed from the Installation dataclass; dacite
+        # strict=True rejects even "patched_files": []. Check raw JSON before
+        # deserialization so the error message is actionable.
+        installations = data.get("installations", {})
+        for inst in installations.values():
+            if isinstance(inst, dict) and "patched_files" in inst:
+                raise TrackingCorruptedError(
+                    str(self._path),
+                    "This Forge install manifest was created by a pre-OSS patching build. "
+                    f"Remove {self._path} and run `forge extension enable` again. "
+                    "If Claude Code was patched, run `claude update` or reinstall Claude Code.",
+                )
+
+        try:
+            return dacite.from_dict(
+                data_class=InstalledManifest,
+                data=data,
+                config=dacite.Config(strict=True),
+            )
+        except (dacite.DaciteError, TypeError, KeyError) as e:
+            raise TrackingCorruptedError(str(self._path), f"deserialization error: {e}")
+
+    def write(self, manifest: InstalledManifest) -> None:
+        """Write tracking manifest atomically.
+
+        Uses core.state.atomic_write_json for atomic writes.
+        Creates parent directory if needed.
+
+        Args:
+            manifest: The manifest to write.
+        """
+        data = asdict(manifest)
+        atomic_write_json(self._path, data)
+
+    def get_installation(self, scope: str, project_path: str | None = None) -> Installation | None:
+        """Get installation for a specific scope and project.
+
+        Args:
+            scope: The scope to look up ("user", "project", "local").
+            project_path: Project path (required for project/local scope).
+
+        Returns:
+            The Installation record, or None if not installed.
+        """
+        key = make_installation_key(scope, project_path)
+        manifest = self.read()
+        return manifest.installations.get(key)
+
+    def set_installation(self, scope: str, installation: Installation, project_path: str | None = None) -> None:
+        """Set installation for a scope and project.
+
+        Args:
+            scope: The scope to set.
+            installation: The installation record.
+            project_path: Project path (required for project/local scope).
+        """
+        key = make_installation_key(scope, project_path)
+        installation.project_path = project_path
+        with file_lock_for_target(target_path=self._path, timeout_s=5.0):
+            manifest = self.read()
+            manifest.installations[key] = installation
+            self.write(manifest)
+
+    def remove_installation(self, scope: str, project_path: str | None = None) -> bool:
+        """Remove installation for a scope and project.
+
+        Args:
+            scope: The scope to remove.
+            project_path: Project path (required for project/local scope).
+
+        Returns:
+            True if removed, False if didn't exist.
+        """
+        key = make_installation_key(scope, project_path)
+        with file_lock_for_target(target_path=self._path, timeout_s=5.0):
+            manifest = self.read()
+            if key not in manifest.installations:
+                return False
+            del manifest.installations[key]
+            self.write(manifest)
+            return True
+
+    def list_installations(self) -> list[tuple[str, str | None, Installation]]:
+        """List all tracked installations.
+
+        Returns:
+            List of (scope, project_path, installation) tuples.
+        """
+        manifest = self.read()
+        result = []
+        for key, installation in manifest.installations.items():
+            scope, project_path = parse_installation_key(key)
+            result.append((scope, project_path, installation))
+        return result
+
+    def has_installation(self, scope: str, project_path: str | None = None) -> bool:
+        """Check if an installation exists for the given scope and project.
+
+        Args:
+            scope: The scope to check.
+            project_path: Project path (required for project/local scope).
+
+        Returns:
+            True if installation exists.
+        """
+        return self.get_installation(scope, project_path) is not None
+
+    def is_forge_managed(self, path: str, scope: str, project_path: str | None = None) -> bool:
+        """Check if a path is managed by Forge in the given scope.
+
+        Args:
+            path: Absolute path to check.
+            scope: Scope to check within.
+            project_path: Project path (required for project/local scope).
+
+        Returns:
+            True if the path is a Forge-managed file.
+        """
+        installation = self.get_installation(scope, project_path)
+        if installation is None:
+            return False
+
+        normalized = str(Path(path).resolve())
+        return any(str(Path(f.target_path).resolve()) == normalized for f in installation.files)

forge/install/version.py

@@ -0,0 +1,141 @@
+"""Claude Code minimum version detection and enforcement.
+
+Forge requires a minimum Claude Code version to ensure hooks, policy enforcement,
+and session features work correctly. This module provides cached version detection
+and comparison utilities used by the installer and session launch flow.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import time
+from dataclasses import dataclass
+
+from packaging.version import InvalidVersion, Version
+
+logger = logging.getLogger(__name__)
+
+# Minimum Claude Code version required by Forge.
+# v2.1.78: hooks load in worktrees, StopFailure event, PreToolUse deny fix (v2.1.77),
+#          transcript_path correct for forked/resumed sessions (v2.1.72).
+MIN_CLAUDE_CODE_VERSION = "2.1.78"
+
+# Process-scoped cache to avoid running `claude --version` on every call.
+_VERSION_CACHE_TTL_S = 300  # 5 minutes
+_cached_version: tuple[float, str | None] | None = None
+
+
+@dataclass
+class VersionCheckResult:
+    """Result of checking Claude Code version against the minimum."""
+
+    ok: bool
+    version: str | None
+    minimum: str
+    reason: str
+
+
+def get_claude_runtime_version() -> str | None:
+    """Detect the installed Claude Code version via ``claude --version``.
+
+    Returns the version string (e.g. ``"2.1.78"``) or None if Claude Code
+    is not installed, times out, or produces unparseable output.
+
+    Results are cached for ``_VERSION_CACHE_TTL_S`` seconds to avoid
+    repeated subprocess calls within a single CLI invocation.
+    """
+    global _cached_version  # noqa: PLW0603 — module-level cache by design
+
+    now = time.monotonic()
+    if _cached_version is not None:
+        cached_at, cached_value = _cached_version
+        if now - cached_at < _VERSION_CACHE_TTL_S:
+            return cached_value
+
+    version = _run_claude_version()
+    _cached_version = (now, version)
+    return version
+
+
+def _run_claude_version() -> str | None:
+    """Run ``claude --version`` and parse the output."""
+    try:
+        result = subprocess.run(
+            ["claude", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+        raw = result.stdout.strip()
+        if not raw:
+            return None
+        # Output is like "2.1.78 (Claude Code)" — strip the suffix
+        if " (Claude Code)" in raw:
+            raw = raw.replace(" (Claude Code)", "")
+        return raw.split()[0] if raw else None
+    except FileNotFoundError:
+        return None
+    except subprocess.TimeoutExpired:
+        return None
+    except Exception:
+        logger.debug("Unexpected error detecting Claude Code version", exc_info=True)
+        return None
+
+
+def check_minimum_version(version_str: str | None = None) -> VersionCheckResult:
+    """Check whether the installed Claude Code meets the minimum version.
+
+    Args:
+        version_str: Explicit version string (for testing). If None, detects
+            the runtime version via ``get_claude_runtime_version()``.
+    """
+    minimum = MIN_CLAUDE_CODE_VERSION
+
+    if version_str is None:
+        version_str = get_claude_runtime_version()
+
+    if version_str is None:
+        return VersionCheckResult(
+            ok=False,
+            version=None,
+            minimum=minimum,
+            reason="Claude Code not found. Install it first: https://docs.anthropic.com/en/docs/claude-code",
+        )
+
+    try:
+        detected = Version(version_str)
+    except InvalidVersion:
+        return VersionCheckResult(
+            ok=False,
+            version=version_str,
+            minimum=minimum,
+            reason=f"Could not parse Claude Code version '{version_str}'.",
+        )
+
+    required = Version(minimum)
+    if detected < required:
+        return VersionCheckResult(
+            ok=False,
+            version=version_str,
+            minimum=minimum,
+            reason=(
+                f"Claude Code {version_str} is below the minimum required "
+                f"version {minimum}. Run 'claude update' to upgrade."
+            ),
+        )
+
+    return VersionCheckResult(
+        ok=True,
+        version=version_str,
+        minimum=minimum,
+        reason="OK",
+    )
+
+
+def reset_version_cache() -> None:
+    """Clear the cached version (for testing)."""
+    global _cached_version  # noqa: PLW0603
+    _cached_version = None

forge/proxy/base_client.py

@@ -0,0 +1,181 @@
+"""
+Abstract base class for all LLM provider clients.
+
+This module defines the interface that all provider clients must implement,
+ensuring consistent behavior across different LLM providers (OpenAI, Gemini, etc.).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, AsyncGenerator, Dict, List, Optional
+
+# Import canonical error types from core.llm.errors
+from forge.core.llm.errors import LLMError
+
+
+class AbstractLLMClient(ABC):
+    """
+    Base class for all LLM provider clients.
+
+    All provider-specific clients must inherit from this class and implement
+    the required methods. This ensures a consistent interface across providers.
+
+    Methods accept and return data in OpenAI format for consistency, as it
+    serves as both a universal intermediate format and the native format for
+    OpenAI providers.
+    """
+
+    @abstractmethod
+    async def create_completion(self, openai_request_dict: Dict[str, Any], request_id: str) -> Dict[str, Any]:
+        """
+        Create a non-streaming completion.
+
+        Args:
+            openai_request_dict: Request in OpenAI format containing messages,
+                                tools, model parameters, etc.
+            request_id: Unique identifier for request tracking and logging
+
+        Returns:
+            Response in OpenAI format
+
+        Raises:
+            AuthenticationError: When authentication fails
+            Exception: For other provider-specific errors
+        """
+        pass
+
+    @abstractmethod
+    async def create_streaming_completion(
+        self, openai_request_dict: Dict[str, Any], request_id: str
+    ) -> AsyncGenerator[str, None]:
+        """
+        Create a streaming completion.
+
+        Args:
+            openai_request_dict: Request in OpenAI format containing messages,
+                                tools, model parameters, etc.
+            request_id: Unique identifier for request tracking and logging
+
+        Yields:
+            Server-sent events (SSE) in OpenAI streaming format
+
+        Raises:
+            AuthenticationError: When authentication fails
+            Exception: For other provider-specific errors
+        """
+        pass
+
+    @abstractmethod
+    async def count_tokens(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> int:
+        """
+        Count tokens for the given messages and optional tools.
+
+        Args:
+            messages: List of messages in OpenAI format
+            tools: Optional list of tools in OpenAI format
+
+        Returns:
+            Total token count
+
+        Raises:
+            Exception: If token counting fails
+        """
+        pass
+
+
+class ToolCallError(LLMError):
+    """
+    Raised when a tool call fails, formatted for LLM consumption.
+
+    This error provides structured information that helps LLMs understand
+    and potentially fix tool-related issues.
+    """
+
+    def __init__(self, error_type: str, tool_name: str, details: Dict[str, Any]):
+        """
+        Initialize a tool call error with LLM-friendly formatting.
+
+        Args:
+            error_type: Category of error (MISSING_PARAM, SCHEMA_MISMATCH, etc.)
+            tool_name: Name of the tool that failed
+            details: Additional context including expected/actual values and suggestions
+        """
+        self.error_type = error_type
+        self.tool_name = tool_name
+        self.details = details
+
+        # Build LLM-friendly message
+        message_parts = [f"Tool call failed [{error_type}]: {tool_name}"]
+
+        if error_type == "MISSING_PARAM":
+            if "param" in details:
+                message_parts.append(f"Missing required parameter: '{details['param']}'")
+            if "expected" in details:
+                message_parts.append(f"Expected structure: {details['expected']}")
+            if "actual" in details:
+                message_parts.append(f"Received: {details['actual']}")
+
+        elif error_type == "SCHEMA_MISMATCH":
+            if "message" in details:
+                message_parts.append(details["message"])
+            if "expected_type" in details:
+                message_parts.append(f"Expected type: {details['expected_type']}")
+            if "actual_type" in details:
+                message_parts.append(f"Actual type: {details['actual_type']}")
+
+        elif error_type == "INVALID_FORMAT":
+            if "message" in details:
+                message_parts.append(details["message"])
+            if "field" in details:
+                message_parts.append(f"Invalid field: '{details['field']}'")
+
+        # Add suggestion if available
+        if "suggestion" in details:
+            message_parts.append(f"Suggestion: {details['suggestion']}")
+
+        super().__init__("\n".join(message_parts))
+
+
+class ProxyStreamError(LLMError):
+    """Raised during streaming when an error occurs.
+
+    This error carries structured information that allows the proxy server
+    to return appropriate HTTP status codes and OpenAI-compatible error responses
+    instead of generic 500 errors.
+
+    Common error types and their HTTP mappings:
+    - "authentication_error" -> 401
+    - "rate_limit_error" -> 429
+    - "invalid_request_error" -> 400
+    - "api_error" -> 500
+    """
+
+    # Standard error type to HTTP status code mapping
+    ERROR_STATUS_MAP = {
+        "authentication_error": 401,
+        "rate_limit_error": 429,
+        "invalid_request_error": 400,
+        "permission_error": 403,
+        "not_found_error": 404,
+        "api_error": 500,
+    }
+
+    def __init__(
+        self,
+        message: str,
+        error_type: str = "api_error",
+        status_code: int | None = None,
+    ) -> None:
+        """Initialize a proxy stream error.
+
+        Args:
+            message: Human-readable error message.
+            error_type: OpenAI-compatible error type for client handling.
+            status_code: HTTP status code override. If None, derived from error_type.
+        """
+        self.error_type = error_type
+        self.status_code = status_code or self.ERROR_STATUS_MAP.get(error_type, 500)
+        super().__init__(message)