basemind 0.20.0

use std::path::PathBuf;
use std::sync::{Arc, Mutex};

use anyhow::{Context, Result};
use clap::{Parser, Subcommand};
use tracing_subscriber::EnvFilter;

use basemind::config::{self, Config, DocumentsCliOverrides};
use basemind::render::{self, Verbosity};
use basemind::store::{LockHolder, Store, StoreError};
use basemind::watcher::{BatchKind, WatchBatch};

mod lang_cli;

#[derive(Parser, Debug)]
#[command(
    name = "basemind",
    version,
    about = "File-watcher and code-map generator using tree-sitter",
    long_about = None
)]
struct Cli {
    /// Repository root. Defaults to the current directory.
    #[arg(long, global = true)]
    root: Option<PathBuf>,

    /// Suppress all but hard failures and the summary.
    #[arg(short, long, global = true, conflicts_with = "verbose")]
    quiet: bool,

    /// Show every per-file result, including unchanged and skipped files.
    #[arg(short, long, global = true)]
    verbose: bool,

    /// Force-disable ANSI colors. NO_COLOR env var is honored automatically.
    #[arg(long, global = true)]
    no_color: bool,

    /// Emit machine-readable JSON instead of the human-readable rendering. Applies
    /// to the tool subcommands (query / git / memory / web / telemetry / cache) and
    /// is ignored — with a warning — on init / scan / rescan / watch / hook / lang.
    #[arg(long, global = true)]
    json: bool,

    /// Which view to query or serve. "working" (default) is the on-disk tree;
    /// "staged" is the git index; "rev-<sha7>" is a previously scanned rev. Used by
    /// the tool subcommands and `serve`; ignored — with a warning — elsewhere.
    #[arg(long, global = true, default_value_t = basemind::store::VIEW_WORKING.to_string())]
    view: String,

    #[command(subcommand)]
    cmd: Cmd,
}

#[derive(Subcommand, Debug)]
enum Cmd {
    /// Initialize a new .basemind/ folder with a default config.
    Init,
    /// Run a one-shot scan over the repository and write the code map.
    Scan(ScanArgs),
    /// Re-index the working tree (full) or only the given paths (incremental). Use after
    /// edits, or to rebuild a stale/empty index without starting the server.
    Rescan(RescanArgs),
    /// Long-running watcher; keeps the code map current as files change.
    Watch,
    /// Query the code map (outline, search, references, call-graph, …).
    #[command(subcommand)]
    Query(basemind::cli::codemap::QueryCmd),
    /// Git history / blame / diff queries.
    #[command(subcommand)]
    Git(basemind::cli::git::GitCmd),
    /// Shared agent memory + document search (needs `--features memory,documents`).
    #[command(subcommand)]
    Memory(basemind::cli::memory::MemoryCmd),
    /// Governance: mine co-change proposals, list, accept, reject (needs `--features memory`).
    #[command(subcommand)]
    Governance(basemind::cli::governance::GovernanceCmd),
    /// On-demand web ingestion (needs `--features crawl`).
    #[command(subcommand)]
    Web(basemind::cli::web::WebCmd),
    /// Headless agent shells: spawn / send / capture / kill / broadcast / list
    /// (needs `--features shells`).
    #[cfg(all(feature = "shells", any(unix, windows)))]
    #[command(subcommand)]
    Shells(basemind::cli::shells::ShellsCmd),
    /// Aggregate telemetry into a usage summary.
    Telemetry {
        /// Aggregation window: `today` (default), `1h`, `24h`, `all`.
        #[arg(long)]
        window: Option<String>,
        /// Optional exact tool-name filter.
        #[arg(long)]
        tool: Option<String>,
    },
    /// Install a pre-commit hook that runs `basemind scan --staged`.
    Hook {
        #[command(subcommand)]
        action: HookCmd,
    },
    /// Manage downloaded tree-sitter grammars.
    Lang {
        #[command(subcommand)]
        action: LangCmd,
    },
    /// Compress verbose command output read from stdin into a compact summary,
    /// failing open (raw passthrough) on errors and preserving credentials.
    CompressOutput(basemind::textcompress::cli::CompressOutputArgs),
    /// Emit a compact `+N/-M` line-diff from a prior file version (`--old`) to
    /// new content read from stdin — the stateless delta re-read primitive.
    Delta(basemind::textcompress::cli::DeltaArgs),
    /// Extract a compact, credential-safe checkpoint (decisions / errors /
    /// changed files) from session text read from stdin; changed files come
    /// from the git working tree, not the text.
    Checkpoint(basemind::textcompress::cli::CheckpointArgs),
    /// Flag wasteful tool usage (redundant reads, repeated queries, oversized
    /// reads) from a JSON-Lines tool-call log read from stdin. Pure analysis.
    DetectWaste(basemind::textcompress::cli::DetectWasteArgs),
    /// Run an MCP server (stdio) exposing the code map to AI agents.
    Serve(ServeArgs),
    /// Manage the `.basemind/` caches (gc / stats / clear). Offline path.
    #[command(subcommand)]
    Cache(basemind::cli::admin::CacheCmd),
    /// Manage the user-global agent-comms broker daemon (needs `--features comms`).
    #[cfg(all(feature = "comms", any(unix, windows)))]
    Comms {
        #[command(subcommand)]
        action: CommsLifecycleCmd,
    },
}

/// Subcommands for `basemind comms`: daemon lifecycle plus the agent verbs.
///
/// Lifecycle verbs (`Daemon`/`Start`/`Stop`/`Status`) manage the singleton broker process. The
/// agent verbs (`Register`/`Agents`/`RoomCreate`/`Rooms`/`Join`/`Leave`/`Post`/`History`/`Read`/
/// `Inbox`) connect to the daemon DIRECTLY via `CommsClient::ensure_and_connect` (see
/// `cli::comms`) — they never build a full server, so they cannot clash with a running `serve`.
#[cfg(all(feature = "comms", any(unix, windows)))]
#[derive(Subcommand, Debug)]
enum CommsLifecycleCmd {
    /// Run the broker loop: bind the singleton socket, serve front-ends, block until shutdown.
    Daemon,
    /// Ensure the daemon is running (spawn if needed); noop when already alive.
    Start,
    /// Ask the running daemon to drain and stop.
    Stop,
    /// Report the daemon's pid / version / uptime / room + subscriber counts.
    Status,
    /// Agent verbs (register / rooms / post / history / inbox …) against the broker.
    #[command(flatten)]
    Agent(basemind::cli::comms::CommsAgentCmd),
}

#[derive(clap::Args, Debug)]
struct ScanArgs {
    /// Index the git staging area instead of the working tree. Used by the
    /// pre-commit hook so the cache reflects what's about to be committed.
    /// Mutually exclusive with --rev.
    #[arg(long, conflicts_with = "rev")]
    staged: bool,
    /// Index the tree at the given revision (HEAD, branch name, sha, HEAD~3).
    /// Writes under .basemind/views/rev-<sha7>/ — separate from the working-tree view.
    #[arg(long, value_name = "REV")]
    rev: Option<String>,
    /// Skip building the git-history index after the scan (overrides config). The history tools
    /// then fall back to the live walk. Equivalent to `BASEMIND_GH_INDEX=0`.
    #[arg(long)]
    no_git_history: bool,
    /// Wipe and fully rebuild the git-history index instead of incrementally syncing it. Use after
    /// a history rewrite if revalidation didn't already trigger a rebuild.
    #[arg(long)]
    rebuild_git_history: bool,
    /// Document-tier overrides. Every flag in this group corresponds to a
    /// `[documents.…]` TOML key and a `BASEMIND_DOCUMENTS_…` env var.
    #[command(flatten)]
    documents: DocumentsCliOverrides,
}

#[derive(clap::Args, Debug)]
struct RescanArgs {
    /// Repo-relative paths to re-index incrementally. When omitted (or with `--full`),
    /// the entire working tree is re-indexed. Paths are forward-slash with no leading `/`.
    #[arg(value_name = "PATH")]
    paths: Vec<String>,
    /// Force a full working-tree re-index even when paths are supplied. Use to rebuild a
    /// stale or empty index from scratch.
    #[arg(long)]
    full: bool,
    /// Skip building the git-history index after the rescan (overrides config).
    #[arg(long)]
    no_git_history: bool,
    /// Wipe and fully rebuild the git-history index instead of incrementally syncing it.
    #[arg(long)]
    rebuild_git_history: bool,
}

#[derive(clap::Args, Debug)]
struct ServeArgs {
    // The view to serve comes from the global `--view` flag (see `Cli::view`), passed
    // into `cmd_serve` — a single source of truth so the two cannot diverge.
    /// LRU capacity per category for the in-process git cache (commit_files, log, blame).
    #[arg(long, default_value_t = 1024)]
    git_cache_mem: usize,
    /// Disable the on-disk git cache. RAM LRU still applies but nothing persists between
    /// `basemind serve` runs.
    #[arg(long)]
    no_git_cache_disk: bool,
    /// Disable the continuous background re-scan. By default `serve` watches the
    /// working tree and incrementally refreshes the index as files change, so the
    /// code map stays current without `rescan`. Pass `--no-watch` to turn that off
    /// for very large repos (e.g. the ~81k-file TypeScript tree) or CI runs where
    /// the per-edit incremental scan isn't worth the cost; refresh manually via the
    /// `rescan` tool instead.
    #[arg(long)]
    no_watch: bool,
    /// Document-tier overrides. Every flag in this group corresponds to a
    /// `[documents.…]` TOML key and a `BASEMIND_DOCUMENTS_…` env var.
    #[command(flatten)]
    documents: DocumentsCliOverrides,
}

#[derive(Subcommand, Debug)]
enum LangCmd {
    /// Show installed grammars and where they live.
    List,
    /// Force-download all supported grammars (no-op if already cached).
    Install,
    /// Delete the grammar cache. Next run will redownload.
    Clean,
}

#[derive(Subcommand, Debug)]
enum HookCmd {
    /// Write .git/hooks/pre-commit that invokes `basemind scan`.
    Install,
}

/// Default tracing directive when `RUST_LOG` is unset, derived from the parsed
/// verbosity. `--quiet` raises the threshold to `warn` so subsystem INFO logs are
/// suppressed during a scan; `--verbose` lowers it to `debug`; otherwise `info`.
/// An explicit `RUST_LOG` always wins (callers honor it before this fallback).
fn default_log_directive(verbosity: Verbosity) -> &'static str {
    match verbosity {
        Verbosity::Quiet => "warn",
        Verbosity::Default => "info",
        Verbosity::Verbose => "debug",
    }
}

fn main() -> Result<()> {
    #[cfg(all(feature = "shells", any(unix, windows)))]
    if let Some(result) = basemind::shells::intercept_internal_reexec() {
        return result;
    }
    // Parse before initializing tracing so the verbosity flag can feed the default
    // log threshold. `Cli::parse()` exits on `--help`/errors and logs nothing, so
    // running it ahead of subscriber init is safe.
    let cli = Cli::parse();
    let verbosity = Verbosity::from_flags(cli.quiet, cli.verbose);

    // Diagnostics → stderr so they never collide with subcommand output (especially `serve`,
    // whose stdout is the MCP JSON-RPC transport). An explicit `RUST_LOG` wins; otherwise the
    // default threshold tracks `--quiet` / `--verbose` so `-q` actually silences subsystem logs.
    tracing_subscriber::fmt()
        .with_env_filter(
            EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(default_log_directive(verbosity))),
        )
        .with_target(false)
        .with_writer(std::io::stderr)
        .init();

    let no_color = cli.no_color;
    let start = cli
        .root
        .clone()
        .map(|p| p.canonicalize().unwrap_or(p))
        .unwrap_or_else(|| std::env::current_dir().expect("cwd"));
    // Prefer the discovered git workdir so `basemind` invoked from a subdirectory still
    // operates against the repo root. Outside a git repo, fall back to CWD.
    let root = match basemind::git::Repo::discover(&start) {
        Ok(repo) => repo.workdir().to_path_buf(),
        Err(_) => start,
    };

    let json = cli.json;
    let view = cli.view.clone();
    // `--json` / `--view` are global for ergonomics but only the tool subcommands
    // (and `serve`, for `--view`) consume them. Warn — rather than silently ignore —
    // when they're passed to a command that has no use for them, so a typo'd
    // invocation doesn't appear to take effect.
    warn_ignored_global_flags(&cli.cmd, json, &view);
    // Query reads cached extracts; grammars are not strictly needed, but the L2
    // escalation path falls back to live extraction. Bootstrap quietly for the
    // tool subcommands so first-time L2 doesn't stall.
    //
    // `dispatch` collapses the identical `cli::run` tool arms (same root/view/json/overrides,
    // differing only in the `ToolCmd` variant) into one call site — removes the duplication and
    // keeps main.rs under the per-file line cap.
    let dispatch = |tc| basemind::cli::run(&root, &view, DocumentsCliOverrides::default(), json, tc);
    match cli.cmd {
        Cmd::Init => cmd_init(&root),
        Cmd::Scan(args) => cmd_scan(&root, &args, verbosity, no_color),
        Cmd::Rescan(args) => cmd_rescan(&root, &args, verbosity, no_color),
        Cmd::Watch => cmd_watch(&root, verbosity, no_color),
        Cmd::Query(q) => {
            let _ = basemind::lang::ensure_grammars();
            dispatch(basemind::cli::ToolCmd::Query(q))
        }
        Cmd::Git(g) => dispatch(basemind::cli::ToolCmd::Git(g)),
        Cmd::Memory(m) => dispatch(basemind::cli::ToolCmd::Memory(m)),
        Cmd::Governance(g) => dispatch(basemind::cli::ToolCmd::Governance(g)),
        Cmd::Web(w) => dispatch(basemind::cli::ToolCmd::Web(w)),
        #[cfg(all(feature = "shells", any(unix, windows)))]
        Cmd::Shells(s) => dispatch(basemind::cli::ToolCmd::Shells(s)),
        Cmd::Telemetry { window, tool } => dispatch(basemind::cli::ToolCmd::Telemetry { window, tool }),
        Cmd::Hook { action } => match action {
            HookCmd::Install => cmd_hook_install(&root),
        },
        Cmd::Lang { action } => match action {
            LangCmd::List => lang_cli::cmd_lang_list(no_color),
            LangCmd::Install => lang_cli::cmd_lang_install(verbosity, no_color),
            LangCmd::Clean => lang_cli::cmd_lang_clean(),
        },
        Cmd::CompressOutput(args) => basemind::textcompress::cli::run(&args),
        Cmd::Delta(args) => basemind::textcompress::cli::run_delta(&args),
        Cmd::Checkpoint(args) => basemind::textcompress::cli::run_checkpoint(&root, &args),
        Cmd::DetectWaste(args) => basemind::textcompress::cli::run_detect_waste(&args),
        Cmd::Serve(args) => cmd_serve(&root, &view, &args),
        Cmd::Cache(action) => basemind::cli::run_cache(&root, action, json),
        #[cfg(all(feature = "comms", any(unix, windows)))]
        Cmd::Comms { action } => cmd_comms(&root, action, json),
    }
}

/// Dispatch a comms lifecycle subcommand. Each command drives a small current-thread tokio
/// runtime — the broker daemon itself uses a multi-thread runtime so concurrent links don't
/// serialize.
#[cfg(all(feature = "comms", any(unix, windows)))]
fn cmd_comms(root: &std::path::Path, action: CommsLifecycleCmd, json: bool) -> Result<()> {
    match action {
        CommsLifecycleCmd::Daemon => basemind::cli::comms_daemon::run(),
        CommsLifecycleCmd::Start => cmd_comms_start(),
        CommsLifecycleCmd::Stop => cmd_comms_lifecycle_rpc(CommsRpc::Stop, json),
        CommsLifecycleCmd::Status => cmd_comms_lifecycle_rpc(CommsRpc::Status, json),
        CommsLifecycleCmd::Agent(cmd) => basemind::cli::comms::run(root, json, cmd),
    }
}

#[cfg(all(feature = "comms", any(unix, windows)))]
enum CommsRpc {
    Stop,
    Status,
}

/// Ensure a daemon is running, spawning it detached if needed.
#[cfg(all(feature = "comms", any(unix, windows)))]
fn cmd_comms_start() -> Result<()> {
    use basemind::comms::singleton;
    let paths = singleton::resolve_paths().context("resolve comms paths")?;
    let socket_path = paths.socket_path.clone();
    let runtime = tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .context("build tokio runtime")?;
    runtime.block_on(async move {
        singleton::ensure_daemon(&paths)
            .await
            .map_err(|e| anyhow::anyhow!("ensure comms daemon: {e}"))
    })?;
    println!("comms daemon is running ({})", socket_path.display());
    Ok(())
}

/// Connect to the running daemon and issue a Stop or Status RPC.
#[cfg(all(feature = "comms", any(unix, windows)))]
fn cmd_comms_lifecycle_rpc(rpc: CommsRpc, json: bool) -> Result<()> {
    use basemind::comms::client::CommsClient;
    use basemind::comms::ids::AgentId;
    use basemind::comms::singleton;

    let paths = singleton::resolve_paths().context("resolve comms paths")?;
    let runtime = tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .context("build tokio runtime")?;

    runtime.block_on(async move {
        // A control client identifies as a fixed CLI agent; no scope context needed.
        let agent = AgentId::parse("basemind-cli").map_err(|e| anyhow::anyhow!("agent id: {e}"))?;
        let mut client = CommsClient::connect(&paths, agent, None, None)
            .await
            .map_err(|e| anyhow::anyhow!("connect to comms daemon: {e}"))?;
        match rpc {
            CommsRpc::Stop => {
                client.stop().await.map_err(|e| anyhow::anyhow!("stop: {e}"))?;
                if json {
                    println!("{{\"stopped\":true}}");
                } else {
                    println!("comms daemon stopping");
                }
            }
            CommsRpc::Status => {
                let status = client.status().await.map_err(|e| anyhow::anyhow!("status: {e}"))?;
                if json {
                    println!(
                        "{}",
                        serde_json::to_string(&status).map_err(|e| anyhow::anyhow!("serialize status: {e}"))?
                    );
                } else {
                    println!(
                        "pid={} version={} proto={} uptime={}s rooms={} subscribers={}",
                        status.pid,
                        status.version,
                        status.proto_ver,
                        status.uptime_secs,
                        status.rooms,
                        status.subscribers,
                    );
                }
            }
        }
        Ok::<(), anyhow::Error>(())
    })?;
    Ok(())
}

/// Emit a `WARN` when a global flag was supplied to a subcommand that does not
/// consume it. `--json` only affects the tool subcommands (query / git / memory /
/// web / telemetry / cache); `--view` additionally affects `serve`. Everything else
/// ignores them, so warning prevents a no-op flag from looking effective.
fn warn_ignored_global_flags(cmd: &Cmd, json: bool, view: &str) {
    let consumes_json = matches!(
        cmd,
        Cmd::Query(_)
            | Cmd::Git(_)
            | Cmd::Memory(_)
            | Cmd::Governance(_)
            | Cmd::Web(_)
            | Cmd::Telemetry { .. }
            | Cmd::Cache(_)
    );
    // Comms verbs emit JSON when `--json` is passed (each verb checks `if json`), so they
    // consume the flag too. Feature-gated to match the `Cmd::Comms` definition.
    #[cfg(all(feature = "comms", any(unix, windows)))]
    let consumes_json = consumes_json || matches!(cmd, Cmd::Comms { .. });
    // Shell verbs render through `emit`, honoring `--json`. Feature-gated to match `Cmd::Shells`.
    #[cfg(all(feature = "shells", any(unix, windows)))]
    let consumes_json = consumes_json || matches!(cmd, Cmd::Shells(_));
    let consumes_view = consumes_json || matches!(cmd, Cmd::Serve(_));

    if json && !consumes_json {
        tracing::warn!("--json has no effect on this subcommand; ignoring");
    }
    if view != basemind::store::VIEW_WORKING && !consumes_view {
        tracing::warn!(view = %view, "--view has no effect on this subcommand; ignoring");
    }
}

fn bootstrap_grammars(verbosity: Verbosity, no_color: bool) -> Result<()> {
    let summary = basemind::lang::ensure_grammars().map_err(|e| anyhow::anyhow!("grammar bootstrap failed: {e}"))?;
    let mut out = render::stdout(no_color);
    render::render_grammar_bootstrap(&mut out, &summary, verbosity);
    Ok(())
}

/// Fully-commented `basemind.toml` scaffold. Doubles as living documentation: every value shown is
/// the built-in default, so an unedited file is a no-op. Written to the repo ROOT (committed);
/// the `.basemind/` cache it drives is gitignored.
const INIT_SCAFFOLD_TOML: &str = r##"# basemind configuration — https://github.com/Goldziher/basemind
# Lives at the repo root and is meant to be committed. The `.basemind/` cache (index + blobs) is
# derived state, gitignored, and wiped on schema bumps — never put durable config there.
# Every value below is the built-in default; uncomment and edit only what you want to change.
"$schema" = "v1"

[scan]
# Files to index. Default is "everything"; the tree-sitter language registry + a binary/size check
# filter the long tail. Narrow it if you only care about specific languages.
# include = ["**/*"]
# Extra exclude globs, ADDED ON TOP of the always-on floor (node_modules, target, dist, .venv,
# __pycache__, .git, .basemind, bazel-*, .idea, .DS_Store, …). You cannot remove a floor entry.
# exclude = []
# Honor .gitignore / .git/info/exclude while walking. Leave on unless you deliberately want
# ignored files indexed.
# respect_gitignore = true
# Follow symlinks during the walk. Off by default — symlinks often escape the repo (e.g. Bazel's
# bazel-* convenience symlinks). Turn on for repos that symlink real source into place.
# follow_symlinks = false
# Skip files larger than this many bytes (prevents minified-bundle stalls).
# max_file_bytes = 2097152
# Skip paths under any submodule root listed in .gitmodules.
# skip_submodules = true
# Run L2 extraction (calls + docs) inline with L1. Powers find_references / find_callers. Turning
# off roughly halves scan time on large repos but leaves reference search empty until an L2 pass.
# eager_l2 = true
# Absolute paths OUTSIDE the repo to also index (e.g. a Bazel external cache). Symlinks are always
# followed for these regardless of scan.follow_symlinks.
# extra_roots = []

[watch]
# Coalesce filesystem events within this window (milliseconds).
# debounce_ms = 250
# Run L2 extraction on live watch edits (extra CPU per edit).
# live_l2 = false

[cache]
# Max extracted file-maps kept hot in memory.
# file_map_lru = 256

[mcp]
# MCP transport. Only "stdio" is supported today.
# transport = "stdio"

[documents]
# Document RAG tier (PDF / Office / HTML / email / images). Requires a `documents` build.
# enabled = true
# Embed documents for semantic search. ON by default — embeddings pay off on real prose / OCR.
# embed = true
# Embedding model preset. Changing it forces a FULL RE-EMBED of the corpus (time + CPU): every
# document is re-encoded at the new model's dimension.
#   fast        — smallest / fastest, lowest quality
#   balanced    — default; 768-dim, good quality/cost tradeoff
#   quality     — larger model, best English quality, slower
#   multilingual— multilingual model for non-English corpora
# embedding_preset = "balanced"
# Globs for documents that are still extracted + indexed but NOT embedded (keyword-only).
# embed_exclude = []
# Route archives (.zip/.tar/.jar/…) into the recursive archive extractor. Off by default so one
# archive can't explode into thousands of embeds. True binaries are always skipped.
# extract_archives = false

[code_search]
# Semantic code-search tier. Requires a `code-search` build.
# enabled = true
# Embed source code for VECTOR search. OFF by default — local embeddings on code aren't worth the
# cost (code is embedded with a general English model, and NL→symbol is already served by the BM25
# keyword lane over the same text). Chunking + BM25 keyword search work regardless. Turn on only if
# you specifically want vector search over code (downloads an ONNX model, re-embeds on preset change).
# embed = false
# Globs for source files that are still chunked + BM25-indexed but NOT embedded (only used when
# embed = true).
# embed_exclude = []
"##;

fn cmd_init(root: &std::path::Path) -> Result<()> {
    // Fix `.gitignore` regardless of whether a config already exists — the `.basemind/` cache must
    // never be committed, and an existing config doesn't imply the ignore entry was ever added.
    ensure_basemind_gitignored(root)?;

    let path = config::config_path(root);
    if path.exists() {
        anyhow::bail!("config already exists at {}", path.display());
    }
    // Refuse to write a defaults scaffold that would silently shadow a legacy in-cache config: the
    // root path always wins in `resolve_config_path`, so writing here would strand the user's tuned
    // settings with no error. Tell them to migrate the file instead (it is still read as a fallback).
    let legacy = config::legacy_config_path(root);
    if legacy.exists() {
        anyhow::bail!(
            "a legacy config exists at {legacy} and is still read as a fallback; move it to {path} \
             to migrate (the root path then takes precedence) — `init` will not write a defaults \
             scaffold that would silently shadow it",
            legacy = legacy.display(),
            path = path.display(),
        );
    }
    std::fs::write(&path, INIT_SCAFFOLD_TOML).with_context(|| format!("write {}", path.display()))?;
    println!("wrote {}", path.display());
    Ok(())
}

/// Ensure the repo `.gitignore` ignores the `.basemind/` cache directory. Appends the entry when
/// missing, creates the file when absent, and is a no-op when the entry is already present (matched
/// against `.basemind` / `.basemind/` with or without a leading slash). Returns whether the file was
/// modified so callers / tests can assert the behavior.
fn ensure_basemind_gitignored(root: &std::path::Path) -> Result<bool> {
    let path = root.join(".gitignore");
    let existing = match std::fs::read_to_string(&path) {
        Ok(contents) => Some(contents),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
        Err(e) => return Err(anyhow::Error::new(e).context(format!("read {}", path.display()))),
    };
    let already = existing.as_deref().is_some_and(|contents| {
        contents.lines().any(|line| {
            let entry = line.trim().trim_start_matches('/').trim_end_matches('/');
            entry == ".basemind"
        })
    });
    if already {
        return Ok(false);
    }
    let mut contents = existing.unwrap_or_default();
    if !contents.is_empty() && !contents.ends_with('\n') {
        contents.push('\n');
    }
    contents.push_str(".basemind/\n");
    std::fs::write(&path, contents).with_context(|| format!("write {}", path.display()))?;
    println!("updated {}", path.display());
    Ok(true)
}

fn load_or_default(root: &std::path::Path) -> Result<Config> {
    load_or_default_with(root, None)
}

/// Variant of [`load_or_default`] that also applies a CLI override layer through
/// the layered merger. Used by `scan` / `serve` to flow `#[command(flatten)]`
/// flags down to the resolved config.
fn load_or_default_with(root: &std::path::Path, cli: Option<DocumentsCliOverrides>) -> Result<Config> {
    match config::load_with_overrides(root, None, cli) {
        Ok(loaded) => Ok(loaded.config),
        Err(config::ConfigError::NotFound(_)) => {
            // load_with_overrides already treats NotFound as "no toml file" via load(),
            // so this branch is reached only if a downstream call surfaces it again.
            tracing::info!("no basemind.toml; using defaults");
            Ok(config::default_for_root(root))
        }
        Err(e) => Err(anyhow::anyhow!(e)),
    }
}

/// Open the store for a writer command (`scan` / `rescan`), translating lock contention
/// into actionable guidance. Two distinct holders can deny the lock — our own `fs2`
/// advisory lock and Fjall's internal exclusive open lock — and a raw `FjallError: Locked`
/// or bare "Locked" is opaque to a user whose editor plugin is quietly running `serve`.
/// `is_lock_contention` collapses both into one friendly message that leads with what to
/// do; the underlying `StoreError` is preserved as the error source (visible under `-v` /
/// the full anyhow chain) so we never swallow the cause.
fn open_store_for_write(root: &std::path::Path, view: &str, what: &str, holder: LockHolder) -> Result<Store> {
    Store::open_with_holder(root, view, holder).map_err(|err| {
        if err.is_lock_contention() {
            anyhow::Error::new(err).context(basemind::store::LOCK_CONTENTION_HELP.to_string())
        } else {
            anyhow::Error::new(err).context(format!("open store ({what})"))
        }
    })
}

/// Pre-flight the store write lock before a CLI `scan` / `rescan`. When a live basemind process
/// already holds it — overwhelmingly the "editor plugin runs `serve` while the user (or another
/// plugin command) runs `scan`" double-run — return an actionable message so the caller prints it
/// and exits cleanly, instead of blocking on the acquire retries and then failing with a raw lock
/// error. `None` means the lock is free (proceed); the acquire still handles the probe→acquire race
/// reactively via [`basemind::store::LOCK_CONTENTION_HELP`].
fn writer_collision_notice(root: &std::path::Path) -> Option<String> {
    let basemind_dir = root.join(basemind::config::BASEMIND_DIR);
    match basemind::store::probe_writer_lock(&basemind_dir) {
        basemind::store::WriterProbe::Free => None,
        basemind::store::WriterProbe::Held { holder: Some(meta) } => Some(format!(
            "`{}` (pid {}) is already running against this repo and keeping the index fresh — \
             running this directly is unnecessary and would collide with it. Use that server's \
             `rescan` tool to refresh the index, or stop it first.",
            meta.command, meta.pid
        )),
        basemind::store::WriterProbe::Held { holder: None } => Some(basemind::store::LOCK_CONTENTION_HELP.to_string()),
    }
}

/// Build / refresh the repo-global git-history index after a working-tree scan (a separate phase
/// from the core file scan). Best-effort: a non-git dir, a disabled toggle, or any failure leaves
/// the index untouched and the history tools fall back to the live walk — never fails the scan.
fn sync_git_history_after_scan(
    root: &std::path::Path,
    cli_enabled: bool,
    force_rebuild: bool,
    out: &mut impl std::io::Write,
) {
    if !cli_enabled || !basemind::git_history::index_enabled() {
        return;
    }
    let Ok(repo) = basemind::git::Repo::discover(root) else {
        return; // not a git repo — nothing to index
    };
    // Share the git-history index across worktrees: a linked worktree resolves it to the MAIN
    // worktree's `.basemind` (the commit graph is identical for every worktree of a clone), so the
    // rebuild is paid once rather than per worktree. Mirrors `store::resolve_blobs_dir`.
    let basemind_dir = basemind::git_history::shared_history_basemind_dir(root);
    let index = match basemind::git_history::GitHistoryIndex::open(&basemind_dir) {
        Ok(index) => index,
        Err(error) => {
            tracing::warn!(?error, "git-history index unavailable; skipping");
            return;
        }
    };
    if force_rebuild && let Err(error) = index.clear(&basemind_dir) {
        tracing::warn!(?error, "git-history index clear failed");
    }
    match basemind::git_history::builder::sync(&index, &repo, &basemind_dir) {
        Ok(outcome) => {
            let summary = match outcome {
                basemind::git_history::builder::RebuildOutcome::Fresh => "git-history index: up to date".to_string(),
                basemind::git_history::builder::RebuildOutcome::Incremental { added } => {
                    format!("git-history index: +{added} commits")
                }
                basemind::git_history::builder::RebuildOutcome::FullRebuild { reason, commits } => {
                    format!("git-history index: rebuilt {commits} commits ({reason})")
                }
            };
            let _ = writeln!(out, "{summary}");
        }
        Err(error) => tracing::warn!(?error, "git-history index sync failed"),
    }
}

fn cmd_scan(root: &std::path::Path, args: &ScanArgs, verbosity: Verbosity, no_color: bool) -> Result<()> {
    bootstrap_grammars(verbosity, no_color)?;
    let config = load_or_default_with(root, Some(args.documents.clone()))?;

    // Decide view + source up front; we need the source to outlive scan, so the Repo lives
    // here. WorkingTree doesn't need a repo at all.
    let mut out = render::stdout(no_color);
    if args.staged {
        let repo = basemind::git::Repo::discover(root).context("`--staged` requires being inside a git repository")?;
        let mut store = open_store_for_write(root, basemind::store::VIEW_STAGED, "staged", LockHolder::Scan)?;
        render::render_scan_header(&mut out, "staged index", verbosity);
        let report = basemind::scanner::scan(
            root,
            &mut store,
            &config,
            basemind::scanner::ScanSource::Staged(&repo),
            basemind::scanner::EmbedMode::Inline,
        )
        .context("scan staged")?;
        render::render_report(&mut out, &report, verbosity);
        // Per-file read/extract failures are non-fatal: the index WAS updated, so exit 0.
        // A genuine failure-to-update aborts earlier via `?` and surfaces a nonzero exit.
        return Ok(());
    }
    if let Some(rev_spec) = &args.rev {
        let repo = basemind::git::Repo::discover(root).context("`--rev` requires being inside a git repository")?;
        let sha = repo.resolve_rev(rev_spec).context("resolve rev")?;
        let short = &sha[..7.min(sha.len())];
        let view = basemind::store::view_name_for_rev(short);
        let mut store = open_store_for_write(root, &view, "rev", LockHolder::Scan)?;
        render::render_scan_header(&mut out, &format!("rev {short}"), verbosity);
        let report = basemind::scanner::scan(
            root,
            &mut store,
            &config,
            basemind::scanner::ScanSource::Rev {
                repo: &repo,
                sha: sha.clone(),
            },
            basemind::scanner::EmbedMode::Inline,
        )
        .context("scan rev")?;
        render::render_report(&mut out, &report, verbosity);
        // Per-file read/extract failures are non-fatal: the index WAS updated, so exit 0.
        return Ok(());
    }

    if let Some(notice) = writer_collision_notice(root) {
        use std::io::Write as _;
        render::render_scan_header(&mut out, "scan", verbosity);
        let _ = writeln!(out, "{notice}");
        return Ok(());
    }
    let mut store = open_store_for_write(root, basemind::store::VIEW_WORKING, "scan", LockHolder::Scan)?;
    let report = basemind::scanner::scan(
        root,
        &mut store,
        &config,
        basemind::scanner::ScanSource::WorkingTree,
        basemind::scanner::EmbedMode::Inline,
    )
    .context("scan")?;
    render::render_report(&mut out, &report, verbosity);
    sync_git_history_after_scan(root, !args.no_git_history, args.rebuild_git_history, &mut out);
    // Per-file read/extract failures are non-fatal: the index WAS updated, so exit 0.
    // A genuine failure-to-update aborts earlier via `?` and surfaces a nonzero exit.
    Ok(())
}

fn cmd_rescan(root: &std::path::Path, args: &RescanArgs, verbosity: Verbosity, no_color: bool) -> Result<()> {
    bootstrap_grammars(verbosity, no_color)?;
    let config = load_or_default(root)?;
    let mut out = render::stdout(no_color);
    if let Some(notice) = writer_collision_notice(root) {
        use std::io::Write as _;
        let _ = writeln!(out, "{notice}");
        return Ok(());
    }
    let mut store = open_store_for_write(root, basemind::store::VIEW_WORKING, "rescan", LockHolder::Rescan)?;

    // `--full` or no paths → full working-tree re-index. Otherwise re-index only the
    // supplied paths incrementally. `scan_paths` resolves paths against `root`, so make
    // each path absolute first (repo-relative input is the documented contract).
    let report = if args.full || args.paths.is_empty() {
        basemind::scanner::scan(
            root,
            &mut store,
            &config,
            basemind::scanner::ScanSource::WorkingTree,
            basemind::scanner::EmbedMode::Inline,
        )
        .context("rescan (full)")?
    } else {
        let abs: Vec<PathBuf> = args.paths.iter().map(|p| root.join(p)).collect();
        basemind::scanner::scan_paths(root, &mut store, &config, &abs, basemind::scanner::EmbedMode::Inline)
            .context("rescan (paths)")?
    };
    render::render_report(&mut out, &report, verbosity);
    sync_git_history_after_scan(root, !args.no_git_history, args.rebuild_git_history, &mut out);
    // Per-file read/extract failures are non-fatal: the index WAS updated, so exit 0
    // (matches `cmd_scan`; a genuine failure-to-update aborts earlier via `?`). Bug #24.
    Ok(())
}

fn cmd_watch(root: &std::path::Path, verbosity: Verbosity, no_color: bool) -> Result<()> {
    bootstrap_grammars(verbosity, no_color)?;
    let config = Arc::new(load_or_default(root)?);
    let store = Arc::new(Mutex::new(
        Store::open_with_holder(root, basemind::store::VIEW_WORKING, LockHolder::Watch).context("open store")?,
    ));

    let runtime = tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .context("build tokio runtime")?;
    let (shutdown_tx, shutdown_rx) = tokio::sync::oneshot::channel::<()>();

    let store_w = Arc::clone(&store);
    let config_w = Arc::clone(&config);
    let root_buf = root.to_path_buf();
    let watcher_handle = std::thread::spawn(move || {
        let mut stdout = render::stdout(no_color);
        let cb: basemind::watcher::BatchCallback = Box::new(move |batch: WatchBatch<'_>| match batch.kind {
            BatchKind::InitialScan => {
                render::render_report(&mut stdout, batch.report, verbosity);
            }
            BatchKind::Incremental { paths } => {
                render::render_batch_header(&mut stdout, paths, verbosity);
                render::render_lines(&mut stdout, batch.report, verbosity);
            }
        });
        basemind::watcher::watch(&root_buf, store_w, config_w, shutdown_rx, cb)
    });

    runtime.block_on(async {
        let _ = tokio::signal::ctrl_c().await;
        tracing::info!("ctrl-c received; shutting down");
        let _ = shutdown_tx.send(());
    });
    match watcher_handle.join() {
        Ok(Ok(())) => Ok(()),
        Ok(Err(e)) => Err(anyhow::anyhow!(e)),
        Err(_) => Err(anyhow::anyhow!("watcher thread panicked")),
    }
}

fn cmd_serve(root: &std::path::Path, view: &str, args: &ServeArgs) -> Result<()> {
    // A named, non-working view (`rev-<sha>`, `staged`) that was never scanned has no
    // index; serving it would silently fall back to an empty index (bug #18). The writer
    // `Store::open` would auto-create the view dir, so guard here BEFORE opening: refuse a
    // named view with no `index.msgpack`. The working view is exempt — it legitimately
    // starts empty and `serve` auto-scans it on first run.
    if view != basemind::store::VIEW_WORKING {
        let index_path = root
            .join(basemind::config::BASEMIND_DIR)
            .join(basemind::store::VIEWS_DIR)
            .join(view)
            .join(basemind::store::INDEX_FILE);
        if !index_path.exists() {
            anyhow::bail!(
                "view {view:?} has not been scanned; run `basemind scan --view {view}` first \
                 (or omit --view to serve the working view)"
            );
        }
    }
    // Open the store in writable mode so the `rescan` MCP tool can run the
    // scanner in-process. The MCP server is the canonical Fjall owner; the
    // standalone `basemind scan` / `basemind watch` CLIs intentionally fail
    // with a lock error when a server is already running against the repo.
    //
    // Editor plugins spawn one `serve` per session (issue #27); only the first
    // wins the exclusive write lock. Rather than exit and hand the client an
    // opaque MCP `-32000`, a contending serve falls back to a read-only open of
    // the *same* shared index so its tools still register and the session is
    // usable: the in-RAM-map + git tools (`outline` / `search_symbols` /
    // `list_files` / `dependents` / `workspace_grep` / git history) answer
    // normally. Fjall holds an exclusive lock on its index, so a second process
    // can't open it — but the call/reference/impl/graph tools fall back to in-RAM
    // indexes built from the shared blobs (`MapCache::calls` / `::impls`), so they
    // keep working too. The lock-holding serve remains the sole writer (auto-scan /
    // watcher / `rescan`).
    let (store, read_only) = match Store::open_with_holder(root, view, LockHolder::Serve) {
        Ok(store) => (store, false),
        Err(error) if error.is_lock_contention() => {
            // Name the real holder instead of always blaming "another serve" (F4). Two distinct
            // causes surface as lock contention: the fs2 `.basemind/.lock` is a genuine second
            // writer (named via the `.lock.meta` sidecar in the error message); a fjall `Locked`
            // that survived `open_index_with_retry` is a transient reader that briefly held the
            // single-holder index lock — not another serve.
            match &error {
                StoreError::Locked { .. } => tracing::warn!(
                    %error,
                    "store write-lock held by another basemind process; starting read-only (reads from the shared index)"
                ),
                _ => tracing::warn!(
                    %error,
                    "Fjall index lock still contended after retry (a transient reader, not another serve); starting read-only (reads from the shared index)"
                ),
            }
            let store = Store::open_read_only(root, view).context("open store read-only")?;
            (store, true)
        }
        Err(error) => return Err(anyhow::Error::new(error).context("open store")),
    };
    let basemind_dir = root.join(basemind::config::BASEMIND_DIR);
    let root_buf = root.to_path_buf();
    let config = Arc::new(load_or_default_with(root, Some(args.documents.clone()))?);

    let runtime = tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .context("build tokio runtime")?;

    // Open the git repo once if we're inside one; pass it to the server so the git-aware
    // tools (`working_tree_status`, `recent_changes`, …) work without re-discovering.
    let repo = basemind::git::Repo::discover(root).ok().map(Arc::new);
    let git_cache = Arc::new(
        basemind::git_cache::GitCache::open(&basemind_dir, args.git_cache_mem, !args.no_git_cache_disk)
            .context("open git cache")?,
    );

    let options = basemind::mcp::ServerOptions {
        background: true,
        watch: !args.no_watch,
        read_only,
    };
    // Lifecycle logging (stderr → the MCP client's server logs) so a serve that "fails for some
    // reason" leaves a diagnosable trace: who started, against what, and exactly why it exited.
    tracing::info!(
        pid = std::process::id(),
        version = env!("CARGO_PKG_VERSION"),
        view,
        read_only,
        root = %root.display(),
        "basemind serve: MCP server starting"
    );
    let outcome = runtime.block_on(async move {
        use rmcp::ServiceExt;
        let server = basemind::mcp::BasemindServer::new_with_options(store, root_buf, config, repo, git_cache, options);
        let transport = rmcp::transport::stdio();
        let service = server
            .serve(transport)
            .await
            .map_err(|e| anyhow::anyhow!("rmcp serve: {e}"))?;
        // Block until the client disconnects (stdio EOF) or we're killed.
        service
            .waiting()
            .await
            .map_err(|e| anyhow::anyhow!("rmcp waiting: {e}"))?;
        Ok::<(), anyhow::Error>(())
    });
    match &outcome {
        // Clean shutdown is the normal exit: the MCP client closed the stdio transport. Restarting
        // a stdio server is the client's responsibility — a new process can't resume the client's
        // initialize handshake — so we exit cleanly and let the client relaunch on its next call.
        Ok(()) => tracing::info!(pid = std::process::id(), "basemind serve: client disconnected, exiting"),
        Err(error) => {
            tracing::error!(pid = std::process::id(), %error, "basemind serve: exiting on error")
        }
    }
    outcome
}

fn cmd_hook_install(root: &std::path::Path) -> Result<()> {
    let hooks_dir = root.join(".git").join("hooks");
    if !hooks_dir.exists() {
        anyhow::bail!("no .git/hooks directory at {}", hooks_dir.display());
    }
    let hook_path = hooks_dir.join("pre-commit");
    // --staged makes the hook index the about-to-be-committed snapshot rather than
    // whatever messy state the working tree might be in. --quiet keeps successful commits
    // free of noise.
    let body = r#"#!/usr/bin/env sh
# Installed by basemind hook install.
set -e
exec basemind scan --staged --quiet
"#;
    std::fs::write(&hook_path, body)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = std::fs::metadata(&hook_path)?.permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&hook_path, perms)?;
    }
    println!("installed pre-commit hook at {}", hook_path.display());
    Ok(())
}