codesearch-mcp 0.0.17-alpha → 0.0.18-alpha

package/dist/src/tools/format-helpers.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textResponse = textResponse;
+exports.errorResponse = errorResponse;
+exports.formatChunk = formatChunk;
+exports.formatGraphContext = formatGraphContext;
+exports.formatDependencies = formatDependencies;
+exports.formatDependents = formatDependents;
+function textResponse(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function errorResponse(text) {
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+function formatChunk(r, label) {
+    return `${label ? `*(${label})*\n` : ''}**File:** ${r.filePath}\n**Project:** ${r.serviceName}\n**Line:** ${r.startLine}\n\`\`\`\n${r.content}\n\`\`\``;
+}
+function formatGraphContext(ctx) {
+    const parts = [];
+    if (ctx?.imports.length)
+        parts.push(`**Imports:** ${ctx.imports.join(' · ')}`);
+    if (ctx?.usedBy.length)
+        parts.push(`**Used by:** ${ctx.usedBy.join(' · ')}`);
+    return parts.length > 0 ? '\n' + parts.join('\n') : '';
+}
+function formatDependencies(filePath, rows, transitive) {
+    const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
+    const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
+    const lines = [`**Dependencies of** \`${filePath}\`\n`, '**Direct:**'];
+    for (const r of direct) {
+        const sym = r.toSymbol ? ` (${r.depType} \`${r.toSymbol}\`)` : ` (${r.depType})`;
+        lines.push(`  → \`${r.toFile}\`${sym}`);
+    }
+    if (indirect.length > 0) {
+        lines.push('\n**Transitive:**');
+        for (const r of indirect) {
+            lines.push(`  → \`${r.toFile}\` (depth ${r.depth}, via \`${r.via}\`)`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatDependents(filePath, rows, transitive) {
+    const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
+    const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
+    const lines = [`**Dependents of** \`${filePath}\`\n`, '**Direct:**'];
+    for (const r of direct) {
+        const sym = r.fromSymbol ? ` (in \`${r.fromSymbol}\`)` : '';
+        lines.push(`  ← \`${r.fromFile}\`${sym}`);
+    }
+    if (indirect.length > 0) {
+        lines.push('\n**Transitive:**');
+        for (const r of indirect) {
+            lines.push(`  ← \`${r.fromFile}\` (depth ${r.depth}, via \`${r.via}\`)`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/src/tools/index.d.ts

@@ -0,0 +1,9 @@
+export { ListProjectsTool } from './ListProjectsTool';
+export { SearchCodebaseTool } from './SearchCodebaseTool';
+export { ReadFileRangeTool } from './ReadFileRangeTool';
+export { GetDependenciesTool } from './GetDependenciesTool';
+export { GetDependentsTool } from './GetDependentsTool';
+export { FindSymbolTool } from './FindSymbolTool';
+export { GetCallersTool } from './GetCallersTool';
+export { ListFilesTool } from './ListFilesTool';
+export { ReadFileTool } from './ReadFileTool';

package/dist/src/tools/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileTool = exports.ListFilesTool = exports.GetCallersTool = exports.FindSymbolTool = exports.GetDependentsTool = exports.GetDependenciesTool = exports.ReadFileRangeTool = exports.SearchCodebaseTool = exports.ListProjectsTool = void 0;
+var ListProjectsTool_1 = require("./ListProjectsTool");
+Object.defineProperty(exports, "ListProjectsTool", { enumerable: true, get: function () { return ListProjectsTool_1.ListProjectsTool; } });
+var SearchCodebaseTool_1 = require("./SearchCodebaseTool");
+Object.defineProperty(exports, "SearchCodebaseTool", { enumerable: true, get: function () { return SearchCodebaseTool_1.SearchCodebaseTool; } });
+var ReadFileRangeTool_1 = require("./ReadFileRangeTool");
+Object.defineProperty(exports, "ReadFileRangeTool", { enumerable: true, get: function () { return ReadFileRangeTool_1.ReadFileRangeTool; } });
+var GetDependenciesTool_1 = require("./GetDependenciesTool");
+Object.defineProperty(exports, "GetDependenciesTool", { enumerable: true, get: function () { return GetDependenciesTool_1.GetDependenciesTool; } });
+var GetDependentsTool_1 = require("./GetDependentsTool");
+Object.defineProperty(exports, "GetDependentsTool", { enumerable: true, get: function () { return GetDependentsTool_1.GetDependentsTool; } });
+var FindSymbolTool_1 = require("./FindSymbolTool");
+Object.defineProperty(exports, "FindSymbolTool", { enumerable: true, get: function () { return FindSymbolTool_1.FindSymbolTool; } });
+var GetCallersTool_1 = require("./GetCallersTool");
+Object.defineProperty(exports, "GetCallersTool", { enumerable: true, get: function () { return GetCallersTool_1.GetCallersTool; } });
+var ListFilesTool_1 = require("./ListFilesTool");
+Object.defineProperty(exports, "ListFilesTool", { enumerable: true, get: function () { return ListFilesTool_1.ListFilesTool; } });
+var ReadFileTool_1 = require("./ReadFileTool");
+Object.defineProperty(exports, "ReadFileTool", { enumerable: true, get: function () { return ReadFileTool_1.ReadFileTool; } });

package/dist/src/web/dashboard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders the RAG dashboard as a single self-contained HTML page (inline CSS +
+ * JS), mirroring the approach in graph.ts. The page is schema-driven: it fetches
+ * /api/schema (from buildJsonSchema — the same source as Step 1's editor support)
+ * and /api/config, then renders a typed form. The Graph tab embeds the full
+ * standalone graph page (GET /graph — same buildHtml as project-graph.html) in
+ * an iframe rather than re-implementing the network here.
+ */
+export declare function renderDashboardHtml(): string;

package/dist/src/web/dashboard.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDashboardHtml = renderDashboardHtml;
+/**
+ * Renders the RAG dashboard as a single self-contained HTML page (inline CSS +
+ * JS), mirroring the approach in graph.ts. The page is schema-driven: it fetches
+ * /api/schema (from buildJsonSchema — the same source as Step 1's editor support)
+ * and /api/config, then renders a typed form. The Graph tab embeds the full
+ * standalone graph page (GET /graph — same buildHtml as project-graph.html) in
+ * an iframe rather than re-implementing the network here.
+ */
+function renderDashboardHtml() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>RAG Dashboard</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui, sans-serif; background: #1a1a2e; color: #eee; height: 100vh; display: flex; flex-direction: column; }
+    #header { padding: 12px 20px; background: #16213e; border-bottom: 1px solid #0f3460; display: flex; align-items: center; gap: 24px; flex-shrink: 0; }
+    #header h1 { font-size: 16px; font-weight: 600; }
+    #tabs { display: flex; gap: 6px; }
+    .tab { padding: 6px 14px; border-radius: 8px; border: 1px solid transparent; background: transparent; color: #88aabb; font-size: 13px; cursor: pointer; }
+    .tab.active { background: #4A90D9; color: #fff; }
+    #main { flex: 1; overflow: auto; padding: 24px; }
+    .panel { display: none; max-width: 900px; margin: 0 auto; }
+    .panel.active { display: block; }
+    /* Graph panel uses the full available width (not the 900px form column). */
+    #graph-panel { max-width: none; }
+
+    /* Config form */
+    .section { background: #16213e; border: 1px solid #0f3460; border-radius: 10px; padding: 16px 18px; margin-bottom: 16px; }
+    .section h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #7aa; margin-bottom: 14px; }
+    .field { display: grid; grid-template-columns: 220px 1fr; align-items: center; gap: 14px; margin-bottom: 12px; }
+    .field:last-child { margin-bottom: 0; }
+    .field label { font-size: 13px; color: #cde; }
+    .field .desc { display: block; font-size: 11px; color: #667; margin-top: 2px; }
+    .field .defval { display: block; font-size: 11px; color: #667; margin-top: 2px; }
+    .field .defval.using { color: #c9a24a; } /* amber — this field is currently using the default */
+    .field input[type=text], .field input[type=password], .field input[type=number], .field select {
+      width: 100%; padding: 7px 9px; border-radius: 6px; border: 1px solid #2a3f6a;
+      background: #0f1a33; color: #eee; font-size: 13px; font-family: inherit;
+    }
+    .field input:focus, .field select:focus { outline: none; border-color: #4A90D9; }
+    .field.invalid input, .field.invalid select { border-color: #e0555a; }
+    .field input[type=checkbox] { width: 16px; height: 16px; accent-color: #4A90D9; }
+    #actions { display: flex; align-items: center; gap: 14px; margin-top: 4px; }
+    button.primary { padding: 9px 20px; border-radius: 8px; border: none; background: #4A90D9; color: #fff; font-size: 13px; cursor: pointer; }
+    button.primary:hover { background: #5a9fe0; }
+    button.primary:disabled { opacity: .5; cursor: default; }
+    #banner { display: none; padding: 10px 14px; border-radius: 8px; font-size: 13px; margin-bottom: 16px; white-space: pre-wrap; }
+    #banner.err { display: block; background: #3a1a1f; border: 1px solid #e0555a; color: #f0b3b6; }
+    #banner.ok { display: block; background: #16332a; border: 1px solid #3fae7a; color: #a8e6c4; }
+
+    /* Projects */
+    #cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 14px; }
+    .card { background: #16213e; border: 1px solid #0f3460; border-radius: 10px; padding: 14px 16px; }
+    .card h3 { font-size: 14px; margin-bottom: 4px; }
+    .card .chunks { font-size: 11px; color: #4A90D9; margin-bottom: 8px; }
+    .card .stack { font-size: 12px; color: #8ab; margin-bottom: 6px; }
+    .card .descr { font-size: 12px; color: #99a; line-height: 1.4; }
+    .card .rel { font-size: 11px; color: #778; margin-top: 8px; }
+    .empty { color: #667; font-size: 13px; padding: 20px 0; }
+
+    /* Graph — embeds the full standalone graph page (/graph) in an iframe, so
+       the filters/legend/project-list sidebar comes for free. A definite height
+       is required; a flex/percentage height would collapse the iframe. */
+    #graph-frame { width: 100%; height: calc(100vh - 130px); border: 1px solid #0f3460; border-radius: 10px; background: #131a30; display: block; }
+  </style>
+</head>
+<body>
+  <div id="header">
+    <h1>RAG Dashboard</h1>
+    <div id="tabs">
+      <button class="tab active" data-tab="config">Config</button>
+      <button class="tab" data-tab="projects">Projects</button>
+      <button class="tab" data-tab="graph">Graph</button>
+    </div>
+  </div>
+  <div id="main">
+    <div class="panel active" id="config-panel">
+      <div id="banner"></div>
+      <form id="config-form"></form>
+      <div id="actions">
+        <button class="primary" id="save-btn" type="button">Save</button>
+        <span id="save-hint" style="font-size:12px;color:#667"></span>
+      </div>
+    </div>
+    <div class="panel" id="projects-panel">
+      <div id="cards"></div>
+    </div>
+    <div class="panel" id="graph-panel">
+      <iframe id="graph-frame" title="Project dependency graph"></iframe>
+    </div>
+  </div>
+
+  <script>
+  const MASK = '********';
+  let schema = null;
+  let config = null;
+  let defaults = {};
+  let fieldOptions = {};
+  let graphLoaded = false;
+
+  // ---- tabs ----
+  document.querySelectorAll('.tab').forEach(btn => {
+    btn.addEventListener('click', () => {
+      document.querySelectorAll('.tab').forEach(b => b.classList.remove('active'));
+      document.querySelectorAll('.panel').forEach(p => p.classList.remove('active'));
+      btn.classList.add('active');
+      const tab = btn.dataset.tab;
+      document.getElementById(tab + '-panel').classList.add('active');
+      if (tab === 'projects') loadProjects();
+      if (tab === 'graph') loadGraph();
+    });
+  });
+
+  // ---- config form ----
+  function nested(obj, path) {
+    return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+  }
+
+  function fmtDefault(v) {
+    if (v === '') return "'' (empty)";
+    return String(v);
+  }
+
+  // A dropdown limited to the given values. Preserves an unknown current value
+  // as an extra option so saving never silently drops it.
+  function selectEl(key, values, value, def) {
+    const sel = document.createElement('select');
+    sel.dataset.key = key; sel.dataset.type = 'string';
+    const blank = document.createElement('option');
+    blank.value = ''; blank.textContent = def !== undefined ? '(default: ' + def + ')' : '(default)';
+    sel.appendChild(blank);
+    const all = values.slice();
+    if (value && !all.includes(value)) all.unshift(value);
+    all.forEach(v => {
+      const o = document.createElement('option'); o.value = v; o.textContent = v;
+      if (value === v) o.selected = true;
+      sel.appendChild(o);
+    });
+    return sel;
+  }
+
+  // Free-text input with a datalist of suggestions (combobox).
+  function comboEl(key, values, value, def) {
+    const frag = document.createDocumentFragment();
+    const inp = document.createElement('input');
+    inp.type = 'text'; inp.dataset.key = key; inp.dataset.type = 'string';
+    const listId = 'dl-' + key.replace(/\\./g, '-');
+    inp.setAttribute('list', listId);
+    if (value !== undefined && value !== null) inp.value = value;
+    else if (def !== undefined && def !== '') inp.placeholder = String(def);
+    const dl = document.createElement('datalist'); dl.id = listId;
+    values.forEach(v => { const o = document.createElement('option'); o.value = v; dl.appendChild(o); });
+    frag.appendChild(inp); frag.appendChild(dl);
+    return frag;
+  }
+
+  function fieldInput(key, spec, value, def) {
+    const isUnset = value === undefined || value === null;
+    const opt = fieldOptions[key];
+    if (opt) return opt.strict ? selectEl(key, opt.values, value, def) : comboEl(key, opt.values, value, def);
+    const enumVals = spec.enum;
+    if (spec.type === 'boolean') {
+      const cb = document.createElement('input');
+      cb.type = 'checkbox'; cb.dataset.key = key; cb.dataset.type = 'boolean';
+      cb.checked = value === true;
+      return cb;
+    }
+    if (Array.isArray(enumVals)) return selectEl(key, enumVals, value, def);
+    const inp = document.createElement('input');
+    const isNum = spec.type === 'number' || spec.type === 'integer';
+    inp.dataset.key = key;
+    inp.dataset.type = isNum ? 'number' : 'string';
+    if (key === 'db.password') inp.type = 'password';
+    else if (isNum) {
+      inp.type = 'number';
+      // Only apply small, meaningful bounds (skip zod's safe-integer noise).
+      if (typeof spec.minimum === 'number' && Math.abs(spec.minimum) < 1e6) inp.min = spec.minimum;
+      if (typeof spec.maximum === 'number' && Math.abs(spec.maximum) < 1e6) inp.max = spec.maximum;
+      if (spec.maximum === 1) inp.step = '0.05';
+    } else inp.type = 'text';
+    if (!isUnset) inp.value = value;
+    // Show the applied default as placeholder when the field is left unset.
+    else if (def !== undefined && def !== '') inp.placeholder = String(def);
+    return inp;
+  }
+
+  function renderField(container, key, spec, value, def) {
+    const isUnset = value === undefined || value === null;
+    const wrap = document.createElement('div');
+    wrap.className = 'field'; wrap.dataset.fieldKey = key;
+    const label = document.createElement('label');
+    let html = key.split('.').pop();
+    if (spec.description) html += '<span class="desc">' + spec.description + '</span>';
+    if (def !== undefined) {
+      html += '<span class="defval' + (isUnset ? ' using' : '') + '">'
+        + (isUnset ? '↪ using default: ' : 'default: ') + fmtDefault(def) + '</span>';
+    }
+    label.innerHTML = html;
+    wrap.appendChild(label);
+    wrap.appendChild(fieldInput(key, spec, value, def));
+    container.appendChild(wrap);
+  }
+
+  function renderForm() {
+    const form = document.getElementById('config-form');
+    form.innerHTML = '';
+    const props = schema.properties || {};
+    for (const [group, gspec] of Object.entries(props)) {
+      const sec = document.createElement('div'); sec.className = 'section';
+      const h = document.createElement('h2'); h.textContent = group; sec.appendChild(h);
+      if (gspec.type === 'object' && gspec.properties) {
+        for (const [field, fspec] of Object.entries(gspec.properties)) {
+          const key = group + '.' + field;
+          renderField(sec, key, fspec, nested(config, key), defaults[key]);
+        }
+      } else {
+        renderField(sec, group, gspec, nested(config, group), defaults[group]);
+      }
+      form.appendChild(sec);
+    }
+  }
+
+  function collectForm() {
+    const out = {};
+    document.querySelectorAll('[data-key]').forEach(el => {
+      const key = el.dataset.key, type = el.dataset.type;
+      let val;
+      if (type === 'boolean') val = el.checked;
+      else if (el.value === '') return; // unset → omit (stay minimal)
+      else if (type === 'number') { const n = Number(el.value); if (Number.isNaN(n)) return; val = n; }
+      else val = el.value;
+      const parts = key.split('.');
+      if (parts.length === 1) out[parts[0]] = val;
+      else { (out[parts[0]] = out[parts[0]] || {})[parts[1]] = val; }
+    });
+    return out;
+  }
+
+  function showBanner(cls, msg) {
+    const b = document.getElementById('banner');
+    b.className = cls; b.textContent = msg;
+  }
+  function clearInvalid() {
+    document.querySelectorAll('.field.invalid').forEach(f => f.classList.remove('invalid'));
+  }
+
+  async function save() {
+    clearInvalid();
+    const btn = document.getElementById('save-btn');
+    btn.disabled = true;
+    try {
+      const res = await fetch('/api/config', {
+        method: 'PUT', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(collectForm()),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        showBanner('ok', 'Saved.');
+        await loadConfig(); // refresh (re-mask password, normalize)
+      } else {
+        showBanner('err', data.error || 'Validation failed');
+        // best-effort inline highlight: mark fields whose key appears in the message
+        document.querySelectorAll('[data-field-key]').forEach(f => {
+          if ((data.error || '').includes(f.dataset.fieldKey)) f.classList.add('invalid');
+        });
+      }
+    } catch (e) {
+      showBanner('err', 'Request failed: ' + e.message);
+    } finally {
+      btn.disabled = false;
+    }
+  }
+  document.getElementById('save-btn').addEventListener('click', save);
+
+  async function loadConfig() {
+    [schema, config, defaults, fieldOptions] = await Promise.all([
+      fetch('/api/schema').then(r => r.json()),
+      fetch('/api/config').then(r => r.json()),
+      fetch('/api/defaults').then(r => r.json()),
+      fetch('/api/field-options').then(r => r.json()),
+    ]);
+    config = config || {};
+    defaults = defaults || {};
+    fieldOptions = fieldOptions || {};
+    renderForm();
+  }
+
+  // ---- projects ----
+  async function loadProjects() {
+    const cards = document.getElementById('cards');
+    cards.innerHTML = '<div class="empty">Loading…</div>';
+    try {
+      const projects = await fetch('/api/projects').then(r => r.json());
+      if (!projects.length) { cards.innerHTML = '<div class="empty">No indexed projects.</div>'; return; }
+      cards.innerHTML = '';
+      projects.forEach(p => {
+        const rel = p.relations ? Object.entries(p.relations)
+          .map(([k, v]) => k + ': ' + (Array.isArray(v) ? v.join(', ') : v)).join(' · ') : '';
+        const card = document.createElement('div'); card.className = 'card';
+        card.innerHTML =
+          '<h3></h3><div class="chunks"></div>' +
+          (p.stack ? '<div class="stack"></div>' : '') +
+          (p.description ? '<div class="descr"></div>' : '') +
+          (rel ? '<div class="rel"></div>' : '');
+        card.querySelector('h3').textContent = p.serviceName;
+        card.querySelector('.chunks').textContent = p.chunks + ' chunks';
+        if (p.stack) card.querySelector('.stack').textContent = p.stack;
+        if (p.description) card.querySelector('.descr').textContent = p.description;
+        if (rel) card.querySelector('.rel').textContent = rel;
+        cards.appendChild(card);
+      });
+    } catch (e) {
+      cards.innerHTML = '<div class="empty">Failed to load projects: ' + e.message + '</div>';
+    }
+  }
+
+  // ---- graph ----
+  // Reuse the full standalone graph page (same HTML as project-graph.html) via
+  // an iframe instead of re-implementing the network here. Loaded lazily on the
+  // first Graph-tab open so the graph page isn't fetched until needed.
+  function loadGraph() {
+    if (graphLoaded) return;
+    graphLoaded = true;
+    document.getElementById('graph-frame').src = '/graph';
+  }
+
+  loadConfig().catch(e => showBanner('err', 'Failed to load config: ' + e.message));
+  </script>
+</body>
+</html>`;
+}

package/docs/web-dashboard.md

@@ -0,0 +1,187 @@
+# 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 **Ollama** 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 } }`:
+
+- **`ollama.model` — strict.** The embedding model is tied to the vector column
+  dimension (`bge-m3` → 1024). Values come from `SUPPORTED_EMBED_MODELS`
+  (`src/constants.ts`); the dropdown does **not** allow free text, so a
+  dimension-incompatible model cannot be set. To add a model, confirm its
+  dimension matches and append it to `SUPPORTED_EMBED_MODELS`.
+- **`search.translateModel`, `reranker.model` — non-strict.** Suggestions are the
+  user's installed Ollama models (`ollama.list()`), but free text is allowed
+  because these are not dimension-bound and the user may pull a new model later.
+  If Ollama is unreachable the list is empty and the field degrades to plain
+  text.
+
+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}` or `400 {error}` |
+| `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 |
+
+---
+
+## 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)` — `node:http` server, routing, and the API handlers. Exports the pure `mergeConfigForSave()` and the `FieldOption` type. |
+| `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`
+- `SUPPORTED_EMBED_MODELS` — `src/constants.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.)
+- `SUPPORTED_EMBED_MODELS` (`constants.ts`) must contain only models whose
+  embedding dimension matches the `vector(...)` column — this one is still a
+  manual invariant, guarded only at the membership level by a unit test.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesearch-mcp",
-  "version": "0.0.17-alpha",
+  "version": "0.0.18-alpha",
   "description": "Local semantic codebase search via MCP — indexes projects into pgvector, exposes search to Claude",
   "license": "MIT",
   "main": "dist/app.js",
@@ -8,11 +8,13 @@
     "rag-index": "dist/app.js",
     "rag-mcp": "dist/app.js",
     "rag-setup": "dist/app.js",
-    "rag-config": "dist/app.js"
+    "rag-config": "dist/app.js",
+    "rag-web": "dist/app.js"
   },
   "files": [
     "dist/",
     "docker/",
+    "docs/",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -21,6 +23,7 @@
     "postbuild": "node -e \"const fs=require('fs');const f='dist/app.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'));fs.chmodSync(f,0o755);\"",
     "prepublishOnly": "npm run build && npm run typecheck",
     "start:mcp": "ts-node app.ts mcp",
+    "start:web": "ts-node app.ts web",
     "index:workspace": "ts-node app.ts index",
     "index:reindex": "ts-node app.ts index --reindex",
     "index:backfill": "ts-node app.ts backfill",