codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

package/docs/web-dashboard.md

@@ -1,206 +0,0 @@
-# Web dashboard (`rag-web`)
-
-A local web UI for configuring and inspecting the RAG server. It provides a
-schema-driven config editor, an overview of indexed projects, and an interactive
-project-dependency graph — all served from a small built-in HTTP server with no
-external framework and no new dependencies (`node:http`).
-
-The dashboard is a thin presentation layer over primitives that already exist:
-config I/O and validation (`src/config-store.ts`), project data
-(`SearcherService.listProjects`), and the graph builder (`src/graph.ts`). It adds
-no business logic of its own beyond request routing and a password-preservation
-merge.
-
----
-
-## Running
-
-```bash
-rag-web                 # http://127.0.0.1:4319
-rag-web --port 8080     # custom port
-npm run start:web       # dev mode (ts-node, no build)
-```
-
-If the `rag-web` binary is not on your `PATH`, either run it from the project
-(`node dist/app.js web`) or register it once with `npm link`.
-
-Keep the terminal open — the server runs until you press `Ctrl+C`. The browser
-can only reach the dashboard while the process is alive.
-
----
-
-## Security model
-
-- **Binds to `127.0.0.1` only.** The server is never exposed on the network;
-  it is a single-user local dev tool, so there is no authentication.
-- **The DB password is never sent to the browser.** `GET /api/config` returns it
-  masked as `********`. On save, if the field is still the mask, the stored
-  password is preserved (`mergeConfigForSave`); a genuinely changed value is
-  written through.
-- **No arbitrary file serving.** Only the known routes below respond; there is no
-  static file handler, so no path-traversal surface.
-
----
-
-## Requirements & failure modes
-
-- Requires a valid `config.json` — `rag-web` goes through the normal container
-  bootstrap and `workspaceRoot` guard. To repair a broken config, use
-  `rag-config edit` (CLI) instead.
-- A failed **DB** connection is non-fatal: the config editor still works; the
-  Projects and Graph tabs show an in-page error.
-- A failed **embedding backend** connection only affects model suggestions (see
-  *Field options*); everything else works.
-
----
-
-## UI tabs
-
-### Config
-A form generated from the config JSON Schema (`buildJsonSchema()` — the same
-schema that powers editor autocomplete on `config.json`). Fields are grouped by
-section and typed automatically:
-
-| Schema shape | Rendered as |
-|---|---|
-| `boolean` | checkbox |
-| `enum` (e.g. `logging.level`) | `<select>` |
-| `integer` / `number` | number input (with sensible `min`/`max`/`step`) |
-| `string` | text input |
-| field in `/api/field-options`, `strict` | `<select>` limited to the list |
-| field in `/api/field-options`, non-strict | text input + `<datalist>` (combobox) |
-
-Two affordances make the effective configuration obvious:
-
-- **Defaults.** Any key left unset shows `↪ using default: <value>` (amber) and
-  the applied value as the input placeholder. A key that *is* set shows a muted
-  `default: <value>` for reference. Source: `GET /api/defaults`
-  (`CONFIG_DEFAULTS`).
-- **Field options.** Fields whose valid values are constrained get a dropdown
-  instead of free text. Source: `GET /api/field-options`. See below.
-
-Saving validates through `parseConfig` and, on failure, shows the validation
-message and highlights the offending fields; on success the config is written
-(with the `$schema` reference preserved) and the form reloads.
-
-### Projects
-Cards for each indexed project from `SearcherService.listProjects()` — name,
-chunk count, and any `.ragmeta.json` metadata (stack, description, relations).
-
-### Graph
-The **full standalone graph page embedded in an `<iframe>`** (`src="/graph"`),
-loaded lazily on first open. `GET /graph` serves the exact same HTML as the
-generated `project-graph.html` (`buildHtml()` in `src/graph.ts`), so the whole
-sidebar comes for free: the node-color legend, the edge-type filter buttons, and
-the project toggle list, plus hover highlighting and auto-fit. The dashboard
-does **not** re-implement vis-network — reusing one page keeps the two graph
-views identical. `GET /api/graph` still returns the raw `{ nodes, edges }` JSON
-(`buildGraphData()`) for programmatic use.
-
----
-
-## Field options (model dropdowns)
-
-Some settings have a constrained set of valid values, so the form offers a list
-rather than free text. `GET /api/field-options` returns
-`{ [dottedKey]: { values: string[], strict: boolean } }`:
-
-- **`embedding.model`, `reranker.model` — non-strict.** `embedding.model`
-  suggests `MODEL_REGISTRY` (`src/constants.ts`) entries plus any model the
-  backend currently serves; `reranker.model` suggests only served models. Both
-  allow free text — a model outside the registry still works (its dimension is
-  probed at index time). Served models come from `IEmbedder.listModels()`,
-  implemented only by `InfinityEmbedder` (2-second-limited `/models` listing);
-  if the backend is unreachable, or the provider doesn't implement `listModels`
-  (`openai-compatible`, `voyage`), the served-model list is empty and the field
-  degrades to registry suggestions only (or plain text for `reranker.model`).
-
-A strict `<select>` preserves an unknown current value as an extra option, so
-saving never silently drops a value that isn't in the list.
-
----
-
-## HTTP API
-
-All routes are served from `127.0.0.1:<port>`.
-
-| Method | Path | Response |
-|---|---|---|
-| `GET`  | `/` | Dashboard HTML (self-contained) |
-| `GET`  | `/api/schema` | JSON Schema of the config (`buildJsonSchema()`) |
-| `GET`  | `/api/defaults` | `CONFIG_DEFAULTS` — dotted key → default value |
-| `GET`  | `/api/field-options` | dotted key → `{ values, strict }` |
-| `GET`  | `/api/config` | Current config, `db.password` masked |
-| `PUT`  | `/api/config` | Save. Body = config JSON. `200 {ok:true, backend:{action,message}}` or `400 {error}`. For `embedding.provider: infinity`, `backend.action` reports whether the Infinity container needed a background recreate (`started`/`already-running`/`not-needed`/`manual-required`/`failed`) — see *Infinity backend recreate* below |
-| `GET`  | `/api/backend-status` | `{ state, message, startedAt, finishedAt }` — progress of the most recent background Infinity recreate this server process started |
-| `GET`  | `/api/projects` | `SearcherService.listProjects()` |
-| `GET`  | `/api/graph` | `{ nodes, edges }` JSON (`buildGraphData()`) |
-| `GET`  | `/graph` | Full interactive graph page (`buildHtml()`), embedded by the Graph tab's iframe |
-
----
-
-## Infinity backend recreate
-
-When a save's `embedding.provider` is `infinity`, the server computes the
-required model set from the **saved** config (freshly re-read from disk, not
-the embedder the process started with) and compares it against what the
-backend currently serves. If a managed container needs to be started or
-recreated to serve the new set, that runs as an in-process background task —
-the `PUT` responds immediately (`action: "started"`) without waiting for it.
-Poll `GET /api/backend-status` for progress (`state: "recreating"` →
-`"ready"`/`"failed"`). Only one `docker compose` run is active at a time; a
-save that arrives while a recreate is already in flight for a managed backend
-responds `already-running`, and at most one follow-up run applies the latest
-such save once the in-flight one finishes. An external (unmanaged) backend
-missing a required model never triggers Docker — the response's `message`
-carries manual `--model-id`/launch instructions instead.
-
----
-
-## Architecture
-
-| File | Responsibility |
-|---|---|
-| `src/commands/WebCommand.ts` | CLI entry. `db.initDb()`, starts the server, keeps `execute()` pending until `SIGINT`/`SIGTERM` (mirrors `McpCommand`), then `server.stop()`. Parses `--port` (default `4319`). |
-| `src/services/WebServerService.ts` | `WebServer(searcher, config, logger, embedder, deps?)` — `node:http` server, routing, the API handlers, and the background Infinity recreate + `/api/backend-status` state. Exports the pure `mergeConfigForSave()` and the `FieldOption` type. |
-| `src/services/infinity-provisioning.ts` | The readiness/recreate primitive the background task delegates to (shared with `InfinityEmbedder` and `rag-setup`) — classification, compose-file rewrite, `docker compose` invocation, readiness polling. |
-| `src/web/dashboard.ts` | `renderDashboardHtml()` — the entire page (HTML + CSS + JS) as one self-contained string, mirroring `graph.ts:buildHtml`. |
-
-Reused primitives (no duplication):
-
-- `readConfigJson` / `parseConfig` / `writeConfigJson` / `buildJsonSchema` /
-  `CONFIG_DEFAULTS` — `src/config-store.ts`
-- `buildGraphData` — `src/graph.ts`
-- `listProjects` — `src/services/SearcherService.ts`
-- `MODEL_REGISTRY` — `src/constants.ts`
-- `evaluateBackend` / `ensureModelSetServed` / `requiredModelSet` — `src/services/infinity-provisioning.ts`
-
-Wiring: `app.ts` detects the `web` mode and dispatches
-`new WebCommand(container, effectiveArgs)`. The command uses the shared
-`Container` services (`db`, `searcher`, `config`, `logger`) — no container
-changes were needed.
-
----
-
-## Extending
-
-- **Constrain another field to a list** — add an entry to `fieldOptions()` in
-  `WebServerService.ts` (`{ values, strict }`). The form renders it automatically
-  (strict → dropdown, non-strict → combobox).
-- **Add a tab / endpoint** — add a route in `WebServer.handle`, a fetch + render
-  in `dashboard.ts`, and a tab button. Keep handlers thin — delegate to a service.
-- **Actions (e.g. trigger reindex)** — deferred by design. This is heavier (a
-  long-running process with live progress, likely via SSE, plus concurrency
-  control) and belongs in its own change rather than the read/config-edit shell.
-
----
-
-## Keep in sync
-
-- `CONFIG_DEFAULTS` (`config-store.ts`) is the **single source of truth** for
-  built-in defaults: `resolvedSchema` in `config.ts` references it in its
-  `.default(...)` calls, so the runtime default and the dashboard-displayed
-  default cannot diverge — no manual sync needed. (A unit test still asserts
-  every key is a valid config key.)
-- `MODEL_REGISTRY` (`constants.ts`) is advisory, not exhaustive — a model
-  outside it still works via the runtime dimension probe at index time.