multi-forge 0.2.0__py3-none-any.whl

forge/install/models.py

@@ -0,0 +1,321 @@
+"""Data models for Forge Installer.
+
+Defines enums for installation options and dataclasses for tracking
+what Forge has installed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+# --- Timestamp helper (matches session/models.py pattern) ---
+
+
+def now_iso() -> str:
+    """Return current UTC time as ISO8601 string."""
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+# --- Enums ---
+
+
+class InstallScope(str, Enum):
+    """Installation scope (mirrors Claude Code's scope model).
+
+    - USER: ~/.claude/... + ~/.claude/settings.json (default)
+    - PROJECT: .claude/... + .claude/settings.json (checked in)
+    - LOCAL: .claude/... + .claude/settings.local.json (personal per-project)
+    """
+
+    USER = "user"
+    PROJECT = "project"
+    LOCAL = "local"
+
+
+class InstallMode(str, Enum):
+    """Installation mode.
+
+    - COPY: Copy files to target (stable install)
+    - SYMLINK: Symlink files to source (development mode)
+    """
+
+    COPY = "copy"
+    SYMLINK = "symlink"
+
+
+class InstallProfile(str, Enum):
+    """Predefined installation profiles.
+
+    - MINIMAL: commands only
+    - STANDARD: commands, agents, hooks, permissions (default)
+    - FULL: all modules including status-line
+    """
+
+    MINIMAL = "minimal"
+    STANDARD = "standard"
+    FULL = "full"
+
+
+class InstallModule(str, Enum):
+    """Installable module types."""
+
+    COMMANDS = "commands"
+    AGENTS = "agents"
+    SKILLS = "skills"
+    HOOKS = "hooks"
+    STATUSLINE = "status-line"
+    PERMISSIONS = "permissions"
+
+
+# Profile -> modules mapping
+PROFILE_MODULES: dict[InstallProfile, set[InstallModule]] = {
+    InstallProfile.MINIMAL: {InstallModule.COMMANDS},
+    InstallProfile.STANDARD: {
+        InstallModule.COMMANDS,
+        InstallModule.AGENTS,
+        InstallModule.SKILLS,
+        InstallModule.HOOKS,
+        InstallModule.PERMISSIONS,
+        InstallModule.STATUSLINE,
+    },
+    InstallProfile.FULL: set(InstallModule),
+}
+
+# Profile ordering (for minimum-profile comparisons in skill filtering)
+PROFILE_RANK: dict[InstallProfile, int] = {
+    InstallProfile.MINIMAL: 0,
+    InstallProfile.STANDARD: 1,
+    InstallProfile.FULL: 2,
+}
+
+# Skills requiring a minimum install profile. Unlisted skills install with
+# any profile that includes the SKILLS module.
+SKILL_PROFILE_REQUIREMENTS: dict[str, InstallProfile] = {
+    "qa": InstallProfile.FULL,
+}
+
+
+def get_gated_skills(profile: InstallProfile) -> list[tuple[str, InstallProfile]]:
+    """Return skills excluded by the given profile, with their required profile.
+
+    Only returns skills that need a higher profile than the one provided.
+    """
+    return sorted(
+        (name, req) for name, req in SKILL_PROFILE_REQUIREMENTS.items() if PROFILE_RANK[profile] < PROFILE_RANK[req]
+    )
+
+
+# Module dependencies (installing X requires also installing Y's settings)
+MODULE_DEPENDENCIES: dict[InstallModule, set[InstallModule]] = {}
+
+# Modules that are file-based (vs settings-only)
+FILE_MODULES: set[InstallModule] = {
+    InstallModule.COMMANDS,
+    InstallModule.AGENTS,
+    InstallModule.SKILLS,
+}
+
+# Modules that are settings-only (no files to install)
+# HOOKS: All hooks are now `forge hook X` commands - no files to copy
+# STATUSLINE: Now `forge status-line` command - no scripts to copy
+SETTINGS_ONLY_MODULES: set[InstallModule] = {
+    InstallModule.PERMISSIONS,
+    InstallModule.HOOKS,
+    InstallModule.STATUSLINE,
+}
+
+
+# --- Tracking dataclasses ---
+
+
+@dataclass
+class InstalledFile:
+    """A file installed by Forge.
+
+    Attributes:
+        target_path: Absolute path where the file was installed.
+        source_path: Absolute path to the source file in forge repo.
+        checksum: SHA256 hash of source content (used to detect source changes).
+                  For copy mode: compare to target checksum to detect if update needed.
+                  For symlink mode: verify symlink points to expected source.
+        mode: "copy" or "symlink".
+        installed_at: ISO8601 timestamp when file was installed.
+    """
+
+    target_path: str
+    source_path: str
+    checksum: str
+    mode: str
+    installed_at: str
+
+
+@dataclass
+class InstalledSettingsEntry:
+    """A settings entry added by Forge.
+
+    Attributes:
+        key_path: Dot-notation path (e.g., "hooks.PreToolUse").
+        value: The added value (for reference/display).
+        merge_type: "append", "union", or "scalar".
+        stable_id: Stable identifier for value-based unmerge:
+                   - For hooks: command path string
+                   - For permissions: the entry value itself
+                   - For scalars: the key_path
+    """
+
+    key_path: str
+    value: Any
+    merge_type: str
+    stable_id: str
+
+
+@dataclass
+class Installation:
+    """Installation record for a single scope.
+
+    Attributes:
+        scope: InstallScope value ("user", "project", "local").
+        project_path: Absolute path to project root (None for user scope).
+                     Used to track multiple local/project installations.
+        mode: InstallMode value ("copy", "symlink").
+        profile: InstallProfile value ("minimal", "standard", "full").
+        modules_enabled: List of InstallModule values that were enabled.
+        files: List of InstalledFile records.
+        settings_entries: List of InstalledSettingsEntry records.
+        settings_backup_path: Path to settings backup file (if created).
+        installed_at: ISO8601 timestamp when first installed.
+        updated_at: ISO8601 timestamp when last updated.
+    """
+
+    scope: str
+    mode: str
+    profile: str
+    project_path: str | None = None
+    modules_enabled: list[str] = field(default_factory=list)
+    files: list[InstalledFile] = field(default_factory=list)
+    settings_entries: list[InstalledSettingsEntry] = field(default_factory=list)
+    settings_backup_path: str | None = None
+    installed_at: str = ""
+    updated_at: str = ""
+
+
+def make_installation_key(scope: str, project_path: str | None = None) -> str:
+    """Create a unique key for an installation.
+
+    Args:
+        scope: The installation scope ("user", "project", "local").
+        project_path: Absolute path to project root (required for project/local).
+
+    Returns:
+        Unique key: "user" for user scope, "{scope}:{path}" for project/local.
+
+    Raises:
+        ValueError: If project_path missing for project/local scope.
+    """
+    if scope == InstallScope.USER.value:
+        return "user"
+    if not project_path:
+        raise ValueError(f"project_path required for {scope} scope")
+    return f"{scope}:{project_path}"
+
+
+def parse_installation_key(key: str) -> tuple[str, str | None]:
+    """Parse an installation key back to scope and project_path.
+
+    Args:
+        key: Installation key from manifest.
+
+    Returns:
+        Tuple of (scope, project_path). project_path is None for user scope.
+    """
+    if key == "user":
+        return (InstallScope.USER.value, None)
+    if ":" in key:
+        scope, path = key.split(":", 1)
+        return (scope, path)
+    # v1 format: bare scope name without path (e.g., "project", "local")
+    return (key, None)
+
+
+# Tracking manifest version
+TRACKING_VERSION = 1
+
+
+@dataclass
+class InstalledManifest:
+    """Root tracking manifest at ~/.forge/installed.json.
+
+    Attributes:
+        version: Schema version for the tracking manifest.
+        installations: Dict mapping scope name to Installation record.
+    """
+
+    version: int = TRACKING_VERSION
+    installations: dict[str, Installation] = field(default_factory=dict)
+
+
+# --- Plan dataclasses (for --dry-run) ---
+
+
+@dataclass
+class FilePlan:
+    """Plan for a single file operation.
+
+    Attributes:
+        action: "install", "update", "remove", or "skip".
+        target_path: Where the file will be installed.
+        source_path: Where the file comes from (None for remove).
+        reason: Explanation for skip/conflict actions.
+    """
+
+    action: str
+    target_path: str
+    source_path: str | None = None
+    reason: str | None = None
+
+
+@dataclass
+class SettingsPlan:
+    """Plan for settings modifications.
+
+    Attributes:
+        action: "merge", "unmerge", or "conflict".
+        key_path: Settings key being modified.
+        value: Value to be set (for merge).
+        current_value: Existing value (for conflict display).
+        reason: Explanation for conflict.
+    """
+
+    action: str
+    key_path: str
+    value: Any = None
+    current_value: Any = None
+    reason: str | None = None
+
+
+@dataclass
+class InstallPlan:
+    """Complete installation plan.
+
+    Attributes:
+        scope: Target scope for installation.
+        mode: Installation mode.
+        profile: Installation profile.
+        modules: List of modules being installed.
+        files: List of file operations.
+        settings: List of settings operations.
+        has_conflicts: True if any conflicts were detected.
+        conflicts: Human-readable conflict descriptions.
+    """
+
+    scope: str
+    mode: str
+    profile: str
+    modules: list[str] = field(default_factory=list)
+    files: list[FilePlan] = field(default_factory=list)
+    settings: list[SettingsPlan] = field(default_factory=list)
+    has_conflicts: bool = False
+    conflicts: list[str] = field(default_factory=list)

forge/install/preset.py

@@ -0,0 +1,272 @@
+"""Claude Code settings preset management.
+
+The preset (~/.forge/claude.preset.json) defines what settings Forge merges
+into Claude Code's settings.json on ``forge extensions enable``.
+
+Built-in content contains only essential infrastructure:
+- hooks: all 13 Forge-managed hook events wiring ``forge hook <name>`` commands
+- statusLine: ``forge status-line`` command
+- permissions: Write/Edit (required by handoff agent's ``claude -p`` subprocess)
+
+Users customize additional permissions, env vars, etc. via ``forge claude preset edit``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from forge.core.paths import get_forge_home
+from forge.core.state import atomic_write_text
+
+PRESET_FILENAME = "claude.preset.json"
+
+
+def get_preset_path() -> Path:
+    """Return the path to ~/.forge/claude.preset.json."""
+    return get_forge_home() / PRESET_FILENAME
+
+
+def get_builtin_preset() -> dict[str, Any]:
+    """Return the built-in preset content (factory defaults).
+
+    Contains only essential Forge infrastructure:
+    - hooks: all 13 Forge-managed hook events
+    - statusLine: forge status-line command
+    - permissions: Write/Edit (handoff agent needs these for claude -p)
+    """
+    return {
+        "permissions": {
+            "allow": [
+                "Write",
+                "Edit",
+            ]
+        },
+        "hooks": {
+            "SessionStart": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook session-start",
+                        }
+                    ]
+                }
+            ],
+            "PreToolUse": [
+                {
+                    "matcher": "Read",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook read-hygiene",
+                            "timeout": 5,
+                        }
+                    ],
+                },
+                {
+                    "matcher": "ExitPlanMode",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook exit-plan-mode",
+                        }
+                    ],
+                },
+                {
+                    "matcher": "Write",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook policy-check",
+                            "timeout": 60,
+                        }
+                    ],
+                },
+                {
+                    "matcher": "Edit",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook policy-check",
+                            "timeout": 60,
+                        }
+                    ],
+                },
+            ],
+            "PostToolUse": [
+                {
+                    "matcher": "Write",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook plan-write",
+                        }
+                    ],
+                }
+            ],
+            "Stop": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook stop",
+                        }
+                    ]
+                }
+            ],
+            "StopFailure": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook stop-failure",
+                        }
+                    ]
+                }
+            ],
+            "UserPromptSubmit": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook user-prompt-submit",
+                        }
+                    ]
+                }
+            ],
+            "PreCompact": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook pre-compact",
+                            "timeout": 10,
+                        }
+                    ],
+                }
+            ],
+            "PostCompact": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook post-compact",
+                            "timeout": 5,
+                        }
+                    ],
+                }
+            ],
+            "WorktreeCreate": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook worktree-create",
+                            "timeout": 30,
+                        }
+                    ],
+                }
+            ],
+            "SubagentStop": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook subagent-stop",
+                            "timeout": 10,
+                        }
+                    ],
+                }
+            ],
+            "TeammateIdle": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook teammate-idle",
+                            "timeout": 60,
+                        }
+                    ]
+                }
+            ],
+            "TaskCompleted": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook task-completed",
+                            "timeout": 60,
+                        }
+                    ]
+                }
+            ],
+            "SessionEnd": [
+                {
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": "forge hook session-end",
+                            "timeout": 5,
+                        }
+                    ]
+                }
+            ],
+        },
+        "statusLine": {
+            "type": "command",
+            "command": "forge status-line",
+            "padding": 0,
+        },
+    }
+
+
+def get_builtin_preset_json() -> str:
+    """Return the built-in preset as formatted JSON."""
+    return json.dumps(get_builtin_preset(), indent=2) + "\n"
+
+
+def ensure_preset() -> Path:
+    """Ensure the preset file exists, creating from built-in if missing.
+
+    Returns the path to the preset file. Idempotent — existing files
+    are never overwritten.
+    """
+    preset_path = get_preset_path()
+    if not preset_path.is_file():
+        preset_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(preset_path, get_builtin_preset_json())
+        os.chmod(str(preset_path), 0o600)
+    return preset_path
+
+
+class PresetCorruptedError(Exception):
+    """Raised when the preset file contains invalid JSON or is not a dict."""
+
+
+def load_preset() -> dict[str, Any]:
+    """Load the preset, auto-creating from built-in if missing.
+
+    Raises PresetCorruptedError with actionable message if the file
+    contains invalid JSON or is not a JSON object.
+    """
+    preset_path = ensure_preset()
+    try:
+        with open(preset_path, encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        raise PresetCorruptedError(
+            f"Preset file has invalid JSON: {preset_path}\n"
+            f"  Error: {e}\n"
+            f"  Fix with: forge claude preset edit\n"
+            f"  Or reset: forge claude preset reset"
+        ) from e
+    if not isinstance(data, dict):
+        raise PresetCorruptedError(
+            f"Preset must be a JSON object, got {type(data).__name__}: {preset_path}\n"
+            f"  Fix with: forge claude preset edit\n"
+            f"  Or reset: forge claude preset reset"
+        )
+    return data