Proposal: CLI install command with interactive setup wizard

[HumanBean17]

Summary

This PR proposes a new java-codebase-rag install command that walks users through a 6-stage interactive setup wizard, eliminating manual config file editing and MCP registration steps.

Status: Proposal — not yet implemented. This PR defines the design and plan for implementation in subsequent PRs.

Problem Statement

Users installing java-codebase-rag face multiple friction points that cause drop-off:

1. Config file creation — manually writing .java-codebase-rag.yml with correct keys and paths
2. MCP server registration — knowing the exact JSON format and file path for their agent host (.claude.json, .qwen/settings.json, .gigacode/settings.json)
3. Agent/skill deployment — copying skill files and agent files to host-specific directories
4. Project indexing — running init with correct flags after config is set up
5. Embedding model — understanding whether to provide a local path or let it auto-download

These steps are documented across multiple files. Non-technical users give up before completing setup.

Proposed Solution

Two new subcommands

java-codebase-rag install [--non-interactive] [--agent {claude-code|qwen-code|gigacode}]... [--scope {user|project}] [--model {auto|<path>}]
java-codebase-rag update [--force] [--dry-run]

Key Design Decisions

Multi-host by default

• Stage 3 uses a checkbox with all 3 agent hosts pre-selected
• Users configure multiple agent hosts (Claude Code, Qwen Code, GigaCode) in a single run
• Non-interactive mode accepts multiple --agent flags

Module-level detection

• Detects Maven/Gradle modules by finding pom.xml or build.gradle* files
• If root has build file: shows only . (entire project as one unit)
• If root has no build file: shows immediate children with build files (microservice roots)
• Prevents overwhelming users with nested Maven modules in large projects

Exit codes

• 0: Success (all stages completed)
• 1: Partial success (failed stages listed, re-run skips completed stages)
• 2: Fatal error (no Java files, required flag missing)

Implementation Sequence

PR-I1: install subcommand

• New java_codebase_rag/installer.py module
• prompt() TTY-abstraction helper
• Host config mapping for 3 agent hosts
• MCP JSON merge logic (preserves existing keys)
• YAML config generation
• Artifact deployment (skill, agent, MCP config)
• .gitignore auto-update
• Integration tests

PR-I2: update subcommand

• Host detection from project/user config files
• Artifact refresh logic
• --force and --dry-run flags
• Graph staleness warning after increment

See propose/completed/CLI-INSTALL-PROPOSE.md for full details and plans/active/PLAN-CLI-INSTALL.md for implementation plan.

Changes in this PR

• ✅ Add proposal document (propose/completed/CLI-INSTALL-PROPOSE.md)
• ✅ Add implementation plan (plans/active/PLAN-CLI-INSTALL.md)
• ✅ Multi-host support (configure multiple agent hosts in one run)
• ✅ Simplified module detection (root build file → single unit)
• ✅ MCP entrypoint resolution with absolute path
• ✅ Source root interactive confirmation
• ✅ Updated validation, re-run semantics, and exit codes

Test plan

Test cases defined in the plan:

• 53 unit tests covering host config mapping, MCP merge, YAML generation, prompt helper, artifact deployment, re-run detection
• Integration tests for non-interactive mode (single-host and multi-host)
• Tests gated behind JAVA_CODEBASE_RAG_RUN_HEAVY=1 for end-to-end validation

Out of scope

• Claude Desktop config editing (different location, different format)
• IDE-specific integrations (VS Code, JetBrains)
• Docker / containerized setup
• Python version checking or virtual environment creation
• microservice_roots advanced configuration (manual YAML editing for complex layouts)

🤖 Generated with Claude Code

[HumanBean17]

Review: Proposal + Plan

The design is solid — multi-host by default, build-file detection over .java scanning, resolved absolute paths in MCP config. These are the right calls. A few things to clean up before merging so the implementing agent isn't working from contradictory sources:

Must-fix

1. Stale rich dependency in the active proposal. propose/active/CLI-INSTALL-PROPOSE.md still lists rich>=13.0 as a new dependency in the "Implementation stack" and "Scope" sections, but the plan's resolved decisions explicitly say "Not added. Reuse cli_format.py." The proposal should match.

2. Duplicate test feat: B2b HTTP_CALLS + ASYNC_CALLS extractor (PR-D1) #12 in the plan. test_yaml_generation_does_not_write_source_root_or_index_dir and test_mcp_merge_adds_to_empty are both numbered 12. This causes off-by-one drift in all subsequent numbers and makes the step-to-test mapping unreliable.

3. Contradiction: nested module detection. The active proposal's test list says "service-a/api/pom.xml → relative path service-a/api detected", but the plan explicitly states "No recursive descent — only immediate children are checked in Case B." The plan is correct — the proposal's test expectation is stale.

4. propose/completed/CLI-INSTALL-PROPOSE.md shouldn't exist yet. Per AGENTS.md: "Move propose into propose/completed/ once the whole effort is landed — not after each PR." Having identically-named files in both active/ and completed/ is confusing. Consider deleting the completed version (the active one supersedes it) or renaming it to make the relationship explicit.

Should-fix

5. Test numbering in the implementation step list is wrong. Step 7 says "Tests 44-48 pass" for select_hosts, but those tests are numbered 47-52. Step 9 says "Tests 40, 45-46, 50 pass" for deploy_artifacts, pulling in tests from unrelated functions. Reconcile after fixing the duplicate feat: B2b HTTP_CALLS + ASYNC_CALLS extractor (PR-D1) #12.

6. Open Questions still marked [TBD]. Both have "Recommended" answers that are resolved in the plan. Promote them to "Resolved design decisions" or remove.

7. update calls resolve_mcp_command(non_interactive=False). The plan's PR-I2 refresh_artifacts uses non_interactive=False, but update is described as "Non-interactive by default." If shutil.which fails during update, it would prompt — inconsistent. Use non_interactive=True with exit code 2, or document the exception.

Minor

8. Atomic write only for MCP config, not YAML. The plan specifies .tmp+rename for MCP config but not for .java-codebase-rag.yml. A crash mid-write could corrupt the YAML. Either apply consistently or acknowledge the omission.

9. run_init_if_needed couples to internal pipeline API. The plan calls resolve_operator_config, run_cocoindex_update, run_build_ast_graph directly. These may not be stable public API — worth noting whether this coupling is acceptable or if these need extraction.

---

Overall: good design, thorough test plan. The issues above are documentation/consistency problems, not design flaws — once cleaned up this is ready for implementation.

[HumanBean17]

Re-review: All previous issues fixed

Checked each item from the previous review against the updated diff:

#	Issue	Status
1	Stale rich dependency in proposal	Fixed — "New dependency: questionary>=2.0" only
2	Duplicate test #12	Fixed — sequential 1-54
3	Nested module detection contradiction	Fixed — test list no longer mentions nested detection
4	propose/completed/ file	Fixed — removed (3 → 2 files)
5	Test numbering in step list	Fixed — steps now match actual test numbers
6	Open Questions [TBD]	Fixed — "Resolved design decisions" section
7	update uses non_interactive=False	Fixed — now non_interactive=True

One remaining fix

The PR description still links to propose/completed/CLI-INSTALL-PROPOSE.md which no longer exists in this PR. Update to propose/active/CLI-INSTALL-PROPOSE.md.

LGTM otherwise — ready to merge after that one link fix.