multi-forge 0.2.0__py3-none-any.whl

forge/install/__init__.py

@@ -0,0 +1,55 @@
+"""Forge installer for Claude Code extensions.
+
+Provides `forge init` / `forge update` / `forge uninstall` / `forge status` commands
+to manage installation of commands, agents, hooks, skills, and settings.
+"""
+
+from __future__ import annotations
+
+from .exceptions import (
+    ConflictError,
+    FileConflictError,
+    ForgeInstallError,
+    NotInstalledError,
+    SettingsConflictError,
+    SourceNotFoundError,
+    TrackingCorruptedError,
+)
+from .models import (
+    FilePlan,
+    Installation,
+    InstalledFile,
+    InstalledManifest,
+    InstalledSettingsEntry,
+    InstallMode,
+    InstallModule,
+    InstallPlan,
+    InstallProfile,
+    InstallScope,
+    SettingsPlan,
+)
+
+__all__ = [
+    # Enums
+    "InstallScope",
+    "InstallMode",
+    "InstallProfile",
+    "InstallModule",
+    # Tracking dataclasses
+    "InstalledFile",
+    "InstalledSettingsEntry",
+    "Installation",
+    "InstalledManifest",
+    # Plan dataclasses
+    "FilePlan",
+    "SettingsPlan",
+    "InstallPlan",
+    # Exceptions
+    "ForgeInstallError",
+    "ConflictError",
+    "FileConflictError",
+    "SettingsConflictError",
+    "TrackingCorruptedError",
+    "NotInstalledError",
+    "SourceNotFoundError",
+]

forge/install/cli.py

@@ -0,0 +1,281 @@
+"""CLI command for forge info (global installation information).
+
+The info command remains at top-level for quick diagnostics.
+Other installation lifecycle commands have moved to `forge extensions` group.
+"""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from forge.core.paths import display_path
+
+from .tracking import TrackingStore
+
+console = Console()
+
+
+# --- Info Command ---
+
+
+@click.command("info")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--sessions", "-s", "max_sessions", default=5, help="Max recent sessions to show")
+def info_cmd(as_json: bool, max_sessions: int) -> None:
+    """Show global Forge installation information.
+
+    Displays comprehensive system status including:
+    - Forge and Claude Code versions
+    - Active session
+    - Tracked installations
+    - Registered proxies
+    - Recent sessions
+
+    \b
+    Examples:
+        forge info              # Full dashboard
+        forge info --json       # JSON output for scripting
+        forge info --sessions 10  # Show more recent sessions
+    """
+    info_data = _gather_info_data(max_sessions)
+
+    if as_json:
+        console.print_json(data=info_data)
+        return
+
+    _print_info_human(info_data)
+
+
+def _gather_info_data(max_sessions: int) -> dict:
+    """Gather all info data into a dict (for both JSON and human output)."""
+    import shutil
+    import subprocess
+
+    from .models import parse_installation_key
+
+    data: dict = {}
+
+    # Forge info
+    try:
+        from importlib.metadata import version
+
+        data["forge_version"] = version("multi-forge")
+    except Exception:
+        data["forge_version"] = "unknown"
+
+    from forge.core.paths import get_forge_home
+
+    data["forge_home"] = str(get_forge_home())
+
+    # Claude Code info
+    claude_path = shutil.which("claude")
+    data["claude_code"] = {
+        "path": claude_path,
+        "version": None,
+    }
+    if claude_path:
+        try:
+            result = subprocess.run(["claude", "--version"], capture_output=True, text=True, timeout=5)
+            if result.returncode == 0:
+                version_str = result.stdout.strip()
+                if " (Claude Code)" in version_str:
+                    version_str = version_str.replace(" (Claude Code)", "")
+                data["claude_code"]["version"] = version_str
+        except Exception:
+            pass
+
+    # Python/uv versions
+    try:
+        import sys
+
+        data["python_version"] = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    except Exception:
+        data["python_version"] = "unknown"
+
+    try:
+        result = subprocess.run(["uv", "--version"], capture_output=True, text=True, timeout=5)
+        if result.returncode == 0:
+            uv_ver = result.stdout.strip().replace("uv ", "")
+            # Strip git hash suffix if present (e.g., "0.6.14 (a4cec56dc 2025-04-09)")
+            if " (" in uv_ver:
+                uv_ver = uv_ver.split(" (")[0]
+            data["uv_version"] = uv_ver
+    except Exception:
+        data["uv_version"] = "unknown"
+
+    # Installations
+    tracking = TrackingStore()
+    try:
+        manifest = tracking.read()
+    except Exception as e:
+        data["tracking_file"] = str(tracking.path)
+        data["tracking_error"] = str(e)
+        data["installations"] = []
+        data["proxies"] = []
+        data["sessions"] = []
+        return data
+    data["tracking_file"] = str(tracking.path)
+    data["installations"] = []
+    for key, inst in manifest.installations.items():
+        scope, project_path = parse_installation_key(key)
+        data["installations"].append(
+            {
+                "key": key,
+                "scope": scope,
+                "project_path": project_path,
+                "profile": inst.profile,
+                "mode": inst.mode,
+                "files_count": len(inst.files),
+                "settings_count": len(inst.settings_entries),
+            }
+        )
+
+    # Proxies
+    data["proxies"] = []
+    try:
+        from forge.proxy.proxies import ProxyRegistryStore
+
+        proxy_store = ProxyRegistryStore()
+        proxy_registry = proxy_store.read()
+        for proxy_id, proxy_entry in proxy_registry.proxies.items():
+            data["proxies"].append(
+                {
+                    "proxy_id": proxy_id,
+                    "base_url": proxy_entry.base_url,
+                    "template": proxy_entry.template,
+                }
+            )
+    except Exception:
+        pass
+
+    # Recent sessions
+    data["sessions"] = []
+    try:
+        from forge.session import SessionManager
+
+        manager = SessionManager()
+        sessions = manager.list_sessions(include_incognito=False)
+        for name, entry in sessions[:max_sessions]:
+            data["sessions"].append(
+                {
+                    "name": name,
+                    "worktree": entry.worktree_path,
+                    "last_accessed": entry.last_accessed_at,
+                }
+            )
+    except Exception:
+        pass
+
+    return data
+
+
+def _print_info_human(data: dict) -> None:
+    """Print info in human-readable format."""
+    # Header
+    console.print("\n[bold cyan]Forge Info[/bold cyan]")
+    console.print("[cyan]" + "─" * 50 + "[/cyan]")
+
+    # System info
+    console.print("\n[bold]System[/bold]")
+    console.print(f"  Forge:        {data.get('forge_version', 'unknown')}")
+    console.print(f"  Install Path: {display_path(data.get('forge_home', 'unknown'))}")
+
+    cc = data.get("claude_code", {})
+    if cc.get("version"):
+        cc_info = cc["version"]
+    elif cc.get("path"):
+        cc_info = f"at {display_path(cc['path'])}"
+    else:
+        cc_info = "[dim]not found[/dim]"
+    console.print(f"  Claude Code:  {cc_info}")
+
+    console.print(f"  Python:       {data.get('python_version', 'unknown')}")
+    console.print(f"  uv:           {data.get('uv_version', 'unknown')}")
+
+    # Tracking errors (e.g., stale pre-OSS manifest)
+    if "tracking_error" in data:
+        console.print("\n[bold red]Tracking Error[/bold red]")
+        console.print(f"  {data['tracking_error']}")
+
+    # Installations
+    installations = data.get("installations", [])
+    console.print(f"\n[bold]Installations[/bold] ({len(installations)})")
+    if installations:
+        table = Table(
+            show_header=True,
+            header_style="bold",
+            box=None,
+            expand=False,
+            padding=(0, 1),
+        )
+        table.add_column("SCOPE", width=8)
+        table.add_column("PATH", overflow="fold", no_wrap=False)
+        table.add_column("PROFILE", width=10)
+        table.add_column("MODE", width=8)
+
+        for inst in installations:
+            raw_path = inst.get("project_path")
+            path_display = display_path(raw_path) if raw_path else "[dim]~/.claude[/dim]"
+            table.add_row(
+                inst.get("scope", ""),
+                path_display,
+                inst.get("profile", ""),
+                inst.get("mode", ""),
+            )
+        console.print(table)
+    else:
+        console.print("  [dim](none)[/dim]")
+
+    # Proxies
+    proxies = data.get("proxies", [])
+    console.print(f"\n[bold]Proxies[/bold] ({len(proxies)})")
+    if proxies:
+        table = Table(
+            show_header=True,
+            header_style="bold",
+            box=None,
+            expand=False,
+            padding=(0, 1),
+        )
+        table.add_column("PROXY ID", width=25)
+        table.add_column("TEMPLATE", width=20)
+        table.add_column("BASE URL", overflow="fold")
+
+        for proxy in proxies:
+            table.add_row(
+                proxy.get("proxy_id", ""),
+                proxy.get("template") or "[dim]-[/dim]",
+                proxy.get("base_url", ""),
+            )
+        console.print(table)
+    else:
+        console.print("  [dim](none)[/dim]")
+
+    # Recent sessions
+    sessions = data.get("sessions", [])
+    console.print(f"\n[bold]Recent Sessions[/bold] ({len(sessions)} shown)")
+    if sessions:
+        table = Table(
+            show_header=True,
+            header_style="bold",
+            box=None,
+            expand=False,
+            padding=(0, 1),
+        )
+        table.add_column("NAME", width=25)
+        table.add_column("LAST ACCESSED", width=20)
+
+        for sess in sessions:
+            # Format timestamp
+            last_accessed = sess.get("last_accessed", "")
+            if last_accessed:
+                # Truncate to date+time
+                last_accessed = last_accessed[:19].replace("T", " ")
+            table.add_row(sess.get("name", ""), last_accessed)
+        console.print(table)
+    else:
+        console.print("  [dim](none)[/dim]")
+
+    console.print()

forge/install/exceptions.py

@@ -0,0 +1,163 @@
+"""Exceptions for Forge Installer.
+
+Follows the pattern from session/exceptions.py: specific exception types
+with context fields for debugging.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ForgeInstallError(Exception):
+    """Base exception for install module."""
+
+
+class ConflictError(ForgeInstallError):
+    """Base for conflict errors."""
+
+
+class FileConflictError(ConflictError):
+    """Raised when a file conflict is detected.
+
+    Attributes:
+        path: The conflicting file path.
+        reason: Why the conflict occurred.
+    """
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"file conflict at '{path}': {reason}")
+
+
+class SettingsConflictError(ConflictError):
+    """Raised when a settings conflict is detected.
+
+    Attributes:
+        key_path: The conflicting settings key (dot-notation).
+        current_value: The existing value in settings.
+        forge_value: The value Forge wants to set.
+    """
+
+    def __init__(self, key_path: str, current_value: Any, forge_value: Any) -> None:
+        self.key_path = key_path
+        self.current_value = current_value
+        self.forge_value = forge_value
+        super().__init__(f"settings conflict at '{key_path}': " f"current={current_value!r}, forge={forge_value!r}")
+
+
+class TrackingCorruptedError(ForgeInstallError):
+    """Raised when tracking file cannot be parsed.
+
+    Attributes:
+        path: Path to the problematic tracking file.
+        reason: What went wrong during parsing.
+    """
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(f"tracking file at '{path}': {reason}")
+
+
+class NotInstalledError(ForgeInstallError):
+    """Raised when trying to update/uninstall with no installation.
+
+    Attributes:
+        scope: The scope that has no installation.
+    """
+
+    def __init__(self, scope: str) -> None:
+        self.scope = scope
+        super().__init__(f"no Forge installation found for scope '{scope}'")
+
+
+class SourceNotFoundError(ForgeInstallError):
+    """Raised when source extension files are missing.
+
+    Attributes:
+        module: The module whose source is missing.
+        path: Expected path to the source.
+    """
+
+    def __init__(self, module: str, path: str) -> None:
+        self.module = module
+        self.path = path
+        super().__init__(f"source for module '{module}' not found at '{path}'")
+
+
+class NestedClaudeDirectoryError(ForgeInstallError):
+    """Raised when project_root is inside a .claude directory.
+
+    This prevents creating nested .claude/.claude directories which can
+    happen if `forge init --project` is run from within a .claude directory.
+
+    Attributes:
+        project_root: The problematic project root path.
+    """
+
+    def __init__(self, project_root: str) -> None:
+        self.project_root = project_root
+        super().__init__(
+            f"project root '{project_root}' is inside a .claude directory; "
+            "this would create nested .claude/.claude directories. "
+            "Run from the project root, not from within .claude/"
+        )
+
+
+class NoClaudeDirectoryError(ForgeInstallError):
+    """Raised when no .claude directory is found walking up from cwd.
+
+    This indicates Forge is being run outside of a Claude Code project,
+    and the user hasn't explicitly specified a scope.
+
+    Attributes:
+        start_path: The directory where the search started.
+    """
+
+    def __init__(self, start_path: str) -> None:
+        self.start_path = start_path
+        super().__init__(
+            f"no .claude directory found walking up from '{start_path}'. "
+            "Run from within a Claude Code project, or use '--scope user' for global install."
+        )
+
+
+class NoForgeInstallationError(ForgeInstallError):
+    """Raised when no Forge installation is found walking up from cwd.
+
+    Different from NotInstalledError: this is for auto-detection when no
+    scope is specified, whereas NotInstalledError is for a specific scope.
+
+    Attributes:
+        start_path: The directory where the search started.
+    """
+
+    def __init__(self, start_path: str) -> None:
+        self.start_path = start_path
+        super().__init__(
+            f"no Forge installation found walking up from '{start_path}'. "
+            "Run 'forge init' first, or specify a scope explicitly."
+        )
+
+
+class PathBoundaryViolationError(ForgeInstallError):
+    """Raised when a path is outside its expected boundary.
+
+    This is a security check to prevent malicious tracking file modifications
+    from causing deletion of arbitrary system files.
+
+    Attributes:
+        path: The offending path.
+        expected_base: The expected parent directory.
+        operation: What was being attempted (e.g., "delete").
+    """
+
+    def __init__(self, path: str, expected_base: str, operation: str = "access") -> None:
+        self.path = path
+        self.expected_base = expected_base
+        self.operation = operation
+        super().__init__(
+            f"security violation: refusing to {operation} '{path}' - " f"not within expected boundary '{expected_base}'"
+        )

forge/install/hooks.py

@@ -0,0 +1,109 @@
+"""Hook installation detection.
+
+Checks whether Forge hooks are installed in Claude Code settings,
+used by CLI commands to warn when features depend on hooks that aren't present.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _find_claude_dir(start: Path) -> Path | None:
+    """Walk up from start to find the nearest .claude/ directory.
+
+    Returns the directory containing .claude/, or None if not found
+    before reaching the filesystem root.
+    """
+    current = start.resolve()
+    for _ in range(50):  # safety bound
+        if (current / ".claude").is_dir():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+    return None
+
+
+def _settings_paths(worktree_path: Path) -> list[Path]:
+    """Return settings files to scan in priority order (local > project > user).
+
+    Walks up from worktree_path to find the nearest .claude/ directory,
+    so detection works correctly from subdirectories.
+    """
+    from forge.session.claude.paths import get_claude_home
+
+    project_root = _find_claude_dir(worktree_path) or worktree_path
+    return [
+        project_root / ".claude" / "settings.local.json",
+        project_root / ".claude" / "settings.json",
+        get_claude_home() / "settings.local.json",
+        get_claude_home() / "settings.json",
+    ]
+
+
+def _entry_has_command(entry: dict, needle: str) -> bool:
+    """Check if a hook entry contains a command matching the needle.
+
+    System boundary: reads Claude Code settings.json which may contain
+    either format depending on when the user last ran forge extensions sync.
+    - Current: {"hooks": [{"type": "command", "command": "..."}]}
+    - Pre-sync: {"type": "command", "command": "..."}
+    """
+    # Pre-sync format: command at entry top level
+    cmd = entry.get("command")
+    if isinstance(cmd, str) and needle in cmd:
+        return True
+    # Current format: nested hooks array
+    for hook in entry.get("hooks", []):
+        if not isinstance(hook, dict):
+            continue
+        cmd = hook.get("command", "")
+        if isinstance(cmd, str) and needle in cmd:
+            return True
+    return False
+
+
+def has_forge_hook(worktree_path: Path, hook_type: str, command_needle: str = "forge hook") -> bool:
+    """Check if a specific Forge hook type is installed in any settings scope.
+
+    Scans local, project, and user settings files for a hook entry whose
+    command contains *command_needle*. The default needle ``"forge hook"``
+    matches any Forge hook; pass a more specific string like
+    ``"forge hook policy-check"`` to require a particular handler.
+
+    Args:
+        worktree_path: Project/worktree root to resolve local/project settings.
+        hook_type: Claude Code hook event name (e.g., "SessionStart", "PreToolUse", "Stop").
+        command_needle: Substring to look for in the command string.
+    """
+    for settings_path in _settings_paths(worktree_path):
+        try:
+            data = json.loads(settings_path.read_text())
+            if not isinstance(data, dict):
+                continue
+            hooks = data.get("hooks")
+            if not isinstance(hooks, dict):
+                continue
+            hook_entries = hooks.get(hook_type)
+            if not hook_entries or not isinstance(hook_entries, list):
+                continue
+            for entry in hook_entries:
+                if not isinstance(entry, dict):
+                    continue
+                if _entry_has_command(entry, command_needle):
+                    return True
+        except (FileNotFoundError, json.JSONDecodeError, OSError, TypeError, AttributeError):
+            continue
+    return False
+
+
+def has_forge_hooks(worktree_path: Path) -> bool:
+    """Check if any Forge hooks are installed.
+
+    Uses SessionStart as the sentinel — it's included in all Forge
+    installations and is the minimum viable hook for session tracking.
+    """
+    return has_forge_hook(worktree_path, "SessionStart")