@lbroth/rothunter 1.0.0-rc.2 → 1.0.0-rc.4

package/README.md

@@ -32,74 +32,69 @@ Full detector list with severities + tunables: [`docs/DETECTORS.md`](./docs/DETE
 | Single-workspace | All 24 |
 | Multi-workspace (cross-repo via `rothunter.config.json`) | 9 cross-repo always-on (duplicate-type, duplicate-function, dead-module, dead-export, dead-api, long-function, deep-nesting, public-any, hot-hub-file) + the remaining 15 looped per workspace with workspace-namespaced fingerprints |
 
-## Quick start
-
-Three paths. Pick one — they all end at <http://localhost:3000>.
+## What you actually get
 
-### 1. Docker (fastest, no clone)
+rothunter has TWO independent pieces:
 
-```bash
-# scan the repo in $(pwd) — needs an LLM endpoint
-docker run --rm -p 3000:3000 \
-  -v "$(pwd):/workspace" \
-  -e ROTHUNTER_LLM_BASE_URL="$LLM_URL" \
-  ghcr.io/lbroth/rothunter:latest
-```
+| Piece | What it does | Where it runs |
+|---|---|---|
+| **Engine + dashboard** (`rothunter`) | parses your repo, runs 24 detectors, serves the Fastify API + React UI on `:3000` | this is what the npm package / docker image ships |
+| **LLM** (any OpenAI-compatible endpoint) | answers the verdict prompts ("is this finding real or intentional?") — typically `llama.cpp` with Qwen2.5-Coder-14B | runs separately, you point rothunter at it |
 
-No `ROTHUNTER_LLM_BASE_URL`? Use the compose stack — it ships an
-llama.cpp sidecar that downloads a 9 GB model on first boot:
+The engine runs WITHOUT the LLM — the deterministic detectors still
+fire, you just don't get the verdict pass that auto-filters the FPs.
+So the question every install path answers is: "do you want me to
+also start an LLM, or are you bringing your own?"
 
-```bash
-git clone https://github.com/lBroth/rothunter && cd rothunter
-ROTHUNTER_WORKSPACE_HOST=/path/to/your-repo npm run docker
-```
+## Quick start
 
-### 2. npx (no Docker)
+The fastest path — `cd` into the repo you want to scan and:
 
 ```bash
-# server + UI on :3000; point at any OpenAI-compatible LLM endpoint
-ROTHUNTER_LLM_BASE_URL=http://127.0.0.1:8080/v1 \
-  npx @lbroth/rothunter
+npx @lbroth/rothunter@next
 ```
 
-The npx flow boots only the server + dashboard. Run the LLM yourself
-with `brew install llama.cpp && llama-server --hf-repo bartowski/Qwen2.5-Coder-14B-Instruct-GGUF` (or aim
-`ROTHUNTER_LLM_BASE_URL` at vLLM / OpenRouter / LM Studio).
+That boots the engine + dashboard on <http://localhost:3000>. The
+current directory is auto-mounted as the workspace. Default LLM
+endpoint is `http://127.0.0.1:8080/v1` (a local `llama.cpp`) — set
+`ROTHUNTER_LLM_BASE_URL` to point elsewhere. **No LLM is required**
+for the scan to run; deterministic detectors fire either way, you
+just lose the LLM-driven auto-FP routing.
 
-### 3. Clone + dev mode (contributor flow)
+### Docker (no node install)
 
 ```bash
-git clone https://github.com/lBroth/rothunter && cd rothunter
-npm run setup        # root + UI deps
-npm run dev:full     # server + UI + auto-launched llama.cpp
+docker run --rm -p 3000:3000 \
+  -v "$(pwd):/workspace" \
+  -e ROTHUNTER_LLM_BASE_URL="http://host.docker.internal:8080/v1" \
+  ghcr.io/lbroth/rothunter:latest
 ```
 
-`dev:full` auto-detects an LLM backend on `PATH`:
+### Docker Compose — bundles llama.cpp + Qwen2.5-Coder-14B
 
-| # | Backend | When picked |
-|---|---------|-------------|
-| 1 | **llama.cpp native** (`llama-server`) | `llama-server` on PATH (`brew install llama.cpp`) — uses Metal / CUDA when the binary supports it |
-| 2 | **Docker** (`docker compose up rothunter-llm`) | Docker Desktop available |
-
-Force a backend or model:
+For "one command, everything boots" (downloads 9 GB on first run):
 
 ```bash
-ROTHUNTER_LLM_BACKEND=llamacpp npm run dev:full
-ROTHUNTER_LLM_MODEL=bartowski/Qwen2.5-Coder-7B-Instruct-GGUF npm run dev:full
+git clone https://github.com/lBroth/rothunter && cd rothunter
+ROTHUNTER_WORKSPACE_HOST=/path/to/your-repo npm run docker
 ```
 
-### Point at a remote LLM
+### Running your own LLM
 
-Skip the auto-launch when you already have an OpenAI-compatible endpoint:
+Any OpenAI-compatible endpoint works (vLLM / Ollama / LM Studio /
+OpenRouter / a colleague's box). Local llama.cpp one-liner:
 
 ```bash
-export ROTHUNTER_LLM_BASE_URL=https://my-llm.internal/v1
-export ROTHUNTER_LLM_MODEL=Qwen2.5-Coder-14B-Instruct
-export ROTHUNTER_LLM_API_KEY=...           # if the endpoint needs auth
-export ROTHUNTER_LLM_CONCURRENCY=4         # raise for vLLM / llama.cpp --parallel N
-npx @lbroth/rothunter
+brew install llama.cpp       # macOS — Linux: see ggml-org/llama.cpp
+llama-server \
+  --hf-repo bartowski/Qwen2.5-Coder-14B-Instruct-GGUF \
+  --hf-file Qwen2.5-Coder-14B-Instruct-Q4_K_M.gguf \
+  --host 127.0.0.1 --port 8080 --jinja -c 8192 -n 256
 ```
 
+Then point rothunter at it via `ROTHUNTER_LLM_BASE_URL`
+(default already targets `http://127.0.0.1:8080/v1`).
+
 ## Layout
 
 ```
@@ -144,7 +139,14 @@ See [`ROADMAP.md`](./ROADMAP.md) for planned detectors (TypeScript misuse:
 
 ## Contributing
 
-PRs welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the detector-author checklist and quality bar.
+PRs welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the
+detector-author checklist and quality bar. Local dev flow:
+
+```bash
+git clone https://github.com/lBroth/rothunter && cd rothunter
+npm run setup        # root + UI deps
+npm run dev:full     # server + UI + auto-launched llama.cpp on PATH
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lbroth/rothunter",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "description": "Self-hosted code-hygiene engine for TypeScript / JavaScript codebases. Deterministic detectors + local LLM verdicts + dashboard.",
   "license": "MIT",
   "author": "lBroth",