leindex 1.6.6

// CLI Interface
//
// This module provides the command-line interface for LeIndex.

use crate::cli::leindex::LeIndex;
use crate::cli::mcp::handlers::{all_tool_handlers, ToolHandler};
use crate::cli::mcp::output::{
    DiagnosticsFormatter, FileSummaryFormatter, ImpactFormatter, PhaseFormatter,
    ProjectMapFormatter, SearchFormatter,
};
use crate::cli::mcp::protocol::{JsonRpcRequest, JsonRpcResponse};
use crate::cli::mcp::McpServer;
use crate::cli::registry::{ProjectRegistry, DEFAULT_MAX_PROJECTS};
use crate::phase::{run_phase_analysis, DocsMode, FormatMode, PhaseOptions, PhaseSelection};
use anyhow::Context;
use anyhow::Result as AnyhowResult;
use clap::{error::ErrorKind, Parser, Subcommand};
use serde_json::{Map, Value};
use std::fs;
use std::net::SocketAddr;
use std::path::PathBuf;
use std::process::{Command, Stdio};
use std::sync::Arc;
use tracing::{info, warn};

const POST_INSTALL_SKIP_ENV: &str = "LEINDEX_SKIP_POST_INSTALL_HOOK";
const POST_INSTALL_STAR_MARKER: &str = ".github-starred";
const POST_INSTALL_VERSION_MARKER: &str = ".post-install-version";
const REPO_STAR_ENDPOINT: &str = "user/starred/scooter-lacroix/LeIndex";

/// LeIndex - Code Search and Analysis Engine
#[derive(Parser, Debug)]
#[command(name = "leindex")]
#[command(author = "LeIndex Contributors")]
#[command(version = env!("CARGO_PKG_VERSION"))]
#[command(about = "Index, search, and analyze codebases with semantic understanding", long_about = None)]
#[command(subcommand_required = false)]
#[command(arg_required_else_help = false)]
pub struct Cli {
    /// Path to the project directory
    #[arg(global = true, long = "project", short = 'p')]
    pub project_path: Option<PathBuf>,

    /// Enable verbose logging
    #[arg(global = true, long = "verbose", short = 'v')]
    pub verbose: bool,

    /// Compatibility flag for some AI tools (defaults to MCP stdio mode)
    #[arg(long = "stdio")]
    pub stdio: bool,

    /// Subcommand to execute
    #[command(subcommand)]
    pub command: Option<Commands>,
}

/// Available CLI commands
#[derive(Subcommand, Debug)]
pub enum Commands {
    /// Index a project for code search and analysis
    #[command(visible_alias = "leindex_index")]
    Index {
        /// Path to the project directory
        #[arg(value_name = "PATH")]
        path: PathBuf,

        /// Force re-indexing even if already indexed
        #[arg(long = "force")]
        force: bool,

        /// Show detailed progress
        #[arg(long = "progress")]
        progress: bool,

        /// Self-imposed RSS limit in megabytes.
        ///
        /// When set, indexing monitors RSS and stops gracefully if the limit
        /// is approached (warning at 90%) or exceeded (error). On Linux a hard
        /// RLIMIT_AS ceiling is also set at 110% of the cap to prevent system
        /// OOM kills. No-op on non-Linux platforms if monitoring is unavailable.
        #[arg(long = "max-memory", value_name = "MB")]
        max_memory: Option<u64>,
    },

    /// Search indexed code
    #[command(visible_alias = "leindex_search")]
    Search {
        /// Search query
        #[arg(value_name = "QUERY")]
        query: String,

        /// Maximum number of results to return
        #[arg(long = "top-k", default_value = "10")]
        top_k: usize,
    },

    /// Perform deep analysis with context expansion
    #[command(visible_alias = "leindex_deep_analyze")]
    Analyze {
        /// Analysis query
        #[arg(value_name = "QUERY")]
        query: String,

        /// Maximum tokens for context expansion
        #[arg(long = "tokens", default_value = "2000")]
        token_budget: usize,
    },

    /// Expand context around a symbol or node
    #[command(visible_alias = "leindex_context")]
    Context {
        /// Symbol or node ID to expand
        #[arg(value_name = "NODE_ID")]
        node_id: String,

        /// Maximum tokens for context expansion
        #[arg(long = "tokens", default_value = "2000")]
        token_budget: usize,
    },

    /// Run additive 5-phase analysis workflow
    #[command(visible_aliases = ["leindex_phase_analysis", "phase_analysis"])]
    Phase {
        /// Specific phase to run (1..5)
        #[arg(long = "phase")]
        phase: Option<u8>,

        /// Run all phases (1..5)
        #[arg(long = "all", default_value_t = false)]
        all: bool,

        /// Formatting mode: ultra|balanced|verbose
        #[arg(long = "mode", default_value = "balanced")]
        mode: String,

        /// Path to analyze (defaults to current/global project)
        #[arg(long = "path")]
        path: Option<PathBuf>,

        /// Maximum files to consider
        #[arg(long = "max-files", default_value = "2000")]
        max_files: usize,

        /// Maximum focus files in phase 3
        #[arg(long = "max-focus-files", default_value = "20")]
        max_focus_files: usize,

        /// Top-N entries for ranking phases
        #[arg(long = "top-n", default_value = "10")]
        top_n: usize,

        /// Maximum output characters
        #[arg(long = "max-chars", default_value = "12000")]
        max_output_chars: usize,

        /// Explicitly opt in to Markdown/Text analysis
        #[arg(long = "include-docs", default_value_t = false)]
        include_docs: bool,

        /// Docs mode: off|markdown|text|all
        #[arg(long = "docs-mode", default_value = "off")]
        docs_mode: String,

        /// Disable incremental freshness checks (forces full refresh)
        #[arg(long = "no-incremental-refresh", default_value_t = false)]
        no_incremental_refresh: bool,
    },

    /// Show system diagnostics
    #[command(visible_alias = "leindex_diagnostics")]
    Diagnostics,

    /// List, inspect, or run the MCP tool surface directly from the CLI
    #[command(disable_help_subcommand = true)]
    Tools {
        /// Tool action to perform
        #[command(subcommand)]
        command: ToolCommands,
    },

    /// Start MCP server for AI assistant integration
    Serve {
        /// Host address to bind to
        #[arg(long = "host", default_value = "127.0.0.1")]
        host: String,

        /// Port to listen on (default: 47268, override with LEINDEX_PORT env var)
        #[arg(long = "port", default_value = "47268")]
        port: u16,
    },

    /// Run MCP server in stdio mode (for AI tool subprocess integration)
    Mcp {
        /// Compatibility flag for some AI tools
        #[arg(long = "stdio")]
        stdio: bool,

        /// Path to a Unix domain socket to listen on (instead of stdio).
        ///
        /// Each connection gets its own MCP session. The socket file is
        /// removed when the server shuts down. Only available on Unix.
        #[arg(long = "socket")]
        socket: Option<PathBuf>,
    },

    /// Start the frontend dashboard
    Dashboard {
        /// Port to run the dashboard on (default: 5173)
        #[arg(long = "port", default_value = "5173")]
        port: u16,

        /// Build for production instead of dev server
        #[arg(long = "prod")]
        prod: bool,
    },

    /// Remove stale LeIndex temp artifacts
    Cleanup {
        /// Maximum age in days for artifacts to keep (default: 7)
        #[arg(long = "max-age-days", default_value = "7")]
        max_age_days: u64,

        /// Show what would be removed without actually removing
        #[arg(long = "dry-run")]
        dry_run: bool,
    },
}

/// Subcommands for inspecting and executing MCP tools from the CLI.
#[derive(Subcommand, Debug)]
pub enum ToolCommands {
    /// List every MCP/CLI tool name and description
    List,

    /// Show comprehensive help for a tool
    Help {
        /// Tool name (for example: leindex_project_map, project_map, or project-map)
        name: String,
    },

    /// Print the JSON argument schema for a tool
    Schema {
        /// Tool name (for example: leindex_project_map, project_map, or project-map)
        name: String,
    },

    /// Execute a tool by name with JSON arguments
    Run {
        /// Tool name (for example: leindex_project_map, project_map, or project-map)
        name: String,

        /// JSON object of tool arguments
        #[arg(long = "args", default_value = "{}")]
        args_json: String,

        /// Additional key=value arguments merged on top of --args
        #[arg(long = "set", value_name = "KEY=VALUE")]
        set: Vec<String>,
    },
}

impl Cli {
    /// Run the CLI
    pub async fn run(self) -> AnyhowResult<()> {
        // Initialize logging
        init_logging_impl(self.verbose);

        // Get global project path
        let global_project = self.project_path;

        // Execute the appropriate command
        // Default to Mcp if no command is provided or if --stdio is set
        let command = if self.stdio {
            Commands::Mcp {
                stdio: true,
                socket: None,
            }
        } else {
            self.command.unwrap_or(Commands::Mcp {
                stdio: false,
                socket: None,
            })
        };

        maybe_complete_post_install_actions(&command);

        match command {
            Commands::Index {
                path,
                force,
                progress,
                max_memory,
            } => cmd_index_impl(path, force, progress, max_memory).await,
            Commands::Search { query, top_k } => {
                cmd_search_impl(query, top_k, global_project).await
            }
            Commands::Analyze {
                query,
                token_budget,
            } => cmd_analyze_impl(query, token_budget, global_project).await,
            Commands::Context {
                node_id,
                token_budget,
            } => cmd_context_impl(node_id, token_budget, global_project).await,
            Commands::Phase {
                phase,
                all,
                mode,
                path,
                max_files,
                max_focus_files,
                top_n,
                max_output_chars,
                include_docs,
                docs_mode,
                no_incremental_refresh,
            } => {
                cmd_phase_impl(
                    phase,
                    all,
                    mode,
                    path,
                    global_project,
                    max_files,
                    max_focus_files,
                    top_n,
                    max_output_chars,
                    include_docs,
                    docs_mode,
                    no_incremental_refresh,
                )
                .await
            }
            Commands::Diagnostics => cmd_diagnostics_impl(global_project).await,
            Commands::Tools { command } => cmd_tools_impl(command, global_project).await,
            Commands::Serve { host, port } => cmd_serve_impl(host, port).await,
            Commands::Mcp { socket, .. } => {
                if let Some(ref socket_path) = socket {
                    cmd_mcp_socket_impl(socket_path, global_project).await
                } else {
                    cmd_mcp_stdio_impl(global_project).await
                }
            }
            Commands::Dashboard { port, prod } => cmd_dashboard_impl(port, prod).await,
            Commands::Cleanup {
                max_age_days,
                dry_run,
            } => cmd_cleanup_impl(max_age_days, dry_run).await,
        }
    }
}

/// Initialize logging implementation
fn init_logging_impl(verbose: bool) {
    let level = if verbose {
        tracing::Level::DEBUG
    } else {
        tracing::Level::INFO
    };

    let subscriber = tracing_subscriber::fmt()
        .with_max_level(level)
        .with_writer(std::io::stderr)
        .finish();

    let _ = tracing::subscriber::set_global_default(subscriber);
}

fn maybe_complete_post_install_actions(command: &Commands) {
    if std::env::var_os(POST_INSTALL_SKIP_ENV).is_some()
        || matches!(command, Commands::Mcp { .. })
        || !running_from_cargo_bin()
    {
        return;
    }

    let leindex_home = match resolve_leindex_home() {
        Ok(path) => path,
        Err(error) => {
            warn!("Post-install actions skipped: {}", error);
            return;
        }
    };

    if post_install_is_current(&leindex_home) {
        return;
    }

    if let Err(error) = complete_post_install_actions(command, &leindex_home) {
        warn!("Post-install actions skipped: {}", error);
    }
}

fn complete_post_install_actions(
    command: &Commands,
    leindex_home: &std::path::Path,
) -> AnyhowResult<()> {
    fs::create_dir_all(leindex_home).context("failed to create LEINDEX_HOME")?;
    cleanup_legacy_user_installations(leindex_home);

    let marker_path = leindex_home.join(POST_INSTALL_STAR_MARKER);
    if !marker_path.exists() {
        emit_post_install_message(command, "Thank you for installing LeIndex.");

        if try_star_repo() {
            emit_post_install_message(command, "Starred scooter-lacroix/LeIndex on GitHub.");
            fs::write(&marker_path, b"starred\n").context("failed to persist star marker")?;
        } else {
            emit_post_install_message(
                command,
                "Could not star the GitHub repo automatically. If GitHub CLI is signed in, run: gh api -X PUT user/starred/scooter-lacroix/LeIndex",
            );
            fs::write(&marker_path, b"prompted\n").context("failed to persist star marker")?;
        }
    }

    warn_if_path_is_shadowed(command);
    write_post_install_version_marker(leindex_home)?;

    Ok(())
}

fn resolve_leindex_home() -> AnyhowResult<PathBuf> {
    if let Ok(path) = std::env::var("LEINDEX_HOME") {
        return Ok(PathBuf::from(path));
    }

    let home = dirs::home_dir().context("HOME is not available")?;
    Ok(home.join(".leindex"))
}

fn post_install_is_current(leindex_home: &std::path::Path) -> bool {
    let marker_path = leindex_home.join(POST_INSTALL_VERSION_MARKER);
    match fs::read_to_string(marker_path) {
        Ok(version) => version.trim() == env!("CARGO_PKG_VERSION"),
        Err(_) => false,
    }
}

fn write_post_install_version_marker(leindex_home: &std::path::Path) -> AnyhowResult<()> {
    let marker_path = leindex_home.join(POST_INSTALL_VERSION_MARKER);
    fs::write(marker_path, format!("{}\n", env!("CARGO_PKG_VERSION")))
        .context("failed to persist post-install marker")
}

fn cleanup_legacy_user_installations(leindex_home: &std::path::Path) {
    let Some(home) = dirs::home_dir() else {
        return;
    };

    let binary_name = platform_binary_name("leindex");
    let legacy_local_bin = home.join(".local").join("bin").join(&binary_name);
    if legacy_local_bin.exists() {
        match fs::remove_file(&legacy_local_bin) {
            Ok(_) => info!("Removed legacy install at {}", legacy_local_bin.display()),
            Err(error) => warn!(
                "Failed to remove legacy install at {}: {}",
                legacy_local_bin.display(),
                error
            ),
        }
    }

    let legacy_home_bin = leindex_home.join("bin").join(binary_name);
    if legacy_home_bin.exists() {
        match fs::remove_file(&legacy_home_bin) {
            Ok(_) => info!("Removed legacy install at {}", legacy_home_bin.display()),
            Err(error) => warn!(
                "Failed to remove legacy install at {}: {}",
                legacy_home_bin.display(),
                error
            ),
        }
    }
}

fn running_from_cargo_bin() -> bool {
    let Ok(current_exe) = std::env::current_exe() else {
        return false;
    };

    let cargo_home = cargo_home_dir();

    let Some(cargo_home) = cargo_home else {
        return false;
    };

    current_exe == cargo_home.join("bin").join(platform_binary_name("leindex"))
}

fn resolve_path_binary(binary_name: &str) -> Option<PathBuf> {
    let path_var = std::env::var_os("PATH")?;
    for entry in std::env::split_paths(&path_var) {
        let candidate = entry.join(binary_name);
        if candidate.is_file() {
            return Some(candidate);
        }

        if cfg!(windows) {
            let exe_candidate = entry.join(platform_binary_name(binary_name));
            if exe_candidate.is_file() {
                return Some(exe_candidate);
            }
        }
    }
    None
}

fn warn_if_path_is_shadowed(command: &Commands) {
    let Ok(current_exe) = std::env::current_exe() else {
        return;
    };

    let Some(resolved) = resolve_path_binary("leindex") else {
        return;
    };

    if resolved == current_exe {
        return;
    }

    emit_post_install_message(
        command,
        &format!(
            "`leindex` currently resolves to {} instead of {}. Remove the older binary or move {} earlier in PATH.",
            resolved.display(),
            current_exe.display(),
            cargo_bin_dir()
                .unwrap_or_else(|| current_exe.parent().unwrap_or_else(|| std::path::Path::new(".")).to_path_buf())
                .display()
        ),
    );
}

fn cargo_home_dir() -> Option<PathBuf> {
    std::env::var("CARGO_HOME")
        .map(PathBuf::from)
        .ok()
        .or_else(|| dirs::home_dir().map(|home| home.join(".cargo")))
}

fn cargo_bin_dir() -> Option<PathBuf> {
    cargo_home_dir().map(|cargo_home| cargo_home.join("bin"))
}

fn platform_binary_name(binary_name: &str) -> String {
    if cfg!(windows) {
        format!("{}.exe", binary_name)
    } else {
        binary_name.to_string()
    }
}

fn try_star_repo() -> bool {
    let auth_ok = Command::new("gh")
        .args(["auth", "status"])
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status()
        .map(|status| status.success())
        .unwrap_or(false);

    if !auth_ok {
        return false;
    }

    Command::new("gh")
        .args([
            "api",
            "-X",
            "PUT",
            "-H",
            "Accept: application/vnd.github+json",
            REPO_STAR_ENDPOINT,
        ])
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status()
        .map(|status| status.success())
        .unwrap_or(false)
}

fn emit_post_install_message(command: &Commands, message: &str) {
    if matches!(command, Commands::Serve { .. } | Commands::Dashboard { .. }) {
        info!("{}", message);
    } else {
        eprintln!("{}", message);
    }
}

/// Get project path from explicit path or current directory
fn get_project_path(explicit: Option<PathBuf>) -> PathBuf {
    explicit.unwrap_or_else(|| std::env::current_dir().unwrap())
}

/// Index command implementation
async fn cmd_index_impl(
    path: PathBuf,
    force: bool,
    _progress: bool,
    max_memory: Option<u64>,
) -> AnyhowResult<()> {
    let canonical_path = path
        .canonicalize()
        .context("Failed to canonicalize project path")?;

    info!("Indexing project at: {}", canonical_path.display());

    // Check if already indexed (unless force)
    if !force {
        // Create temporary LeIndex to check if already indexed
        if let Ok(check_leindex) = LeIndex::new(&canonical_path) {
            if check_leindex.is_indexed() {
                println!("Project already indexed. Use --force to re-index.");
                println!("  Use --force to re-index if you have made changes.");
                return Ok(());
            }
        }
    }

    // Apply hard RSS limit via rlimit if requested (Linux-only)
    if let Some(mb) = max_memory {
        crate::cli::memory_cap::apply_hard_limit(mb)?;
    }

    // Create LeIndex and index the project
    let mut leindex = LeIndex::new(&canonical_path).context("Failed to create LeIndex instance")?;

    let max_memory_bytes = max_memory.map(|mb| mb * 1024 * 1024);
    let stats = tokio::task::spawn_blocking(move || {
        leindex.index_project_with_memory_cap(force, max_memory_bytes)
    })
    .await
    .context("Indexing task failed")?
    .context("Indexing failed")?;

    // Print results
    println!("\n✓ Indexing complete!");
    println!("  Files parsed: {}", stats.files_parsed);
    println!("  Successful: {}", stats.successful_parses);
    println!("  Failed: {}", stats.failed_parses);
    println!("  Signatures: {}", stats.total_signatures);
    println!("  PDG nodes: {}", stats.pdg_nodes);
    println!("  PDG edges: {}", stats.pdg_edges);
    println!("  Indexed nodes: {}", stats.indexed_nodes);
    println!("  Time: {}ms", stats.indexing_time_ms);

    Ok(())
}

/// Search command implementation
async fn cmd_search_impl(
    query: String,
    top_k: usize,
    project: Option<PathBuf>,
) -> AnyhowResult<()> {
    let project_path = get_project_path(project);
    let canonical_path = project_path
        .canonicalize()
        .context("Failed to canonicalize project path")?;

    info!("Searching for: {}", query);

    // Create LeIndex and try to load from storage
    let mut leindex = LeIndex::new(&canonical_path).context("Failed to create LeIndex instance")?;

    // Load from storage if available
    if let Err(e) = leindex.load_from_storage() {
        warn!("Failed to load from storage: {}", e);
        warn!("Project may not be indexed. Run 'leindex index' first.");
    }

    // Perform search
    let results = leindex
        .search(&query, top_k, None)
        .context("Search failed")?;

    if results.is_empty() {
        println!("No results found for: {}", query);
        return Ok(());
    }

    // Convert results to JSON value for formatter
    let results_json: Vec<Value> = results
        .iter()
        .map(|r| {
            serde_json::json!({
                "rank": r.rank,
                "symbol": r.symbol_name,
                "file_path": r.file_path,
                "node_id": r.node_id,
                "score": r.score.overall,
                "tfidf_score": r.score.tfidf,
                "neural_score": r.score.neural,
                "text_score": r.score.text_match,
                "structural_score": r.score.structural,
                "context": r.context,
                "language": r.language,
            })
        })
        .collect();

    // Use beautiful formatter
    let formatter = SearchFormatter::new();
    println!(
        "{}",
        formatter.format(&serde_json::json!(results_json), &query)
    );

    Ok(())
}

/// Analyze command implementation
async fn cmd_analyze_impl(
    query: String,
    token_budget: usize,
    project: Option<PathBuf>,
) -> AnyhowResult<()> {
    let project_path = get_project_path(project);
    let canonical_path = project_path
        .canonicalize()
        .context("Failed to canonicalize project path")?;

    info!("Analyzing: {}", query);

    // Create LeIndex and try to load from storage
    let mut leindex = LeIndex::new(&canonical_path).context("Failed to create LeIndex instance")?;

    // Load from storage if available
    if let Err(e) = leindex.load_from_storage() {
        warn!("Failed to load from storage: {}", e);
        warn!("Project may not be indexed. Run 'leindex index' first.");
    }

    // Perform analysis
    let result = leindex
        .analyze(&query, token_budget)
        .context("Analysis failed")?;

    // Print results with nice formatting
    let output = format_analysis_output(&query, &result);
    println!("{}", output);

    Ok(())
}

fn format_analysis_output(query: &str, result: &crate::cli::leindex::AnalysisResult) -> String {
    use crate::cli::mcp::output::{BOLD, DIM, LIGHT_CYAN, RESET};

    let mut out = String::new();
    out.push_str(&format!(
        "{}┌─ Analysis: {} ─┐{}\n",
        LIGHT_CYAN, query, RESET
    ));
    out.push_str(&format!(
        "  {}Found:{} {} entry point(s)\n",
        BOLD,
        RESET,
        result.results.len()
    ));
    out.push_str(&format!(
        "  {}Tokens:{} {}\n",
        BOLD, RESET, result.tokens_used
    ));
    out.push_str(&format!(
        "  {}Time:{} {}ms\n",
        BOLD, RESET, result.processing_time_ms
    ));

    if let Some(context) = &result.context {
        out.push('\n');
        out.push_str(&format!("  {}{}{}\n", BOLD, "Context:", RESET));
        let context_str: &str = context.as_str();
        let truncated = crate::cli::mcp::output::truncate_chars(context_str, 300);
        out.push_str(&format!("  {}{}{}", DIM, truncated, RESET));
    }

    out
}

/// Context command implementation
async fn cmd_context_impl(
    node_id: String,
    token_budget: usize,
    project: Option<PathBuf>,
) -> AnyhowResult<()> {
    let args = merge_tool_args(
        serde_json::json!({
            "node_id": node_id,
            "token_budget": token_budget
        }),
        &[],
        project.as_ref(),
    )?;

    let value = execute_tool_handler("leindex_context", args, project).await?;

    let formatter = SearchFormatter::new();
    let display_value = value
        .get("results")
        .cloned()
        .unwrap_or_else(|| value.clone());
    println!("{}", formatter.format(&display_value, &node_id));

    Ok(())
}

/// Phase command implementation
#[allow(clippy::too_many_arguments)]
async fn cmd_phase_impl(
    phase: Option<u8>,
    all: bool,
    mode: String,
    path: Option<PathBuf>,
    project: Option<PathBuf>,
    max_files: usize,
    max_focus_files: usize,
    top_n: usize,
    max_output_chars: usize,
    include_docs: bool,
    docs_mode: String,
    no_incremental_refresh: bool,
) -> AnyhowResult<()> {
    if !all && phase.is_none() {
        anyhow::bail!("Specify either --phase <1..5> or --all");
    }

    if all && phase.is_some() {
        anyhow::bail!("Use either --phase or --all, not both");
    }

    let target_path = path
        .or(project)
        .unwrap_or_else(|| std::env::current_dir().unwrap());
    let canonical_path = target_path
        .canonicalize()
        .context("Failed to canonicalize phase analysis path")?;

    let (root, focus_files) = if canonical_path.is_file() {
        let parent = canonical_path
            .parent()
            .map(PathBuf::from)
            .ok_or_else(|| anyhow::anyhow!("phase analysis file path has no parent directory"))?;
        (parent, vec![canonical_path.clone()])
    } else {
        (canonical_path, Vec::new())
    };

    let parsed_mode = FormatMode::parse(&mode)
        .ok_or_else(|| anyhow::anyhow!("Invalid mode '{}'. Use ultra|balanced|verbose", mode))?;

    let parsed_docs_mode = DocsMode::parse(&docs_mode).ok_or_else(|| {
        anyhow::anyhow!(
            "Invalid docs mode '{}'. Use off|markdown|text|all",
            docs_mode
        )
    })?;

    let selection = if all {
        PhaseSelection::All
    } else {
        let p = phase.unwrap();
        PhaseSelection::from_number(p)
            .ok_or_else(|| anyhow::anyhow!("Invalid phase '{}'. Use 1..5", p))?
    };

    let options = PhaseOptions {
        root,
        focus_files,
        mode: parsed_mode,
        max_files,
        max_focus_files,
        top_n,
        max_output_chars,
        use_incremental_refresh: !no_incremental_refresh,
        include_docs,
        docs_mode: parsed_docs_mode,
        hotspot_keywords: PhaseOptions::default().hotspot_keywords,
    };

    let report = tokio::task::spawn_blocking(move || run_phase_analysis(options, selection))
        .await
        .context("Phase task failed")??;

    println!("{}", report.formatted_output);
    Ok(())
}

/// Diagnostics command implementation
async fn cmd_diagnostics_impl(project: Option<PathBuf>) -> AnyhowResult<()> {
    let project_path = get_project_path(project);
    let canonical_path = project_path
        .canonicalize()
        .context("Failed to canonicalize project path")?;

    info!("Fetching diagnostics");

    // Create LeIndex and try to load from storage
    let mut leindex = LeIndex::new(&canonical_path).context("Failed to create LeIndex instance")?;

    // Load from storage if available
    if let Err(e) = leindex.load_from_storage() {
        warn!("Failed to load from storage: {}", e);
    }

    // Get diagnostics
    let diag = leindex
        .get_diagnostics()
        .context("Failed to get diagnostics")?;

    // Convert to JSON for formatter
    let diag_json = serde_json::json!({
        "project_path": diag.project_path,
        "indexed_files": diag.stats.files_parsed,
        "index_size_mb": diag.memory_usage_bytes as f64 / 1024.0 / 1024.0,
        "symbol_count": diag.stats.indexed_nodes,
        "issues": []
    });

    // Use beautiful formatter
    let formatter = DiagnosticsFormatter::new();
    println!("{}", formatter.format(&diag_json));

    Ok(())
}

async fn cmd_tools_impl(command: ToolCommands, project: Option<PathBuf>) -> AnyhowResult<()> {
    match command {
        ToolCommands::List => {
            for handler in all_tool_handlers() {
                println!("{}\t{}", handler.name(), handler.description());
            }
            Ok(())
        }
        ToolCommands::Help { name } => {
            let handler = find_tool_handler(&name)
                .ok_or_else(|| anyhow::anyhow!("Unknown tool '{}'", name))?;
            print_tool_help(&handler);
            Ok(())
        }
        ToolCommands::Schema { name } => {
            let handler = find_tool_handler(&name)
                .ok_or_else(|| anyhow::anyhow!("Unknown tool '{}'", name))?;
            print_json_value(&handler.argument_schema())?;
            Ok(())
        }
        ToolCommands::Run {
            name,
            args_json,
            set,
        } => {
            let parsed_args = parse_tool_args_json(&args_json)?;
            let args = merge_tool_args(parsed_args.clone(), &set, project.as_ref())?;
            let value = execute_tool_handler(&name, args, project).await?;

            // Use appropriate formatter based on tool name
            let normalized_name = name.to_lowercase().replace(['-', '.'], "_");
            let formatted = match normalized_name.as_str() {
                "leindex_search" | "search" => {
                    let formatter = SearchFormatter::new();
                    formatter.format(
                        &value,
                        parsed_args
                            .get("query")
                            .and_then(|v| v.as_str())
                            .unwrap_or(""),
                    )
                }
                "leindex_context" | "context" => {
                    let formatter = SearchFormatter::new();
                    let display_value = value
                        .get("results")
                        .cloned()
                        .unwrap_or_else(|| value.clone());
                    formatter.format(
                        &display_value,
                        parsed_args
                            .get("node_id")
                            .and_then(|v| v.as_str())
                            .unwrap_or(""),
                    )
                }
                "leindex_diagnostics" | "diagnostics" => {
                    let formatter = DiagnosticsFormatter::new();
                    formatter.format(&value)
                }
                "leindex_project_map" | "project_map" => {
                    let formatter = ProjectMapFormatter::new();
                    formatter.format(&value)
                }
                "leindex_impact_analysis" | "impact_analysis" => {
                    let formatter = ImpactFormatter::new();
                    formatter.format(&value)
                }
                "leindex_file_summary" | "file_summary" => {
                    let formatter = FileSummaryFormatter::new();
                    formatter.format(&value)
                }
                "leindex_phase_analysis" | "phase_analysis" => {
                    let formatter = PhaseFormatter::new();
                    formatter.format(&value)
                }
                "leindex_git_status" | "git_status" => {
                    use crate::cli::mcp::output::GitStatusFormatter;
                    let formatter = GitStatusFormatter::new();
                    formatter.format(&value)
                }
                _ => {
                    // Default to JSON output
                    serde_json::to_string_pretty(&value).unwrap_or_default()
                }
            };

            println!("{}", formatted);
            Ok(())
        }
    }
}

/// Serve command implementation - Start MCP server
async fn cmd_serve_impl(host: String, port: u16) -> AnyhowResult<()> {
    // Check for environment variable override (for customization via LEINDEX_PORT)
    let port = if let Ok(env_port) = std::env::var("LEINDEX_PORT") {
        env_port.parse::<u16>().unwrap_or(port)
    } else {
        port
    };

    // Parse the address
    let addr: SocketAddr = format!("{}:{}", host, port)
        .parse()
        .context("Invalid address or port")?;

    info!("Starting MCP server on {}", addr);

    // Create and run the MCP server
    let server = McpServer::with_address(addr).context("Failed to create MCP server")?;

    println!("\nLeIndex MCP Server\n");
    println!("Server starting on http://{}\n", addr);
    println!("Available endpoints:");
    println!("  POST /mcp           - JSON-RPC 2.0 endpoint");
    println!("  GET  /mcp/tools/list - List available tools");
    println!("  GET  /health         - Health check");
    println!("\nConfiguration:");
    println!("  Port: {} (override with LEINDEX_PORT env var)", port);
    println!("\nPress Ctrl+C to stop the server\n");

    server.run().await.context("Server error")?;

    Ok(())
}

/// MCP stdio command implementation - Run MCP server in stdio mode
/// This mode allows AI tools to start LeIndex as a subprocess for automatic integration
async fn cmd_mcp_stdio_impl(project: Option<PathBuf>) -> AnyhowResult<()> {
    use crate::cli::mcp::protocol::{JsonRpcError, JsonRpcMessage, JsonRpcResponse};
    use std::io::{self, BufRead, Read, Write};

    let project_path = get_project_path(project);
    let canonical_path = project_path
        .canonicalize()
        .context("Failed to canonicalize project path")?;

    info!(
        "Starting LeIndex MCP stdio server for project: {}",
        canonical_path.display()
    );

    // Create LeIndex instance
    let mut leindex = LeIndex::new(&canonical_path).context("Failed to create LeIndex instance")?;

    // Try to load from storage, but don't fail if not indexed yet
    let _ = leindex.load_from_storage();

    // Initialize global state for handlers
    let registry = Arc::new(ProjectRegistry::with_initial_project(
        DEFAULT_MAX_PROJECTS,
        leindex,
    ));
    let _ = crate::cli::mcp::server::SERVER_STATE.set(registry.clone());

    // Initialize handlers
    let _ = crate::cli::mcp::server::HANDLERS.set(all_tool_handlers());

    // Initialize SERVER_INSTANCE for stdio mode
    let server = crate::cli::mcp::server::McpServer {
        config: crate::cli::mcp::server::McpServerConfig::default(),
        _registry: registry.clone(),
        handshake_complete: Arc::new(std::sync::atomic::AtomicBool::new(false)),
        session_handshakes: Arc::new(std::sync::Mutex::new(std::collections::HashMap::new())),
    };
    crate::cli::mcp::server::SERVER_INSTANCE
        .set(Arc::new(server))
        .map_err(|_| anyhow::anyhow!("Server instance already initialized"))?;

    eprintln!("[INFO] LeIndex MCP stdio server starting");
    eprintln!("[INFO] Project: {}", canonical_path.display());
    eprintln!("[INFO] Reading JSON-RPC from stdin, writing to stdout");
    eprintln!("[INFO] Press Ctrl+C to stop\n");

    let stdin = io::stdin();
    let mut stdout = io::stdout().lock();
    let mut reader = io::BufReader::new(stdin.lock());
    let mut use_content_length = false;

    loop {
        let mut line = String::new();
        let bytes = match reader.read_line(&mut line) {
            Ok(b) => b,
            Err(e) => {
                eprintln!("[ERROR] Failed to read stdin: {}", e);
                continue;
            }
        };
        if bytes == 0 {
            break;
        }

        let line_trim = line.trim_end();
        if line_trim.is_empty() {
            continue;
        }

        let (json_payload, framed) = if line_trim
            .to_ascii_lowercase()
            .starts_with("content-length:")
        {
            let len_str = line_trim.split(':').nth(1).unwrap_or("").trim();
            let length: usize = match len_str.parse() {
                Ok(v) => v,
                Err(e) => {
                    eprintln!("[ERROR] Invalid Content-Length header: {}", e);
                    continue;
                }
            };

            // Consume remaining header lines until blank line
            loop {
                let mut header = String::new();
                if reader.read_line(&mut header).unwrap_or(0) == 0 {
                    break;
                }
                if header.trim().is_empty() {
                    break;
                }
            }

            let mut buf = vec![0u8; length];
            if let Err(e) = reader.read_exact(&mut buf) {
                eprintln!("[ERROR] Failed to read JSON payload: {}", e);
                break;
            }

            (String::from_utf8_lossy(&buf).to_string(), true)
        } else {
            (line_trim.to_string(), false)
        };

        use_content_length = use_content_length || framed;

        // Parse JSON-RPC message (request or notification)
        let message = match JsonRpcMessage::from_json(&json_payload) {
            Ok(m) => m,
            Err(e) => {
                let error_response = JsonRpcResponse::error(serde_json::Value::Null, e);
                let response = serde_json::to_string(&error_response).unwrap_or_default();
                if use_content_length {
                    let _ = writeln!(
                        stdout,
                        "Content-Length: {}\r\n\r\n{}",
                        response.len(),
                        response
                    );
                } else if writeln!(stdout, "{}", response).is_err() {
                    break;
                }
                let _ = stdout.flush();
                continue;
            }
        };

        // Handle based on message type
        match message {
            JsonRpcMessage::Notification(notification) => {
                eprintln!(
                    "[INFO] Received notification: {} (type: {})",
                    notification.method,
                    notification.notification_type()
                );
                continue;
            }
            JsonRpcMessage::Request(request) => {
                let request_id = request.id.clone().unwrap_or(serde_json::Value::Null);

                let response = match handle_mcp_request(request, project_path.clone()).await {
                    Ok(r) => r,
                    Err(e) => Some(JsonRpcResponse::error(
                        request_id,
                        JsonRpcError::internal_error(e.to_string()),
                    )),
                };

                // Notifications (e.g. notifications/initialized) must not receive
                // a response per JSON-RPC 2.0 spec — skip serializing/sending.
                let Some(response) = response else {
                    continue;
                };

                let response_json = match serde_json::to_string(&response) {
                    Ok(j) => j,
                    Err(e) => {
                        format!("{{\"jsonrpc\":\"2.0\",\"id\":null,\"error\":{{\"code\":-32700,\"message\":\"Failed to serialize response: {}\"}}}}", e)
                    }
                };

                if use_content_length {
                    if writeln!(
                        stdout,
                        "Content-Length: {}\r\n\r\n{}",
                        response_json.len(),
                        response_json
                    )
                    .is_err()
                    {
                        eprintln!("[ERROR] Failed to write to stdout");
                        break;
                    }
                } else if writeln!(stdout, "{}", response_json).is_err() {
                    eprintln!("[ERROR] Failed to write to stdout");
                    break;
                }
                let _ = stdout.flush();
            }
        }
    }

    Ok(())
}

/// MCP Unix socket command implementation — run MCP server on a Unix domain socket.
#[cfg(unix)]
async fn cmd_mcp_socket_impl(
    socket_path: &std::path::Path,
    project: Option<PathBuf>,
) -> AnyhowResult<()> {
    let project_path = get_project_path(project);
    let canonical_path = project_path
        .canonicalize()
        .context("Failed to canonicalize project path")?;

    info!(
        "Starting LeIndex MCP Unix socket server at {} for project: {}",
        socket_path.display(),
        canonical_path.display()
    );

    // Create LeIndex instance
    let mut leindex = LeIndex::new(&canonical_path).context("Failed to create LeIndex instance")?;
    let _ = leindex.load_from_storage();

    // Initialize global state for handlers
    let registry = Arc::new(ProjectRegistry::with_initial_project(
        DEFAULT_MAX_PROJECTS,
        leindex,
    ));
    let _ = crate::cli::mcp::server::SERVER_STATE.set(registry.clone());

    // Initialize handlers
    let _ = crate::cli::mcp::server::HANDLERS.set(all_tool_handlers());

    // Create MCP server instance
    let server = crate::cli::mcp::server::McpServer::new(
        crate::cli::mcp::server::McpServerConfig::default(),
    )
    .context("Failed to create MCP server")?;

    println!("\nLeIndex MCP Unix Socket Server\n");
    println!("Socket: {}", socket_path.display());
    println!("Project: {}", canonical_path.display());
    println!("\nPress Ctrl+C to stop the server\n");

    server.run_socket(socket_path).await
}

/// MCP Unix socket command implementation — stub for non-Unix platforms.
#[cfg(not(unix))]
async fn cmd_mcp_socket_impl(
    _socket_path: &std::path::Path,
    _project: Option<PathBuf>,
) -> AnyhowResult<()> {
    anyhow::bail!("Unix sockets are not supported on this platform");
}

fn parse_tool_args_json(args_json: &str) -> AnyhowResult<Value> {
    let value: Value =
        serde_json::from_str(args_json).context("Tool arguments must be valid JSON")?;
    if !value.is_object() {
        anyhow::bail!("Tool arguments must be a JSON object");
    }
    Ok(value)
}

fn merge_tool_args(
    args: Value,
    set_args: &[String],
    project: Option<&PathBuf>,
) -> AnyhowResult<Value> {
    let mut object = match args {
        Value::Object(map) => map,
        _ => Map::new(),
    };

    for entry in set_args {
        let (key, raw_value) = entry
            .split_once('=')
            .ok_or_else(|| anyhow::anyhow!("Invalid --set '{}'. Use KEY=VALUE", entry))?;
        let value = serde_json::from_str(raw_value)
            .unwrap_or_else(|_| Value::String(raw_value.to_string()));
        object.insert(key.to_string(), value);
    }

    if let Some(project) = project {
        if !object.contains_key("project_path") {
            let canonical = project.canonicalize().unwrap_or_else(|_| project.clone());
            object.insert(
                "project_path".to_string(),
                Value::String(canonical.display().to_string()),
            );
        }
    }

    Ok(Value::Object(object))
}

fn print_json_value(value: &Value) -> AnyhowResult<()> {
    println!(
        "{}",
        serde_json::to_string_pretty(value).context("Failed to format JSON output")?
    );
    Ok(())
}

fn print_tool_help(handler: &ToolHandler) {
    let schema = handler.argument_schema();
    let normalized = normalize_tool_name(handler.name());
    let short_name = normalized
        .strip_prefix("leindex_")
        .unwrap_or(normalized.as_str())
        .to_string();
    let kebab_short = short_name.replace('_', "-");
    let kebab_full = normalized.replace('_', "-");

    println!("{}", handler.name());
    println!("{}", handler.description());
    println!();
    println!("Aliases:");
    println!("  {}", handler.name());
    if short_name != handler.name() {
        println!("  {}", short_name);
    }
    if kebab_short != short_name {
        println!("  {}", kebab_short);
    }
    if kebab_full != normalized && kebab_full != kebab_short {
        println!("  {}", kebab_full);
    }
    println!();
    println!("Usage:");
    println!("  leindex tools help {}", handler.name());
    println!("  leindex tools schema {}", handler.name());
    println!(
        "  leindex tools run {} --args '<json-object>'",
        handler.name()
    );
    println!(
        "  leindex tools run {} --set key=value --set other=true",
        handler.name()
    );

    if let Some(properties) = schema.get("properties").and_then(|v| v.as_object()) {
        println!();
        println!("Arguments:");

        let required = schema
            .get("required")
            .and_then(|v| v.as_array())
            .map(|items| {
                items
                    .iter()
                    .filter_map(|item| item.as_str())
                    .collect::<std::collections::HashSet<_>>()
            })
            .unwrap_or_default();

        for (name, property) in properties {
            let required_marker = if required.contains(name.as_str()) {
                "required"
            } else {
                "optional"
            };
            let property_type = property
                .get("type")
                .and_then(|v| v.as_str())
                .or_else(|| {
                    property
                        .get("oneOf")
                        .and_then(|v| v.as_array())
                        .map(|_| "multiple")
                })
                .unwrap_or("value");
            let description = property
                .get("description")
                .and_then(|v| v.as_str())
                .unwrap_or("");
            let default = property.get("default");

            println!("  {} ({}, {})", name, property_type, required_marker);
            if !description.is_empty() {
                println!("    {}", description);
            }
            if let Some(default) = default {
                println!("    default: {}", default);
            }
        }
    }

    println!();
    println!("Schema:");
    println!(
        "{}",
        serde_json::to_string_pretty(&schema).unwrap_or_else(|_| "{}".to_string())
    );
}

fn normalize_tool_name(name: &str) -> String {
    name.trim().to_ascii_lowercase().replace('-', "_")
}

fn find_tool_handler(name: &str) -> Option<ToolHandler> {
    let normalized = normalize_tool_name(name);

    all_tool_handlers().into_iter().find(|handler| {
        let handler_name = normalize_tool_name(handler.name());
        let title = handler.title();
        let short_name = extract_short_name(&handler_name);

        // Check all possible formats:
        // 1. handler.name() - e.g., "leindex.context"
        // 2. short name from handler - e.g., "context"
        // 3. title - e.g., "leindex_context" (normalized)
        // 4. legacy format - e.g., "leindex_context" in input matches "context" from handler
        // 5. MCP-compliant format - e.g., "leindex.index" in input matches "leindex.index" from handler
        // 6. Direct legacy format - e.g., "leindex_search" matches handler name "leindex.search" after normalization

        handler_name == normalized
            || short_name == normalized
            || normalize_tool_name(title) == normalized
            // Legacy leindex_* format - check if input has leindex_ prefix matching short name
            || (normalized.starts_with("leindex_") && short_name == normalized.strip_prefix("leindex_").unwrap_or(""))
    })
}

/// Extract short name from a tool name.
/// For "leindex_foo" returns "foo", for "leindex [foo bar]" returns "foo_bar", for "leindex.foo-bar" returns "foo_bar".
fn extract_short_name(name: &str) -> String {
    // Handle "leindex [foo bar]" format (normalized to "leindex [foo bar]")
    if let Some(inside) = name.strip_prefix("leindex [") {
        if let Some(inside) = inside.strip_suffix(']') {
            let with_underscores = inside.replace(' ', "_");
            return normalize_tool_name(&with_underscores);
        }
    }
    // Handle "leindex.foo-bar" format (MCP-compliant: leindex.search, leindex.project-map)
    if let Some(inside) = name.strip_prefix("leindex.") {
        return normalize_tool_name(inside);
    }
    // Handle old "leindex_foo" format
    name.strip_prefix("leindex_")
        .map(normalize_tool_name)
        .unwrap_or_else(|| normalize_tool_name(name))
}

async fn execute_tool_handler(
    name: &str,
    args: Value,
    project: Option<PathBuf>,
) -> AnyhowResult<Value> {
    let handler =
        find_tool_handler(name).ok_or_else(|| anyhow::anyhow!("Unknown tool '{}'", name))?;
    let registry = build_tool_registry(project)?;
    handler
        .execute(&registry, args)
        .await
        .map_err(|error| anyhow::anyhow!("{}", error))
}

fn build_tool_registry(project: Option<PathBuf>) -> AnyhowResult<Arc<ProjectRegistry>> {
    let initial = get_project_path(project);
    let canonical = initial.canonicalize().with_context(|| {
        format!(
            "Failed to canonicalize project path '{}'",
            initial.display()
        )
    })?;
    let project_root = if canonical.is_file() {
        canonical
            .parent()
            .map(PathBuf::from)
            .ok_or_else(|| anyhow::anyhow!("File path '{}' has no parent", canonical.display()))?
    } else {
        canonical
    };

    let mut leindex =
        LeIndex::new(&project_root).context("Failed to create LeIndex instance for tool run")?;
    let _ = leindex.load_from_storage();

    Ok(Arc::new(ProjectRegistry::with_initial_project(
        DEFAULT_MAX_PROJECTS,
        leindex,
    )))
}

/// Dashboard command implementation - Start the frontend dashboard
async fn cmd_dashboard_impl(port: u16, prod: bool) -> AnyhowResult<()> {
    use std::process::Command;

    // Find the dashboard directory.
    let current_dir = std::env::current_dir().context("Failed to get current directory")?;
    let dashboard_path = {
        let mut candidates = Vec::new();

        // 1) Current directory.
        candidates.push(current_dir.join("dashboard"));

        // 2) Parent traversal for source checkouts.
        let mut parent = current_dir.as_path();
        for _ in 0..5 {
            if let Some(next) = parent.parent() {
                candidates.push(next.join("dashboard"));
                parent = next;
            } else {
                break;
            }
        }

        // 3) Explicit override for packaged installs.
        if let Ok(explicit) = std::env::var("LEINDEX_DASHBOARD_DIR") {
            candidates.push(PathBuf::from(explicit));
        }

        // 4) Installer default location.
        if let Ok(home) = std::env::var("HOME") {
            candidates.push(PathBuf::from(home).join(".leindex").join("dashboard"));
        }

        candidates
            .into_iter()
            .find(|path| path.exists() && path.is_dir())
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "Dashboard directory not found. Checked current repo paths, LEINDEX_DASHBOARD_DIR, and ~/.leindex/dashboard."
                )
            })?
    };

    // Check if bun is installed
    let bun_exists = Command::new("bun")
        .arg("--version")
        .output()
        .map(|o| o.status.success())
        .unwrap_or(false);

    if !bun_exists {
        anyhow::bail!(
            "Bun is required to run the dashboard. Please install it first:\n  curl -fsSL https://bun.sh/install | bash"
        );
    }

    println!("\nLeIndex Dashboard\n");
    println!("Starting dashboard server...\n");

    if prod {
        // Build for production
        println!("Building dashboard for production...");
        let build_status = Command::new("bun")
            .current_dir(&dashboard_path)
            .arg("run")
            .arg("build")
            .status()
            .context("Failed to build dashboard")?;

        if !build_status.success() {
            anyhow::bail!("Dashboard build failed");
        }

        println!("\nDashboard built successfully!");
        println!("Built files: {}/dist", dashboard_path.display());
        println!("\nTo serve the production build, use:");
        println!("  cd {} && bun run start", dashboard_path.display());
    } else {
        // Start dev server
        println!("Dashboard will be available at: http://localhost:{}", port);
        println!("Press Ctrl+C to stop the server\n");

        let status = Command::new("bun")
            .current_dir(&dashboard_path)
            .arg("run")
            .arg("dev")
            .status()
            .context("Failed to start dashboard")?;

        if !status.success() {
            anyhow::bail!("Dashboard server exited with error");
        }
    }

    Ok(())
}

/// Cleanup command implementation — remove stale LeIndex temp artifacts.
async fn cmd_cleanup_impl(max_age_days: u64, dry_run: bool) -> AnyhowResult<()> {
    use crate::cli::cleanup::run_gc;
    use std::time::Duration;

    let max_age = Duration::from_secs(max_age_days * 24 * 3600);

    if dry_run {
        // In dry-run mode we scan but do not remove
        println!("LeIndex Cleanup (dry run)\n");
        println!(
            "Scanning for artifacts older than {} day(s)...\n",
            max_age_days
        );

        let report = run_gc_dry_run(max_age);
        println!("{}", report);
    } else {
        println!("LeIndex Cleanup\n");
        println!("Removing artifacts older than {} day(s)...\n", max_age_days);

        let report = run_gc(max_age);
        println!("{}", report);
    }

    Ok(())
}

/// Dry-run GC: scan and report without removing anything.
fn run_gc_dry_run(max_age: std::time::Duration) -> crate::cli::cleanup::GcReport {
    use crate::cli::cleanup::artifact_scan_roots;
    use std::time::SystemTime;
    use tracing::debug;

    let mut report = crate::cli::cleanup::GcReport::default();
    let cutoff = SystemTime::now() - max_age;

    for root in artifact_scan_roots() {
        if !root.exists() {
            continue;
        }

        if root
            .file_name()
            .map(|n| n.to_string_lossy().starts_with("lephase-"))
            .unwrap_or(false)
        {
            count_artifact(&root, &cutoff, &mut report);
            continue;
        }

        let entries = match std::fs::read_dir(&root) {
            Ok(e) => e,
            Err(err) => {
                debug!("Cannot read {}: {}", root.display(), err);
                continue;
            }
        };

        for entry in entries.flatten() {
            let path = entry.path();
            if !path.is_dir() {
                continue;
            }
            if path.file_name().map(|n| n == ".leindex").unwrap_or(false) {
                continue;
            }
            count_artifact(&path, &cutoff, &mut report);
        }
    }

    report
}

fn count_artifact(
    dir: &std::path::Path,
    cutoff: &std::time::SystemTime,
    report: &mut crate::cli::cleanup::GcReport,
) {
    use crate::cli::cleanup::{
        artifact_age, dir_size, is_leindex_artifact, is_leindex_artifact_by_pattern,
    };
    use tracing::debug;

    if !is_leindex_artifact(dir) && !is_leindex_artifact_by_pattern(dir) {
        return;
    }

    report.scanned += 1;

    let age = artifact_age(dir);
    if age >= *cutoff {
        debug!("Artifact {} is not stale yet", dir.display());
        return;
    }

    let size = dir_size(dir);
    debug!(
        "Would remove stale artifact: {} ({:.2} MB)",
        dir.display(),
        size as f64 / 1024.0 / 1024.0
    );
    report.removed += 1;
    report.bytes_freed += size;
}

/// Handle a single MCP request and return the response
#[allow(clippy::needless_return)]
async fn handle_mcp_request(
    request: JsonRpcRequest,
    _project_path: PathBuf,
) -> anyhow::Result<Option<JsonRpcResponse>> {
    use crate::cli::mcp::server::{
        handle_tool_call, list_tools_json, HANDLERS, SERVER_INSTANCE, SERVER_STATE,
    };

    let method_name = request.method.clone();
    let id = request.id.clone().unwrap_or(serde_json::Value::Null);

    // Notifications (id is null) must not receive a response per JSON-RPC 2.0 spec
    if request.id.is_none() {
        tracing::debug!("Ignoring notification: {}", method_name);
        return Ok(None);
    }

    // Get server instance to check handshake status
    let server_instance = match SERVER_INSTANCE.get() {
        Some(s) => s,
        None => {
            return Ok(Some(JsonRpcResponse::error(
                id,
                crate::cli::mcp::protocol::JsonRpcError::new(
                    -32603,
                    "Server instance not initialized",
                ),
            )));
        }
    };

    // Check handshake completion for non-initialize requests
    if !server_instance
        .handshake_complete
        .load(std::sync::atomic::Ordering::SeqCst)
        && method_name != "initialize"
        && method_name != "ping"
    {
        return Ok(Some(JsonRpcResponse::error(
            id,
            crate::cli::mcp::protocol::JsonRpcError::new(
                -32000,
                "Server not initialized. Call 'initialize' first.",
            ),
        )));
    }

    // Get the global state and handlers
    let state = SERVER_STATE
        .get()
        .ok_or_else(|| anyhow::anyhow!("Server state not initialized"))?;

    let handlers = HANDLERS
        .get()
        .ok_or_else(|| anyhow::anyhow!("Handlers not initialized"))?;

    // Handle different methods
    match method_name.as_str() {
        "initialize" => {
            // MCP protocol initialization handshake
            // Mark handshake as complete
            server_instance
                .handshake_complete
                .store(true, std::sync::atomic::Ordering::SeqCst);

            // Return server capabilities with comprehensive description
            return Ok(Some(JsonRpcResponse::success(
                id,
                serde_json::json!({
                    "protocolVersion": "2024-11-05",
                    "capabilities": {
                        "tools": {
                            "listChanged": true
                        },
                        "prompts": {
                            "listChanged": true
                        },
                        "resources": {
                            "listChanged": true,
                            "subscribe": false
                        },
                        "logging": {},
                        "progress": true
                    },
                    "serverInfo": {
                        "name": "leindex",
                        "version": env!("CARGO_PKG_VERSION"),
                        "description": "LeIndex MCP Server - Semantic code indexing and analysis with PDG-based tools. Provides 18+ specialized tools for code comprehension: semantic search, symbol lookup, impact analysis, structural code queries, and intelligent editing. Uses Program Dependence Graphs for superior code understanding compared to traditional text-based tools."
                    }
                }),
            )));
        }

        "ping" => {
            // Simple health check
            Ok(Some(JsonRpcResponse::success(id, serde_json::json!({}))))
        }
        "tools/call" => {
            // Use the centralized tool call handler that formats for MCP
            let result = handle_tool_call(state, handlers, &request).await;
            Ok(Some(JsonRpcResponse::from_result(id, result)))
        }
        "tools/list" => {
            // List all available tools using centralized formatter
            Ok(Some(JsonRpcResponse::success(
                id,
                list_tools_json(handlers),
            )))
        }
        _ => Ok(Some(JsonRpcResponse::error(
            id,
            crate::cli::mcp::protocol::JsonRpcError::method_not_found(method_name),
        ))),
    }
}

/// Main entry point for the CLI
pub async fn main() -> AnyhowResult<()> {
    match Cli::try_parse() {
        Ok(cli) => cli.run().await,
        Err(err) => {
            if matches!(
                err.kind(),
                ErrorKind::DisplayHelp | ErrorKind::DisplayVersion
            ) {
                maybe_complete_post_install_actions(&Commands::Diagnostics);
            }
            err.exit()
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_cli_parsing() {
        let cli = Cli::try_parse_from(["leindex", "index", "/path/to/project"]).unwrap();
        assert!(matches!(cli.command, Some(Commands::Index { .. })));
    }

    #[test]
    fn test_mcp_command_parsing() {
        let cli = Cli::try_parse_from(["leindex", "mcp"]).unwrap();
        assert!(matches!(cli.command, Some(Commands::Mcp { .. })));
    }

    #[test]
    fn test_stdio_flag_parsing() {
        let cli = Cli::try_parse_from(["leindex", "--stdio"]).unwrap();
        assert!(cli.stdio);
    }

    #[test]
    fn test_search_command() {
        let cli = Cli::try_parse_from(["leindex", "search", "test query"]).unwrap();
        match cli.command {
            Some(Commands::Search { query, top_k, .. }) => {
                assert_eq!(query, "test query");
                assert_eq!(top_k, 10);
            }
            _ => panic!("Expected Search command"),
        }
    }

    #[test]
    fn test_phase_command_parsing() {
        let cli =
            Cli::try_parse_from(["leindex", "phase", "--phase", "2", "--mode", "ultra"]).unwrap();
        match cli.command {
            Some(Commands::Phase {
                phase, all, mode, ..
            }) => {
                assert_eq!(phase, Some(2));
                assert!(!all);
                assert_eq!(mode, "ultra");
            }
            _ => panic!("Expected Phase command"),
        }
    }

    #[test]
    fn test_dashboard_command_parsing() {
        let cli = Cli::try_parse_from(["leindex", "dashboard"]).unwrap();
        match cli.command {
            Some(Commands::Dashboard { port, prod }) => {
                assert_eq!(port, 5173);
                assert!(!prod);
            }
            _ => panic!("Expected Dashboard command"),
        }
    }

    #[test]
    fn test_dashboard_command_with_port() {
        let cli = Cli::try_parse_from(["leindex", "dashboard", "--port", "3000"]).unwrap();
        match cli.command {
            Some(Commands::Dashboard { port, prod }) => {
                assert_eq!(port, 3000);
                assert!(!prod);
            }
            _ => panic!("Expected Dashboard command"),
        }
    }

    #[test]
    fn test_dashboard_command_prod() {
        let cli = Cli::try_parse_from(["leindex", "dashboard", "--prod"]).unwrap();
        match cli.command {
            Some(Commands::Dashboard { port, prod }) => {
                assert_eq!(port, 5173);
                assert!(prod);
            }
            _ => panic!("Expected Dashboard command"),
        }
    }

    #[test]
    fn test_tools_help_command_parsing() {
        let cli = Cli::try_parse_from(["leindex", "tools", "help", "project_map"]).unwrap();
        match cli.command {
            Some(Commands::Tools {
                command: ToolCommands::Help { name },
            }) => assert_eq!(name, "project_map"),
            _ => panic!("Expected tools help command"),
        }
    }

    #[test]
    fn test_tools_run_command_parsing() {
        let cli = Cli::try_parse_from([
            "leindex",
            "tools",
            "run",
            "project_map",
            "--args",
            "{\"depth\":1}",
            "--set",
            "include_symbols=true",
        ])
        .unwrap();

        match cli.command {
            Some(Commands::Tools {
                command:
                    ToolCommands::Run {
                        name,
                        args_json,
                        set,
                    },
            }) => {
                assert_eq!(name, "project_map");
                assert_eq!(args_json, "{\"depth\":1}");
                assert_eq!(set, vec!["include_symbols=true"]);
            }
            _ => panic!("Expected tools run command"),
        }
    }

    #[test]
    fn test_find_tool_handler_accepts_short_and_full_names() {
        assert!(find_tool_handler("LeIndex [Project Map]").is_some());
        assert!(find_tool_handler("project_map").is_some());
        assert!(find_tool_handler("project-map").is_some());
    }

    #[test]
    fn test_cleanup_command_parsing() {
        let cli = Cli::try_parse_from(["leindex", "cleanup"]).unwrap();
        match cli.command {
            Some(Commands::Cleanup {
                max_age_days,
                dry_run,
            }) => {
                assert_eq!(max_age_days, 7);
                assert!(!dry_run);
            }
            _ => panic!("Expected Cleanup command"),
        }
    }

    #[test]
    fn test_cleanup_command_with_flags() {
        let cli = Cli::try_parse_from(["leindex", "cleanup", "--max-age-days", "14", "--dry-run"])
            .unwrap();
        match cli.command {
            Some(Commands::Cleanup {
                max_age_days,
                dry_run,
            }) => {
                assert_eq!(max_age_days, 14);
                assert!(dry_run);
            }
            _ => panic!("Expected Cleanup command"),
        }
    }
}