thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/hooks/installer.py

@@ -0,0 +1,850 @@
+"""
+Installs ThinkStack hooks for Claude Code, git, and Google Antigravity (AGENTS.md).
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Canonical hooks.json configuration
+# ---------------------------------------------------------------------------
+
+# Hooks fire a process per event; scope them to mutating tools so read-heavy
+# agent sessions don't pay ~1 spawn per file read.
+MUTATING_TOOLS_MATCHER = "Write|Edit|MultiEdit|NotebookEdit|Bash"
+
+# Commands ThinkStack has shipped historically — replaced on re-install so
+# users are upgraded to the current fast/detached commands in place.
+_LEGACY_HOOK_COMMAND_PREFIXES = ("thinkstack hooks run", "thinkstack-hook", "sh -c 'thinkstack-hook")
+
+CLAUDE_HOOKS_CONFIG: dict = {
+    "hooks": {
+        "PreToolUse": [
+            {
+                "matcher": MUTATING_TOOLS_MATCHER,
+                "hooks": [
+                    {"type": "command", "command": "thinkstack-hook pre-tool-use"}
+                ],
+            }
+        ],
+        "UserPromptSubmit": [
+            {
+                "hooks": [
+                    {"type": "command", "command": "thinkstack-hook user-prompt-submit"}
+                ]
+            }
+        ],
+        "PostToolUse": [
+            {
+                "matcher": MUTATING_TOOLS_MATCHER,
+                "hooks": [
+                    # Detached: capture is write-only telemetry; the IDE never
+                    # consumes its output, so don't make the user wait on it.
+                    {"type": "command", "command": "sh -c 'thinkstack-hook post-tool-use >/dev/null 2>&1 &'"}
+                ],
+            }
+        ],
+        "Stop": [
+            {
+                "hooks": [
+                    {"type": "command", "command": "thinkstack-hook session-end"}
+                ]
+            }
+        ],
+    }
+}
+
+# OpenCode hook events use a flat per-entry { command, matcher? } shape
+# (unlike Claude Code's nested { hooks: [{ type: "command", command: ... }] }).
+OPENCODE_HOOKS_CONFIG: dict = {
+    "hooks": {
+        "PreUserPrompt": [
+            {
+                "command": "thinkstack-hook open-code-pre-prompt",
+            }
+        ],
+        "PreToolUse": [
+            {
+                "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+                "command": "thinkstack-hook pre-tool-use",
+            }
+        ],
+        "PostToolUse": [
+            {
+                "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+                "command": "sh -c 'thinkstack-hook post-tool-use &'",
+            }
+        ],
+        "Stop": [
+            {
+                "command": "thinkstack-hook session-end",
+            }
+        ],
+    }
+}
+
+
+# ---------------------------------------------------------------------------
+# Result dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HookInstallResult:
+    claude_hooks_written: bool = False
+    claude_hooks_path: str = ""
+    git_hook_written: bool = False
+    git_hook_path: str = ""
+    # S26 git-capture hooks (post-commit, post-merge, post-checkout, post-rewrite)
+    git_capture_hooks_written: bool = False
+    git_capture_hooks: dict[str, str] = field(default_factory=dict)
+    skills_written: bool = False
+    skills_installed: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Deep-merge helpers
+# ---------------------------------------------------------------------------
+
+
+def _deep_merge(base: dict, overlay: dict) -> dict:
+    """
+    Recursively merge *overlay* into *base*.
+
+    - For dicts: recurse.
+    - For lists keyed under "hooks" event names: append overlay entries
+      whose commands are not already present.
+    - Scalar values: overlay wins.
+    """
+    result = copy.deepcopy(base)
+    for key, val in overlay.items():
+        if key in result and isinstance(result[key], dict) and isinstance(val, dict):
+            result[key] = _deep_merge(result[key], val)
+        elif key in result and isinstance(result[key], list) and isinstance(val, list):
+            # Merge lists without duplicating identical entries
+            existing_cmds = _extract_commands(result[key])
+            for item in val:
+                item_cmds = _extract_commands([item])
+                if not item_cmds or not item_cmds.issubset(existing_cmds):
+                    result[key].append(copy.deepcopy(item))
+        else:
+            result[key] = copy.deepcopy(val)
+    return result
+
+
+def _extract_commands(items: list) -> set:
+    """Extract all command strings from a list of hook entries."""
+    cmds: set = set()
+    for item in items:
+        if isinstance(item, dict):
+            for hook in item.get("hooks", []):
+                if isinstance(hook, dict) and "command" in hook:
+                    cmds.add(hook["command"])
+    return cmds
+
+
+def _strip_thinkstack_hook_entries(settings: dict) -> dict:
+    """Remove hook entries whose every command is a ThinkStack-shipped command,
+    so re-installation upgrades them instead of accumulating duplicates.
+    User-authored entries (any non-ThinkStack command) are kept intact."""
+    result = copy.deepcopy(settings)
+    hooks = result.get("hooks")
+    if not isinstance(hooks, dict):
+        return result
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            continue
+        kept = []
+        for entry in entries:
+            cmds = _extract_commands([entry])
+            if cmds and all(
+                c.startswith(_LEGACY_HOOK_COMMAND_PREFIXES) for c in cmds
+            ):
+                continue
+            kept.append(entry)
+        hooks[event] = kept
+    return result
+
+
+# ---------------------------------------------------------------------------
+# install_claude_hooks
+# ---------------------------------------------------------------------------
+
+
+def install_claude_hooks(project_root: str) -> tuple[bool, str]:
+    """
+    Merge ThinkStack hooks into .claude/settings.json under *project_root*.
+
+    Claude Code only reads hooks from its settings files (settings.json /
+    settings.local.json) — a standalone hooks.json is never loaded.
+
+    - Creates .claude/ directory if it does not exist.
+    - Deep-merges ThinkStack hooks into the existing settings.json without
+      removing existing keys (permissions, env, other hooks, ...).
+    - Migrates a legacy .claude/hooks.json written by older ThinkStack versions
+      into settings.json and removes it.
+    - Returns (True, path) on success, (False, error_message) on failure.
+    """
+    try:
+        claude_dir = Path(project_root) / ".claude"
+        claude_dir.mkdir(parents=True, exist_ok=True)
+
+        settings_path = claude_dir / "settings.json"
+
+        existing: dict = {}
+        if settings_path.exists():
+            try:
+                existing = json.loads(settings_path.read_text(encoding="utf-8"))
+            except Exception:
+                existing = {}
+
+        legacy_path = claude_dir / "hooks.json"
+        legacy_migrated = False
+        if legacy_path.exists():
+            try:
+                legacy = json.loads(legacy_path.read_text(encoding="utf-8"))
+            except Exception:
+                legacy = None
+            if isinstance(legacy, dict) and isinstance(legacy.get("hooks"), dict):
+                existing = _deep_merge(existing, {"hooks": legacy["hooks"]})
+                legacy_migrated = True
+            # Unreadable or unexpected shape: leave the file in place — never
+            # delete config we could not migrate.
+
+        existing = _strip_thinkstack_hook_entries(existing)
+        merged = _deep_merge(existing, CLAUDE_HOOKS_CONFIG)
+        settings_path.write_text(json.dumps(merged, indent=2), encoding="utf-8")
+        # Remove the legacy file only after its content is safely in settings.json.
+        if legacy_migrated:
+            legacy_path.unlink()
+        return True, str(settings_path)
+
+    except Exception as exc:
+        return False, str(exc)
+
+
+# ---------------------------------------------------------------------------
+# install_git_commit_hook
+# ---------------------------------------------------------------------------
+
+
+def install_git_commit_hook(repo_root: str) -> tuple[bool, str]:
+    """
+    Install the git commit-msg hook in .git/hooks/commit-msg.
+
+    Calls thinkstack_core.hooks.git_commit.install_hook(repo_root).
+    Returns (True, path) on success, (False, reason) when no .git found or
+    on any other error.
+    """
+    git_dir = Path(repo_root) / ".git"
+    if not git_dir.is_dir():
+        return False, "no .git found"
+
+    try:
+        from thinkstack_core.hooks.git_commit import install_hook
+
+        install_hook(Path(repo_root))
+        hook_path = str(git_dir / "hooks" / "commit-msg")
+        return True, hook_path
+
+    except Exception as exc:
+        return False, str(exc)
+
+
+# ---------------------------------------------------------------------------
+# install_git_capture_hooks
+# ---------------------------------------------------------------------------
+
+
+def install_git_capture_hooks(repo_root: str) -> tuple[bool, dict[str, str]]:
+    """
+    Install the S26 git capture hooks in .git/hooks/.
+
+    Returns (True, {hook_name: path}) on success, (False, {hook_name: error})
+    when no .git/hooks directory is found or on any other error.
+    """
+    try:
+        from thinkstack_core.hooks.git_capture import (
+            install_git_capture_hooks as _install_git_capture_hooks,
+        )
+
+        ok, paths = _install_git_capture_hooks(Path(repo_root))
+        return ok, paths
+    except Exception as exc:
+        return False, {"error": str(exc)}
+
+
+# ---------------------------------------------------------------------------
+# install_all_hooks
+# ---------------------------------------------------------------------------
+
+
+def install_all_hooks(project_root: str) -> HookInstallResult:
+    """
+    Install all ThinkStack hooks (Claude Code + git).
+
+    Never raises — all exceptions are captured into result.errors.
+    """
+    result = HookInstallResult()
+
+    # Claude Code hooks
+    try:
+        ok, path = install_claude_hooks(project_root)
+        result.claude_hooks_written = ok
+        result.claude_hooks_path = path
+        if not ok:
+            result.errors.append(f"claude hooks: {path}")
+    except Exception as exc:
+        result.errors.append(f"claude hooks exception: {exc}")
+
+    # Git commit-msg hook
+    try:
+        ok, path = install_git_commit_hook(project_root)
+        result.git_hook_written = ok
+        result.git_hook_path = path
+        if not ok:
+            result.errors.append(f"git hook: {path}")
+    except Exception as exc:
+        result.errors.append(f"git hook exception: {exc}")
+
+    # S26 git capture hooks
+    try:
+        ok, paths = install_git_capture_hooks(project_root)
+        result.git_capture_hooks_written = ok
+        result.git_capture_hooks = paths
+        if not ok:
+            result.errors.append(f"git capture hooks: {paths}")
+    except Exception as exc:
+        result.errors.append(f"git capture hooks exception: {exc}")
+
+    # OpenCode / Claude Code skills
+    try:
+        ok, names = install_skills()
+        result.skills_written = ok
+        result.skills_installed = names
+        if not ok:
+            result.errors.append(f"skills: {names}")
+    except Exception as exc:
+        result.errors.append(f"skills exception: {exc}")
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Skill installation
+# ---------------------------------------------------------------------------
+
+_DEVTOCH_SKILLS = [
+    "thinkstack-session-start",
+    "thinkstack-auto-sync",
+    "pr-reviewer",
+]
+
+_DEFAULT_SKILLS_DIR = Path.home() / ".claude" / "skills"
+
+
+def install_skills(
+    skills_dir: Path | None = None,
+    package_skills_path: Path | None = None,
+) -> tuple[bool, list[str]]:
+    """Copy ThinkStack skills from the package to ~/.claude/skills/.
+
+    The skills are shipped as package data in thinkstack_core/skills/<name>/SKILL.md.
+    On install, each skill directory is created or updated in the target skills dir.
+
+    Returns (all_ok, list_of_skill_names).
+    """
+    target_dir = skills_dir or _DEFAULT_SKILLS_DIR
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    if package_skills_path is None:
+        try:
+            from importlib.resources import files
+            package_skills_path = Path(str(files("thinkstack_core") / "skills"))
+        except Exception:
+            package_skills_path = Path(__file__).parent.parent / "skills"
+
+    installed: list[str] = []
+    all_ok = len(_DEVTOCH_SKILLS) > 0
+
+    for skill_name in _DEVTOCH_SKILLS:
+        try:
+            src = package_skills_path / skill_name / "SKILL.md"
+            if not src.exists():
+                continue
+            dst_dir = target_dir / skill_name
+            dst_dir.mkdir(parents=True, exist_ok=True)
+            dst = dst_dir / "SKILL.md"
+            dst.write_text(src.read_text(encoding="utf-8"))
+            if skill_name not in installed:
+                installed.append(skill_name)
+        except Exception:
+            all_ok = False
+
+    return all_ok, installed
+
+
+# ---------------------------------------------------------------------------
+# AGENTS.md block for Google Antigravity
+# ---------------------------------------------------------------------------
+
+ANTIGRAVITY_AGENTS_MD_BLOCK = """
+## ThinkStack — Reasoning Capture
+
+This project uses ThinkStack for AI governance. These steps are mandatory for all agent actions.
+
+### At the start of every task
+
+Call `thinkstack_context` (MCP tool) before reading files or writing code:
+- Tool: `thinkstack_context`
+- Args: `{ "max_tokens": 2000 }`
+
+Use the returned context to understand prior decisions before proceeding.
+
+### Before writing or editing any code
+
+Call `thinkstack_commit` before the first file write:
+- Tool: `thinkstack_commit`
+- Args: `{ "message": "<what you decided and WHY — include alternatives considered>", "concepts": ["<concept>"], "confidence": 0.0–1.0 }`
+
+The message must explain the *why*, not just the *what*.
+"Added login endpoint" is not acceptable.
+"Chose JWT over sessions because the service is stateless" is.
+
+### When touching sensitive areas
+
+Call `thinkstack_sensitivity_add` for auth, payments, database schema, secrets, PII, external APIs:
+- Tool: `thinkstack_sensitivity_add`
+- Args: `{ "concept": "<auth|schema|payments|secrets|pii|api|security|config>", "confidence": 0.0–1.0, "disclosure_level": "PUBLIC|PROTECTED|PRIVATE" }`
+
+| Level | Use when |
+|---|---|
+| PUBLIC | General design decisions |
+| PROTECTED | Internal implementation, business logic |
+| PRIVATE | Credentials, PII, secrets |
+"""
+
+
+# ---------------------------------------------------------------------------
+# install_agents_md
+# ---------------------------------------------------------------------------
+
+
+def install_agents_md(project_root: str) -> tuple[bool, str]:
+    """
+    Write (or append to) AGENTS.md under *project_root* with the ThinkStack
+    governance block for Google Antigravity.
+
+    - Creates AGENTS.md if it does not exist.
+    - If AGENTS.md already contains the marker ``## ThinkStack``, does nothing
+      (idempotent).
+    - Returns (True, path) on success, (False, error_message) on failure.
+    """
+    try:
+        import re
+
+        agents_md_path = Path(project_root) / "AGENTS.md"
+        # Any-level ThinkStack heading counts as installed — projects may promote
+        # the block to an H1; appending our copy next to it would duplicate it.
+        marker_re = re.compile(r"^#{1,6}\s+ThinkStack\b", re.MULTILINE)
+
+        if agents_md_path.exists():
+            existing = agents_md_path.read_text(encoding="utf-8")
+            if marker_re.search(existing):
+                return True, str(agents_md_path)
+
+        with agents_md_path.open("a", encoding="utf-8") as f:
+            f.write(ANTIGRAVITY_AGENTS_MD_BLOCK)
+
+        return True, str(agents_md_path)
+
+    except Exception as exc:
+        return False, str(exc)
+
+
+# ---------------------------------------------------------------------------
+# get_hooks_status
+# ---------------------------------------------------------------------------
+
+
+def get_hooks_status(project_root: str) -> dict:
+    """
+    Return the install status of ThinkStack hooks without writing anything.
+
+    Returns:
+        {
+            "claude_hooks": bool,
+            "claude_hooks_path": str,
+            "git_hook": bool,
+            "git_hook_path": str,
+            "git_capture_hooks": dict[str, bool],
+            "git_capture_hooks_path": dict[str, str],
+        }
+    """
+    settings_path = Path(project_root) / ".claude" / "settings.json"
+    claude_hooks_path = str(settings_path)
+    claude_hooks = False
+    if settings_path.exists():
+        try:
+            data = json.loads(settings_path.read_text(encoding="utf-8"))
+            cmds: set = set()
+            for entries in (data.get("hooks") or {}).values():
+                if isinstance(entries, list):
+                    cmds |= _extract_commands(entries)
+            claude_hooks = any(
+                c.startswith("thinkstack-hook") or c.startswith("sh -c 'thinkstack-hook")
+                for c in cmds
+            )
+        except Exception:
+            claude_hooks = False
+
+    git_hook_path = str(Path(project_root) / ".git" / "hooks" / "commit-msg")
+    git_hook = Path(git_hook_path).exists()
+
+    hooks_dir = Path(project_root) / ".git" / "hooks"
+    git_capture_hook_names = ["post-commit", "post-merge", "post-checkout", "post-rewrite"]
+    git_capture_hooks: dict[str, bool] = {}
+    git_capture_hooks_path: dict[str, str] = {}
+    for name in git_capture_hook_names:
+        hook_path = hooks_dir / name
+        exists = hook_path.exists()
+        git_capture_hooks[name] = exists
+        git_capture_hooks_path[name] = str(hook_path)
+
+    return {
+        "claude_hooks": claude_hooks,
+        "claude_hooks_path": claude_hooks_path,
+        "git_hook": git_hook,
+        "git_hook_path": git_hook_path,
+        "git_capture_hooks": git_capture_hooks,
+        "git_capture_hooks_path": git_capture_hooks_path,
+    }
+
+
+# ---------------------------------------------------------------------------
+# IDE / project-type detection
+# ---------------------------------------------------------------------------
+
+_IDE_DETECTION_MARKERS: dict[str, str] = {
+    ".claude": "claude-code",
+    ".cursor": "cursor",
+    ".vscode": "vscode",
+    ".kiro": "kiro",
+    ".antigravity": "antigravity",
+    "mcp_config.json": "antigravity",
+}
+
+
+def _detect_ides(project_dir: str) -> list[str]:
+    """
+    Detect installed IDE directories/files in *project_dir*.
+
+    Scans for ``.claude/``, ``.cursor/``, ``.vscode/``, ``.kiro/``,
+    ``.antigravity/``, and ``mcp_config.json``. Returns a list of
+    IDE identifiers in the order they were found, with duplicates removed
+    (``mcp_config.json`` and ``.antigravity/`` both map to ``antigravity``).
+    """
+    root = Path(project_dir)
+    found: list[str] = []
+    seen: set[str] = set()
+    for marker, ide_name in _IDE_DETECTION_MARKERS.items():
+        if (root / marker).exists() and ide_name not in seen:
+            found.append(ide_name)
+            seen.add(ide_name)
+    return found
+
+
+_PROJECT_TYPE_MARKERS: dict[str, str] = {
+    "pyproject.toml": "python",
+    "requirements.txt": "python",
+    "setup.py": "python",
+    "go.mod": "go",
+    "composer.json": "php",
+    "package.json": "typescript",
+    "tsconfig.json": "typescript",
+}
+
+
+def _detect_project_type(project_dir: str) -> str:
+    """
+    Detect the dominant project type in *project_dir*.
+
+    Scans for ``pyproject.toml``, ``package.json``, ``go.mod``,
+    ``composer.json``, and related markers. Returns one of:
+    ``python``, ``typescript``, ``react``, ``go``, ``php``, or ``generic``.
+    """
+    root = Path(project_dir)
+    for marker, project_type in _PROJECT_TYPE_MARKERS.items():
+        if (root / marker).exists():
+            if marker == "package.json":
+                try:
+                    data = json.loads((root / marker).read_text(encoding="utf-8"))
+                    deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+                    if "react" in deps:
+                        return "react"
+                except Exception:
+                    pass
+            return project_type
+    return "generic"
+
+
+# ---------------------------------------------------------------------------
+# Shared MCP server entry for Cursor / Antigravity
+# ---------------------------------------------------------------------------
+
+_MCP_SERVER_ENTRY = {
+    "thinkstack": {
+        "command": "thinkstack",
+        "args": ["mcp-server"],
+    }
+}
+
+
+# ---------------------------------------------------------------------------
+# install_claude_mcp
+# ---------------------------------------------------------------------------
+
+# Claude Code reads project-scope MCP servers only from <root>/.mcp.json;
+# a mcpServers key inside .claude/settings.json is silently ignored.
+CLAUDE_MCP_SERVER_ENTRY = {
+    "thinkstack": {
+        "command": "node",
+        "args": ["__THINKSTACK_BRIDGE_PATH__"],
+        "env": {
+            "THINKSTACK_MCP_URL": "__THINKSTACK_MCP_URL__",
+            "THINKSTACK_API_KEY": "__THINKSTACK_API_KEY__",
+        },
+    }
+}
+
+
+def _read_json_dict_or_backup(path: Path) -> dict:
+    """
+    Parse *path* as a JSON object. If it is unparseable or not an object,
+    rename it to ``<name>.bak`` so hand-edited content is never silently
+    clobbered, and return an empty dict.
+    """
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        data = None
+    if isinstance(data, dict):
+        return data
+    path.rename(path.with_name(path.name + ".bak"))
+    return {}
+
+
+def _pop_legacy_settings_mcp_entry(root: Path) -> Optional[dict]:
+    """
+    Remove a thinkstack entry stranded in .claude/settings.json mcpServers
+    (where Claude Code never reads it) and return it, or None.
+
+    Other mcpServers entries are left untouched; the mcpServers key itself is
+    dropped when the thinkstack entry was the only one.
+    """
+    settings_path = root / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return None
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    servers = settings.get("mcpServers")
+    if not isinstance(servers, dict) or "thinkstack" not in servers:
+        return None
+    entry = servers.pop("thinkstack")
+    if not servers:
+        del settings["mcpServers"]
+    settings_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    return entry if isinstance(entry, dict) else None
+
+
+def install_claude_mcp(project_root: str) -> tuple[bool, str]:
+    """
+    Write (or merge into) <project_root>/.mcp.json for Claude Code.
+
+    Adds the thinkstack MCP server entry pointing to the Cloudflare Worker
+    via the ThinkStack MCP bridge script. Preserves any existing servers.
+    Idempotent — skips write if thinkstack entry already present.
+    Migrates a thinkstack entry written to .claude/settings.json by older
+    ThinkStack versions, preserving its configured values.
+    Returns (True, path) on success, (False, error_message) on failure.
+    """
+    try:
+        root = Path(project_root)
+        mcp_path = root / ".mcp.json"
+
+        existing: dict = {}
+        if mcp_path.exists():
+            existing = _read_json_dict_or_backup(mcp_path)
+
+        legacy_entry = _pop_legacy_settings_mcp_entry(root)
+
+        servers = existing.setdefault("mcpServers", {})
+        if "thinkstack" not in servers or _uses_local_stdio(servers.get("thinkstack", {})):
+            entry = legacy_entry or _build_claude_mcp_entry(root)
+            servers["thinkstack"] = entry
+            mcp_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+
+        return True, str(mcp_path)
+
+    except Exception as exc:
+        return False, str(exc)
+
+
+def _uses_local_stdio(entry: dict) -> bool:
+    """Return True if the MCP entry uses a local thinkstack stdio process."""
+    if isinstance(entry, dict):
+        cmd = entry.get("command", "")
+        args = entry.get("args", [])
+        if cmd == "thinkstack" and any("mcp-server" in a for a in args):
+            return True
+    return False
+
+
+def _build_claude_mcp_entry(root: Path) -> dict:
+    """Build a Claude Code MCP entry pointing to the Cloudflare Worker via bridge."""
+    import os
+    mcp_url = ""
+    api_key = ""
+    bridge_path = ""
+
+    # Read from existing opencode.json if present
+    opencode_json = root / "opencode.json"
+    if opencode_json.exists():
+        try:
+            oc = json.loads(opencode_json.read_text(encoding="utf-8"))
+            mcp_cfg = oc.get("mcp", {}).get("thinkstack", {})
+            env = mcp_cfg.get("environment", {})
+            mcp_url = env.get("THINKSTACK_MCP_URL", "")
+            api_key = env.get("THINKSTACK_API_KEY", "")
+            if isinstance(mcp_cfg.get("command"), list) and len(mcp_cfg.get("command", [])) > 1:
+                bridge_path = mcp_cfg["command"][1]
+        except Exception:
+            pass
+
+    if not bridge_path:
+        try:
+            from importlib.resources import files
+            bridge_path = str(files("thinkstack_core") / "cloud" / "thinkstack-mcp-bridge.js")
+        except Exception:
+            bridge_path = os.path.join(os.path.dirname(__file__), "..", "cloud", "thinkstack-mcp-bridge.js")
+
+    return {
+        "command": "node",
+        "args": [bridge_path],
+        "env": {
+            "THINKSTACK_MCP_URL": mcp_url or os.environ.get("THINKSTACK_MCP_URL", ""),
+            "THINKSTACK_API_KEY": api_key or os.environ.get("THINKSTACK_API_KEY", ""),
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# install_cursor_mcp
+# ---------------------------------------------------------------------------
+
+
+def install_opencode_hooks(project_root: str) -> tuple[bool, str]:
+    """
+    Merge ThinkStack hooks into ``<project_root>/opencode.json`` for OpenCode.
+
+    - Reads the existing opencode.json if it exists.
+    - Deep-merges ThinkStack's OpenCode hooks into the ``hooks`` key.
+    - Strips previously-installed ThinkStack hook entries so re-installation
+      upgrades them in-place instead of accumulating duplicates.
+    - Returns (True, path) on success, (False, error_message) on failure.
+    """
+    try:
+        root = Path(project_root)
+        config_path = root / "opencode.json"
+
+        existing: dict = {}
+        if config_path.exists():
+            existing = _read_json_dict_or_backup(config_path)
+
+        hooks_existing: dict = existing.setdefault("hooks", {})
+        working = {"hooks": hooks_existing}
+        working = _strip_thinkstack_hook_entries(working)
+        merged = _deep_merge(working, OPENCODE_HOOKS_CONFIG)
+
+        result_obj = dict(existing)
+        result_obj["hooks"] = merged.get("hooks", {})
+        config_path.write_text(json.dumps(result_obj, indent=2), encoding="utf-8")
+
+        return True, str(config_path)
+    except Exception as exc:
+        return False, str(exc)
+
+
+def install_cursor_mcp(project_root: str) -> tuple[bool, str]:
+    """
+    Write (or merge into) .cursor/mcp.json under *project_root*.
+
+    Adds the thinkstack MCP server entry. Preserves any existing servers.
+    Idempotent — skips write if thinkstack entry already present.
+    Returns (True, path) on success, (False, error_message) on failure.
+    """
+    try:
+        cursor_dir = Path(project_root) / ".cursor"
+        cursor_dir.mkdir(parents=True, exist_ok=True)
+        mcp_path = cursor_dir / "mcp.json"
+
+        existing: dict = {}
+        if mcp_path.exists():
+            try:
+                existing = json.loads(mcp_path.read_text(encoding="utf-8"))
+            except Exception:
+                existing = {}
+
+        servers = existing.setdefault("mcpServers", {})
+        if "thinkstack" not in servers:
+            servers["thinkstack"] = _MCP_SERVER_ENTRY["thinkstack"]
+            mcp_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+
+        return True, str(mcp_path)
+
+    except Exception as exc:
+        return False, str(exc)
+
+
+# ---------------------------------------------------------------------------
+# install_antigravity_mcp
+# ---------------------------------------------------------------------------
+
+
+def install_antigravity_mcp(project_root: str) -> tuple[bool, str]:
+    """
+    Write (or merge into) mcp_config.json at *project_root*.
+
+    Antigravity uses a project-level mcp_config.json for MCP server registration.
+    Adds the thinkstack MCP server entry. Preserves any existing servers.
+    Idempotent — skips write if thinkstack entry already present.
+    Returns (True, path) on success, (False, error_message) on failure.
+    """
+    try:
+        mcp_path = Path(project_root) / "mcp_config.json"
+
+        existing: dict = {}
+        if mcp_path.exists():
+            try:
+                existing = json.loads(mcp_path.read_text(encoding="utf-8"))
+            except Exception:
+                existing = {}
+
+        servers = existing.setdefault("mcpServers", {})
+        if "thinkstack" not in servers:
+            servers["thinkstack"] = _MCP_SERVER_ENTRY["thinkstack"]
+            mcp_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+
+        return True, str(mcp_path)
+
+    except Exception as exc:
+        return False, str(exc)