dsh-codebase-chat 0.16.4 → 0.19.0

package/README.md

@@ -1,58 +1,89 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/shinzarou-eng/dsh-codebase-chat/main/docs/assets/logo.svg" width="120" height="120" alt="dsh-codebase-chat logo">
+  <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>Multi-language codebase intelligence for DeepSeek Harness and any MCP IDE.</strong><br>
-  Chat, search, explain, refactor, audit, and generate board-ready reports from local code.
+  <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
 </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&color=blue" alt="npm"></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&color=purple" alt="npm mcp"></a>
-  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/releases"><img src="https://img.shields.io/github/v/release/shinzarou-eng/dsh-codebase-chat?logo=github" alt="release"></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=blue" alt="license"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?logo=nodedotjs" alt="node"></a>
-  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-purple" alt="mcp"></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=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>
 </p>
 
 <p align="center">
-  <a href="https://shinzarou-eng.github.io/dsh-codebase-chat">Website</a> ·
-  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/releases">Releases</a> ·
-  <a href="#install">Install</a> ·
-  <a href="#mcp">MCP</a> ·
-  <a href="#commands">Commands</a> ·
-  <a href="#faq">FAQ</a>
+  <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="ROADMAP.md">Roadmap</a> ·
+  <a href="CHANGELOG.md">Changelog</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+<br>
+
+<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>
 </p>
 
 ---
 
-## Why dsh-codebase-chat?
+## In plain words
 
-Most codebase assistants are **slow, paywalled, or force you to upload source code to the cloud**. **dsh-codebase-chat** runs **locally**, reads only the files you point at, and turns raw code into structured intelligence — with **source citations, confidence scores, and severity labels**.
+> **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.
 
-| Capability | What it gives you |
+| Term | Meaning |
 | --- | --- |
-| **Chat** | Ask anything about the project in plain language. |
-| **Search** | Find symbols, terms, and usages with line references. |
-| **Explain** | Understand a file or function with real code excerpts. |
-| **Refactor** | Get production-ready code changes with diff rationale. |
-| **Intelligence Pro** | CTO-level audit: architecture, tech radar, debt, security, competitors, roadmap. |
-| **Audit** | Dedicated non-conformity and tech-debt scan with fixes. |
-| **Strategic Report** | Board-ready SWOT, score cards, 90-day roadmap, marketing angle. |
-| **Tasks** | Auto-generate `TASKS.md` with sprints, Before/After blocks, and patch application. |
-| **Player Brief** | UX / playthrough analysis from a real user perspective. |
-| **Crea** | Slogans, taglines, and feature ideas inspired by the code. |
+| **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. |
+
+<details>
+<summary><strong>🇫🇷 En termes simples</strong></summary>
+
+<br>
+
+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.
+
+</details>
+
+---
+
+## Why dsh-codebase-chat?
+
+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.
+
+- **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.
 
 ---
 
 ## Quick start
 
-### 1. DeepSeek Harness plugin
+### Option A — DeepSeek Harness plugin
 
-```powershell
+```bash
 pnpm add dsh-codebase-chat
 # or
 npm install dsh-codebase-chat
@@ -60,75 +91,85 @@ npm install dsh-codebase-chat
 
 Then open `http://127.0.0.1:3080` and click the **Codebase Pro** button in the sidebar.
 
-### 2. Standalone MCP server
+### Option B — MCP server (Cursor, Claude, Windsurf…)
 
 ```bash
-# Install globally
-npm install -g dsh-codebase-chat-mcp
-
-# Or run without installing
 npx dsh-codebase-chat-mcp
 ```
 
-Configure Windsurf / Cursor / Claude:
-
 ```json
 {
   "mcpServers": {
     "dsh-codebase-chat": {
       "command": "npx",
-      "args": ["dsh-codebase-chat-mcp"],
-      "env": {
-        "DEEPSEEK_API_KEY": "sk-...",
-        "CODEBASE_MODEL": "deepseek-chat"
-      }
+      "args": ["dsh-codebase-chat-mcp"]
     }
   }
 }
 ```
 
-See [`mcp/README.md`](mcp/README.md) for the full config.
+> **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.
 
-### 3. From source
+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 install && pnpm build
 ```
 
 ---
 
-## Commands
-
-```powershell
-# Ask a question
-dsh --profile headless '/codebase "how is auth handled?"'
+## Tool suite
 
-# Ask with explicit project
-dsh --profile headless '/codebase "how is auth handled?" --project C:\my-app'
+Every capability is exposed as a DSH tool, a slash command, and an MCP tool.
 
-# Append a creative idea
-dsh --profile headless '/codebase "how does storage work?" --project C:\my-app --crea --crea-theme "slogan"'
+| 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)
 
-# Search, explain, refactor
+```powershell
+dsh --profile headless '/codebase "how is auth handled?" --project C:\my-app'
 dsh --profile headless '/codebase-search "usePetStore" --project C:\my-app'
 dsh --profile headless '/codebase-explain "storage.ts" --project C:\my-app'
 dsh --profile headless '/codebase-refactor "split this hook" --file storage.ts --project C:\my-app'
-
-# Professional briefs
 dsh --profile headless '/codebase-intel --project C:\my-app'
-dsh --profile headless '/codebase-audit --project C:\my-app'
-dsh --profile headless '/codebase-report --project C:\my-app'
-dsh --profile headless '/codebase-ceo --project C:\my-app'
-dsh --profile headless '/codebase-player --project C:\my-app'
-
-# Tasks & apply
+dsh --profile headless '/codebase-audit --project C:\my-app --lang en'
 dsh --profile headless '/codebase-tasks --project C:\my-app'
-dsh --profile headless '/codebase-tasks-raw --project C:\my-app'
 dsh --profile headless '/codebase-apply-tasks --project C:\my-app'
-
-# Build & git
 dsh --profile headless '/codebase-build --project C:\my-app'
 dsh --profile headless '/codebase-git --project C:\my-app'
 ```
@@ -139,123 +180,119 @@ dsh --profile headless '/codebase-git --project C:\my-app'
 
 ```mermaid
 graph LR
-  A[User query] --> B[Codebase Pro UI / MCP / CLI]
-  B --> C[Context collector]
-  C --> D[Project files]
-  C --> E[Module graph / debt / tests]
-  C --> F[Prompt builder]
-  F --> G[LLM]
-  G --> H[Structured response with citations]
+  A[Query] --> B[Index]
+  B --> C[Retrieve]
+  C --> D[Prompt]
+  D --> E[LLM]
+  E --> F[Cited answer]
 ```
 
-1. **Context collector** reads `package.json`, source files, tests, config, git, build output.
-2. **Module graph** maps who calls who.
-3. **Debt scanner** flags `TODO` / `FIXME` / `HACK` / `console.log` / `any` / `debugger`.
-4. **Prompt builder** assembles a language-aware, evidence-based prompt.
-5. **LLM** returns a response that includes source citations, confidence scores, and severity badges.
-
----
-
-## Evidence & scoring
-
-Every technical claim, risk, and opportunity is marked with:
+1. **Index** — AST + regex extraction 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.
 
-- `[source: relative/path/file.ts:line]`
-- `[Confidence: X%]`
-- `[Severity: Critical/High/Medium/Low]`
+### Safe apply pipeline
 
-No fabricated citations, no hand-waving.
+`/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.
 
 ---
 
-## Multi-language
-
-The plugin detects the user's language and generates the entire prompt in that language.
-
-- `fr` — French
-- `en` — English
+## Configuration
 
-More languages can be added by extending the `build*Prompt` functions.
+| 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_PROTECTED_PATHS` | built-in list | Extra paths that can never be patched |
+| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | MCP 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 |
 
 ---
 
-## Web UI
+## Project layout
 
-When installed in the **web** profile, the plugin adds a **Codebase Pro** button in the sidebar footer:
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/shinzarou-eng/dsh-codebase-chat/main/docs/assets/codebase-pro-button.svg" alt="Codebase Pro button" width="240">
-</p>
-
-One click opens the brief selector and launches the chosen mode in the user's language.
-
----
+```
+├── lib/            DeepSeek Harness plugin (index.js) + Codebase Pro UI (client.js)
+├── src/            TypeScript engine — indexer, extractor, retriever, tokenizer, context, CLI
+├── mcp/            Standalone MCP server package (dsh-codebase-chat-mcp)
+├── test/           Vitest suites (extractor, retriever, tasks pipeline)
+├── docs/           Landing page (GitHub Pages) + assets
+└── dist/           Build output (tsup)
+```
 
-## Install as a DSH plugin
+### Development
 
-```powershell
-dsh plugin --profile headless add dsh-codebase-chat
-dsh plugin --profile web add dsh-codebase-chat
+```bash
+pnpm install      # install workspace deps
+pnpm build        # tsup → dist/
+pnpm test         # vitest run
+pnpm typecheck    # tsc --noEmit
 ```
 
-For a local development build, use the `file:` path to your clone.
-
 ---
 
 ## FAQ
 
-**Does it send my code to the cloud?**  
-No. All context collection and prompt building run on your machine. Only the final prompt is sent to the LLM you configure.
-
-**Can I use it with Claude, Cursor, or Windsurf?**  
-Yes. Install `dsh-codebase-chat-mcp` and add it to your MCP server config.
-
-**Does it work without DeepSeek Harness?**  
-Yes. The `dsh-codebase-chat-mcp` package is fully standalone.
-
-**Which languages are supported?**  
-French and English out of the box. The prompt builders are designed to be extended.
-
----
-
-## Troubleshooting
-
-### `EADDRINUSE` — port 3080 already in use
+<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>
+<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>
+
+<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>
+
+<details>
+<summary><strong>Troubleshooting: EADDRINUSE on port 3080</strong></summary>
+<br>
 
 ```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>
 
 ---
 
 ## Roadmap
 
-- [ ] More language packs
-- [ ] VS Code extension
-- [ ] Indexed project cache for huge repos
-- [ ] Interactive diff viewer in DSH UI
+Highlights — see [ROADMAP.md](ROADMAP.md) for the full plan:
+
+- **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
 
 ---
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Run `node --check lib/index.js` before committing
-4. Open a PR against `main`
-
-See [CONTRIBUTING.md](https://github.com/shinzarou-eng/dsh-codebase-chat/blob/main/CONTRIBUTING.md) for details.
-
----
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Run `pnpm typecheck && pnpm test` before opening a PR.
 
 ## Support
 
-Open an issue on [GitHub](https://github.com/shinzarou-eng/dsh-codebase-chat/issues).
-
----
+- [Open an issue](https://github.com/shinzarou-eng/dsh-codebase-chat/issues)
+- [SUPPORT.md](SUPPORT.md)
 
 ## License
 
-[MIT](https://github.com/shinzarou-eng/dsh-codebase-chat/blob/main/LICENSE) — Built and maintained by [shinzarou-eng](https://github.com/shinzarou-eng).
+[MIT](LICENSE) — Built and maintained by [shinzarou-eng](https://github.com/shinzarou-eng).

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node