From 585ea7ffa7c3529a5d922bf414636f58746ce3df Mon Sep 17 00:00:00 2001 From: Dmitry Teryaev Date: Mon, 8 Jun 2026 15:52:35 +0300 Subject: [PATCH] docs: document CLI install/update commands and move completed proposal Move CLI-INSTALL-PROPOSE.md and PLAN-CLI-INSTALL.md to completed/ now that both PR-I1 (install) and PR-I2 (update) are implemented. Update README.md and JAVA-CODEBASE-RAG-CLI.md to document the new interactive setup wizard (java-codebase-rag install) and the post-upgrade refresh command (java-codebase-rag update). Co-Authored-By: Claude Opus 4.7 --- README.md | 31 +++++++- docs/JAVA-CODEBASE-RAG-CLI.md | 74 +++++++++++++++++++ .../{active => completed}/PLAN-CLI-INSTALL.md | 0 .../CLI-INSTALL-PROPOSE.md | 0 4 files changed, 104 insertions(+), 1 deletion(-) rename plans/{active => completed}/PLAN-CLI-INSTALL.md (100%) rename propose/{active => completed}/CLI-INSTALL-PROPOSE.md (100%) diff --git a/README.md b/README.md index f880d63..35cf8a5 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,31 @@ pip install java-codebase-rag Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups. The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase`. +### Interactive setup (recommended) + +Run `java-codebase-rag install` from your Java project root to launch an interactive setup wizard that: + +1. Detects Java source directories (Maven/Gradle modules) +2. Configures the embedding model (auto-downloads ~90MB or uses a local path) +3. Selects agent hosts (Claude Code, Qwen Code, GigaCode) +4. Deploys MCP registration, skill, and agent artifacts +5. Generates `.java-codebase-rag.yml` configuration +6. Runs `init` to build the index + +```bash +# Interactive mode +java-codebase-rag install + +# Non-interactive mode (for CI/automation) +java-codebase-rag install --non-interactive --agent claude-code +``` + +After `pip install --upgrade java-codebase-rag`, run `java-codebase-rag update` to refresh shipped artifacts. + +### Manual registration + +If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) for the full CLI reference. + > **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change. --- @@ -84,7 +109,9 @@ If vector hits come back and graph expansion adds neighbor symbols, the install ## Wire into an MCP host -### Claude Code +> **Quick setup:** Run `java-codebase-rag install` from your Java project root. The interactive wizard handles MCP registration, skill deployment, and configuration for Claude Code, Qwen Code, and GigaCode in one step. + +### Claude Code (manual) With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped: @@ -167,6 +194,8 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi | Group | Subcommand | What it does | |---|---|---| +| Setup | `install` | Interactive setup wizard: config, MCP registration, skill/agent deployment, indexing. | +| Setup | `update` | Refresh shipped artifacts (skill, agent, MCP entry) after pip upgrade. | | Lifecycle | `init` | First-time index. Refuses if artifacts already exist. | | Lifecycle | `increment` | CocoIndex catch-up + incremental Kuzu update. `--vectors-only` for Lance only. | | Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. | diff --git a/docs/JAVA-CODEBASE-RAG-CLI.md b/docs/JAVA-CODEBASE-RAG-CLI.md index d95a62a..7df7c3f 100644 --- a/docs/JAVA-CODEBASE-RAG-CLI.md +++ b/docs/JAVA-CODEBASE-RAG-CLI.md @@ -17,6 +17,80 @@ If `java-codebase-rag` is missing, run the module entrypoint: .venv/bin/python -m java_codebase_rag.cli --help ``` +## Setup commands + +### `install` + +Interactive setup wizard that walks users through Java source detection, embedding model selection, agent host configuration, artifact deployment, and YAML config generation. Use `--non-interactive` for CI/automation. + +```bash +# Interactive mode +java-codebase-rag install + +# Non-interactive mode (requires at least one --agent) +java-codebase-rag install --non-interactive --agent claude-code +java-codebase-rag install --non-interactive --agent claude-code --agent qwen-code + +# With custom embedding model +java-codebase-rag install --model /path/to/model + +# User-scope installation (available globally) +java-codebase-rag install --scope user +``` + +**Flags:** +- `--non-interactive` — Run without prompts (requires `--agent`). +- `--agent {claude-code,qwen-code,gigacode}` — Agent host to configure (can be passed multiple times). +- `--scope {project,user}` — Installation scope (default: `project`). Project scope writes to `./` in the project repo; user scope writes to `~/./` (globally available). +- `--model MODEL` — Embedding model path or `auto` (default: `auto`, downloads `sentence-transformers/all-MiniLM-L6-v2` on first run). + +**Exit codes:** +- `0` — Success (all stages completed). +- `1` — Partial success (some stages failed). Re-run `install` to retry failed stages. +- `2` — Fatal error (no Java files found, required flag missing). + +**Stages:** +1. Java source detection — Maven/Gradle module roots. +2. Embedding model selection — auto-download or local path. +3. Agent host selection — Claude Code, Qwen Code, GigaCode (multi-select). +4. Install scope — project or user. +5. MCP entrypoint resolution + artifact deployment — config, skill, agent files. +6. Index + finish — YAML generation, `.gitignore` update, `init`. + +**Re-running `install`:** If `.java-codebase-rag.yml` exists, the installer shows current values and offers "Update" (pre-filled) or "Start fresh". Existing MCP entries are updated in-place (merged, not duplicated). Skill/agent files trigger overwrite confirmation. + +### `update` + +Post-upgrade refresh: overwrites skill and agent files with the latest shipped versions and updates the MCP command path. Requires a prior `install` run. + +```bash +# Refresh after pip upgrade +pip install --upgrade java-codebase-rag +java-codebase-rag update + +# Preview changes without writing +java-codebase-rag update --dry-run + +# Force overwrite all artifacts +java-codebase-rag update --force +``` + +**Flags:** +- `--force` — Overwrite all artifacts even if content matches. +- `--dry-run` — Print changes without writing files. + +**Behavior:** +- Detects previously configured agent hosts (scans both project-level and user-level config files). +- Refreshes skill and agent files (versioned assets from the package). +- Updates MCP entrypoint path if `java-codebase-rag-mcp` has moved. +- Runs `increment` on the index if it exists (LanceDB catch-up). Prints graph staleness warning. +- Skips MCP config if the entry already exists and is correct. + +**Exit codes:** +- `0` — Success. +- `1` — Partial failure (some artifacts failed to write). +- `2` — No configured hosts found. + ## Output mode - **TTY:** human-readable `pprint` of the payload on stdout (except **successful selective `reprocess`** with `--vectors-only` / `--graph-only`, which prints `Rebuilt:` / `Skipped:` lines instead of dumping the full dict). diff --git a/plans/active/PLAN-CLI-INSTALL.md b/plans/completed/PLAN-CLI-INSTALL.md similarity index 100% rename from plans/active/PLAN-CLI-INSTALL.md rename to plans/completed/PLAN-CLI-INSTALL.md diff --git a/propose/active/CLI-INSTALL-PROPOSE.md b/propose/completed/CLI-INSTALL-PROPOSE.md similarity index 100% rename from propose/active/CLI-INSTALL-PROPOSE.md rename to propose/completed/CLI-INSTALL-PROPOSE.md