java-codebase-rag 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

java_codebase_rag/installer.py

@@ -0,0 +1,1339 @@
+"""Interactive installer module for java-codebase-rag.
+
+This module provides the `install` subcommand that walks users through:
+1. Java source detection
+2. Embedding model selection
+3. Agent host selection
+4. Scope selection (project/user)
+5. Artifact deployment (MCP config, skill, agent)
+6. YAML config generation and indexing
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, NamedTuple
+
+import yaml
+
+Scope = Literal["project", "user"]
+
+# MCP server name constant
+_MCP_SERVER_NAME = "java-codebase-rag"
+
+# Exit code constants
+EXIT_SUCCESS = 0
+EXIT_PARTIAL = 1
+EXIT_FATAL = 2
+
+
+class ArtifactResult(NamedTuple):
+    """Result of deploying a single artifact."""
+
+    path: Path
+    success: bool
+    error: str | None
+
+
+@dataclass(frozen=True)
+class HostConfig:
+    """Configuration for an agent host."""
+
+    name: str  # "claude-code", "qwen-code", "gigacode"
+    dir_name: str  # ".claude", ".qwen", ".gigacode"
+    mcp_project: str  # ".mcp.json", ".qwen/settings.json", ".gigacode/settings.json"
+    mcp_user: str  # ".claude.json", ".qwen/settings.json", ".gigacode/settings.json"
+
+    def scope_path(self, scope: Scope, cwd: Path) -> Path:
+        """Return the host directory for the given scope."""
+        if scope == "project":
+            return cwd / self.dir_name
+        else:  # user
+            return Path.home() / self.dir_name
+
+    def mcp_config_path(self, scope: Scope, cwd: Path) -> Path:
+        """Return the full path to the MCP config file."""
+        if scope == "project":
+            return cwd / self.mcp_project
+        else:  # user
+            return Path.home() / self.mcp_user
+
+    def skills_dir(self, scope: Scope, cwd: Path) -> Path:
+        """Return the skills directory path."""
+        return self.scope_path(scope, cwd) / "skills"
+
+    def agents_dir(self, scope: Scope, cwd: Path) -> Path:
+        """Return the agents directory path."""
+        return self.scope_path(scope, cwd) / "agents"
+
+
+HOSTS: dict[str, HostConfig] = {
+    "claude-code": HostConfig(
+        name="claude-code",
+        dir_name=".claude",
+        mcp_project=".mcp.json",
+        mcp_user=".claude.json",
+    ),
+    "qwen-code": HostConfig(
+        name="qwen-code",
+        dir_name=".qwen",
+        mcp_project=".qwen/settings.json",
+        mcp_user=".qwen/settings.json",
+    ),
+    "gigacode": HostConfig(
+        name="gigacode",
+        dir_name=".gigacode",
+        mcp_project=".gigacode/settings.json",
+        mcp_user=".gigacode/settings.json",
+    ),
+}
+
+
+def prompt(
+    prompt_type: str,
+    message: str,
+    *,
+    choices=None,
+    default=None,
+) -> list[str] | str | bool:
+    """Interactive prompt that dispatches to questionary on TTY, returns default otherwise.
+
+    Args:
+        prompt_type: Type of prompt ("checkbox", "select", "text", "confirm")
+        message: Prompt message to display
+        choices: List of choices (for checkbox/select)
+        default: Default value to return when not interactive
+
+    Returns:
+        - checkbox: list[str] of selected values
+        - select: str of selected value
+        - text: str of entered text
+        - confirm: bool (True/False)
+    """
+    if not sys.stdin.isatty():
+        return default
+
+    # Lazy import questionary only when needed (TTY)
+    import questionary
+    from prompt_toolkit.styles import Style
+
+    # Strip default ANSI colors — rely on ●/○ indicators only, no fg/bg highlights
+    # noinherit prevents prompt_toolkit from merging in questionary's default fg colors
+    no_color_style = Style(
+        [
+            ("highlighted", "noinherit"),
+            ("selected", "noinherit"),
+            ("pointer", "noinherit bold"),
+        ]
+    )
+
+    try:
+        if prompt_type == "checkbox":
+            return questionary.checkbox(message, choices=choices, style=no_color_style).ask()
+        elif prompt_type == "select":
+            return questionary.select(message, choices=choices, style=no_color_style).ask()
+        elif prompt_type == "text":
+            return questionary.text(message, default=default, style=no_color_style).ask()
+        elif prompt_type == "confirm":
+            return questionary.confirm(message, style=no_color_style).ask()
+        else:
+            raise ValueError(f"Unknown prompt_type: {prompt_type}")
+    except KeyboardInterrupt:
+        # User Ctrl+C is a clean abort, not a traceback
+        raise SystemExit(2)
+
+
+def detect_java_directories(source_root: Path) -> list[Path]:
+    """Return Maven/Gradle module roots. If root has build file, returns [Path('.')].
+
+    Checks if source_root itself contains a build file (pom.xml, build.gradle, build.gradle.kts).
+    If YES: returns [Path(".")] — the entire project is indexed as one unit.
+    If NO: scans immediate children for directories containing build files.
+
+    Args:
+        source_root: Root directory to scan for Java projects
+
+    Returns:
+        List of detected module roots (relative to source_root)
+
+    Raises:
+        SystemExit(2): If no build files found in source_root or immediate children
+    """
+    build_files = ["pom.xml", "build.gradle", "build.gradle.kts"]
+
+    # Check if source_root itself has a build file
+    for bf in build_files:
+        if (source_root / bf).is_file():
+            return [Path(".")]
+
+    # Scan immediate children for build files
+    detected = []
+    for child in source_root.iterdir():
+        if not child.is_dir():
+            continue
+        # Check if this child directory has a build file
+        for bf in build_files:
+            if (child / bf).is_file():
+                detected.append(Path(child.name))
+                break
+
+    if not detected:
+        print(f"Error: No Java build files (pom.xml, build.gradle, build.gradle.kts) found in {source_root} or its immediate children.")
+        raise SystemExit(2)
+
+    return detected
+
+
+def confirm_source_root(cwd: Path, *, non_interactive: bool) -> Path:
+    """Show cwd as source root, let user accept or change it. Returns resolved source_root.
+
+    Args:
+        cwd: Current working directory (default source root)
+        non_interactive: If True, return cwd without prompting
+
+    Returns:
+        Resolved source root path
+    """
+    if non_interactive:
+        return cwd
+
+    message = f"Source root [{cwd}]:"
+    user_input = prompt("text", message, default=str(cwd))
+
+    if not user_input or user_input == str(cwd):
+        return cwd
+
+    # Expand ~ and $HOME
+    expanded = os.path.expandvars(user_input.strip())
+    expanded = os.path.expanduser(expanded)
+    result = Path(expanded)
+
+    # Validate path exists and is a directory
+    while not result.is_dir():
+        print(f"Error: Path {result} does not exist or is not a directory.")
+        user_input = prompt("text", "Source root:", default=str(cwd))
+        if not user_input or user_input == str(cwd):
+            return cwd
+        expanded = os.path.expandvars(user_input.strip())
+        expanded = os.path.expanduser(expanded)
+        result = Path(expanded)
+
+    return result.resolve()
+
+
+def resolve_model(model_input: str | None, *, non_interactive: bool) -> str:
+    """Resolve embedding model path or 'auto'.
+
+    Args:
+        model_input: User-provided model path or None
+        non_interactive: If True, return "auto" without prompting
+
+    Returns:
+        Resolved model string ("auto" or a valid path)
+    """
+    if model_input:
+        # Expand ~ and $HOME
+        expanded = os.path.expandvars(model_input.strip())
+        expanded = os.path.expanduser(expanded)
+        model_path = Path(expanded)
+
+        if model_path.exists():
+            return str(model_path)
+
+        # Path not found
+        if non_interactive:
+            print(f"Warning: Model path {model_input} not found, falling back to 'auto'.")
+            return "auto"
+
+        confirmed = prompt(
+            "confirm",
+            f"Model path {model_input} not found. Use 'auto' instead?",
+        )
+        if confirmed:
+            return "auto"
+        else:
+            # Re-prompt for model path
+            new_input = prompt("text", "Enter model path (or 'auto'):", default="auto")
+            if new_input == "auto" or not new_input:
+                return "auto"
+            return resolve_model(new_input, non_interactive=non_interactive)
+
+    if non_interactive:
+        return "auto"
+
+    # Interactive with no CLI input: prompt for model
+    user_input = prompt("text", "Embedding model path (or 'auto'):", default="auto")
+    if user_input == "auto" or not user_input:
+        return "auto"
+    return resolve_model(user_input, non_interactive=False)
+
+
+def select_hosts(*, non_interactive: bool, cli_agents: list[str] | None) -> list[HostConfig]:
+    """Select agent hosts from checkbox or CLI flags. Returns list of selected HostConfig.
+
+    Args:
+        non_interactive: If True, use CLI flags only
+        cli_agents: List of agent names from CLI flags
+
+    Returns:
+        List of selected HostConfig objects
+
+    Raises:
+        SystemExit(2): If no agents selected or invalid agent name
+    """
+    if cli_agents:
+        # Validate agent names
+        for agent in cli_agents:
+            if agent not in HOSTS:
+                print(f"Error: Unknown agent '{agent}'. Valid agents: {', '.join(HOSTS.keys())}")
+                raise SystemExit(2)
+        return [HOSTS[agent] for agent in cli_agents]
+
+    if non_interactive:
+        print("Error: --agent flag is required in non-interactive mode.")
+        print(f"Valid agents: {', '.join(HOSTS.keys())}")
+        raise SystemExit(2)
+
+    # Interactive: show checkbox with claude-code pre-selected (most common)
+    # Changed from all pre-selected to avoid confusion
+    host_names = list(HOSTS.keys())
+    choices = [
+        {"name": name, "value": name, "checked": (name == "claude-code")}
+        for name in host_names
+    ]
+
+    print("Note: You can select multiple agent hosts with Space. Navigate with arrow keys.")
+    selected = prompt("checkbox", "Select agent hosts to configure:", choices=choices)
+
+    if not selected:
+        # User unselected all - prompt to re-select or abort
+        retry = prompt(
+            "confirm",
+            "At least one agent host is required. Re-select hosts?",
+        )
+        if retry:
+            return select_hosts(non_interactive=False, cli_agents=None)
+        else:
+            raise SystemExit(2)
+
+    # Show confirmation of what will be deployed
+    print(f"Will deploy to: {', '.join(selected)}")
+    return [HOSTS[name] for name in selected]
+
+
+def select_scope(*, non_interactive: bool, cli_scope: str | None) -> Scope:
+    """Select 'project' or 'user' scope.
+
+    Args:
+        non_interactive: If True, return "project" without prompting
+        cli_scope: Scope from CLI flag
+
+    Returns:
+        Selected scope ("project" or "user")
+    """
+    if cli_scope:
+        if cli_scope not in ("project", "user"):
+            print(f"Error: Invalid scope '{cli_scope}'. Must be 'project' or 'user'.")
+            raise SystemExit(2)
+        return cli_scope  # type: ignore
+
+    if non_interactive:
+        return "project"
+
+    # Interactive: prompt for scope
+    print("Note: 'project' scope stores configs in the project directory.")
+    print("      'user' scope stores configs in your home directory.")
+    selected = prompt(
+        "select",
+        "Select installation scope:",
+        choices=["project", "user"],
+    )
+
+    if not selected:
+        return "project"
+
+    print(f"Selected scope: {selected}")
+    return selected  # type: ignore
+
+
+def resolve_mcp_command(*, non_interactive: bool) -> str:
+    """Resolve the absolute path to java-codebase-rag-mcp.
+
+    Returns the path string for use as MCP 'command' value.
+
+    Args:
+        non_interactive: If True, exit with code 2 when not found
+
+    Returns:
+        Absolute path to java-codebase-rag-mcp executable
+
+    Raises:
+        SystemExit(2): If not found and non-interactive, or user aborts
+    """
+    mcp_path = shutil.which("java-codebase-rag-mcp")
+
+    if mcp_path:
+        return mcp_path
+
+    # Not found on PATH
+    if non_interactive:
+        print("Error: `java-codebase-rag-mcp` not found on PATH.")
+        print("Ensure `java-codebase-rag` is installed, then re-run with `--non-interactive --agent <host>`.")
+        raise SystemExit(2)
+
+    # Interactive: prompt user for path
+    print("Warning: `java-codebase-rag-mcp` not found on PATH.")
+    user_path = prompt(
+        "text",
+        "Enter the full path to java-codebase-rag-mcp (or 'abort'):",
+        default="abort",
+    )
+
+    if user_path == "abort" or not user_path:
+        raise SystemExit(2)
+
+    # Expand and validate the provided path
+    expanded = os.path.expandvars(user_path.strip())
+    expanded = os.path.expanduser(expanded)
+    path_obj = Path(expanded)
+
+    while not path_obj.is_file():
+        print(f"Error: Path {path_obj} does not exist or is not a file.")
+        user_path = prompt(
+            "text",
+            "Enter the full path to java-codebase-rag-mcp (or 'abort'):",
+            default="abort",
+        )
+        if user_path == "abort" or not user_path:
+            raise SystemExit(2)
+        expanded = os.path.expandvars(user_path.strip())
+        expanded = os.path.expanduser(expanded)
+        path_obj = Path(expanded)
+
+    # Check if executable
+    if not os.access(path_obj, os.X_OK):
+        print(f"Warning: {path_obj} is not executable. This may cause issues.")
+
+    return str(path_obj.resolve())
+
+
+def merge_mcp_config(config_path: Path, host: HostConfig, *, mcp_command: str) -> bool:
+    """Read, merge, write MCP config. Returns True if entry was added/updated.
+
+    Args:
+        config_path: Path to MCP config file
+        host: HostConfig for the agent host
+        mcp_command: Resolved absolute path to java-codebase-rag-mcp
+
+    Returns:
+        True if entry was added/updated, False if no change needed
+
+    Raises:
+        ValueError: If existing config file cannot be parsed as JSON
+    """
+    # Read existing config (or start with empty dict)
+    if config_path.is_file():
+        try:
+            with open(config_path, "r") as f:
+                config = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Failed to parse {config_path}: {e}") from e
+    else:
+        config = {}
+
+    # Ensure mcpServers key exists
+    if "mcpServers" not in config:
+        config["mcpServers"] = {}
+
+    # Prepare new entry
+    new_entry = {"command": mcp_command, "type": "stdio"}
+    existing_entry = config["mcpServers"].get(_MCP_SERVER_NAME)
+
+    # Check if entry already exists with same config
+    if existing_entry == new_entry:
+        return False
+
+    # Merge/update entry
+    config["mcpServers"][_MCP_SERVER_NAME] = new_entry
+
+    # Write atomically (write to tmp, then rename)
+    tmp_name = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=config_path.parent,
+            prefix=f".{config_path.name}.",
+            delete=False,
+        ) as tmp:
+            json.dump(config, tmp, indent=2)
+            tmp.flush()
+            os.fsync(tmp.fileno())
+            tmp_name = tmp.name
+
+        # Atomic rename
+        os.rename(tmp_name, config_path)
+        return True
+    except (IOError, OSError) as e:
+        if tmp_name:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+        raise RuntimeError(f"Failed to write {config_path}: {e}") from e
+
+
+def _read_package_artifact(relative_path: str) -> str:
+    """Read a shipped artifact from package data. Returns UTF-8 text."""
+    from importlib.resources import files
+
+    package = files("java_codebase_rag.install_data")
+    return package.joinpath(relative_path).read_text(encoding="utf-8")
+
+
+def deploy_artifacts(
+    hosts: list[HostConfig],
+    scope: Scope,
+    cwd: Path,
+    *,
+    non_interactive: bool,
+    mcp_command: str,
+) -> list[ArtifactResult]:
+    """Deploy artifacts (MCP config, skill, agent) to selected hosts.
+
+    Args:
+        hosts: List of HostConfig objects to deploy to
+        scope: Installation scope ("project" or "user")
+        cwd: Current working directory
+        non_interactive: If True, skip overwrite prompts
+        mcp_command: Resolved absolute path to java-codebase-rag-mcp
+
+    Returns:
+        List of ArtifactResult objects for each deployment
+    """
+    results = []
+
+    for host in hosts:
+        # Deploy MCP config
+        mcp_config_path = host.mcp_config_path(scope, cwd)
+        mcp_result = _deploy_mcp_config(
+            mcp_config_path,
+            host,
+            non_interactive=non_interactive,
+            mcp_command=mcp_command,
+        )
+        results.append(mcp_result)
+
+        # Deploy skill
+        skills_dir = host.skills_dir(scope, cwd)
+        skill_dest = skills_dir / "explore-codebase" / "SKILL.md"
+        skill_result = _deploy_file(
+            skill_dest,
+            "skills/explore-codebase/SKILL.md",
+            artifact_type="skill",
+            non_interactive=non_interactive,
+        )
+        results.append(skill_result)
+
+        # Deploy agent
+        agents_dir = host.agents_dir(scope, cwd)
+        agent_dest = agents_dir / "explorer-rag-enhanced.md"
+        agent_result = _deploy_file(
+            agent_dest,
+            "agents/explorer-rag-enhanced.md",
+            artifact_type="agent",
+            non_interactive=non_interactive,
+        )
+        results.append(agent_result)
+
+    return results
+
+
+def _deploy_mcp_config(
+    config_path: Path,
+    host: HostConfig,
+    *,
+    non_interactive: bool,
+    mcp_command: str,
+) -> ArtifactResult:
+    """Deploy MCP config file."""
+    try:
+        # Ensure parent directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Check writability
+        if not _is_writable(config_path.parent):
+            return ArtifactResult(
+                path=config_path,
+                success=False,
+                error=f"Directory not writable: {config_path.parent}",
+            )
+
+        # Merge config (returns True if updated, False if already current)
+        merge_mcp_config(config_path, host, mcp_command=mcp_command)
+        return ArtifactResult(path=config_path, success=True, error=None)
+    except ValueError as e:
+        return ArtifactResult(path=config_path, success=False, error=str(e))
+    except Exception as e:
+        return ArtifactResult(path=config_path, success=False, error=str(e))
+
+
+def _deploy_file(
+    dest_path: Path,
+    package_relative_path: str,
+    *,
+    artifact_type: str,
+    non_interactive: bool,
+) -> ArtifactResult:
+    """Deploy a single file from package data to destination."""
+    try:
+        # Ensure parent directory exists
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Check writability
+        if not _is_writable(dest_path.parent):
+            return ArtifactResult(
+                path=dest_path,
+                success=False,
+                error=f"Directory not writable: {dest_path.parent}",
+            )
+
+        # Read package data
+        content = _read_package_artifact(package_relative_path)
+
+        # Check if file exists
+        if dest_path.is_file():
+            # Check if content is identical
+            existing_content = dest_path.read_text(encoding="utf-8")
+            if content == existing_content:
+                return ArtifactResult(path=dest_path, success=True, error=None)
+
+            # File exists with different content - prompt for overwrite
+            if non_interactive:
+                # Skip in non-interactive mode
+                return ArtifactResult(
+                    path=dest_path,
+                    success=False,
+                    error="File exists (skipped in non-interactive mode)",
+                )
+
+            # Interactive: prompt for overwrite
+            choice = prompt(
+                "select",
+                f"{artifact_type.capitalize()} file exists at {dest_path}",
+                choices=[
+                    {"name": "Overwrite", "value": "overwrite"},
+                    {"name": "Skip", "value": "skip"},
+                    {"name": "Abort", "value": "abort"},
+                ],
+            )
+
+            if choice == "skip":
+                return ArtifactResult(
+                    path=dest_path,
+                    success=False,
+                    error="Skipped by user",
+                )
+            elif choice == "abort":
+                raise SystemExit(2)
+
+        # Write file
+        dest_path.write_text(content, encoding="utf-8")
+        return ArtifactResult(path=dest_path, success=True, error=None)
+    except SystemExit:
+        raise
+    except Exception as e:
+        return ArtifactResult(path=dest_path, success=False, error=str(e))
+
+
+def _is_writable(path: Path) -> bool:
+    """Check if a directory is writable."""
+    try:
+        test_file = path / ".write_test_java_codebase_rag"
+        test_file.touch()
+        test_file.unlink()
+        return True
+    except (OSError, IOError):
+        return False
+
+
+def generate_yaml_config(
+    source_root: Path,
+    model: str,
+    microservice_roots: list[str] | None,
+    existing_yaml: dict | None,
+) -> str:
+    """Generate .java-codebase-rag.yml content from installer answers.
+
+    Args:
+        source_root: Source root directory
+        model: Embedding model path or "auto"
+        microservice_roots: List of microservice roots (None means all)
+        existing_yaml: Existing YAML data for re-run update mode
+
+    Returns:
+        YAML configuration string
+    """
+    # Start with existing YAML or empty dict
+    config = existing_yaml.copy() if existing_yaml else {}
+
+    # Write microservice_roots only if subset selected
+    if microservice_roots:
+        config["microservice_roots"] = microservice_roots
+    elif "microservice_roots" in config:
+        # Remove if not needed (was set before but user wants all)
+        del config["microservice_roots"]
+
+    # Write embedding.model only if not auto
+    if model != "auto":
+        if "embedding" not in config:
+            config["embedding"] = {}
+        config["embedding"]["model"] = model
+    elif "embedding" in config and "model" in config["embedding"]:
+        # Remove model if using auto
+        if config["embedding"] == {"model": model}:
+            del config["embedding"]
+        else:
+            config["embedding"].pop("model", None)
+
+    # Keys NOT written by installer (preserved if present):
+    # - source_root (config.py resolves from walk-up discovery)
+    # - index_dir (config.py defaults to <source_root>/.java-codebase-rag)
+    # - embedding.device (user can add manually)
+    # - hints.enabled (defaults to True in config.py)
+    # - brownfield_overrides (user-managed)
+
+    return yaml.dump(config, default_flow_style=False, sort_keys=False)
+
+
+def update_gitignore(cwd: Path) -> None:
+    """Add .java-codebase-rag/ to .gitignore if not already present.
+
+    Args:
+        cwd: Current working directory
+    """
+    gitignore_path = cwd / ".gitignore"
+
+    # Check if git repo
+    if not (cwd / ".git").is_dir():
+        return
+
+    # Read existing .gitignore or create new
+    if gitignore_path.is_file():
+        lines = gitignore_path.read_text(encoding="utf-8").splitlines()
+    else:
+        lines = []
+
+    # Check for pattern (with or without trailing slash)
+    pattern_to_check = ".java-codebase-rag"
+    already_present = any(
+        line.strip().rstrip("/") == pattern_to_check or line.strip() == f"{pattern_to_check}/"
+        for line in lines
+    )
+
+    if not already_present:
+        lines.append("")
+        lines.append("# java-codebase-rag index directory")
+        lines.append(".java-codebase-rag/")
+        gitignore_path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def run_init_if_needed(
+    source_root: Path,
+    index_dir: Path,
+    model: str,
+    *,
+    non_interactive: bool,
+    quiet: bool,
+) -> bool:
+    """Run init if index directory has no artifacts. Return True if init was run.
+
+    Args:
+        source_root: Source root directory
+        index_dir: Index directory path
+        model: Embedding model path or "auto"
+        non_interactive: If True, suppress prompts
+        quiet: If True, suppress output
+
+    Returns:
+        True if init was run, False if skipped
+    """
+    from java_codebase_rag.config import (
+        index_dir_has_existing_artifacts,
+        resolve_operator_config,
+    )
+    from java_codebase_rag.pipeline import run_build_ast_graph, run_cocoindex_update
+
+    has_existing, _ = index_dir_has_existing_artifacts(index_dir)
+    if has_existing:
+        print("Index already exists. Run `java-codebase-rag reprocess` to rebuild.")
+        return False
+
+    print("Creating index...")
+    cfg = resolve_operator_config(
+        source_root=source_root,
+        cli_index_dir=None,  # use default (<source_root>/.java-codebase-rag)
+        cli_embedding_model=model if model != "auto" else None,
+    )
+    cfg.apply_to_os_environ()
+
+    env = cfg.subprocess_env()
+
+    # Run CocoIndex update
+    coco = run_cocoindex_update(env, full_reprocess=False, quiet=quiet)
+    if coco.returncode != 0:
+        print(f"Error: CocoIndex update failed with code {coco.returncode}")
+        return False
+
+    # Run AST graph build
+    g = run_build_ast_graph(
+        source_root=cfg.source_root,
+        kuzu_path=cfg.kuzu_path,
+        verbose=not quiet,
+        quiet=quiet,
+        env=env,
+    )
+    if g.returncode != 0:
+        print(f"Error: AST graph build failed with code {g.returncode}")
+        return False
+
+    print("Index created successfully.")
+    return True
+
+
+def handle_rerun(cwd: Path, *, non_interactive: bool) -> dict | None:
+    """If .java-codebase-rag.yml exists, offer update/fresh-start. Return existing YAML data or None.
+
+    Args:
+        cwd: Current working directory
+        non_interactive: If True, default to "Update" mode
+
+    Returns:
+        Parsed existing YAML data if updating, None if starting fresh
+    """
+    config_path = cwd / ".java-codebase-rag.yml"
+
+    if not config_path.is_file():
+        return None
+
+    try:
+        with open(config_path, "r") as f:
+            existing_config = yaml.safe_load(f) or {}
+    except yaml.YAMLError as e:
+        print(f"Warning: Failed to parse existing config: {e}")
+        return None
+
+    if non_interactive:
+        # Default to update mode in non-interactive
+        print(f"Found existing config at {config_path}")
+        return existing_config
+
+    # Interactive: show current values and ask
+    print(f"Found existing config at {config_path}")
+    print("Current configuration:")
+    for key, value in existing_config.items():
+        print(f"  {key}: {value}")
+
+    choice = prompt(
+        "select",
+        "Choose an action:",
+        choices=[
+            {"name": "Update (keep existing values)", "value": "update"},
+            {"name": "Start fresh (new config)", "value": "fresh"},
+            {"name": "Abort", "value": "abort"},
+        ],
+    )
+
+    if choice == "abort":
+        raise SystemExit(2)
+    elif choice == "fresh":
+        return None
+    else:  # update
+        return existing_config
+
+
+def detect_configured_hosts(cwd: Path) -> list[tuple[HostConfig, str]]:
+    """Scan project + user config files for java-codebase-rag MCP entries.
+
+    Args:
+        cwd: Current working directory (for project-scope configs)
+
+    Returns:
+        List of (host_config, scope) tuples where scope is "project" or "user"
+    """
+    detected = []
+
+    # Check all hosts in both project and user scopes
+    for host_name, host_config in HOSTS.items():
+        # Check project scope
+        project_mcp_path = host_config.mcp_config_path("project", cwd)
+        if _has_java_codebase_rag_entry(project_mcp_path):
+            detected.append((host_config, "project"))
+
+        # Check user scope
+        user_mcp_path = host_config.mcp_config_path("user", cwd)
+        if _has_java_codebase_rag_entry(user_mcp_path):
+            detected.append((host_config, "user"))
+
+    return detected
+
+
+def _has_java_codebase_rag_entry(config_path: Path) -> bool:
+    """Check if MCP config file has a java-codebase-rag entry.
+
+    Args:
+        config_path: Path to MCP config file
+
+    Returns:
+        True if file exists and contains java-codebase-rag in mcpServers
+    """
+    if not config_path.is_file():
+        return False
+
+    try:
+        with open(config_path, "r") as f:
+            config = json.load(f)
+    except (json.JSONDecodeError, IOError, OSError):
+        return False
+
+    mcp_servers = config.get("mcpServers", {})
+    return _MCP_SERVER_NAME in mcp_servers
+
+
+def refresh_artifacts(
+    host: HostConfig,
+    scope: str,
+    cwd: Path,
+    *,
+    force: bool,
+    dry_run: bool,
+) -> list[ArtifactResult]:
+    """Overwrite skill and agent files from package data. Skip MCP if entry is correct.
+
+    Args:
+        host: HostConfig for the agent host
+        scope: Installation scope ("project" or "user")
+        cwd: Current working directory
+        force: If True, overwrite all files even if matching
+        dry_run: If True, print changes without writing
+
+    Returns:
+        List of ArtifactResult objects for each artifact
+    """
+    results = []
+
+    # Refresh skill file
+    skills_dir = host.skills_dir(scope, cwd)
+    skill_dest = skills_dir / "explore-codebase" / "SKILL.md"
+    skill_result = _refresh_file(
+        skill_dest,
+        "skills/explore-codebase/SKILL.md",
+        artifact_type="skill",
+        force=force,
+        dry_run=dry_run,
+    )
+    results.append(skill_result)
+
+    # Refresh agent file
+    agents_dir = host.agents_dir(scope, cwd)
+    agent_dest = agents_dir / "explorer-rag-enhanced.md"
+    agent_result = _refresh_file(
+        agent_dest,
+        "agents/explorer-rag-enhanced.md",
+        artifact_type="agent",
+        force=force,
+        dry_run=dry_run,
+    )
+    results.append(agent_result)
+
+    # Refresh MCP config (update command path if needed)
+    mcp_config_path = host.mcp_config_path(scope, cwd)
+    mcp_result = _refresh_mcp_config(mcp_config_path, host, force=force, dry_run=dry_run)
+    results.append(mcp_result)
+
+    return results
+
+
+def _refresh_file(
+    dest_path: Path,
+    package_relative_path: str,
+    *,
+    artifact_type: str,
+    force: bool,
+    dry_run: bool,
+) -> ArtifactResult:
+    """Refresh a single file from package data.
+
+    Args:
+        dest_path: Destination file path
+        package_relative_path: Path relative to install_data
+        artifact_type: Type of artifact (for error messages)
+        force: If True, overwrite even if matching
+        dry_run: If True, print without writing
+
+    Returns:
+        ArtifactResult with success status
+    """
+    try:
+        # Read package data
+        package_content = _read_package_artifact(package_relative_path)
+
+        # Check if file exists
+        if dest_path.is_file():
+            existing_content = dest_path.read_text(encoding="utf-8")
+
+            # Skip if content matches and not forcing
+            if package_content == existing_content and not force:
+                return ArtifactResult(path=dest_path, success=True, error=None)
+
+            # Content differs or force mode
+            if dry_run:
+                print(f"Would update {artifact_type} file at {dest_path}")
+                return ArtifactResult(path=dest_path, success=True, error=None)
+
+        elif dry_run:
+            print(f"Would create {artifact_type} file at {dest_path}")
+            return ArtifactResult(path=dest_path, success=True, error=None)
+
+        # Ensure parent directory exists
+        if not dry_run:
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Check writability
+            if not _is_writable(dest_path.parent):
+                return ArtifactResult(
+                    path=dest_path,
+                    success=False,
+                    error=f"Directory not writable: {dest_path.parent}",
+                )
+
+        # Write file (skip in dry_run mode)
+        if not dry_run:
+            dest_path.write_text(package_content, encoding="utf-8")
+            print(f"Updated {artifact_type} file at {dest_path}")
+
+        return ArtifactResult(path=dest_path, success=True, error=None)
+
+    except Exception as e:
+        return ArtifactResult(path=dest_path, success=False, error=str(e))
+
+
+def _refresh_mcp_config(
+    config_path: Path,
+    host: HostConfig,
+    *,
+    force: bool,
+    dry_run: bool,
+) -> ArtifactResult:
+    """Refresh MCP config entry (update command path if needed).
+
+    Args:
+        config_path: Path to MCP config file
+        host: HostConfig for the agent host
+        force: If True, update even if matching
+        dry_run: If True, print without writing
+
+    Returns:
+        ArtifactResult with success status
+    """
+    try:
+        # Resolve current MCP command path
+        # Catch SystemExit because resolve_mcp_command raises it when binary not found
+        try:
+            mcp_command = resolve_mcp_command(non_interactive=True)
+        except SystemExit:
+            return ArtifactResult(
+                path=config_path,
+                success=False,
+                error="java-codebase-rag-mcp not found on PATH",
+            )
+
+        # Prepare new entry
+        new_entry = {"command": mcp_command, "type": "stdio"}
+
+        # Read existing config
+        if config_path.is_file():
+            try:
+                with open(config_path, "r") as f:
+                    config = json.load(f)
+            except json.JSONDecodeError as e:
+                return ArtifactResult(
+                    path=config_path,
+                    success=False,
+                    error=f"Failed to parse {config_path}: {e}",
+                )
+        else:
+            config = {}
+
+        # Ensure mcpServers key exists
+        if "mcpServers" not in config:
+            config["mcpServers"] = {}
+
+        existing_entry = config["mcpServers"].get(_MCP_SERVER_NAME)
+
+        # Check if entry already matches (skip unless force)
+        if existing_entry == new_entry and not force:
+            return ArtifactResult(path=config_path, success=True, error=None)
+
+        # Entry differs or force mode
+        if dry_run:
+            print(f"Would update MCP config at {config_path}")
+            return ArtifactResult(path=config_path, success=True, error=None)
+
+        # Merge/update entry
+        config["mcpServers"][_MCP_SERVER_NAME] = new_entry
+
+        # Ensure parent directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Check writability
+        if not _is_writable(config_path.parent):
+            return ArtifactResult(
+                path=config_path,
+                success=False,
+                error=f"Directory not writable: {config_path.parent}",
+            )
+
+        # Write atomically
+        tmp_name = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                dir=config_path.parent,
+                prefix=f".{config_path.name}.",
+                delete=False,
+            ) as tmp:
+                json.dump(config, tmp, indent=2)
+                tmp.flush()
+                os.fsync(tmp.fileno())
+                tmp_name = tmp.name
+
+            # Atomic rename
+            os.rename(tmp_name, config_path)
+            print(f"Updated MCP config at {config_path}")
+            return ArtifactResult(path=config_path, success=True, error=None)
+
+        except (IOError, OSError) as e:
+            if tmp_name:
+                try:
+                    os.unlink(tmp_name)
+                except OSError:
+                    pass
+            raise RuntimeError(f"Failed to write {config_path}: {e}") from e
+
+    except SystemExit as e:
+        # Catch SystemExit from resolve_mcp_command and other exits
+        return ArtifactResult(path=config_path, success=False, error=f"Command failed: {e.code}")
+    except Exception as e:
+        return ArtifactResult(path=config_path, success=False, error=str(e))
+
+
+def run_update(
+    *,
+    force: bool,
+    dry_run: bool,
+    cwd: Path | None = None,
+) -> int:
+    """Run the update pipeline. Returns exit code.
+
+    Args:
+        force: If True, overwrite all artifacts even if matching
+        dry_run: If True, print changes without writing
+        cwd: Current working directory (defaults to Path.cwd())
+
+    Returns:
+        Exit code (0=success, 1=partial, 2=fatal)
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+    cwd = cwd.resolve()
+
+    # Detect configured hosts
+    configured_hosts = detect_configured_hosts(cwd)
+
+    if not configured_hosts:
+        print("No configured agent hosts found.")
+        print("Run `java-codebase-rag install` first.")
+        return EXIT_FATAL
+
+    print(f"Found {len(configured_hosts)} configured host(s).")
+
+    # Refresh artifacts for each host
+    all_results = []
+    for host_config, scope in configured_hosts:
+        print(f"\nRefreshing {host_config.name} ({scope} scope)...")
+        results = refresh_artifacts(host_config, scope, cwd, force=force, dry_run=dry_run)
+        all_results.extend(results)
+
+    # Check for partial failures
+    partial_failures = [r for r in all_results if not r.success]
+    has_artifact_failures = len(partial_failures) > 0
+    if partial_failures:
+        print("\nWarning: Some artifacts failed to update:")
+        for r in partial_failures:
+            print(f"  {r.path}: {r.error}")
+
+    # Check if index exists
+    from java_codebase_rag.config import (
+        discover_project_root,
+        index_dir_has_existing_artifacts,
+        resolve_operator_config,
+    )
+    from java_codebase_rag.pipeline import run_cocoindex_update
+
+    project_root = discover_project_root(cwd)
+    if project_root is None:
+        print("\nNo project configuration found (.java-codebase-rag.yml).")
+        print("Skipping index update.")
+        return EXIT_PARTIAL if has_artifact_failures else EXIT_SUCCESS
+
+    # Resolve configuration
+    try:
+        cfg = resolve_operator_config(source_root=project_root, cli_index_dir=None)
+        index_dir = cfg.index_dir
+    except Exception as e:
+        print(f"\nWarning: Failed to resolve configuration: {e}")
+        print("Skipping index update.")
+        return EXIT_PARTIAL if has_artifact_failures else EXIT_SUCCESS
+
+    # Check if index has existing artifacts
+    index_exists, _ = index_dir_has_existing_artifacts(index_dir)
+
+    if not index_exists:
+        print("\nNo index found.")
+        print("Run `java-codebase-rag install` to create one.")
+        return EXIT_PARTIAL if has_artifact_failures else EXIT_SUCCESS
+
+    # Run increment (LanceDB catch-up)
+    if not dry_run:
+        print("\nUpdating index (incremental LanceDB update)...")
+        cfg.apply_to_os_environ()
+        env = cfg.subprocess_env()
+
+        coco = run_cocoindex_update(env, full_reprocess=False, quiet=True)
+        if coco.returncode != 0:
+            print(f"Error: Index update failed with code {coco.returncode}")
+            return 1
+
+        # Print graph staleness warning
+        from java_codebase_rag.cli import _INCREMENT_WARNING_LINES
+        print("\n" + "\n".join(_INCREMENT_WARNING_LINES))
+    else:
+        print("\nWould run incremental index update.")
+
+    # Print summary
+    print("\nUpdate complete.")
+    successful = [r for r in all_results if r.success]
+    print(f"Updated {len(successful)} artifact(s).")
+
+    return 1 if has_artifact_failures else 0
+
+
+def run_install(
+    *,
+    non_interactive: bool,
+    agents: list[str] | None,
+    scope: str | None,
+    model: str | None,
+    source_root: Path | None = None,
+    quiet: bool = False,
+) -> int:
+    """Run the install pipeline. Returns exit code.
+
+    Args:
+        non_interactive: If True, skip all prompts
+        agents: List of agent names from CLI flags
+        scope: Scope from CLI flag
+        model: Model from CLI flag
+        source_root: Source root path (defaults to cwd if None)
+        quiet: If True, suppress output
+
+    Returns:
+        Exit code (0=success, 1=partial, 2=fatal)
+    """
+    # Stage 0: Determine source root
+    cwd = Path.cwd() if source_root is None else source_root
+    cwd = cwd.resolve()
+
+    # Stage 0.5: Check for existing config (re-run detection)
+    existing_config = handle_rerun(cwd, non_interactive=non_interactive)
+
+    # Stage 1: Java source detection (with confirmation in interactive mode)
+    source_root = confirm_source_root(cwd, non_interactive=non_interactive)
+
+    # Detect Java directories
+    try:
+        java_dirs = detect_java_directories(source_root)
+    except SystemExit as e:
+        return e.code
+
+    # Stage 2: Embedding model
+    resolved_model = resolve_model(model, non_interactive=non_interactive)
+
+    # Stage 3-4: Agent host + scope selection
+    try:
+        hosts = select_hosts(non_interactive=non_interactive, cli_agents=agents)
+        selected_scope = select_scope(non_interactive=non_interactive, cli_scope=scope)
+    except SystemExit as e:
+        return e.code
+
+    # Stage 5: Artifact deployment
+    mcp_command = resolve_mcp_command(non_interactive=non_interactive)
+    results = deploy_artifacts(
+        hosts,
+        selected_scope,
+        source_root,
+        non_interactive=non_interactive,
+        mcp_command=mcp_command,
+    )
+
+    # Check for partial failures
+    partial_failures = [r for r in results if not r.success]
+    if partial_failures:
+        print("Warning: Some artifacts failed to deploy:")
+        for r in partial_failures:
+            print(f"  {r.path}: {r.error}")
+        if all(
+            r.success
+            for r in results
+            if r.path.suffix in [".json", ".yml", ".yaml"]
+        ):
+            # MCP configs succeeded - non-critical
+            print("Continuing (MCP configs deployed successfully)...")
+        else:
+            # Critical failures
+            return 1
+
+    # Stage 6: Index + finish
+    # Generate YAML config
+    yaml_content = generate_yaml_config(
+        source_root,
+        resolved_model,
+        microservice_roots=[str(d) for d in java_dirs] if len(java_dirs) > 1 else None,
+        existing_yaml=existing_config,
+    )
+
+    # Write YAML config
+    config_path = source_root / ".java-codebase-rag.yml"
+    config_path.write_text(yaml_content, encoding="utf-8")
+
+    # Update .gitignore
+    update_gitignore(source_root)
+
+    if not quiet:
+        print("Configuration written to", config_path)
+
+    # Run init if index directory is empty
+    index_dir = (source_root / ".java-codebase-rag").resolve()
+    run_init_if_needed(
+        source_root,
+        index_dir,
+        resolved_model,
+        non_interactive=non_interactive,
+        quiet=quiet,
+    )
+
+    return 0