dsh-codebase-chat 0.22.0 → 0.23.0

package/README.md

@@ -1,27 +1,20 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/shinzarou-eng/dsh-codebase-chat/main/docs/assets/logo.png" width="110" height="110" alt="dsh-codebase-chat logo">
-</p>
-
-<h1 align="center">dsh-codebase-chat</h1>
-
-<p align="center">
-  <strong>Local-first codebase intelligence — chat, audit, refactor, and report on any repository.</strong><br>
-  DeepSeek Harness plugin &nbsp;·&nbsp; standalone MCP server &nbsp;·&nbsp; CLI
+  <a href="https://shinzarou-eng.github.io/dsh-codebase-chat">
+    <img src="https://raw.githubusercontent.com/shinzarou-eng/dsh-codebase-chat/main/docs/assets/social-preview.png" alt="dsh-codebase-chat — Your codebase, fully understood" width="100%">
+  </a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/dsh-codebase-chat"><img src="https://img.shields.io/npm/v/dsh-codebase-chat?logo=npm&label=plugin&color=7cc7ff" alt="npm plugin"></a>
-  <a href="https://www.npmjs.com/package/dsh-codebase-chat-mcp"><img src="https://img.shields.io/npm/v/dsh-codebase-chat-mcp?logo=npm&label=mcp&color=b08cff" alt="npm mcp"></a>
-  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/blob/main/LICENSE"><img src="https://img.shields.io/github/license/shinzarou-eng/dsh-codebase-chat?color=97a3b0" alt="license"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-5fed83?logo=nodedotjs" alt="node >= 20"></a>
-  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-39c5cf" alt="MCP compatible"></a>
-  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/stargazers"><img src="https://img.shields.io/github/stars/shinzarou-eng/dsh-codebase-chat?style=social" alt="stars"></a>
+  <a href="https://www.npmjs.com/package/dsh-codebase-chat"><img src="https://img.shields.io/npm/v/dsh-codebase-chat?logo=npm&label=plugin&color=6ec2ff" alt="npm plugin"></a>
+  <a href="https://www.npmjs.com/package/dsh-codebase-chat-mcp"><img src="https://img.shields.io/npm/v/dsh-codebase-chat-mcp?logo=npm&label=mcp&color=a78bfa" alt="npm mcp"></a>
+  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/blob/main/LICENSE"><img src="https://img.shields.io/github/license/shinzarou-eng/dsh-codebase-chat?color=93a1b5" alt="license"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-4ade80?logo=nodedotjs" alt="node >= 20"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-22d3ee" alt="MCP compatible"></a>
 </p>
 
 <p align="center">
   <a href="https://shinzarou-eng.github.io/dsh-codebase-chat"><strong>Website</strong></a> ·
-  <a href="#quick-start">Quick start</a> ·
-  <a href="#tool-suite">Tools</a> ·
+  <a href="mcp/README.md">MCP docs</a> ·
   <a href="ROADMAP.md">Roadmap</a> ·
   <a href="CHANGELOG.md">Changelog</a> ·
   <a href="CONTRIBUTING.md">Contributing</a>
@@ -29,75 +22,133 @@
 
 <br>
 
+## Get started
+
+```bash
+npx dsh-codebase-chat-mcp setup
+```
+
+The wizard detects **Claude, Cursor, Windsurf and VS Code**, writes the MCP config, done.
+No JSON to edit — and **no API key**: in `promptOnly` mode your host model does the thinking.
+
+Other paths — DeepSeek Harness plugin · CLI · from source · manual config: **[Reference](#reference)**.
+
 <p align="center">
-  <img src="docs/assets/demo.gif" alt="dsh-codebase-chat CLI demo" width="820"><br>
-  <em>Real terminal output — <a href="docs/assets/demo-mcp.gif">MCP session</a> · <a href="docs/assets/demo-fr.gif">French mode</a></em>
+  <img src="docs/assets/demo.gif" alt="dsh-codebase-chat CLI demo" width="840"><br>
+  <em>Live terminal capture — <a href="docs/assets/demo-mcp.gif">MCP session</a> · <a href="docs/assets/demo-fr.gif">French mode</a></em>
 </p>
 
----
+## What a real session looks like
 
-## In plain words
+Run on this repository — the exact text the tools return:
 
-> **New here?** Point it at a folder of code on your computer. Ask questions in plain
-> language — *"How does login work?"*, *"Is there a hardcoded password?"*, *"What should
-> I fix first?"* — in French or English. Every answer cites the exact file and line it
-> came from, so you can verify it in seconds. Nothing is uploaded anywhere.
+```console
+$ npx dsh-codebase-chat --project . --health
 
-| Term | Meaning |
-| --- | --- |
-| **MCP server** | A plug format that lets AI assistants (Claude, Cursor…) use extra tools. Install once, your IDE can "see" your code. |
-| **Index** | Like the index at the back of a book — a map of every function and file, so answers are instant. |
-| **Prompt-only mode** | The tool prepares the context; your existing AI writes the answer. No extra API key, no extra cost. |
-| **Deterministic analysis** | Checks computed directly from your code — same input, same result, every time. No guessing. |
+== STATIC ANALYSIS — dsh-codebase-chat ==
+Health score: 52/100 (D) · 33 files analyzed · 65 local imports
 
-<details>
-<summary><strong>🇫🇷 En termes simples</strong></summary>
+● Circular dependencies (0)
+  none
 
-<br>
+● Unused files (candidates) (1)
+  lib/client.js
 
-Pointez-le vers un dossier de code sur votre ordinateur. Posez des questions en langage
-clair — *« Comment fonctionne la connexion ? », « Y a-t-il un mot de passe codé en dur ? »,
-« Que devrais-je réparer en premier ? »* — en français ou en anglais. Chaque réponse cite
-exactement le fichier et la ligne d'où elle vient, donc vous pouvez vérifier en quelques
-secondes. Rien n'est envoyé sur internet.
+● Unused exports (candidates) (45)
+  lib/cache.js:21 — cachePath
+  lib/index.js:2952 — normalizeLabels
+  lib/index.js:2952 — getProjectName
+  …
 
-</details>
+● Duplicate code blocks (2)
+  12 lines × 2 files — lib/index.js, src/project.ts
+  6 lines × 2 files — src/indexer.ts, src/retriever.ts
 
----
+● Complexity hotspots (13)
+  lib/index.js — score 418
+  src/analysis.ts — score 81
+  lib/client.js — score 55
+  …
+```
 
-## Why dsh-codebase-chat?
+```console
+$ npx dsh-codebase-chat --project . --search "health score computation"
 
-Most codebase assistants are slow, paywalled, or require uploading your source to the cloud.
-**dsh-codebase-chat** runs entirely on your machine: it indexes your repository, retrieves the
-chunks that matter, and assembles a **sourced prompt** — every answer comes back with
-`[source: file:line]` citations, confidence scores, and severity labels.
+--- src/analysis.ts :: formatHealthReportMd (FUNCTION) [source: src/analysis.ts:285-353] ---
+--- src/analysis.ts :: analyzeProject       (FUNCTION) [source: src/analysis.ts:149-232] ---
+--- src/analysis.ts :: HealthReport         (TYPE)     [source: src/analysis.ts:15-26]   ---
 
-- **Local-first** — indexing, retrieval, and prompt building never leave your machine.
-- **Bilingual** — every prompt, report, and UI string in French and English.
-- **Everywhere** — DeepSeek Harness plugin, standalone MCP server (Cursor, Claude, Windsurf…), and a plain CLI.
-- **Decision-grade output** — not just answers: CTO briefs, audits, TASKS.md plans, board reports.
+$ npx dsh-codebase-chat --project . --ask "how is the index cached?"
 
----
+> dsh-codebase-chat · prompt-only mode (no API key)
+> Chunks: 81 · Tokens: 59,934 → handed to the host model
+> Cite every technical claim with [source: relative/path:line].
+```
+
+`codebase_health` runs fully offline — deterministic, no LLM, same input → same score.
+Every answer from `codebase_chat` arrives with `[source: file:line]` receipts you can verify in seconds.
+
+## Why it wins
+
+| | Paste into a chat | Hosted assistant | **dsh-codebase-chat** |
+| --- | :-: | :-: | :-: |
+| Sees your **whole** repo, not one file | ❌ | ✅ | ✅ |
+| `[source: file:line]` citations | ❌ | ~ | ✅ |
+| Code stays on your machine | ❌ | ❌ | ✅ |
+| Inside Claude / Cursor / Windsurf | ❌ | ~ | ✅ |
+| Deterministic health score, no LLM | ❌ | ❌ | ✅ |
+| Free — no API key, no account | ~ | ❌ | ✅ |
+
+## How it works
+
+<p align="center">
+  <img src="docs/assets/how-it-works.png" alt="Pipeline: source → AST index → retrieval → briefing → host model → cited answer, all local-first" width="100%">
+</p>
+
+`/codebase-apply` writes safely — **dry-run** · **`.dsh-backups/`** before overwrite · **protected paths** · never outside the project.
+
+## The 12 tools
+
+| Understand | Decide | Act | Explore |
+| --- | --- | --- | --- |
+| `codebase_chat` | `codebase_intelligence` | `codebase_refactor` | `codebase_player` |
+| `codebase_search` | `codebase_audit` | `codebase_tasks` | `codebase_crea` |
+| `codebase_explain` | `codebase_report` | | |
+| `codebase_health` | `codebase_ceo` | | |
 
-## Quick start
+Same engine, three surfaces: **MCP tools** in your IDE, **slash commands** in DeepSeek Harness, **CLI flags** anywhere. Every tool takes `lang` (`fr`/`en`), `embed`, `promptOnly`, `maxTokens`.
 
-### Option A — DeepSeek Harness plugin
+## Reference
+
+<details>
+<summary><strong>Install — all paths</strong></summary>
+<br>
+
+**DeepSeek Harness plugin**
 
 ```bash
 dsh plugin --profile web add dsh-codebase-chat
-# without a global dsh install:
-npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-codebase-chat
 ```
 
-Then restart `dsh web`, open `http://127.0.0.1:3080` and click the **Codebase Pro** button in the sidebar.
+Then restart `dsh web` → `http://127.0.0.1:3080` → **Codebase Pro** button.
 
-### Option B — MCP server (Cursor, Claude, Windsurf…)
+**CLI**
 
 ```bash
-npx dsh-codebase-chat-mcp setup   # detects Claude/Cursor/Windsurf/VS Code and writes the config
+npx dsh-codebase-chat --project C:\my-app --ask "how is auth handled?"
+npx dsh-codebase-chat --project C:\my-app --health   # offline, no LLM
+npx dsh-codebase-chat --project C:\my-app --health --diff main   # only what changed
+npx dsh-codebase-chat --project C:\my-app --watch    # index stays hot while you code
 ```
 
-Or configure manually:
+**From source**
+
+```bash
+git clone https://github.com/shinzarou-eng/dsh-codebase-chat.git
+cd dsh-codebase-chat && pnpm install && pnpm build
+```
+
+**Manual MCP config**
 
 ```json
 {
@@ -110,58 +161,13 @@ Or configure manually:
 }
 ```
 
-> **No API key needed.** Without `DEEPSEEK_API_KEY` / `OPENAI_API_KEY`, the server runs in
-> `promptOnly` mode and hands the assembled context to your host model. See
-> [`mcp/README.md`](mcp/README.md) for direct-LLM configuration.
-
-### Option C — CLI
-
-```bash
-npx dsh-codebase-chat --project C:\my-app --ask "how is auth handled?"
-npx dsh-codebase-chat --project C:\my-app --search "rate limiting"
-npx dsh-codebase-chat --project C:\my-app --file src/auth.ts
-npx dsh-codebase-chat --project C:\my-app --stats
-npx dsh-codebase-chat --project C:\my-app --health   # deterministic static analysis, no LLM
-```
-
-`--health` runs entirely offline: circular dependencies, unused files/exports, duplicated
-blocks, complexity hotspots, and a health score — handy as a quick quality gate.
-
-The first run builds a cached index under `CODEBASE_CACHE_DIR`; subsequent runs are incremental.
-
-### From source
-
-```bash
-git clone https://github.com/shinzarou-eng/dsh-codebase-chat.git
-cd dsh-codebase-chat
-pnpm install && pnpm build
-```
+Without `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` the server runs `promptOnly`. Set either key for direct-LLM calls — see [`mcp/README.md`](mcp/README.md).
 
----
-
-## Tool suite
-
-Every capability is exposed as a DSH tool, a slash command, and an MCP tool.
+</details>
 
-| Tool | What it does |
-| --- | --- |
-| `codebase_chat` | Q&amp;A on your project with cited sources |
-| `codebase_search` | Find symbols, terms, and usages across the repo |
-| `codebase_explain` | Explain a file or symbol — fallback symbol search included |
-| `codebase_refactor` | Propose a concrete refactor with Before/After diff |
-| `codebase_intelligence` | Full CTO brief: architecture, debt, security, roadmap |
-| `codebase_audit` | Tech-debt and non-conformity scan with severity |
-| `codebase_report` | Strategic board report — SWOT, risks, opportunities |
-| `codebase_ceo` | One-page executive brief |
-| `codebase_tasks` | Generate a sprinted `TASKS.md` action plan |
-| `codebase_player` | UX / playthrough brief from a user's point of view |
-| `codebase_crea` | Creative and marketing angles extracted from the code |
-| `codebase_health` | **Deterministic** static analysis — circular deps, dead code, duplication, complexity, health score. No LLM needed |
-
-Common parameters: `projectPath`, `lang` (`fr`/`en`), `embed` (local semantic embeddings),
-`promptOnly` (MCP), `style` (reports).
-
-### Slash commands (DeepSeek Harness)
+<details>
+<summary><strong>Slash commands (DeepSeek Harness)</strong></summary>
+<br>
 
 ```powershell
 dsh --profile headless '/codebase "how is auth handled?" --project C:\my-app'
@@ -176,38 +182,11 @@ dsh --profile headless '/codebase-build --project C:\my-app'
 dsh --profile headless '/codebase-git --project C:\my-app'
 ```
 
----
-
-## How it works
-
-```mermaid
-graph LR
-  A[Query] --> B[Index]
-  B --> C[Retrieve]
-  C --> D[Prompt]
-  D --> E[LLM]
-  E --> F[Cited answer]
-```
-
-1. **Index** — real AST extraction (Babel for JS/TS, tree-sitter WASM for Python, Go, Rust, Java, C# and PHP, regex fallback elsewhere) builds a symbol-level index, cached on disk and refreshed incrementally (mtime/size based — no full re-reads).
-2. **Retrieve** — lexical scoring plus optional local multilingual embeddings (`Xenova/paraphrase-multilingual-MiniLM-L12-v2`) select the most relevant chunks inside a token budget.
-3. **Prompt** — a language-aware prompt is assembled with module graphs, metrics, debt signals, and file excerpts.
-4. **Answer** — the model responds with `[source: file:line]` citations, `[Confidence: X%]`, and `[Severity: …]` labels.
-
-### Safe apply pipeline
-
-`/codebase-apply` and `/codebase-apply-tasks` support dry-run, create `.dsh-backups/` copies
-before overwriting, enforce protected paths, and never write outside the selected project.
-
----
-
-## Configuration
-
-### `.codebase-chat.json` — per-project settings
+</details>
 
-Drop this file at the project root to tune indexing, prompts and safety. Every key
-is optional; explicit CLI flags and tool arguments always take precedence, and a
-missing or malformed file falls back to built-in defaults.
+<details>
+<summary><strong><code>.codebase-chat.json</code> — per-project settings</strong></summary>
+<br>
 
 ```json
 {
@@ -222,28 +201,49 @@ missing or malformed file falls back to built-in defaults.
 
 | Key | Effect |
 | --- | --- |
-| `lang` | Default prompt language (`en` or `fr`) for the CLI, MCP tools and slash commands |
-| `maxTokens` | Default context budget when the caller passes none |
-| `ignoreDirs` | Extra directory names skipped by indexing, `codebase_health` and the file tree |
-| `ignoreFiles` | Extra file names skipped the same way |
-| `ignoreGlobs` | Globs on project-relative paths — `**` spans directories, `*` one segment, `?` one char |
-| `protectedPaths` | Extra paths the apply pipeline can never patch (adds to `DSH_PROTECTED_PATHS` and built-ins) |
+| `lang` | Default prompt language (`en`/`fr`) — CLI, MCP tools, slash commands |
+| `maxTokens` | Context budget when the caller passes none |
+| `ignoreDirs` / `ignoreFiles` | Extra names skipped by indexing, `codebase_health`, file tree |
+| `ignoreGlobs` | Globs on project-relative paths — `**` spans dirs, `*` one segment |
+| `protectedPaths` | Paths the apply pipeline can never patch |
+
+</details>
 
-### Environment variables
+<details>
+<summary><strong>Environment variables</strong></summary>
+<br>
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `CODEBASE_CACHE_DIR` | OS cache dir | Where the index cache lives |
-| `DSH_PROJECT_ALIASES` | — | Extra `name=path` project aliases (`;`-separated) |
-| `DSH_DAKO_PROJECT` | — | Override the built-in `dako` alias target |
+| `DSH_PROJECT_ALIASES` | — | Extra `name=path` aliases (`;`-separated) |
+| `DSH_DAKO_PROJECT` | — | Override the built-in `dako` alias |
 | `DSH_PROTECTED_PATHS` | built-in list | Extra paths that can never be patched |
-| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | MCP direct-LLM mode only |
+| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | Direct-LLM mode only |
 | `DEEPSEEK_BASE_URL` / `OPENAI_BASE_URL` | `https://api.deepseek.com/v1` | Custom endpoint |
 | `CODEBASE_MODEL` | `deepseek-chat` | Model for direct-LLM mode |
 
----
+</details>
+
+<details>
+<summary><strong>Plain words — 🇫🇷 inside</strong></summary>
+<br>
+
+Point it at a folder of code. Ask questions like a human — *"How does login work?"*, *"What should I fix first?"* — in French or English. Every answer cites the exact file and line it came from. **Nothing is uploaded anywhere.**
+
+*Pointez-le vers un dossier de code. Posez vos questions en langage clair. Chaque réponse cite le fichier et la ligne exacts. **Rien n'est envoyé sur internet.***
+
+| Term | Meaning |
+| --- | --- |
+| **MCP server** | A plug format that lets AI assistants use extra tools. Install once — your IDE can "see" your code. |
+| **Prompt-only** | The tool prepares the context; your existing AI writes the answer. No extra key, no extra cost. |
+| **Deterministic** | Computed directly from your code — same input, same result, every time. |
+
+</details>
 
-## Project layout
+<details>
+<summary><strong>Project layout & dev</strong></summary>
+<br>
 
 ```
 ├── lib/            DeepSeek Harness plugin (index.js) + Codebase Pro UI (client.js)
@@ -254,75 +254,60 @@ missing or malformed file falls back to built-in defaults.
 └── dist/           Build output (tsup)
 ```
 
-### Development
-
 ```bash
-pnpm install      # install workspace deps
-pnpm build        # tsup → dist/
-pnpm test         # vitest run
-pnpm typecheck    # tsc --noEmit
+pnpm install && pnpm build && pnpm test && pnpm typecheck
 ```
 
----
-
-## FAQ
-
-<details>
-<summary><strong>Does it send my code to the cloud?</strong></summary>
-<br>
-No. Indexing, retrieval, and prompt building run on your machine. In MCP prompt-only mode, nothing leaves your machine at all — the host model reads the assembled context directly.
 </details>
 
 <details>
-<summary><strong>Do I need an API key?</strong></summary>
+<summary><strong>FAQ</strong></summary>
 <br>
-Not for the MCP server — without a key it returns the built prompt to the host model. A <code>DEEPSEEK_API_KEY</code> or <code>OPENAI_API_KEY</code> is only needed for direct LLM calls. Inside DeepSeek Harness, the plugin uses your configured model.
-</details>
 
-<details>
-<summary><strong>Which languages are supported?</strong></summary>
-<br>
-French and English out of the box via the <code>lang</code> parameter on every tool and command. The prompt builders are designed to be extended.
-</details>
+**Does it send my code to the cloud?**
+No. Indexing, retrieval, and prompt building run on your machine. In prompt-only mode, nothing leaves it at all.
 
-<details>
-<summary><strong>Is applying patches safe?</strong></summary>
-<br>
-Yes. Apply workflows support dry-run, create backups before overwriting, enforce protected paths, and keep all writes inside the selected project.
-</details>
+**Do I need an API key?**
+Not for the MCP server — without a key it returns the built prompt to the host model. A key is only needed for direct LLM calls. Inside DeepSeek Harness, the plugin uses your configured model.
 
-<details>
-<summary><strong>Troubleshooting: EADDRINUSE on port 3080</strong></summary>
-<br>
+**Which languages are supported?**
+French and English via `lang` on every tool. Source-side, AST covers JS/TS, Python, Go, Rust, Java, C#, PHP — the rest is indexed line by line.
 
+**Is applying patches safe?**
+Yes. Dry-run, backups before overwrite, protected paths, writes stay inside the project.
+
+**EADDRINUSE on port 3080?**
 ```powershell
 Get-NetTCPConnection -LocalPort 3080 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
 ```
+Then restart `dsh --profile web`.
 
-Then restart <code>dsh --profile web</code>.
 </details>
 
----
+<details>
+<summary><strong>Roadmap</strong></summary>
+<br>
 
-## Roadmap
+| | |
+| --- | --- |
+| **Shipped** | tree-sitter AST (7 languages), deterministic health score, MCP setup wizard, `.codebase-chat.json`, `--diff` scoping, `--watch` mode |
+| **Next** | GitHub Issues export from TASKS.md, prompt language packs (ES/DE/PT) |
+| **Planned** | VS Code extension, HTTP/SSE transport, PR review mode, report export |
+| **Exploring** | multi-repo workspaces, shared team index cache, CI bot |
 
-Highlights — see [ROADMAP.md](ROADMAP.md) for the full plan:
+<sub>Full detail: <a href="ROADMAP.md">ROADMAP.md</a></sub>
 
-- **Next**: tree-sitter parsing (Python, Go, Rust, Java), watch mode, GitHub Issues export
-- **Planned**: VS Code extension, HTTP/SSE transport, PR review mode, report export (HTML/PDF)
-- **Exploring**: multi-repo workspaces, shared team index cache, CI bot
+</details>
 
 ---
 
-## Contributing
-
-Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Run `pnpm typecheck && pnpm test` before opening a PR.
-
-## Support
-
-- [Open an issue](https://github.com/shinzarou-eng/dsh-codebase-chat/issues)
-- [SUPPORT.md](SUPPORT.md)
-
-## License
-
-[MIT](LICENSE) — Built and maintained by [shinzarou-eng](https://github.com/shinzarou-eng).
+<p align="center">
+  <strong>If this project helps you — <a href="https://github.com/shinzarou-eng/dsh-codebase-chat">star it on GitHub</a> ⭐</strong>
+  <br><br>
+  <a href="https://shinzarou-eng.github.io/dsh-codebase-chat">Website</a> ·
+  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/issues">Issues</a> ·
+  <a href="SUPPORT.md">Support</a> ·
+  <a href="SECURITY.md">Security</a>
+  <br><br>
+  <sub><a href="LICENSE">MIT License</a> — built and maintained by <a href="https://github.com/shinzarou-eng">shinzarou-eng</a></sub>
+</p>