cli/

install.rs

//! `mushroomdb install` / `uninstall` — wire the /mushroom skill, the MCP
//! server, the prompt hooks and the git hooks into an assistant.
//!
//! # Design notes
//!
//! - Idempotent: running install twice is a no-op (exit 0).
//! - Non-destructive: refuses to overwrite user files install didn't create.
//! - Manifest-driven uninstall: tracks every file, key, hook, ignore line and
//!   external registration it wrote; removes exactly that.
//! - The only network access is the optional pre-warm, which is a best-effort
//!   warm cache and never fails the install.
//!
//! # User-scope MCP config location (verified 2026-09-02 by live inspection)
//!
//! Claude Code user-level MCP servers live in `~/.claude.json` under the
//! top-level `"mcpServers"` key. This was verified empirically on a live
//! Claude Code install: `~/.claude/settings.json` holds env/permissions/hooks
//! but NO mcpServers key. Cursor uses `~/.cursor/mcp.json` (same format as
//! project-level `.cursor/mcp.json`). Codex keeps its own config and is
//! written through the `codex` CLI rather than by editing a file.

use crate::CliError;
use serde::{Deserialize, Serialize};
use std::ffi::{OsStr, OsString};
use std::fs;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};

// Template files embedded at compile time. Files live inside the crates/cli
// package so `cargo package` includes them in the published tarball.
// Path is relative to this source file (crates/cli/src/install.rs).
const SKILL_TEMPLATE: &str = include_str!("../skills/mushroom/SKILL.md");
const CURSOR_RULES_TEMPLATE: &str = include_str!("../skills/mushroom/cursor-rules.mdc");

/// Placeholder string replaced with the real db path in embedded templates.
const DB_PATH_PLACEHOLDER: &str = "{{DB_PATH}}";

/// Placeholder string replaced with the command that invokes mushroomdb.
/// Substituted with [`McpCommand::shell`], which is already shell-quoted, so
/// the templates must leave it unquoted.
const BIN_PLACEHOLDER: &str = "{{BIN}}";

/// The MCP server name we write. Must not be changed without a migration.
const SERVER_NAME: &str = "mushroomdb";

/// The binary name looked up on PATH and used as the bare MCP command.
const BIN_NAME: &str = "mushroomdb";

/// The npm package the `npx` form runs. Same name as the binary.
const NPM_PACKAGE: &str = "mushroomdb";

/// The version an `npx` entry pins: the one that wrote it.
const CRATE_VERSION: &str = env!("CARGO_PKG_VERSION");

/// How long the optional pre-warm may take before it is abandoned. A cold
/// `npx` download of a native package is slow on a slow link, and the whole
/// point is to pay that cost here rather than at the assistant's first prompt.
const PREWARM_TIMEOUT_SECS: u64 = 180;

/// The Node runtime a resolved launcher is handed to. Looked up on PATH: any
/// machine with `npx` has it, since npm ships with Node.
const NODE_BIN: &str = "node";

/// The flag the npm launcher answers with the vendored native binary's path.
const PRINT_BINARY_FLAG: &str = "--print-binary";

/// The flag the npm launcher answers with its own absolute path.
const PRINT_LAUNCHER_FLAG: &str = "--print-launcher";

// ---------------------------------------------------------------------------
// How the server is invoked
// ---------------------------------------------------------------------------

/// How the MCP server entry (and the skill's bootstrap commands) invoke
/// mushroomdb.
///
/// The assistant host spawns the MCP server by `command`, so that command has
/// to resolve from *its* process, not from the shell install ran in. A bare
/// name only works when it resolves on the host's PATH, and the one case where
/// that is provable is when the `mushroomdb` PATH resolves to is this very
/// executable. Everything else — npm's Node shim, a different build, a local
/// `target/release` binary, no hit at all — pins the published package and
/// lets `npx` fetch it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum McpCommand {
    /// `npx -y mushroomdb@<version> …` — the fallback when the package cannot
    /// be located, and the only form that works from a machine where nothing
    /// is installed globally.
    Npx { version: String },
    /// The published package's own native binary, located once at install time
    /// and run directly. The fast form, and what a hook gets whenever the
    /// package has been fetched.
    ///
    /// Everything else in this enum that reaches the published package ends up
    /// running this exact file; the difference is what it costs to get there.
    /// Measured warm, `--version` end to end: `npx` 514 ms, `node <launcher>`
    /// 118 ms, this 7 ms. Node's own startup is nearly all of the difference —
    /// the launcher script's only job is to spawn this binary — and a hook pays
    /// it on every prompt and every edit.
    NativeBinary {
        /// Absolute path to the vendored executable.
        binary: PathBuf,
        /// The version it was resolved from; re-resolved on upgrade.
        version: String,
    },
    /// `node <launcher.js> …` — the same published package reached through its
    /// npm shim. The fallback for an install whose native binary could not be
    /// located (a postinstall that never fetched it, say): still resolved once
    /// rather than on every invocation, just through a Node startup.
    NodeLauncher {
        /// Absolute path to the package's `bin` script.
        launcher: PathBuf,
        /// The version it was resolved from; re-resolved on upgrade.
        version: String,
    },
    /// An absolute path the user named with `--command`.
    Explicit(PathBuf),
    /// `mushroomdb` resolves on PATH *and* is this executable: the bare name
    /// is safe and follows upgrades.
    OnPath,
}

impl McpCommand {
    /// The `npx` form pinned to the version of the binary writing it.
    #[must_use]
    pub fn npx() -> Self {
        McpCommand::Npx {
            version: CRATE_VERSION.to_string(),
        }
    }

    /// The program to exec and the arguments that come before the subcommand.
    fn program(&self) -> (String, Vec<String>) {
        match self {
            McpCommand::Npx { version } => (
                "npx".to_string(),
                vec!["-y".to_string(), format!("{NPM_PACKAGE}@{version}")],
            ),
            McpCommand::NativeBinary { binary, .. } => {
                (binary.to_string_lossy().into_owned(), Vec::new())
            }
            McpCommand::NodeLauncher { launcher, .. } => (
                NODE_BIN.to_string(),
                vec![launcher.to_string_lossy().into_owned()],
            ),
            McpCommand::Explicit(p) => (p.to_string_lossy().into_owned(), Vec::new()),
            McpCommand::OnPath => (BIN_NAME.to_string(), Vec::new()),
        }
    }

    /// The MCP server entry: `{"command": …, "args": [… , sub, db]}`.
    ///
    /// Nothing here is shell-quoted. An MCP host spawns the command with an
    /// argv, so a path with a space in it is one element and quoting it would
    /// make the quotes part of the filename.
    #[must_use]
    pub fn json_entry(&self, sub: &str, db: &str) -> serde_json::Value {
        let (command, mut args) = self.program();
        args.push(sub.to_string());
        args.push(db.to_string());
        serde_json::json!({ "command": command, "args": args })
    }

    /// The same invocation as a command *prefix* for a POSIX shell, already
    /// quoted where quoting is needed.
    ///
    /// Hook entries and the skill's copy-paste lines are read by a shell, so
    /// an explicit path — and a resolved binary or launcher path, which lives
    /// wherever npm put it — has to survive a space in it. The bare name and
    /// the `npx` form contain no metacharacters and are left as they read.
    #[must_use]
    pub fn shell(&self) -> String {
        let (command, args) = self.program();
        let mut out = match self {
            McpCommand::Explicit(_) | McpCommand::NativeBinary { .. } => sh_quote(&command),
            _ => command,
        };
        for a in args {
            out.push(' ');
            match self {
                McpCommand::NodeLauncher { .. } => out.push_str(&sh_quote(&a)),
                _ => out.push_str(&a),
            }
        }
        out
    }

    /// The full argv, for handing to another CLI that registers servers.
    fn argv(&self, sub: &str, db: &str) -> Vec<String> {
        let (command, mut args) = self.program();
        args.push(sub.to_string());
        args.push(db.to_string());
        let mut out = vec![command];
        out.extend(args);
        out
    }
}

/// Decide how the MCP entry should invoke mushroomdb, from an explicit
/// `--command` (if any) and the real environment.
///
/// `explicit` is `install`'s `--command` flag; `enable` has no such flag and
/// always passes `None`, so it re-derives whatever `install` would choose
/// right now rather than replaying what an earlier install or `disable`
/// recorded.
#[must_use]
pub fn detect_mcp_command(explicit: Option<&Path>) -> McpCommand {
    if let Some(path) = explicit {
        return McpCommand::Explicit(path.to_path_buf());
    }
    match std::env::current_exe() {
        Ok(exe) => classify_mcp_command(std::env::var_os("PATH").as_deref(), &exe),
        // Cannot locate ourselves — the pinned package always resolves.
        Err(_) => McpCommand::npx(),
    }
}

/// Pure classifier behind [`detect_mcp_command`]: decide whether the
/// `mushroomdb` that PATH resolves to is the executable now running.
///
/// A file named `mushroomdb` on PATH is not enough. `npx mushroomdb install`
/// prepends `~/.npm/_npx/<hash>/node_modules/.bin` to PATH, and the
/// `mushroomdb` there is npm's Node shim (`#!/usr/bin/env node`), not our
/// native binary; `npm i -g mushroomdb` installs the same shim. Treating that
/// as "on PATH" wrote a bare `mushroomdb` command that resolved only inside
/// the npx-spawned shell, so the MCP server and recall hook died with ENOENT
/// everywhere else (the v0.5.0 bug).
///
/// So: take the first PATH hit — that is what a bare name would resolve to —
/// and canonicalize both it and `current_exe`. Equal paths mean the bare name
/// runs this very executable, including via a symlink (how `cargo install` and
/// Homebrew expose it), which is the one case where the bare name is safe and
/// survives upgrades. Anything else means pinning the published package.
#[must_use]
pub fn classify_mcp_command(path_var: Option<&OsStr>, current_exe: &Path) -> McpCommand {
    // What a bare `mushroomdb` would resolve to: the first PATH entry holding
    // a file by that name (`is_file` follows symlinks, so links count).
    let Some(hit) = path_var.and_then(|p| {
        std::env::split_paths(p)
            .map(|dir| dir.join(BIN_NAME))
            .find(|candidate| candidate.is_file())
    }) else {
        return McpCommand::npx();
    };

    // Identity, not name. Canonicalizing resolves symlinks and `..`, so a link
    // to us compares equal; if either side cannot be resolved we cannot prove
    // it is us, and the pinned package is the answer that always works.
    match (fs::canonicalize(&hit), fs::canonicalize(current_exe)) {
        (Ok(on_path), Ok(running)) if on_path == running => McpCommand::OnPath,
        _ => McpCommand::npx(),
    }
}

// ---------------------------------------------------------------------------
// How the store is named
// ---------------------------------------------------------------------------

/// The argument every written command uses in place of a store path when the
/// store is to be resolved at run time.
pub const AUTO_ARG: &str = "--auto";

/// How the config an install writes names the store.
///
/// A project install writes `--auto`, not a path. The MCP entry, the two
/// settings hooks and the three git hook blocks then resolve the store when
/// they run — `$CLAUDE_PROJECT_DIR/mushroom-memory`, else `mushroom-memory` at
/// the root of the working tree they were run in.
///
/// The reason is `git worktree`. Those config files live in the repository and
/// get committed, so an absolute path baked into them follows a new worktree
/// across and points every hook there at the *other* checkout's store: the
/// graph then describes files that are not the ones being edited. Resolving at
/// run time gives each working tree its own store, which is the only answer
/// that is right in both checkouts.
///
/// `--db <path>` opts out and pins an absolute path; user scope always pins
/// `~/.mushroomdb/memory`, since `--auto` inside any checkout would resolve to
/// that project instead.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StoreRef {
    /// Where the store actually is for the checkout install ran in. Every
    /// local decision — the `.gitignore` line, the skill's prose, the
    /// pre-flight conflict check — needs a real directory whichever form is
    /// written into the config.
    path: PathBuf,
    /// Whether written config says `--auto` rather than that path.
    auto: bool,
    /// Whether `--auto` resolves to this same store in this checkout. Always
    /// true when `auto` is. Also true for a `--db` that happens to name the
    /// default store, so an upgrade over an `--auto` install replaces its
    /// hooks instead of running both.
    auto_equivalent: bool,
}

impl StoreRef {
    /// A store the config names `--auto`, living at `path` for this checkout.
    #[must_use]
    pub fn auto(path: impl Into<PathBuf>) -> Self {
        let path = path.into();
        StoreRef {
            path,
            auto: true,
            auto_equivalent: true,
        }
    }

    /// A store the config names by absolute path.
    #[must_use]
    pub fn pinned(path: impl Into<PathBuf>) -> Self {
        StoreRef {
            path: path.into(),
            auto: false,
            auto_equivalent: false,
        }
    }

    /// Mark a pinned store as the one `--auto` also resolves to here.
    #[must_use]
    pub fn also_auto(mut self) -> Self {
        self.auto_equivalent = true;
        self
    }

    /// Where the store is on this machine, right now.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }

    /// Whether written config resolves the store at run time.
    #[must_use]
    pub fn is_auto(&self) -> bool {
        self.auto
    }

    /// The argument written into an MCP entry's `args` array: `--auto`, or the
    /// path. Not shell-quoted — an MCP host spawns an argv, where quotes would
    /// become part of the filename.
    #[must_use]
    pub fn arg(&self) -> String {
        if self.auto {
            AUTO_ARG.to_string()
        } else {
            self.path.to_string_lossy().into_owned()
        }
    }

    /// The same argument for a command line a shell reads, quoted where
    /// quoting is needed. `--auto` needs none; a path may contain a space.
    #[must_use]
    pub fn shell_arg(&self) -> String {
        if self.auto {
            AUTO_ARG.to_string()
        } else {
            sh_quote(&self.path.to_string_lossy())
        }
    }

    /// How the summary line describes the store.
    fn describe(&self) -> String {
        if self.auto {
            format!("{AUTO_ARG} (resolves to {})", self.path.display())
        } else {
            format!("{} (pinned)", self.path.display())
        }
    }

    /// Every command tail a hook of ours for `sub` may end with, for this
    /// store: the path spelling always, and the `--auto` spelling when that
    /// resolves here too.
    ///
    /// Both are needed because an upgrade must recognise what the *previous*
    /// version wrote. 0.6.0 wrote an absolute path; this version writes
    /// `--auto`; either one left behind alongside the other means two recall
    /// digests on every prompt.
    fn hook_tails(&self, sub: &str) -> Vec<String> {
        let mut out = vec![format!(" {sub} {}", sh_quote(&self.path.to_string_lossy()))];
        if self.auto_equivalent {
            out.push(format!(" {sub} {AUTO_ARG}"));
        }
        out
    }

    /// Whether an existing config argument names this same store: the same
    /// spelling, the same path, or `--auto` where `--auto` means this store.
    ///
    /// This is what makes an upgrade an upgrade rather than a conflict — a
    /// 0.6.0 entry naming `<project>/mushroom-memory` is the store `--auto`
    /// now resolves to, so it is rewritten rather than refused.
    fn names_same_store(&self, existing_arg: &str) -> bool {
        if existing_arg == AUTO_ARG {
            return self.auto_equivalent;
        }
        Path::new(existing_arg) == self.path
    }
}

// ---------------------------------------------------------------------------
// Options
// ---------------------------------------------------------------------------

/// Which assistant platform(s) to wire up.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Platform {
    ClaudeCode,
    Cursor,
    Codex,
    All,
}

impl Platform {
    pub fn parse(s: &str) -> Result<Self, String> {
        match s {
            "claude-code" => Ok(Platform::ClaudeCode),
            "cursor" => Ok(Platform::Cursor),
            "codex" => Ok(Platform::Codex),
            "all" => Ok(Platform::All),
            other => Err(format!(
                "--platform must be claude-code | cursor | codex | all, got: {other}"
            )),
        }
    }

    pub(crate) fn label(&self) -> &'static str {
        match self {
            Platform::ClaudeCode => "claude-code",
            Platform::Cursor => "cursor",
            Platform::Codex => "codex",
            Platform::All => "all",
        }
    }
}

/// Where the install lives: alongside one repository, or once for the user.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Scope {
    Project,
    User,
}

impl Scope {
    pub(crate) fn label(self) -> &'static str {
        match self {
            Scope::Project => "project",
            Scope::User => "user",
        }
    }
}

/// Options parsed from `mushroomdb install [flags]` or `mushroomdb uninstall [flags]`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InstallOpts {
    /// Which platform to wire up. `None` = auto-detect.
    pub platform: Option<Platform>,
    /// Project or user scope. `None` = auto: project inside a git checkout.
    pub scope: Option<Scope>,
    /// Database directory. `None` = use the scope default.
    pub db: Option<PathBuf>,
    /// `--command <path>`: invoke this binary instead of `npx`/the bare name.
    pub command: Option<PathBuf>,
    /// Write the `post-commit` / `post-checkout` / `post-merge` sync hooks.
    pub git_hooks: bool,
    /// Run `npx -y mushroomdb@<v> --version` once so the first real spawn is
    /// not a cold download.
    pub prewarm: bool,
}

/// Options parsed from `mushroomdb enable [flags]` or `mushroomdb disable [flags]`.
///
/// Deliberately narrower than [`InstallOpts`]: neither command takes `--db`,
/// `--command` or `--no-git-hooks` — they act on whatever an existing install
/// already recorded, not on a fresh choice of store or binary.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ToggleOpts {
    /// Which platform to act on. `None` = auto-detect, same as `install`.
    pub platform: Option<Platform>,
    /// Project or user scope. `None` = auto: project inside a git checkout.
    pub scope: Option<Scope>,
}

/// The store directory an install with no `--db` uses.
#[must_use]
pub fn default_db(scope: Scope, project_root: &Path, home: &Path) -> PathBuf {
    match scope {
        Scope::Project => project_root.join("mushroom-memory"),
        Scope::User => home.join(".mushroomdb").join("memory"),
    }
}

/// Whether this platform's host guarantees `--auto` resolves to this project.
///
/// Only Claude Code does. It sets `$CLAUDE_PROJECT_DIR` for both MCP servers
/// and hook processes, so the first resolution step always answers, whatever
/// working directory the process happens to have.
///
/// Cursor and Codex set no such variable. `--auto` there would rest entirely
/// on the host spawning the server inside the checkout, and if it did not,
/// resolution would fall through to `~/.mushroomdb/memory`: an empty store,
/// with the `.gitignore` line and the rules file both naming a different
/// directory, and nothing anywhere reporting an error. The assistant would
/// simply see a graph with nothing in it. So those two get the path.
///
/// The worktree argument is weaker for them in any case. `.mcp.json` and the
/// two settings hooks are Claude Code's, and they are what a `git worktree`
/// carries across; a Cursor install's committed artifact is one rules file
/// that names the store in prose.
fn resolves_at_runtime(platform: &Platform) -> bool {
    match platform {
        Platform::ClaudeCode => true,
        Platform::Cursor | Platform::Codex => false,
        // `expand_platform` never produces it; false is the safe reading.
        Platform::All => false,
    }
}

/// How each requested platform will name the store, in the order they were
/// asked for.
fn platform_stores(
    project_root: &Path,
    home: &Path,
    scope: Scope,
    db: Option<&Path>,
    platforms: &[Platform],
) -> Vec<(Platform, StoreRef)> {
    platforms
        .iter()
        .map(|p| {
            (
                p.clone(),
                store_ref(project_root, home, scope, db, resolves_at_runtime(p)),
            )
        })
        .collect()
}

/// The summary's `store` line(s).
///
/// One line when every platform names the store the same way, which is every
/// single-platform install and most `--platform all` ones. When they differ —
/// Claude Code resolving `--auto` beside a Cursor entry that cannot — each is
/// labelled, because "which one is pinned" is exactly what a reader needs.
fn describe_stores(stores: &[(Platform, StoreRef)]) -> String {
    let all_same = stores.windows(2).all(|w| w[0].1 == w[1].1);
    match stores.first() {
        None => String::new(),
        Some((_, first)) if all_same => format!("  store  {}\n", first.describe()),
        _ => stores
            .iter()
            .map(|(p, s)| format!("  store  {}: {}\n", p.label(), s.describe()))
            .collect(),
    }
}

/// The store the *repository* wiring names: the `.gitignore` line and the
/// three git hook blocks.
///
/// `--auto` is safe here on its own terms, whatever platform asked for the
/// install: git runs a hook with the working tree it acted on as the working
/// directory, so the store resolves from that tree with no assistant, and no
/// `$CLAUDE_PROJECT_DIR`, involved. It is written when any installed platform
/// writes it, so the git hooks and the assistant's own config agree — and
/// pinned otherwise, so a Cursor-only install is one store spelled one way.
fn repo_store_ref(
    project_root: &Path,
    home: &Path,
    scope: Scope,
    db: Option<&Path>,
    platforms: &[Platform],
) -> StoreRef {
    let runtime_ok = platforms.iter().any(resolves_at_runtime);
    store_ref(project_root, home, scope, db, runtime_ok)
}

/// How one platform will name the store in everything written for it.
///
/// `--auto` is written only where it provably resolves to the same directory:
/// the default store, in project scope, inside a git checkout, for a host that
/// resolves it (`runtime_ok`, from [`resolves_at_runtime`]). The checkout
/// condition is what makes the fallback safe — a hook that never receives
/// `$CLAUDE_PROJECT_DIR` still finds the store by walking up to the working
/// tree root, and there is no working tree root to find without it. Everywhere
/// else the path is pinned, because a wrong `--auto` would silently build a
/// second store under the home directory and report nothing.
fn store_ref(
    project_root: &Path,
    home: &Path,
    scope: Scope,
    db: Option<&Path>,
    runtime_ok: bool,
) -> StoreRef {
    let default = default_db(scope, project_root, home);
    let Some(pinned) = db.map(|d| absolutise(d, project_root)) else {
        if runtime_ok && scope == Scope::Project && project_root.join(".git").exists() {
            return StoreRef::auto(default);
        }
        // Pinned, but `--auto` would still name this same directory in project
        // scope — so a `--auto` entry an earlier build wrote here is this
        // install's to rewrite rather than a conflicting one to refuse.
        let pinned = StoreRef::pinned(default);
        return if scope == Scope::Project {
            pinned.also_auto()
        } else {
            pinned
        };
    };
    // A `--db` naming the very store `--auto` resolves to is still pinned —
    // the user asked for a path — but an `--auto` hook from an earlier install
    // points at the same place and is this install's to replace.
    let auto_here = default_db(Scope::Project, project_root, home);
    if pinned == auto_here {
        return StoreRef::pinned(pinned).also_auto();
    }
    StoreRef::pinned(pinned)
}

/// Resolve the scope, and say whether it was inferred.
///
/// A git checkout is a project: its store belongs beside it, is ignored by the
/// repository, and its hooks fire on its commits. Anywhere else there is no
/// project to scope to, so the install is the user's.
pub(crate) fn resolve_scope(project_root: &Path, requested: Option<Scope>) -> (Scope, bool) {
    match requested {
        Some(s) => (s, false),
        None if project_root.join(".git").exists() => (Scope::Project, true),
        None => (Scope::User, true),
    }
}

// ---------------------------------------------------------------------------
// External programs
// ---------------------------------------------------------------------------

/// The world outside the two directories install is given: the programs it
/// shells out to (`codex`, `npx`) and how long it will wait for them.
///
/// Carried explicitly rather than read from the process environment at the
/// point of use, so a test can point PATH at a directory of stand-ins without
/// mutating global state that its neighbours share.
#[derive(Debug, Clone)]
pub struct Externals {
    /// PATH used to resolve external programs. `None` resolves nothing.
    pub path: Option<OsString>,
    /// Budget for the pre-warm.
    pub prewarm_timeout: Duration,
}

impl Externals {
    /// The real process environment.
    #[must_use]
    pub fn from_env() -> Self {
        Self::with_path(std::env::var_os("PATH"))
    }

    /// The same, with an explicit PATH.
    #[must_use]
    pub fn with_path(path: Option<OsString>) -> Self {
        Self {
            path,
            prewarm_timeout: Duration::from_secs(PREWARM_TIMEOUT_SECS),
        }
    }

    /// The first executable named `program` on this PATH.
    pub(crate) fn which(&self, program: &str) -> Option<PathBuf> {
        let path = self.path.as_ref()?;
        std::env::split_paths(path)
            .map(|dir| dir.join(program))
            .find(|c| is_executable(c))
    }
}

fn is_executable(path: &Path) -> bool {
    let Ok(meta) = fs::metadata(path) else {
        return false;
    };
    if !meta.is_file() {
        return false;
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        meta.permissions().mode() & 0o111 != 0
    }
    #[cfg(not(unix))]
    {
        true
    }
}

/// Run `bin` to completion, returning its stderr (trimmed) on a non-zero exit.
fn run_and_capture(bin: &Path, args: &[String]) -> Result<(), String> {
    let out = std::process::Command::new(bin)
        .args(args)
        .output()
        .map_err(|e| format!("cannot run {}: {e}", bin.display()))?;
    if out.status.success() {
        return Ok(());
    }
    let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
    let detail = if stderr.is_empty() {
        String::new()
    } else {
        format!(": {stderr}")
    };
    Err(format!(
        "{} {} exited with {}{detail}",
        bin.display(),
        args.join(" "),
        out.status
    ))
}

/// Run `bin`, giving up after `timeout`. Output is discarded — only the exit
/// status matters — so the child cannot block on a pipe nobody drains.
fn run_with_timeout(bin: &Path, args: &[String], timeout: Duration) -> Result<(), String> {
    let mut child = std::process::Command::new(bin)
        .args(args)
        .stdin(std::process::Stdio::null())
        .stdout(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .spawn()
        .map_err(|e| format!("cannot run {}: {e}", bin.display()))?;
    let deadline = Instant::now() + timeout;
    loop {
        match child.try_wait() {
            Ok(Some(status)) if status.success() => return Ok(()),
            Ok(Some(status)) => return Err(format!("exited with {status}")),
            Ok(None) => {}
            Err(e) => return Err(format!("cannot wait for {}: {e}", bin.display())),
        }
        if Instant::now() >= deadline {
            let _ = child.kill();
            let _ = child.wait();
            return Err(format!("timed out after {}s", timeout.as_secs()));
        }
        std::thread::sleep(Duration::from_millis(25));
    }
}

/// Run `bin`, capturing stdout and giving up after `timeout`.
///
/// The pipe is drained on another thread so a child that writes more than a
/// pipe buffer cannot deadlock against the timeout loop watching it.
fn capture_with_timeout(bin: &Path, args: &[String], timeout: Duration) -> Result<String, String> {
    let mut child = std::process::Command::new(bin)
        .args(args)
        .stdin(std::process::Stdio::null())
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::null())
        .spawn()
        .map_err(|e| format!("cannot run {}: {e}", bin.display()))?;
    let mut stdout = child.stdout.take().expect("stdout is piped");
    let (tx, rx) = std::sync::mpsc::channel::<String>();
    std::thread::spawn(move || {
        use std::io::Read as _;
        let mut out = String::new();
        let _ = stdout.read_to_string(&mut out);
        let _ = tx.send(out);
    });
    let deadline = Instant::now() + timeout;
    loop {
        match child.try_wait() {
            Ok(Some(status)) if status.success() => {
                return Ok(rx.recv_timeout(Duration::from_secs(1)).unwrap_or_default());
            }
            Ok(Some(status)) => return Err(format!("exited with {status}")),
            Ok(None) if Instant::now() >= deadline => {
                let _ = child.kill();
                let _ = child.wait();
                return Err(format!("timed out after {}s", timeout.as_secs()));
            }
            Ok(None) => std::thread::sleep(Duration::from_millis(25)),
            Err(e) => return Err(format!("cannot wait for {}: {e}", bin.display())),
        }
    }
}

/// Ask the published package where something of its own is, once.
///
/// `flag` is [`PRINT_BINARY_FLAG`] or [`PRINT_LAUNCHER_FLAG`]; the package
/// answers with an absolute path and exits. Writing that path into the hooks
/// takes the whole npx resolution — cache check, version resolve, an extra Node
/// process — off the per-prompt and per-edit path.
///
/// Chosen over `npm root -g` (only finds a *global* install, which the npx
/// route never makes) and over `npm exec --offline` (still pays npm's own
/// startup on every call). Asking the package itself is the one answer that is
/// correct for however it was installed, and it is the same fetch the pre-warm
/// already ran, so it costs an install nothing extra.
///
/// Every failure is recoverable: the caller falls back a step.
fn ask_package(version: &str, flag: &str, ext: &Externals) -> Result<PathBuf, String> {
    let npx = ext
        .which("npx")
        .ok_or_else(|| "npx is not on PATH".to_string())?;
    let args = vec![
        "-y".to_string(),
        format!("{NPM_PACKAGE}@{version}"),
        flag.to_string(),
    ];
    let out = capture_with_timeout(&npx, &args, ext.prewarm_timeout)?;
    // The last non-blank line: npm is entitled to print notices before it.
    let path = out
        .lines()
        .map(str::trim)
        .rfind(|l| !l.is_empty())
        .ok_or_else(|| format!("{NPM_PACKAGE}@{version} {flag} printed nothing"))?;
    let path = PathBuf::from(path);
    if !path.is_absolute() {
        return Err(format!("{} is not an absolute path", path.display()));
    }
    if !path.is_file() {
        return Err(format!("{} does not exist", path.display()));
    }
    Ok(path)
}

/// Turn an `npx` command into a resolved, directly-runnable one, so the hooks
/// it writes do not spawn `npx` on every invocation.
///
/// Three rungs, best first:
///
/// 1. **The native binary** (`--print-binary`). What every other form ends up
///    running anyway, reached without a Node startup in front of it.
/// 2. **`node <launcher>`** (`--print-launcher`). For a package whose vendored
///    binary was never fetched, and only when `node` is on PATH to run it.
/// 3. **`npx`**, unchanged, with a warning saying the hooks will be slow.
///
/// Returns the command to write; the one-line warning for the summary when
/// every rung failed; and whether the package was fetched on the way, which
/// tells the caller the separate pre-warm has nothing left to do. Anything
/// other than the `npx` form is already a direct path and is handed back
/// untouched.
fn resolve_fast_command(cmd: &McpCommand, ext: &Externals) -> (McpCommand, Option<String>, bool) {
    let McpCommand::Npx { version } = cmd else {
        return (cmd.clone(), None, false);
    };
    // Asking the package anything downloads it first, so one question warms
    // the cache exactly as the pre-warm's `--version` would. If `npx` is not
    // there to ask, nothing was fetched and the pre-warm's own report of that
    // is worth having.
    let fetched = ext.which("npx").is_some();
    let binary_err = match ask_package(version, PRINT_BINARY_FLAG, ext) {
        Ok(binary) => {
            return (
                McpCommand::NativeBinary {
                    binary,
                    version: version.clone(),
                },
                None,
                fetched,
            )
        }
        Err(e) => e,
    };
    // No binary. The launcher is the same package one Node startup away, and
    // it is only worth writing if `node` is there to run it.
    if ext.which(NODE_BIN).is_some() {
        if let Ok(launcher) = ask_package(version, PRINT_LAUNCHER_FLAG, ext) {
            return (
                McpCommand::NodeLauncher {
                    launcher,
                    version: version.clone(),
                },
                None,
                fetched,
            );
        }
    }
    (
        cmd.clone(),
        Some(format!(
            "warning: could not resolve {NPM_PACKAGE}@{version} to a path ({binary_err}) — \
             the hooks will spawn npx on every prompt and every edit"
        )),
        fetched,
    )
}

// ---------------------------------------------------------------------------
// Manifest — tracks everything install wrote so uninstall can undo it.
// ---------------------------------------------------------------------------

#[derive(Serialize, Deserialize, Default, Debug)]
struct Manifest {
    /// Files created by this install (absolute paths).
    files: Vec<PathBuf>,
    /// MCP JSON keys added by this install.
    mcp_keys: Vec<ManagedMcpKey>,
    /// Hook entries added to a settings.json by this install.
    #[serde(default)]
    hooks: Vec<ManagedHook>,
    /// Git hook files this install put its block into.
    #[serde(default)]
    git_hooks: Vec<PathBuf>,
    /// Single lines added to a file the user owns (the `.gitignore` entry).
    #[serde(default)]
    gitignore: Vec<ManagedLine>,
    /// Whether a Codex MCP server was registered through the `codex` CLI.
    #[serde(default)]
    codex: bool,
    /// Whether `disable` has turned this install off. The tracking fields
    /// above (`mcp_keys`, `hooks`, `git_hooks`, `codex`) still describe what
    /// the install owns even while disabled — `disable` does not clear them,
    /// it only takes the config off disk and sets this flag — so `uninstall`
    /// needs no disabled-aware branch of its own: every removal it attempts
    /// is already a no-op for whatever `disable` already removed.
    #[serde(default)]
    disabled: bool,
    /// The exact `mcpServers.mushroomdb` entry `disable` removed from each
    /// file, captured byte-for-byte before the removal. `enable` reads the
    /// store argument back out of these (see [`store_from_arg`]) rather than
    /// replaying the entry itself — the command it writes is re-resolved
    /// fresh, since the published package may have moved since `disable` ran.
    #[serde(default)]
    stashed_mcp: Vec<StashedMcpEntry>,
    /// The command `install` (or the last successful `enable`) was asked to
    /// write, *before* [`resolve_fast_command`] turned an `Npx` request into a
    /// concrete native-binary or launcher path. `enable` reads this back so it
    /// can tell an explicit `--command` pin apart from an `npx` resolution
    /// that happened to land on the same shape of value (an absolute path) —
    /// something the resolved JSON entry alone cannot distinguish. `None` only
    /// for a manifest written before this field existed.
    #[serde(default)]
    requested_cmd: Option<StoredCommand>,
}

impl Manifest {
    /// Drop entries no version of this install may act on as written. See
    /// [`load_manifest`] for why a `.gitignore` in `files` is one of them.
    fn sanitised(mut self) -> Self {
        self.files
            .retain(|f| f.file_name() != Some(OsStr::new(".gitignore")));
        self
    }

    fn is_empty(&self) -> bool {
        self.files.is_empty()
            && self.mcp_keys.is_empty()
            && self.hooks.is_empty()
            && self.git_hooks.is_empty()
            && self.gitignore.is_empty()
            && !self.codex
    }
}

/// One `mcpServers.<server>` entry [`run_disable_with`] took out of a config
/// file, kept whole so [`entry_db`] can still read the store argument back out
/// of it later.
#[derive(Serialize, Deserialize, Debug, Clone)]
struct StashedMcpEntry {
    /// The JSON file the entry was removed from (absolute path).
    file: PathBuf,
    /// The key inside `mcpServers`.
    server: String,
    /// The entry itself, exactly as it read before removal.
    entry: serde_json::Value,
}

/// The three requestable shapes of [`McpCommand`] — the ones a caller can ask
/// for, as opposed to [`McpCommand::NativeBinary`]/[`McpCommand::NodeLauncher`],
/// which only [`resolve_fast_command`] ever produces, by resolving an `Npx`
/// request. Serializable so a manifest can carry it across a `disable`/`enable`
/// round trip.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
enum StoredCommand {
    Npx { version: String },
    Explicit(PathBuf),
    OnPath,
}

impl StoredCommand {
    /// The request behind `cmd`, or `None` for a value only resolution
    /// produces — there is nothing to remember about those beyond the `Npx`
    /// request that led to them, which is captured before resolution runs.
    fn from_mcp(cmd: &McpCommand) -> Option<Self> {
        match cmd {
            McpCommand::Npx { version } => Some(StoredCommand::Npx {
                version: version.clone(),
            }),
            McpCommand::Explicit(p) => Some(StoredCommand::Explicit(p.clone())),
            McpCommand::OnPath => Some(StoredCommand::OnPath),
            McpCommand::NativeBinary { .. } | McpCommand::NodeLauncher { .. } => None,
        }
    }

    fn into_mcp(self) -> McpCommand {
        match self {
            StoredCommand::Npx { version } => McpCommand::Npx { version },
            StoredCommand::Explicit(p) => McpCommand::Explicit(p),
            StoredCommand::OnPath => McpCommand::OnPath,
        }
    }
}

#[derive(Serialize, Deserialize, Debug, Clone)]
struct ManagedMcpKey {
    /// The JSON file the key was added to (absolute path).
    file: PathBuf,
    /// The key inside `mcpServers`.
    server: String,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
struct ManagedHook {
    /// The settings.json file the hook was added to (absolute path).
    file: PathBuf,
    /// The hook event name (e.g. `UserPromptSubmit`).
    event: String,
    /// The exact command string that was added.
    command: String,
}

/// One line this install appended to a text file the user owns.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
struct ManagedLine {
    /// The file the line was added to (absolute path).
    file: PathBuf,
    /// The exact line, without its newline.
    line: String,
    /// Whether the file itself did not exist before this install. Only such a
    /// file may be deleted on uninstall, and only if nothing is left in it.
    #[serde(default)]
    created: bool,
}

/// Claude Code hook event this install wires: fires before each prompt is
/// sent, so the recall digest lands as context ahead of the user's turn.
pub(crate) const HOOK_EVENT: &str = "UserPromptSubmit";
/// Kept short: the hook must never noticeably slow a prompt.
const HOOK_TIMEOUT_SECS: u64 = 5;

/// The second hook event: fires after a tool call, so an edit reaches the
/// graph while the assistant is still working rather than at the next commit.
pub(crate) const TOUCH_EVENT: &str = "PostToolUse";
/// The tools that change a file on disk. Anything else — a read, a search, a
/// shell command — leaves the working tree as the graph already has it.
const TOUCH_MATCHER: &str = "Edit|Write|MultiEdit";
/// Longer than the prompt hook's: re-extracting a file costs more than reading
/// a digest, and nothing is waiting on the answer. The run is `async`, so this
/// bounds a background process rather than the assistant's turn.
const TOUCH_TIMEOUT_SECS: u64 = 30;

/// Single-quote `s` for embedding in a POSIX shell command line, escaping
/// embedded single quotes as `'\''`. Claude Code runs a `type: "command"`
/// hook through a shell, so an unquoted path containing whitespace or shell
/// metacharacters is word-split and the hook silently receives the wrong
/// arguments — quoting keeps the command exact.
fn sh_quote(s: &str) -> String {
    format!("'{}'", s.replace('\'', r"'\''"))
}

/// The exact command string written into the hook entry. Both halves arrive
/// already quoted where quoting is needed.
fn recall_hook_command(shell: &str, store: &StoreRef) -> String {
    format!("{shell} recall {}", store.shell_arg())
}

/// The exact command string written into the post-edit hook entry. `touch` in
/// hook mode prints nothing and exits 0 whatever it is handed.
fn touch_hook_command(shell: &str, store: &StoreRef) -> String {
    format!("{shell} touch {}", store.shell_arg())
}

/// One `hooks.<event>` array entry in Claude Code's settings.json shape.
fn hook_entry(command: &str) -> serde_json::Value {
    serde_json::json!({ "hooks": [ { "type": "command", "command": command, "timeout": HOOK_TIMEOUT_SECS } ] })
}

/// The `PostToolUse` entry: matched to the file-editing tools, and `async` so
/// the assistant's tool call returns without waiting for the re-extraction.
fn touch_hook_entry(command: &str) -> serde_json::Value {
    serde_json::json!({
        "matcher": TOUCH_MATCHER,
        "hooks": [ {
            "type": "command",
            "command": command,
            "timeout": TOUCH_TIMEOUT_SECS,
            "async": true
        } ]
    })
}

/// True if any hook group under `event` contains a command hook equal to `command`.
pub(crate) fn settings_has_hook(root: &serde_json::Value, event: &str, command: &str) -> bool {
    root["hooks"][event]
        .as_array()
        .map(|groups| {
            groups.iter().any(|g| {
                g["hooks"]
                    .as_array()
                    .map(|hs| hs.iter().any(|h| h["command"] == command))
                    .unwrap_or(false)
            })
        })
        .unwrap_or(false)
}

/// Add one hook to `settings_file` (created if absent). Idempotent: no-op if
/// `command` is already present under `event`. Every other key in the file —
/// including other hook events and groups — is preserved. Errors out (no
/// write) rather than overwriting if `hooks` or `hooks.<event>` already exists
/// with an unexpected JSON type, or if the file's top level is not a JSON
/// object.
///
/// `entry` is the group to append, built by the caller: the two events this
/// install wires want different shapes, and only the caller knows which.
fn merge_hook_entry(
    settings_file: &Path,
    event: &str,
    command: &str,
    entry: serde_json::Value,
    manifest: &mut Manifest,
) -> Result<(), CliError> {
    let mut root: serde_json::Value = if settings_file.exists() {
        let raw = fs::read_to_string(settings_file)
            .map_err(|e| CliError(format!("cannot read {}: {e}", settings_file.display())))?;
        serde_json::from_str(&raw)
            .map_err(|e| CliError(format!("invalid JSON in {}: {e}", settings_file.display())))?
    } else {
        serde_json::json!({})
    };

    if !root.is_object() {
        return Err(CliError(format!(
            "{} is not a JSON object at its top level — refusing to add a hook",
            settings_file.display()
        )));
    }

    if settings_has_hook(&root, event, command) {
        return Ok(());
    }

    // Validate the shapes we are about to write into before touching
    // anything: a wrong-shaped `hooks` or `hooks.<event>` value belongs to
    // the user (or another tool) and must never be silently overwritten.
    match root.get("hooks") {
        None => root["hooks"] = serde_json::json!({}),
        Some(v) if v.is_object() => {}
        Some(_) => {
            return Err(CliError(format!(
                "{}: \"hooks\" is not a JSON object — refusing to overwrite it",
                settings_file.display()
            )));
        }
    }
    match root["hooks"].get(event) {
        None => root["hooks"][event] = serde_json::json!([]),
        Some(v) if v.is_array() => {}
        Some(_) => {
            return Err(CliError(format!(
                "{}: \"hooks.{event}\" is not a JSON array — refusing to overwrite it",
                settings_file.display()
            )));
        }
    }
    root["hooks"][event].as_array_mut().unwrap().push(entry);

    let parent = settings_file.parent().unwrap_or(Path::new("."));
    fs::create_dir_all(parent)
        .map_err(|e| CliError(format!("cannot create {}: {e}", parent.display())))?;
    let json = serde_json::to_string_pretty(&root)
        .map_err(|e| CliError(format!("cannot serialize settings: {e}")))?;
    fs::write(settings_file, json)
        .map_err(|e| CliError(format!("cannot write {}: {e}", settings_file.display())))?;

    manifest.hooks.push(ManagedHook {
        file: settings_file.to_path_buf(),
        event: event.into(),
        command: command.into(),
    });
    Ok(())
}

/// Remove exactly the hook groups whose only command is `command`; drop the
/// command from mixed groups; leave everything else semantically unchanged.
/// Returns whether the file was rewritten — that is, whether the hook was
/// there to remove at all.
fn remove_hook_entry(settings_file: &Path, event: &str, command: &str) -> Result<bool, CliError> {
    drop_hooks(settings_file, event, |c| c == command)
}

/// Whether `command` is one of our hook bodies for `store`, whatever binary it
/// names.
///
/// The command prefix is exactly what changes between versions — 0.5.x wrote
/// the absolute path of a copied binary, 0.6.0 an `npx` pin, 0.6.1 a resolved
/// `node <launcher>`, a developer's `--command` a build path — so identity is
/// the tail: the subcommand and the store this install is wiring. Both
/// spellings of that store count, since `--auto` replaced a written path in
/// 0.6.1 and a hook left behind in the other spelling would run alongside the
/// new one. A hook naming a *different* store belongs to a different install
/// and is not ours to touch.
pub(crate) fn is_our_hook_command(command: &str, sub: &str, store: &StoreRef) -> bool {
    store
        .hook_tails(sub)
        .iter()
        .any(|tail| command.ends_with(tail))
}

/// The same identity test for a line that does not *end* with the invocation:
/// a git hook block backgrounds it and redirects its output, so the store
/// argument sits in the middle of the line rather than at the end of it.
pub(crate) fn line_runs_for_store(line: &str, sub: &str, store: &StoreRef) -> bool {
    store.hook_tails(sub).iter().any(|tail| line.contains(tail))
}

/// Take out every hook of ours for `event` that is not the one we are about
/// to write. Returns whether anything was removed.
///
/// Without this an upgrade appends: `merge_hook_entry` matches on the exact
/// command string, so a 0.5.x entry naming `~/.mushroomdb/bin/mushroomdb` is
/// not recognised, survives, and keeps running alongside the new one — two
/// recall digests injected on every prompt.
fn remove_stale_hooks(
    settings_file: &Path,
    event: &str,
    sub: &str,
    store: &StoreRef,
    desired: &str,
) -> Result<bool, CliError> {
    drop_hooks(settings_file, event, |c| {
        c != desired && is_our_hook_command(c, sub, store)
    })
}

/// Drop every hook under `event` whose command satisfies `drop_it`, pruning
/// groups that end up empty. Returns whether the file was rewritten.
///
/// Reads `hooks.<event>` through immutable accessors first, so a settings
/// file where the user removed the `hooks` key (or `<event>`, or shaped
/// either as something other than an object/array) is left byte-for-byte
/// untouched rather than having a stray `null` written back in. Every other
/// key is preserved, though the file is re-serialized (comments are not
/// supported since `serde_json` is strict JSON).
fn drop_hooks(
    settings_file: &Path,
    event: &str,
    drop_it: impl Fn(&str) -> bool,
) -> Result<bool, CliError> {
    if !settings_file.exists() {
        return Ok(false);
    }
    let raw = fs::read_to_string(settings_file)
        .map_err(|e| CliError(format!("cannot read {}: {e}", settings_file.display())))?;
    let mut root: serde_json::Value = serde_json::from_str(&raw).map_err(|e| {
        CliError(format!(
            "corrupt settings json at {}: {e}",
            settings_file.display()
        ))
    })?;

    let Some(mut groups) = root
        .get("hooks")
        .and_then(|h| h.get(event))
        .and_then(|g| g.as_array())
        .cloned()
    else {
        // No matching (or well-shaped) event array — nothing of ours to
        // remove; leave the file exactly as it is, no write at all.
        return Ok(false);
    };

    for g in groups.iter_mut() {
        if let Some(hs) = g["hooks"].as_array_mut() {
            hs.retain(|h| !h["command"].as_str().is_some_and(&drop_it));
        }
    }
    groups.retain(|g| {
        g["hooks"]
            .as_array()
            .map(|hs| !hs.is_empty())
            .unwrap_or(true)
    });

    let before = root.clone();
    if groups.is_empty() {
        root["hooks"].as_object_mut().unwrap().remove(event);
    } else {
        root["hooks"][event] = serde_json::Value::Array(groups);
    }
    if root == before {
        // The event array held none of our commands, so there is nothing to
        // remove. Writing anyway would re-serialize a file we do not own —
        // `serde_json` is built without `preserve_order`, so the user's key
        // order and indentation would be rewritten for no reason.
        return Ok(false);
    }

    let json = serde_json::to_string_pretty(&root)
        .map_err(|e| CliError(format!("cannot serialize settings: {e}")))?;
    fs::write(settings_file, json)
        .map_err(|e| CliError(format!("cannot write {}: {e}", settings_file.display())))?;
    Ok(true)
}

// ---------------------------------------------------------------------------
// Public entry points
// ---------------------------------------------------------------------------

/// Everything the write phase needs, gathered once so the per-step functions
/// stay readable.
struct Ctx<'a> {
    project_root: &'a Path,
    home: &'a Path,
    scope: Scope,
    /// The store the repository wiring names — the `.gitignore` line and the
    /// git hook blocks. Each platform's own config gets its own [`StoreRef`],
    /// passed to the per-platform writers, because only Claude Code can
    /// resolve `--auto`; see [`repo_store_ref`] and [`resolves_at_runtime`].
    repo_store: &'a StoreRef,
    cmd: &'a McpCommand,
    ext: &'a Externals,
    git_hooks: bool,
    prewarm: bool,
}

/// Anchor a user-supplied path to `base` when it is relative, and drop any
/// `./` segments.
///
/// A relative `--command` or `--db` is convenient to type and wrong to store:
/// the assistant spawns the MCP server, and the hooks and git hooks run, from
/// whatever directory those processes happen to be in, not the one the install
/// was typed in. Nothing is canonicalized — resolving symlinks would rewrite
/// a path the user chose deliberately.
fn absolutise(path: &Path, base: &Path) -> PathBuf {
    let joined = if path.is_absolute() {
        path.to_path_buf()
    } else {
        base.join(path)
    };
    let mut out = PathBuf::new();
    for c in joined.components() {
        match c {
            std::path::Component::CurDir => {}
            other => out.push(other),
        }
    }
    out
}

/// Whether `p` is a program name to be looked up on PATH rather than a file to
/// be anchored: one plain component, no separator, no `.` or `..`.
///
/// `--command mushroomdb` means "whatever `mushroomdb` PATH resolves to" and
/// stays that way in both forms we write — an MCP host resolves a bare
/// `command` on PATH, and quoting a bare name in a shell does not defeat the
/// lookup either. Anchoring it would invent `<cwd>/mushroomdb`, a file that
/// need not exist, and the install would report success over a server that
/// cannot spawn.
fn is_bare_program_name(p: &Path) -> bool {
    let mut components = p.components();
    matches!(
        (components.next(), components.next()),
        (Some(std::path::Component::Normal(_)), None)
    )
}

/// Anchor a `--command` unless it is a bare program name.
fn absolutise_command(path: &Path, base: &Path) -> PathBuf {
    if is_bare_program_name(path) {
        path.to_path_buf()
    } else {
        absolutise(path, base)
    }
}

/// Install the /mushroom skill and MCP server entry for the resolved platforms.
///
/// `project_root` is the directory where project-scope config files live
/// (`.mcp.json`, `.claude/`, `.cursor/`). `home` is the user HOME directory.
/// Tests pass temp directories for both; main.rs passes real values.
pub fn run_install(
    project_root: &Path,
    home: &Path,
    opts: &InstallOpts,
) -> Result<String, CliError> {
    run_install_with(
        project_root,
        home,
        opts,
        &detect_mcp_command(opts.command.as_deref()),
        &Externals::from_env(),
    )
}

/// Like [`run_install`], but with the server command and the external
/// environment supplied by the caller instead of detected. Tests use this to
/// stay deterministic and offline; `run_install` is the real-environment
/// wrapper.
pub fn run_install_with(
    project_root: &Path,
    home: &Path,
    opts: &InstallOpts,
    cmd: &McpCommand,
    ext: &Externals,
) -> Result<String, CliError> {
    let (scope, auto_scope) = resolve_scope(project_root, opts.scope);
    // Whatever the caller handed us, what gets written resolves from anywhere:
    // an absolute path, or a name PATH answers for.
    let cmd = match cmd {
        McpCommand::Explicit(p) => McpCommand::Explicit(absolutise_command(p, project_root)),
        other => other.clone(),
    };
    // What was actually asked for, before resolution turns an `Npx` request
    // into a concrete path — `enable` reads this back later to tell an
    // explicit `--command` pin apart from a resolved `npx` path, which the
    // written JSON entry alone cannot distinguish (both are absolute paths).
    let requested_cmd = StoredCommand::from_mcp(&cmd);
    // Resolve the published package to a concrete launcher once, here, so no
    // hook has to. Skipped by `--no-prewarm`, which is the flag for "do not
    // reach the network during this install"; the `npx` form still works, it
    // is just slower on every invocation.
    let (cmd, launcher_note, package_fetched) = if opts.prewarm {
        resolve_fast_command(&cmd, ext)
    } else {
        (cmd, None, false)
    };
    let cmd = &cmd;

    let resolved = resolve_platform(project_root, home, opts.platform.as_ref())?;
    let platforms = expand_platform(&resolved);

    // Each platform names the store in its own terms: only Claude Code can be
    // relied on to resolve `--auto`. The repository wiring gets its own, since
    // git resolves it without any assistant.
    let stores = platform_stores(project_root, home, scope, opts.db.as_deref(), &platforms);
    let repo_store = repo_store_ref(project_root, home, scope, opts.db.as_deref(), &platforms);

    // Check for anything that would make this install fail halfway before
    // writing a single byte.
    for (plat, store) in &stores {
        preflight_check(project_root, home, plat, scope, store, ext)?;
    }

    let ctx = Ctx {
        project_root,
        home,
        scope,
        repo_store: &repo_store,
        cmd,
        ext,
        git_hooks: opts.git_hooks,
        prewarm: opts.prewarm && !package_fetched,
    };

    let manifest_path = manifest_path(project_root, home, scope, &platforms);

    // Load the existing manifest so we can union it with what this run writes.
    // This covers partial-drift re-installs: if SKILL.md was edited but the MCP
    // entry is still intact, only the file is re-written this run; unioning
    // preserves the MCP key in the saved manifest so uninstall cleans it up too.
    let existing = load_manifest(&manifest_path);
    // `install` doubles as `enable` for a disabled install: it rewrites
    // everything `disable` took off disk the same as it would repair any
    // other drift, so the only extra step is clearing the flag once that
    // write lands, and saying so in the summary.
    let was_disabled = existing.disabled;

    let mut manifest = Manifest {
        requested_cmd,
        ..Manifest::default()
    };
    let mut notes: Vec<String> = Vec::new();
    notes.extend(launcher_note);
    if was_disabled {
        notes.push("this install was disabled — install re-enabled it".to_string());
    }

    let outcome = write_everything(&ctx, &stores, &mut manifest, &mut notes);
    if let Err(e) = outcome {
        // Persist whatever was already written (an earlier platform's files,
        // a git hook) so uninstall can still clean up after a partial
        // failure. Best effort: the original error wins.
        if !manifest.is_empty() {
            let merged = union_manifests(load_manifest(&manifest_path), &manifest);
            let _ = write_manifest(&manifest_path, &merged);
        }
        return Err(e);
    }

    let anything_written = !manifest.is_empty();
    if anything_written || was_disabled {
        // Union this-run entries with the existing manifest (dedup by path/key).
        let mut merged = if anything_written {
            union_manifests(existing, &manifest)
        } else {
            existing
        };
        if was_disabled {
            merged.disabled = false;
            merged.stashed_mcp.clear();
        }
        write_manifest(&manifest_path, &merged)?;
    }

    let labels: Vec<&str> = platforms.iter().map(Platform::label).collect();
    let mut out = format!("mushroomdb installed ({})\n", labels.join(", "));
    out.push_str(&format!(
        "  scope  {}{}\n",
        scope.label(),
        if auto_scope { " (auto-detected)" } else { "" }
    ));
    for f in &manifest.files {
        out.push_str(&format!("  wrote  {}\n", f.display()));
    }
    for k in &manifest.mcp_keys {
        out.push_str(&format!(
            "  added  mcpServers.{} in {}\n",
            k.server,
            k.file.display()
        ));
    }
    for h in &manifest.hooks {
        out.push_str(&format!(
            "  added  {} hook in {}\n",
            h.event,
            h.file.display()
        ));
    }
    for g in &manifest.gitignore {
        out.push_str(&format!("  added  {} to {}\n", g.line, g.file.display()));
    }
    for h in &manifest.git_hooks {
        out.push_str(&format!("  added  git hook {}\n", h.display()));
    }
    if manifest.codex {
        out.push_str(&format!("  added  codex mcp server {SERVER_NAME}\n"));
    }
    if anything_written {
        out.push_str(&format!("  manifest  {}\n", manifest_path.display()));
        out.push_str(&format!("  mcp command  {}\n", cmd.shell()));
        out.push_str(&describe_stores(&stores));
    } else {
        out.push_str("  (already installed — no changes)\n");
    }
    for n in &notes {
        out.push_str(&format!("  {n}\n"));
    }
    out.push_str(&format!(
        "next: restart Claude Code in {}, then type /mushroom\n",
        project_root.display()
    ));
    Ok(out)
}

/// The whole write phase, so a failure anywhere in it still leaves the caller
/// holding the partial manifest.
fn write_everything(
    ctx: &Ctx<'_>,
    stores: &[(Platform, StoreRef)],
    manifest: &mut Manifest,
    notes: &mut Vec<String>,
) -> Result<(), CliError> {
    let platforms: Vec<Platform> = stores.iter().map(|(p, _)| p.clone()).collect();
    if let Some(w) = scope_conflict_note(ctx, &platforms) {
        notes.push(w);
    }

    for (plat, store) in stores {
        install_platform(ctx, plat, store, manifest, notes)?;
    }

    // The repository-level wiring is shared by the platforms whose config
    // lives in the repository: the store is ignored by git and the graph is
    // re-synced after commits whichever of them reads it.
    //
    // A Codex-only install is excluded. It writes nothing else project-local
    // (Codex keeps its own config, and the manifest for it lives under the
    // home directory), so an ignore line and three git hooks recorded there
    // would be removed by a `uninstall --platform codex` out from under a
    // Claude Code install that shares the repository and never recorded them.
    let repo_wiring = platforms
        .iter()
        .any(|p| matches!(p, Platform::ClaudeCode | Platform::Cursor));
    if ctx.scope == Scope::Project && repo_wiring {
        ensure_gitignore_line(ctx, manifest)?;
        if ctx.git_hooks {
            install_git_hooks(ctx, manifest)?;
        }
    }

    if let Some(w) = prewarm(ctx) {
        notes.push(w);
    }
    Ok(())
}

/// Find the manifest for an existing install, the way `uninstall`, `disable`
/// and `enable` all need to: an inferred scope that turns up nothing falls
/// back to the other one before giving up, and giving up is an error naming
/// `verb`.
///
/// An inferred scope is a guess, and guessing wrong here means telling
/// someone with a perfectly good user-scope install that they have nothing to
/// act on — 0.5.x had no scope detection, so every install made by it inside a
/// checkout is exactly that case. A scope the user stated is not
/// second-guessed. Returns the scope actually used, since a fallback changes it.
fn locate_manifest(
    project_root: &Path,
    home: &Path,
    scope: Scope,
    auto_scope: bool,
    platforms: &[Platform],
    verb: &str,
) -> Result<(Scope, PathBuf), CliError> {
    let mut scope = scope;
    let mut path = manifest_path(project_root, home, scope, platforms);
    if auto_scope && !path.exists() {
        let other = match scope {
            Scope::Project => Scope::User,
            Scope::User => Scope::Project,
        };
        let alt = manifest_path(project_root, home, other, platforms);
        if alt.exists() {
            scope = other;
            path = alt;
        }
    }
    if !path.exists() {
        return Err(CliError(format!(
            "no install manifest found at {} — nothing to {verb}",
            path.display()
        )));
    }
    Ok((scope, path))
}

/// Uninstall: remove exactly what install wrote. Reads the manifest.
pub fn run_uninstall(
    project_root: &Path,
    home: &Path,
    opts: &InstallOpts,
) -> Result<String, CliError> {
    run_uninstall_with(project_root, home, opts, &Externals::from_env())
}

/// Like [`run_uninstall`], with the external environment supplied by the
/// caller (Codex removal shells out to the `codex` CLI).
pub fn run_uninstall_with(
    project_root: &Path,
    home: &Path,
    opts: &InstallOpts,
    ext: &Externals,
) -> Result<String, CliError> {
    let (scope, auto_scope) = resolve_scope(project_root, opts.scope);
    let resolved = resolve_platform(project_root, home, opts.platform.as_ref())?;
    let platforms = expand_platform(&resolved);

    let (scope, manifest_path) = locate_manifest(
        project_root,
        home,
        scope,
        auto_scope,
        &platforms,
        "uninstall",
    )?;
    let manifest = load_manifest(&manifest_path);

    let mut removed = Vec::new();

    // Remove MCP keys first (before files, in case files include .mcp.json).
    // Each line is printed only for a removal that happened: after an upgrade
    // the manifest also lists the commands the upgrade already replaced, and
    // claiming to have removed those would be a report of work not done.
    for key in &manifest.mcp_keys {
        if remove_mcp_key(&key.file, &key.server)? {
            removed.push(format!(
                "removed  mcpServers.{} from {}",
                key.server,
                key.file.display()
            ));
        }
    }

    // Remove hooks (before files, same reasoning as MCP keys).
    for h in &manifest.hooks {
        if remove_hook_entry(&h.file, &h.event, &h.command)? {
            removed.push(format!(
                "removed  {} hook from {}",
                h.event,
                h.file.display()
            ));
        }
    }

    // Git hooks: the marked region only, never the user's own lines.
    for h in &manifest.git_hooks {
        if remove_git_hook(h)? {
            removed.push(format!("removed  git hook block from {}", h.display()));
        }
    }

    // The ignore line, exactly as it was written. A file that exists only
    // because install created it goes too — but only when our line was all it
    // ever held; anything the user added to it since is theirs to keep.
    for g in &manifest.gitignore {
        if remove_line(&g.file, &g.line)? {
            removed.push(format!("removed  {} from {}", g.line, g.file.display()));
        }
        if g.created && g.file.exists() && file_is_blank(&g.file) {
            fs::remove_file(&g.file)
                .map_err(|e| CliError(format!("cannot remove {}: {e}", g.file.display())))?;
            removed.push(format!("removed  {}", g.file.display()));
        }
    }

    // Codex holds its own config; hand the removal back to its CLI. Not being
    // able to reach `codex` must not strand every other thing the manifest
    // lists.
    if manifest.codex {
        remove_codex(ext, &mut removed, "removed")?;
    }

    // Remove files.
    for f in &manifest.files {
        if f.exists() {
            fs::remove_file(f)
                .map_err(|e| CliError(format!("cannot remove {}: {e}", f.display())))?;
            removed.push(format!("removed  {}", f.display()));
        }
    }

    // Remove the manifest itself.
    if manifest_path.exists() {
        fs::remove_file(&manifest_path)
            .map_err(|e| CliError(format!("cannot remove manifest: {e}")))?;
    }

    let mut out = "mushroomdb uninstalled\n".to_string();
    out.push_str(&format!(
        "  scope  {}{}\n",
        scope.label(),
        if auto_scope { " (auto-detected)" } else { "" }
    ));
    for line in &removed {
        out.push_str(&format!("  {line}\n"));
    }
    Ok(out)
}

// ---------------------------------------------------------------------------
// Enable / disable — turn an install off without removing it
// ---------------------------------------------------------------------------
//
// `disable` takes the dynamic, per-assistant config off disk — the MCP entry,
// the two Claude Code hooks, the three git hook blocks, the Codex
// registration — and leaves everything a person might have customised or that
// the store depends on: the skill/rules file, the store itself, the
// `.gitignore` line. `enable` puts the config back, re-derived from whatever
// `install` would choose right now rather than replayed byte-for-byte, so an
// upgrade of the published package between the two calls is picked up instead
// of pinned to a path that may no longer resolve.
//
// Neither command clears `mcp_keys` / `hooks` / `git_hooks` / `codex` on the
// manifest — those keep describing what the install *owns*, disabled or not —
// which is what lets `uninstall` work unmodified from a disabled install: it
// already treats every removal as a no-op when there is nothing left to
// remove.

fn scope_dir(project_root: &Path, home: &Path, scope: Scope) -> PathBuf {
    match scope {
        Scope::Project => project_root.to_path_buf(),
        Scope::User => home.to_path_buf(),
    }
}

/// The `mcpServers.<server>` entry in `mcp_file`, if the file and the entry
/// both exist.
fn read_mcp_entry(mcp_file: &Path, server: &str) -> Result<Option<serde_json::Value>, CliError> {
    if !mcp_file.exists() {
        return Ok(None);
    }
    let raw = fs::read_to_string(mcp_file)
        .map_err(|e| CliError(format!("cannot read {}: {e}", mcp_file.display())))?;
    let root: serde_json::Value = serde_json::from_str(&raw)
        .map_err(|e| CliError(format!("corrupt mcp json at {}: {e}", mcp_file.display())))?;
    let entry = &root["mcpServers"][server];
    Ok(if entry.is_null() {
        None
    } else {
        Some(entry.clone())
    })
}

/// Reconstruct the [`StoreRef`] an existing config argument names — the same
/// argument [`StoreRef::arg`] would have written. `enable` uses this to read
/// which store a stashed MCP entry (and the hooks wired alongside it) was for.
fn store_from_arg(arg: &str, project_root: &Path, home: &Path) -> StoreRef {
    if arg == AUTO_ARG {
        return StoreRef::auto(crate::resolve_auto_db(None, project_root, home));
    }
    let path = PathBuf::from(arg);
    if path == default_db(Scope::Project, project_root, home) {
        return StoreRef::pinned(path).also_auto();
    }
    StoreRef::pinned(path)
}

/// The config file `disable` would have stashed `platform`'s MCP entry from —
/// the same file [`platform_stores`]/[`install_platform`] write to. `None` for
/// Codex, whose registration is not a file this program reads.
fn platform_mcp_file(
    platform: &Platform,
    project_root: &Path,
    home: &Path,
    scope: Scope,
) -> Option<PathBuf> {
    match platform {
        Platform::ClaudeCode => Some(claude_mcp_file(project_root, home, scope)),
        Platform::Cursor => Some(cursor_mcp_file(project_root, home, scope)),
        Platform::Codex | Platform::All => None,
    }
}

/// The store `enable` should write for `platform`: whichever one that
/// platform's own stashed MCP entry named, matched by which file it was
/// stashed from — Claude Code and Cursor can disagree (only Claude Code
/// resolves `--auto`; see [`resolves_at_runtime`]), so a single stash entry
/// must never be applied to every platform. Falls back to the same default
/// `install` would pick with no `--db` when nothing was stashed for this
/// platform — always true for Codex, whose registration is not a file this
/// program reads, so a Codex install made with an explicit `--db` cannot be
/// recovered exactly and is re-registered at the default store instead.
fn recover_store_for(
    manifest: &Manifest,
    platform: &Platform,
    project_root: &Path,
    home: &Path,
    scope: Scope,
) -> StoreRef {
    platform_mcp_file(platform, project_root, home, scope)
        .and_then(|file| manifest.stashed_mcp.iter().find(|s| s.file == file))
        .and_then(|s| entry_db(&s.entry))
        .map(|arg| store_from_arg(arg, project_root, home))
        .unwrap_or_else(|| {
            store_ref(
                project_root,
                home,
                scope,
                None,
                resolves_at_runtime(platform),
            )
        })
}

/// The store the repository wiring (`.gitignore`, the git hook blocks) should
/// name for `enable`: whichever recovered per-platform store resolves at
/// runtime (Claude Code's, when present — same preference [`repo_store_ref`]
/// gives a fresh install), else the first platform's. Mirrors
/// [`repo_store_ref`], sourced from what was actually recovered rather than
/// recomputed independently, so it can never disagree with what
/// `install_claude_code`/`install_cursor` just wrote.
fn repo_store_for_enable(stores: &[(Platform, StoreRef)]) -> StoreRef {
    stores
        .iter()
        .find(|(p, _)| resolves_at_runtime(p))
        .or_else(|| stores.first())
        .map(|(_, s)| s.clone())
        .expect("enable always resolves at least one platform")
}

/// Turn an install off: remove the MCP entry, the two Claude Code hooks, the
/// git hook blocks and the Codex registration; leave the skill/rules file, the
/// store, and the `.gitignore` line untouched. Idempotent.
pub fn run_disable(
    project_root: &Path,
    home: &Path,
    opts: &ToggleOpts,
) -> Result<String, CliError> {
    run_disable_with(project_root, home, opts, &Externals::from_env())
}

/// Like [`run_disable`], with the external environment supplied by the caller
/// (Codex removal shells out to the `codex` CLI).
pub fn run_disable_with(
    project_root: &Path,
    home: &Path,
    opts: &ToggleOpts,
    ext: &Externals,
) -> Result<String, CliError> {
    let (scope, auto_scope) = resolve_scope(project_root, opts.scope);
    let resolved = resolve_platform(project_root, home, opts.platform.as_ref())?;
    let platforms = expand_platform(&resolved);
    let (scope, manifest_path) =
        locate_manifest(project_root, home, scope, auto_scope, &platforms, "disable")?;
    let mut manifest = load_manifest(&manifest_path);

    let dir = scope_dir(project_root, home, scope);
    if manifest.disabled {
        return Ok(format!(
            "mushroomdb is already disabled in {}\n",
            dir.display()
        ));
    }

    let mut changed = Vec::new();
    let mut stashed = Vec::new();
    for key in &manifest.mcp_keys {
        let Some(entry) = read_mcp_entry(&key.file, &key.server)? else {
            continue;
        };
        stashed.push(StashedMcpEntry {
            file: key.file.clone(),
            server: key.server.clone(),
            entry,
        });
        if remove_mcp_key(&key.file, &key.server)? {
            changed.push(format!(
                "disabled  mcpServers.{} in {}",
                key.server,
                key.file.display()
            ));
        }
    }

    for h in &manifest.hooks {
        if remove_hook_entry(&h.file, &h.event, &h.command)? {
            changed.push(format!(
                "disabled  {} hook in {}",
                h.event,
                h.file.display()
            ));
        }
    }

    for h in &manifest.git_hooks {
        if remove_git_hook(h)? {
            changed.push(format!("disabled  git hook block in {}", h.display()));
        }
    }

    if manifest.codex {
        remove_codex(ext, &mut changed, "disabled")?;
    }

    manifest.disabled = true;
    manifest.stashed_mcp = stashed;
    write_manifest(&manifest_path, &manifest)?;

    let mut out = String::new();
    for line in &changed {
        out.push_str(line);
        out.push('\n');
    }
    out.push_str(&format!(
        "mushroomdb is disabled in {}; enable with: mushroomdb enable\n",
        dir.display()
    ));
    Ok(out)
}

/// Turn a disabled install back on. Re-adds the MCP entry, the two Claude Code
/// hooks and the git hook blocks using the store a stashed entry named and the
/// command `install` would resolve right now — not a replay of what
/// `disable` took out, which may no longer be the fastest path to the
/// published package. Idempotent, and a no-op (not an error) when the install
/// is not disabled.
pub fn run_enable(project_root: &Path, home: &Path, opts: &ToggleOpts) -> Result<String, CliError> {
    run_enable_with(
        project_root,
        home,
        opts,
        &detect_mcp_command(None),
        &Externals::from_env(),
    )
}

/// Like [`run_enable`], with the server command and the external environment
/// supplied by the caller. Tests use this to stay deterministic and offline.
pub fn run_enable_with(
    project_root: &Path,
    home: &Path,
    opts: &ToggleOpts,
    cmd: &McpCommand,
    ext: &Externals,
) -> Result<String, CliError> {
    let (scope, auto_scope) = resolve_scope(project_root, opts.scope);
    let resolved = resolve_platform(project_root, home, opts.platform.as_ref())?;
    let platforms = expand_platform(&resolved);
    let (scope, manifest_path) =
        locate_manifest(project_root, home, scope, auto_scope, &platforms, "enable")?;
    let mut manifest = load_manifest(&manifest_path);

    let dir = scope_dir(project_root, home, scope);
    if !manifest.disabled {
        return Ok(format!(
            "mushroomdb is already enabled in {}\n",
            dir.display()
        ));
    }

    // Restore what was actually requested before, not the caller's
    // auto-detected `cmd` — that would silently drop an explicit `--command`
    // pin the moment it was disabled. `Npx` is re-resolved below exactly like
    // `install` would (the "current shapes" part); `Explicit` is used
    // verbatim unless the binary it names is gone, in which case this falls
    // back to the caller's `cmd` and says so. A manifest with no stash at all
    // (written before this field existed) also falls back, silently — there
    // is nothing to have dropped.
    let mut notes: Vec<String> = Vec::new();
    let base_cmd = match manifest.requested_cmd.clone() {
        Some(StoredCommand::Explicit(p)) if is_bare_program_name(&p) || p.is_file() => {
            McpCommand::Explicit(p)
        }
        Some(StoredCommand::Explicit(p)) => {
            notes.push(format!(
                "warning: the pinned command {} no longer exists — re-detected the command instead",
                p.display()
            ));
            cmd.clone()
        }
        Some(other) => other.into_mcp(),
        None => cmd.clone(),
    };
    let base_cmd = match &base_cmd {
        McpCommand::Explicit(p) => McpCommand::Explicit(absolutise_command(p, project_root)),
        other => other.clone(),
    };
    let (cmd, launcher_note, _) = resolve_fast_command(&base_cmd, ext);
    let cmd = &cmd;
    notes.extend(launcher_note);

    // Each platform's own stashed entry says which store *that* platform was
    // installed with — Claude Code and Cursor can disagree, since only Claude
    // Code resolves `--auto`. A Codex-only install stashes nothing and falls
    // back to the same default a fresh install would pick.
    let stores: Vec<(Platform, StoreRef)> = platforms
        .iter()
        .map(|p| {
            (
                p.clone(),
                recover_store_for(&manifest, p, project_root, home, scope),
            )
        })
        .collect();
    let repo_store = repo_store_for_enable(&stores);
    let had_git_hooks = !manifest.git_hooks.is_empty();

    let ctx = Ctx {
        project_root,
        home,
        scope,
        repo_store: &repo_store,
        cmd,
        ext,
        git_hooks: true,
        prewarm: false,
    };

    let mut fresh = Manifest::default();
    for (plat, store) in &stores {
        match plat {
            Platform::ClaudeCode => install_claude_code(&ctx, store, &mut fresh, &mut notes)?,
            Platform::Cursor => install_cursor(&ctx, store, &mut fresh, &mut notes)?,
            Platform::Codex => install_codex(&ctx, store, &mut fresh)?,
            Platform::All => unreachable!("expand_platform never produces All"),
        }
    }

    let repo_wiring = platforms
        .iter()
        .any(|p| matches!(p, Platform::ClaudeCode | Platform::Cursor));
    if had_git_hooks && scope == Scope::Project && repo_wiring {
        install_git_hooks(&ctx, &mut fresh)?;
    }

    // Fold this run's writes into the manifest: entries for files this run
    // touched replace what was there before (the command may have re-resolved
    // to a different path since `disable`); anything this run did not touch
    // — a platform this call was not asked to enable — survives untouched.
    let touched_mcp: Vec<&PathBuf> = fresh.mcp_keys.iter().map(|k| &k.file).collect();
    manifest
        .mcp_keys
        .retain(|k| !touched_mcp.contains(&&k.file));
    manifest.mcp_keys.extend(fresh.mcp_keys.iter().cloned());

    let touched_hooks: Vec<(&PathBuf, &str)> = fresh
        .hooks
        .iter()
        .map(|h| (&h.file, h.event.as_str()))
        .collect();
    manifest
        .hooks
        .retain(|h| !touched_hooks.contains(&(&h.file, h.event.as_str())));
    manifest.hooks.extend(fresh.hooks.iter().cloned());

    if !fresh.git_hooks.is_empty() {
        manifest.git_hooks = fresh.git_hooks.clone();
    }
    manifest.codex |= fresh.codex;
    for f in &fresh.files {
        if !manifest.files.contains(f) {
            manifest.files.push(f.clone());
        }
    }

    manifest.disabled = false;
    manifest.stashed_mcp.clear();
    // Remember what was actually used this round — the restored pin, the
    // fallback it took because that pin was gone, or the unresolved `Npx`
    // request (never the resolved native-binary/launcher path resolution
    // turned it into) — so the *next* `disable`/`enable` round trip starts
    // from what is actually true now rather than a permanently stale pin.
    manifest.requested_cmd = StoredCommand::from_mcp(&base_cmd);
    write_manifest(&manifest_path, &manifest)?;

    let mut out = String::new();
    for k in &fresh.mcp_keys {
        out.push_str(&format!(
            "enabled  mcpServers.{} in {}\n",
            k.server,
            k.file.display()
        ));
    }
    for h in &fresh.hooks {
        out.push_str(&format!(
            "enabled  {} hook in {}\n",
            h.event,
            h.file.display()
        ));
    }
    for g in &fresh.git_hooks {
        out.push_str(&format!("enabled  git hook {}\n", g.display()));
    }
    if fresh.codex {
        out.push_str(&format!("enabled  codex mcp server {SERVER_NAME}\n"));
    }
    for n in &notes {
        out.push_str(&format!("  {n}\n"));
    }
    out.push_str(&format!("mushroomdb is enabled in {}\n", dir.display()));
    Ok(out)
}

// ---------------------------------------------------------------------------
// Platform resolution
// ---------------------------------------------------------------------------

pub(crate) fn resolve_platform(
    project_root: &Path,
    home: &Path,
    requested: Option<&Platform>,
) -> Result<Platform, CliError> {
    if let Some(p) = requested {
        return Ok(p.clone());
    }

    // Auto-detect. Codex is never inferred: registering with it runs another
    // program, which is not something to do because a directory exists.
    let has_claude = home.join(".claude").exists() || project_root.join(".claude").exists();
    let has_cursor = project_root.join(".cursor").exists() || home.join(".cursor").exists();

    match (has_claude, has_cursor) {
        (true, true) => Ok(Platform::All),
        (true, false) => Ok(Platform::ClaudeCode),
        (false, true) => Ok(Platform::Cursor),
        (false, false) => Err(CliError(
            "cannot auto-detect platform: neither ~/.claude nor .cursor/ found.\n\
             Pass --platform claude-code, --platform cursor, --platform codex, or --platform all."
                .to_string(),
        )),
    }
}

/// `All` is the two platforms whose config this program writes itself. Codex
/// is deliberately not in it: it is wired by running the `codex` CLI, which
/// may not exist, and `--platform all` must not fail on a machine that simply
/// does not have it.
pub(crate) fn expand_platform(p: &Platform) -> Vec<Platform> {
    match p {
        Platform::All => vec![Platform::ClaudeCode, Platform::Cursor],
        other => vec![other.clone()],
    }
}

// ---------------------------------------------------------------------------
// Pre-flight conflict check (no writes)
// ---------------------------------------------------------------------------

fn preflight_check(
    project_root: &Path,
    home: &Path,
    platform: &Platform,
    scope: Scope,
    store: &StoreRef,
    ext: &Externals,
) -> Result<(), CliError> {
    match platform {
        Platform::ClaudeCode => {
            check_mcp_conflict(&claude_mcp_file(project_root, home, scope), store)
        }
        Platform::Cursor => check_mcp_conflict(&cursor_mcp_file(project_root, home, scope), store),
        // Nothing of Codex's is a file we read; what can fail early is the CLI
        // being absent, and that is worth saying before anything is written.
        Platform::Codex => codex_bin(ext).map(|_| ()),
        Platform::All => unreachable!("expand_platform never produces All"),
    }
}

pub(crate) fn claude_mcp_file(project_root: &Path, home: &Path, scope: Scope) -> PathBuf {
    match scope {
        Scope::Project => project_root.join(".mcp.json"),
        // User-scope: verified empirically on a live Claude Code install.
        // ~/.claude.json holds top-level mcpServers; ~/.claude/settings.json
        // holds env/permissions/hooks but no mcpServers key.
        Scope::User => home.join(".claude.json"),
    }
}

pub(crate) fn cursor_mcp_file(project_root: &Path, home: &Path, scope: Scope) -> PathBuf {
    match scope {
        Scope::Project => project_root.join(".cursor").join("mcp.json"),
        Scope::User => home.join(".cursor").join("mcp.json"),
    }
}

/// The store an existing entry serves: the argument straight after `mcp`,
/// which is either a path or `--auto`.
///
/// Its position moved between versions — 0.5.x wrote `["mcp", db]`, the npx
/// form writes `["-y", "mushroomdb@x.y.z", "mcp", db]`, a resolved launcher
/// writes `["<launcher>", "mcp", "--auto"]` — so the subcommand is what
/// locates it, not an index.
pub(crate) fn entry_db(entry: &serde_json::Value) -> Option<&str> {
    let args = entry["args"].as_array()?;
    let at = args.iter().position(|a| a == "mcp")?;
    args.get(at + 1)?.as_str()
}

/// Check if a MCP JSON file has a conflicting `mushroomdb` entry.
///
/// A conflict is: the file exists, has `mcpServers.mushroomdb`, and the store
/// it names differs from the one we'd write. An entry for the SAME store with
/// a different `command` — or the same store spelled the other way, which is
/// every 0.6.0 entry now that a project install writes `--auto` — is ours to
/// repair, so it is not a conflict.
fn check_mcp_conflict(mcp_file: &Path, store: &StoreRef) -> Result<(), CliError> {
    if !mcp_file.exists() {
        return Ok(());
    }
    let raw = fs::read_to_string(mcp_file)
        .map_err(|e| CliError(format!("cannot read {}: {e}", mcp_file.display())))?;
    let v: serde_json::Value = serde_json::from_str(&raw)
        .map_err(|e| CliError(format!("invalid JSON in {}: {e}", mcp_file.display())))?;

    let existing = &v["mcpServers"][SERVER_NAME];
    if existing.is_null() {
        return Ok(()); // Key absent — no conflict.
    }

    let existing_db = entry_db(existing).unwrap_or("");
    if store.names_same_store(existing_db) {
        return Ok(()); // Same store — idempotent or repairable, no conflict.
    }

    Err(CliError(format!(
        "conflict: {} already has mcpServers.mushroomdb pointing to {:?}\n\
         To update it, run `mushroomdb uninstall` first, then re-install.\n\
         Or manually edit {} and remove the existing mushroomdb entry.",
        mcp_file.display(),
        existing_db,
        mcp_file.display()
    )))
}

/// A server registered in the *other* scope still shows up in the assistant,
/// and two of them pointed at two stores is a confusing place to be. Say so;
/// never touch the other scope's file.
fn scope_conflict_note(ctx: &Ctx<'_>, platforms: &[Platform]) -> Option<String> {
    if !platforms.contains(&Platform::ClaudeCode) {
        return None;
    }
    let (other, label, flag) = match ctx.scope {
        Scope::Project => (
            claude_mcp_file(ctx.project_root, ctx.home, Scope::User),
            "user",
            "--user",
        ),
        Scope::User => (
            claude_mcp_file(ctx.project_root, ctx.home, Scope::Project),
            "project",
            "--project",
        ),
    };
    if !has_our_server(&other) {
        return None;
    }
    Some(format!(
        "warning: a {label}-scope mushroomdb server also exists ({}) — \
         both will load; to remove that one run: mushroomdb uninstall {flag}",
        other.display()
    ))
}

pub(crate) fn has_our_server(mcp_file: &Path) -> bool {
    let Ok(raw) = fs::read_to_string(mcp_file) else {
        return false;
    };
    serde_json::from_str::<serde_json::Value>(&raw)
        .map(|v| !v["mcpServers"][SERVER_NAME].is_null())
        .unwrap_or(false)
}

// ---------------------------------------------------------------------------
// Per-platform installation
// ---------------------------------------------------------------------------

fn install_platform(
    ctx: &Ctx<'_>,
    platform: &Platform,
    store: &StoreRef,
    manifest: &mut Manifest,
    notes: &mut Vec<String>,
) -> Result<(), CliError> {
    match platform {
        Platform::ClaudeCode => install_claude_code(ctx, store, manifest, notes),
        Platform::Cursor => install_cursor(ctx, store, manifest, notes),
        Platform::Codex => install_codex(ctx, store, manifest),
        Platform::All => unreachable!("expand_platform never produces All"),
    }
}

/// Substitute both template placeholders. `bin_cmd` is the pre-quoted shell
/// form, so the templates carry `{{BIN}}` unquoted.
fn render_template(template: &str, db_str: &str, bin_cmd: &str) -> String {
    template
        .replace(DB_PATH_PLACEHOLDER, db_str)
        .replace(BIN_PLACEHOLDER, bin_cmd)
}

fn install_claude_code(
    ctx: &Ctx<'_>,
    store: &StoreRef,
    manifest: &mut Manifest,
    notes: &mut Vec<String>,
) -> Result<(), CliError> {
    let shell = ctx.cmd.shell();
    // The skill is prose a reader follows by hand, so it names the directory
    // the store is in rather than the `--auto` the machine-read config uses.
    let db_str = store.path().to_string_lossy();
    let skill_content = render_template(SKILL_TEMPLATE, &db_str, &shell);

    let skill_dir = match ctx.scope {
        Scope::Project => ctx
            .project_root
            .join(".claude")
            .join("skills")
            .join("mushroom"),
        Scope::User => ctx.home.join(".claude").join("skills").join("mushroom"),
    };
    let skill_file = skill_dir.join("SKILL.md");

    // Idempotent: skip if the file already has the same content.
    if !file_matches(&skill_file, &skill_content) {
        fs::create_dir_all(&skill_dir)
            .map_err(|e| CliError(format!("cannot create {}: {e}", skill_dir.display())))?;
        fs::write(&skill_file, &skill_content)
            .map_err(|e| CliError(format!("cannot write {}: {e}", skill_file.display())))?;
        manifest.files.push(skill_file);
    }

    let mcp_file = claude_mcp_file(ctx.project_root, ctx.home, ctx.scope);
    merge_mcp_entry(&mcp_file, ctx, store, manifest, notes)?;

    // Both hooks: settings.json in the same scope as the skill. The prompt
    // hook first, so a manifest lists them in the order they were written.
    let settings_file = match ctx.scope {
        Scope::Project => ctx.project_root.join(".claude").join("settings.json"),
        Scope::User => ctx.home.join(".claude").join("settings.json"),
    };
    // An earlier install of ours for this same store is replaced, not joined:
    // its command names a binary this version no longer writes, and leaving it
    // would run both on every prompt.
    let recall = recall_hook_command(&shell, store);
    if remove_stale_hooks(&settings_file, HOOK_EVENT, "recall", store, &recall)? {
        notes.push(format!("replaced stale {HOOK_EVENT} hook"));
    }
    merge_hook_entry(
        &settings_file,
        HOOK_EVENT,
        &recall,
        hook_entry(&recall),
        manifest,
    )?;
    let touch = touch_hook_command(&shell, store);
    if remove_stale_hooks(&settings_file, TOUCH_EVENT, "touch", store, &touch)? {
        notes.push(format!("replaced stale {TOUCH_EVENT} hook"));
    }
    merge_hook_entry(
        &settings_file,
        TOUCH_EVENT,
        &touch,
        touch_hook_entry(&touch),
        manifest,
    )?;

    Ok(())
}

fn install_cursor(
    ctx: &Ctx<'_>,
    store: &StoreRef,
    manifest: &mut Manifest,
    notes: &mut Vec<String>,
) -> Result<(), CliError> {
    let db_str = store.path().to_string_lossy();
    let rules_content = render_template(CURSOR_RULES_TEMPLATE, &db_str, &ctx.cmd.shell());

    let rules_dir = match ctx.scope {
        Scope::Project => ctx.project_root.join(".cursor").join("rules"),
        Scope::User => ctx.home.join(".cursor").join("rules"),
    };
    let rules_file = rules_dir.join("mushroom.mdc");

    if !file_matches(&rules_file, &rules_content) {
        fs::create_dir_all(&rules_dir)
            .map_err(|e| CliError(format!("cannot create {}: {e}", rules_dir.display())))?;
        fs::write(&rules_file, &rules_content)
            .map_err(|e| CliError(format!("cannot write {}: {e}", rules_file.display())))?;
        manifest.files.push(rules_file);
    }

    let mcp_file = cursor_mcp_file(ctx.project_root, ctx.home, ctx.scope);
    merge_mcp_entry(&mcp_file, ctx, store, manifest, notes)?;

    Ok(())
}

/// The `codex` executable, or an error that says what to do about it.
fn codex_bin(ext: &Externals) -> Result<PathBuf, CliError> {
    ext.which("codex").ok_or_else(|| {
        CliError(
            "codex was not found on PATH — install the Codex CLI, or drop \
             `--platform codex`"
                .to_string(),
        )
    })
}

/// Take the Codex registration back out, through `codex mcp remove`. Appends
/// one line to `out` on success (`"{verb}  codex mcp server mushroomdb"`), or
/// a warning naming the manual fallback when `codex` cannot be reached — not
/// being able to reach it must not strand every other thing the caller is
/// removing. Shared by `uninstall` and `disable`, which take the registration
/// off disk the same way and differ only in whether they still own it after.
fn remove_codex(ext: &Externals, out: &mut Vec<String>, verb: &str) -> Result<(), CliError> {
    match ext.which("codex") {
        Some(bin) => {
            run_and_capture(&bin, &["mcp".into(), "remove".into(), SERVER_NAME.into()])
                .map_err(|e| CliError(format!("codex mcp remove failed: {e}")))?;
            out.push(format!("{verb}  codex mcp server {SERVER_NAME}"));
        }
        None => out.push(
            "warning: codex is not on PATH — run `codex mcp remove mushroomdb` yourself"
                .to_string(),
        ),
    }
    Ok(())
}

/// Register the server with Codex through its own CLI.
///
/// Codex owns its configuration file and its format is its business, so this
/// writes nothing: it runs `codex mcp add mushroomdb -- <command> <args…>` and
/// lets Codex record it. 0.6.0 ships no Codex skill — the MCP tools carry
/// their own descriptions, which is what Codex reads.
fn install_codex(ctx: &Ctx<'_>, store: &StoreRef, manifest: &mut Manifest) -> Result<(), CliError> {
    let bin = codex_bin(ctx.ext)?;
    let mut args = vec![
        "mcp".to_string(),
        "add".to_string(),
        SERVER_NAME.to_string(),
        "--".to_string(),
    ];
    args.extend(ctx.cmd.argv("mcp", &store.arg()));
    run_and_capture(&bin, &args).map_err(|e| CliError(format!("codex mcp add failed: {e}")))?;
    manifest.codex = true;
    Ok(())
}

// ---------------------------------------------------------------------------
// Repository wiring: the ignore line and the sync hooks
// ---------------------------------------------------------------------------

/// The git hooks a sync belongs in: after a commit lands, after a branch
/// changes the working tree, and after a merge brings other people's commits
/// in. All three leave the graph a commit behind if they are skipped.
pub(crate) const GIT_HOOKS: &[&str] = &["post-commit", "post-checkout", "post-merge"];

/// The `.gitignore` line for a store kept inside the repository, or `None`
/// when it is kept outside — a repository has no business ignoring a path it
/// does not contain.
fn gitignore_line(project_root: &Path, db: &Path) -> Option<String> {
    let rel = db.strip_prefix(project_root).ok()?;
    if rel.as_os_str().is_empty() {
        return None;
    }
    Some(format!("{}/", rel.to_string_lossy().replace('\\', "/")))
}

/// Append the store directory to the repository's `.gitignore` unless some
/// spelling of it is already listed. Creates the file if it is absent.
fn ensure_gitignore_line(ctx: &Ctx<'_>, manifest: &mut Manifest) -> Result<(), CliError> {
    let Some(line) = gitignore_line(ctx.project_root, ctx.repo_store.path()) else {
        return Ok(());
    };
    let path = ctx.project_root.join(".gitignore");
    let existed = path.exists();
    let current = match fs::read_to_string(&path) {
        Ok(s) => s,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => String::new(),
        Err(e) => return Err(CliError(format!("cannot read {}: {e}", path.display()))),
    };
    let bare = line.trim_end_matches('/');
    if current
        .lines()
        .map(str::trim)
        .any(|l| l == line || l == bare || l == format!("/{line}") || l == format!("/{bare}"))
    {
        return Ok(());
    }
    let mut next = current;
    if !next.is_empty() && !next.ends_with('\n') {
        next.push('\n');
    }
    next.push_str(&line);
    next.push('\n');
    fs::write(&path, next)
        .map_err(|e| CliError(format!("cannot write {}: {e}", path.display())))?;
    // `created` is what lets uninstall leave a repository that had no
    // `.gitignore` with none again — but only if our line is still all that is
    // in it. Anything the user has added since is theirs, and the file stays.
    manifest.gitignore.push(ManagedLine {
        file: path,
        line,
        created: !existed,
    });
    Ok(())
}

/// Whether the file is gone or holds nothing but whitespace.
fn file_is_blank(path: &Path) -> bool {
    match fs::read_to_string(path) {
        Ok(s) => s.trim().is_empty(),
        Err(_) => true,
    }
}

/// Remove one exact line from a text file. Returns whether anything changed;
/// a file that does not hold the line is not rewritten at all.
fn remove_line(path: &Path, line: &str) -> Result<bool, CliError> {
    let Ok(current) = fs::read_to_string(path) else {
        return Ok(false);
    };
    if !current.lines().any(|l| l == line) {
        return Ok(false);
    }
    let kept: Vec<&str> = current.lines().filter(|l| *l != line).collect();
    let mut next = kept.join("\n");
    if !next.is_empty() {
        next.push('\n');
    }
    fs::write(path, next).map_err(|e| CliError(format!("cannot write {}: {e}", path.display())))?;
    Ok(true)
}

/// The directory git will actually run this checkout's hooks from, following
/// the `gitdir:` link a worktree or submodule leaves in place of a `.git`
/// directory.
///
/// The subtlety is the last step. A linked worktree's gitdir is
/// `<main>/.git/worktrees/<name>`, but git resolves hooks through the
/// **common** dir — `git rev-parse --git-path hooks` inside a worktree answers
/// `<main>/.git/hooks`, not the worktree's own. Writing a hook into the
/// worktree's gitdir puts it somewhere git never looks: the file is there, it
/// is executable, and nothing ever runs it. A linked worktree records the way
/// back in a `commondir` file next to its gitdir (contents `../..`), so this
/// follows it whenever it is there.
///
/// A submodule has no `commondir` and its own gitdir *is* its hooks dir
/// (`.git/modules/<path>/hooks`), which is what the plain resolution already
/// computes — so the absence of the file is the signal to stop.
pub(crate) fn git_hooks_dir(project_root: &Path) -> Option<PathBuf> {
    let dot_git = project_root.join(".git");
    if dot_git.is_dir() {
        return Some(dot_git.join("hooks"));
    }
    let text = fs::read_to_string(&dot_git).ok()?;
    let target = text.strip_prefix("gitdir:")?.trim();
    let target = Path::new(target);
    let resolved = if target.is_absolute() {
        target.to_path_buf()
    } else {
        project_root.join(target)
    };
    // A linked worktree defers its hooks to the common dir; a submodule keeps
    // its own. The `commondir` file is what tells the two apart.
    let base = match fs::read_to_string(resolved.join("commondir")) {
        Ok(rel) => {
            let rel_path = PathBuf::from(rel.trim());
            if rel_path.is_absolute() {
                rel_path
            } else {
                lexically_normalize(&resolved.join(rel_path))
            }
        }
        Err(_) => resolved,
    };
    Some(base.join("hooks"))
}

/// Resolve `.` and `..` in a path textually, without touching the filesystem.
///
/// `commondir` is written relative (`../..`), so joining it leaves a path that
/// works but reads badly in `doctor`'s output and in the manifest. This is
/// purely cosmetic and deliberately does not canonicalize: resolving symlinks
/// would rewrite a path the user gave us into one they do not recognise. A
/// leading `..` with nothing to pop is kept, since dropping it would change
/// where the path points.
fn lexically_normalize(path: &Path) -> PathBuf {
    let mut out = PathBuf::new();
    for part in path.components() {
        match part {
            std::path::Component::CurDir => {}
            std::path::Component::ParentDir => {
                let can_pop = out
                    .components()
                    .next_back()
                    .is_some_and(|c| matches!(c, std::path::Component::Normal(_)));
                if !can_pop || !out.pop() {
                    out.push("..");
                }
            }
            other => out.push(other.as_os_str()),
        }
    }
    out
}

fn install_git_hooks(ctx: &Ctx<'_>, manifest: &mut Manifest) -> Result<(), CliError> {
    // Not a checkout: there is nothing to hook into, and that is not an error.
    let Some(dir) = git_hooks_dir(ctx.project_root) else {
        return Ok(());
    };
    let shell = ctx.cmd.shell();
    for name in GIT_HOOKS {
        let file = dir.join(name);
        if merge_git_hook(&file, &shell, ctx.repo_store)? {
            manifest.git_hooks.push(file);
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Pre-warm
// ---------------------------------------------------------------------------

/// Fetch the pinned package once, so the assistant's first spawn of the MCP
/// server is not a cold `npx` download inside a startup timeout.
///
/// Best effort in every direction: it only applies to the `npx` form, it is
/// skipped when asked to be, and a failure is a line in the summary rather
/// than a failed install — the entry that was written is correct either way.
///
/// Whenever [`resolve_fast_command`] got as far as asking `npx` anything, it
/// already ran this fetch — asking the package a question downloads it first —
/// so the caller clears `Ctx::prewarm` and this does not run a second time.
/// The match below is the remaining guard: a resolved binary or launcher is
/// not the `npx` form and needs no warming either way.
fn prewarm(ctx: &Ctx<'_>) -> Option<String> {
    if !ctx.prewarm {
        return None;
    }
    let McpCommand::Npx { version } = ctx.cmd else {
        return None;
    };
    let args = vec![
        "-y".to_string(),
        format!("{NPM_PACKAGE}@{version}"),
        "--version".to_string(),
    ];
    let Some(npx) = ctx.ext.which("npx") else {
        return Some(
            "warning: pre-warm skipped — npx is not on PATH; the first MCP \
             spawn will download the package"
                .to_string(),
        );
    };
    match run_with_timeout(&npx, &args, ctx.ext.prewarm_timeout) {
        Ok(()) => None,
        Err(e) => Some(format!(
            "warning: pre-warm of {NPM_PACKAGE}@{version} failed ({e}) — \
             the first MCP spawn will download the package"
        )),
    }
}

// ---------------------------------------------------------------------------
// MCP JSON merge helpers
// ---------------------------------------------------------------------------

/// Add `mcpServers.mushroomdb` to a JSON config file. Creates the file if
/// absent. No-op if the entry already matches (idempotent). An entry that is
/// present but different is an upgrade: it is rewritten, and the summary says
/// so, because a stale command is exactly the failure this replaces.
fn merge_mcp_entry(
    mcp_file: &Path,
    ctx: &Ctx<'_>,
    store: &StoreRef,
    manifest: &mut Manifest,
    notes: &mut Vec<String>,
) -> Result<(), CliError> {
    let mut root: serde_json::Value = if mcp_file.exists() {
        let raw = fs::read_to_string(mcp_file)
            .map_err(|e| CliError(format!("cannot read {}: {e}", mcp_file.display())))?;
        serde_json::from_str(&raw)
            .map_err(|e| CliError(format!("invalid JSON in {}: {e}", mcp_file.display())))?
    } else {
        serde_json::json!({})
    };

    // Ensure `mcpServers` object exists.
    if !root["mcpServers"].is_object() {
        root["mcpServers"] = serde_json::json!({});
    }

    let desired = ctx.cmd.json_entry("mcp", &store.arg());
    let existing = &root["mcpServers"][SERVER_NAME];

    if existing == &desired {
        return Ok(()); // Exact match — idempotent.
    }
    let replaced = !existing.is_null();

    // Write the entry.
    root["mcpServers"][SERVER_NAME] = desired;

    let parent = mcp_file.parent().unwrap_or(Path::new("."));
    fs::create_dir_all(parent)
        .map_err(|e| CliError(format!("cannot create {}: {e}", parent.display())))?;

    let json = serde_json::to_string_pretty(&root)
        .map_err(|e| CliError(format!("cannot serialize mcp json: {e}")))?;
    fs::write(mcp_file, json)
        .map_err(|e| CliError(format!("cannot write {}: {e}", mcp_file.display())))?;

    manifest.mcp_keys.push(ManagedMcpKey {
        file: mcp_file.to_path_buf(),
        server: SERVER_NAME.to_string(),
    });
    if replaced {
        notes.push(format!(
            "updated mcp command in {} → {} mcp {}",
            mcp_file.display(),
            ctx.cmd.shell(),
            store.arg()
        ));
    }

    Ok(())
}

/// Remove `mcpServers.<server>` from a JSON config file. Leaves the file in
/// place (with the key removed) unless `mcpServers` becomes empty, in which
/// case we still leave the file (the user may have other keys).
///
/// Returns whether the key was there. A file that does not hold it is not
/// rewritten at all, for the same reason `drop_hooks` does not: re-serializing
/// a file we take nothing out of would reorder and re-indent the user's keys
/// for no reason.
fn remove_mcp_key(mcp_file: &Path, server: &str) -> Result<bool, CliError> {
    if !mcp_file.exists() {
        return Ok(false);
    }
    let raw = fs::read_to_string(mcp_file)
        .map_err(|e| CliError(format!("cannot read {}: {e}", mcp_file.display())))?;
    let mut root: serde_json::Value = serde_json::from_str(&raw)
        .map_err(|e| CliError(format!("corrupt mcp json at {}: {e}", mcp_file.display())))?;

    let removed = root["mcpServers"]
        .as_object_mut()
        .is_some_and(|servers| servers.remove(server).is_some());
    if !removed {
        return Ok(false);
    }

    let json = serde_json::to_string_pretty(&root)
        .map_err(|e| CliError(format!("cannot serialize mcp json: {e}")))?;
    fs::write(mcp_file, json)
        .map_err(|e| CliError(format!("cannot write {}: {e}", mcp_file.display())))?;
    Ok(true)
}

// ---------------------------------------------------------------------------
// Manifest helpers
// ---------------------------------------------------------------------------

pub(crate) fn manifest_path(
    project_root: &Path,
    home: &Path,
    scope: Scope,
    platforms: &[Platform],
) -> PathBuf {
    // Codex writes nothing project-local — its registration lives wherever the
    // Codex CLI keeps it — so a Codex-only install records itself under the
    // home directory whatever the scope, in its own file so it cannot collide
    // with a user-scope Claude Code manifest.
    if platforms == [Platform::Codex] {
        return home.join(".mushroomdb").join("install-manifest-codex.json");
    }
    if scope == Scope::User {
        return home.join(".mushroomdb").join("install-manifest.json");
    }
    // Project scope: prefer the Claude Code location; fall back to Cursor.
    if platforms.contains(&Platform::ClaudeCode) {
        project_root
            .join(".claude")
            .join("skills")
            .join("mushroom")
            .join(".install-manifest.json")
    } else {
        project_root.join(".cursor").join(".install-manifest.json")
    }
}

/// Load an existing manifest from `path`. Returns an empty manifest if absent or unparseable.
///
/// A `.gitignore` is never a file this install may delete outright, whatever a
/// manifest says. An earlier 0.6.0 build recorded a `.gitignore` it created in
/// `files`, which the uninstall file loop removes unconditionally — taking any
/// line the user had added to it since. The `gitignore` entry in the same
/// manifest already carries the one line that is ours, and that is the only
/// route by which the file may be touched, so the stale `files` entry is
/// dropped on the way in.
fn load_manifest(path: &Path) -> Manifest {
    let raw = match fs::read_to_string(path) {
        Ok(s) => s,
        Err(_) => return Manifest::default(),
    };
    serde_json::from_str::<Manifest>(&raw)
        .unwrap_or_default()
        .sanitised()
}

/// Whether an install at this scope has been turned off by `disable`. `false`
/// for a scope with no manifest at all — `doctor` falls through to its normal
/// "no config entry" checks in that case rather than reporting a disabled
/// state that was never installed.
pub(crate) fn is_disabled(
    project_root: &Path,
    home: &Path,
    scope: Scope,
    platforms: &[Platform],
) -> bool {
    load_manifest(&manifest_path(project_root, home, scope, platforms)).disabled
}

/// Union `existing` with `this_run`, deduplicating by path (files, git hooks),
/// by (file, server) pair (mcp_keys), and by full equality (hooks, lines).
/// Entries from `this_run` win on collision so the manifest always reflects
/// the latest state.
fn union_manifests(mut existing: Manifest, this_run: &Manifest) -> Manifest {
    for f in &this_run.files {
        if !existing.files.contains(f) {
            existing.files.push(f.clone());
        }
    }
    for k in &this_run.mcp_keys {
        let already = existing
            .mcp_keys
            .iter()
            .any(|e| e.file == k.file && e.server == k.server);
        if !already {
            existing.mcp_keys.push(k.clone());
        }
    }
    for h in &this_run.hooks {
        if !existing.hooks.contains(h) {
            existing.hooks.push(h.clone());
        }
    }
    for h in &this_run.git_hooks {
        if !existing.git_hooks.contains(h) {
            existing.git_hooks.push(h.clone());
        }
    }
    for l in &this_run.gitignore {
        if !existing.gitignore.contains(l) {
            existing.gitignore.push(l.clone());
        }
    }
    existing.codex |= this_run.codex;
    if let Some(c) = &this_run.requested_cmd {
        existing.requested_cmd = Some(c.clone());
    }
    existing
}

fn write_manifest(path: &Path, manifest: &Manifest) -> Result<(), CliError> {
    let parent = path.parent().unwrap_or(Path::new("."));
    fs::create_dir_all(parent).map_err(|e| {
        CliError(format!(
            "cannot create manifest dir {}: {e}",
            parent.display()
        ))
    })?;
    let json = serde_json::to_string_pretty(manifest)
        .map_err(|e| CliError(format!("cannot serialize manifest: {e}")))?;
    fs::write(path, json)
        .map_err(|e| CliError(format!("cannot write manifest {}: {e}", path.display())))?;
    Ok(())
}

// ---------------------------------------------------------------------------
// Git hook block — `mushroomdb sync` after every commit
// ---------------------------------------------------------------------------
//
// A git hook file belongs to the repository owner, not to us. Everything below
// therefore edits one marked region and nothing else: the region is rewritten
// in place when it changes, and removing it restores the user's lines exactly.
// The pure text transforms are split out from the filesystem wrappers so the
// merge and removal rules can be reasoned about — and tested — without a disk.

/// Opening marker of the region this module owns inside a git hook.
pub const HOOK_BEGIN: &str = "# >>> mushroomdb >>>";
/// Closing marker of that region.
pub const HOOK_END: &str = "# <<< mushroomdb <<<";
/// Written as the first line when we create a hook file ourselves.
const HOOK_SHEBANG: &str = "#!/bin/sh";

/// The block a git hook runs: one backgrounded, silenced `sync`.
///
/// Backgrounded (`( … & )` in a subshell, so no job-control notice reaches the
/// terminal) because a hook must not make `git commit` wait on a graph
/// refresh, and silenced because a hook that prints — or fails — on a store
/// that is momentarily busy would be noise on every commit. `sync` exits 3 when
/// another process holds the write lock, and the next commit picks the work up.
///
/// `shell` is the already-quoted command prefix from [`McpCommand::shell`];
/// the store contributes either `--auto` or its own quoted path, since a path
/// with a space in it would otherwise be word-split into two arguments.
///
/// `--auto` is what makes the block correct in a `git worktree`. Git runs a
/// hook with the working tree it acted on as the working directory, so `sync`
/// walks up from there to that tree's own root and updates that tree's own
/// store — the same block, committed once, doing the right thing in every
/// checkout of the repository.
#[must_use]
pub fn git_hook_block(shell: &str, store: &StoreRef) -> String {
    format!(
        "{HOOK_BEGIN}\n( {shell} sync {} >/dev/null 2>&1 & )\n{HOOK_END}\n",
        store.shell_arg()
    )
}

/// What [`strip_hook_block`] found in a hook file.
enum Stripped {
    /// No opening marker: every line belongs to whoever wrote the file.
    Absent,
    /// A complete region was removed; this is what is left.
    Removed(String),
    /// An opening marker with no closing marker. Where our region ends is
    /// unknowable, so nothing may be removed.
    Unterminated,
}

/// `text` with our marked region removed.
///
/// Blank lines left dangling at the end are dropped, so a merge followed by a
/// removal returns the original bytes rather than the original plus the blank
/// separator the merge inserted.
///
/// An opening marker with no closing marker is [`Stripped::Unterminated`]
/// rather than "ours to the end of the file". Someone hand-edited the region,
/// and the lines below the opening marker are now as likely to be theirs as
/// ours — a `make lint` they added under it would be deleted by the guess.
/// Both public helpers turn this into an error and write nothing, which is the
/// same rule the rest of this module follows for a config file whose shape it
/// does not recognise.
fn strip_hook_block(text: &str) -> Stripped {
    let mut kept: Vec<&str> = Vec::new();
    let mut inside = false;
    let mut found = false;
    for line in text.lines() {
        if !inside && line.trim_end() == HOOK_BEGIN {
            inside = true;
            found = true;
            continue;
        }
        if inside {
            if line.trim_end() == HOOK_END {
                inside = false;
            }
            continue;
        }
        kept.push(line);
    }
    if !found {
        return Stripped::Absent;
    }
    if inside {
        return Stripped::Unterminated;
    }
    while kept.last().is_some_and(|l| l.trim().is_empty()) {
        kept.pop();
    }
    let mut out = kept.join("\n");
    if !out.is_empty() {
        out.push('\n');
    }
    Stripped::Removed(out)
}

/// The error both helpers return for [`Stripped::Unterminated`].
fn unterminated(hook_file: &Path) -> CliError {
    CliError(format!(
        "{}: a mushroomdb block opens with `{HOOK_BEGIN}` but never closes \
         — refusing to edit it; delete the block by hand and re-run",
        hook_file.display()
    ))
}

/// What the hook file should contain once `block` is in it.
///
/// Idempotent by construction: any existing region is stripped first and the
/// fresh one appended, so a re-merge of the same block reproduces the same
/// bytes and a merge of a *different* block rewrites in place instead of
/// stacking a second region.
fn merged_hook_text(existing: Option<&str>, block: &str) -> Result<String, ()> {
    let base = match existing {
        None => String::new(),
        Some(text) => match strip_hook_block(text) {
            Stripped::Absent => text.to_string(),
            Stripped::Removed(rest) => rest,
            Stripped::Unterminated => return Err(()),
        },
    };
    let mut lines: Vec<&str> = base.lines().collect();
    while lines.last().is_some_and(|l| l.trim().is_empty()) {
        lines.pop();
    }
    // A file we are creating needs an interpreter line; one the user wrote
    // already has whichever they chose, and we must not add a second.
    if lines.is_empty() {
        lines.push(HOOK_SHEBANG);
    }
    let mut out = lines.join("\n");
    out.push_str("\n\n");
    out.push_str(block);
    Ok(out)
}

/// Whether `text` is nothing but an interpreter line — the shape a hook file we
/// created is left in once our region is stripped out of it.
fn only_a_shebang(text: &str) -> bool {
    text.lines()
        .filter(|l| !l.trim().is_empty())
        .all(|l| l.starts_with("#!"))
}

/// Put the sync block in `hook_file`, creating the file (mode 755, with a
/// `#!/bin/sh` line) if it is not there. Returns whether anything changed.
///
/// Every line the user has in the file is preserved, and running this twice
/// with the same arguments writes nothing the second time. A file whose
/// mushroomdb block was hand-edited so its closing marker is gone is an error
/// and is left byte-for-byte alone; see [`strip_hook_block`].
pub fn merge_git_hook(hook_file: &Path, shell: &str, store: &StoreRef) -> Result<bool, CliError> {
    let existing = if hook_file.exists() {
        Some(
            fs::read_to_string(hook_file)
                .map_err(|e| CliError(format!("cannot read {}: {e}", hook_file.display())))?,
        )
    } else {
        None
    };
    let next = merged_hook_text(existing.as_deref(), &git_hook_block(shell, store))
        .map_err(|()| unterminated(hook_file))?;
    if existing.as_deref() == Some(next.as_str()) {
        return Ok(false);
    }
    let parent = hook_file.parent().unwrap_or(Path::new("."));
    fs::create_dir_all(parent)
        .map_err(|e| CliError(format!("cannot create {}: {e}", parent.display())))?;
    fs::write(hook_file, &next)
        .map_err(|e| CliError(format!("cannot write {}: {e}", hook_file.display())))?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        // git ignores a hook that is not executable, so this is not cosmetic.
        fs::set_permissions(hook_file, fs::Permissions::from_mode(0o755)).map_err(|e| {
            CliError(format!(
                "cannot make {} executable: {e}",
                hook_file.display()
            ))
        })?;
    }
    Ok(true)
}

/// Take the sync block back out of `hook_file`. Returns whether anything
/// changed.
///
/// The file itself is deleted only when nothing but an interpreter line is
/// left, which is exactly the state a hook *we* created is in — a hook the user
/// wrote has their lines in it and is rewritten rather than removed. An empty
/// stub of theirs would be deleted too, which git cannot tell apart from the
/// stub never having existed.
///
/// An unterminated block is an error and the file is left alone; see
/// [`strip_hook_block`].
pub fn remove_git_hook(hook_file: &Path) -> Result<bool, CliError> {
    if !hook_file.exists() {
        return Ok(false);
    }
    let existing = fs::read_to_string(hook_file)
        .map_err(|e| CliError(format!("cannot read {}: {e}", hook_file.display())))?;
    let next = match strip_hook_block(&existing) {
        // None of it is ours; leave the file untouched.
        Stripped::Absent => return Ok(false),
        Stripped::Removed(rest) => rest,
        Stripped::Unterminated => return Err(unterminated(hook_file)),
    };
    if only_a_shebang(&next) {
        fs::remove_file(hook_file)
            .map_err(|e| CliError(format!("cannot remove {}: {e}", hook_file.display())))?;
        return Ok(true);
    }
    fs::write(hook_file, next)
        .map_err(|e| CliError(format!("cannot write {}: {e}", hook_file.display())))?;
    Ok(true)
}

// ---------------------------------------------------------------------------
// Utilities
// ---------------------------------------------------------------------------

/// True if the file exists and its content equals `expected`.
fn file_matches(path: &Path, expected: &str) -> bool {
    fs::read_to_string(path)
        .map(|s| s == expected)
        .unwrap_or(false)
}