@skill-map/cli 0.10.0 → 0.11.0

package/dist/cli.js

@@ -409,11 +409,11 @@ function buildIgnoreFilter(opts = {}) {
     ig.add(opts.ignoreFileText);
   }
   return {
-    ignores(relativePath) {
-      if (relativePath === "" || relativePath === "." || relativePath === "./") {
+    ignores(relativePath2) {
+      if (relativePath2 === "" || relativePath2 === "." || relativePath2 === "./") {
         return false;
       }
-      const normalised = relativePath.replace(/^\.\//, "").replace(/\\/g, "/").replace(/^\//, "");
+      const normalised = relativePath2.replace(/^\.\//, "").replace(/\\/g, "/").replace(/^\//, "");
       if (normalised === "") return false;
       return ig.ignores(normalised);
     }
@@ -624,31 +624,79 @@ var claudeProvider = {
   // pairs the relative manifest-style schema path (mirrors what the
   // spec's provider.schema.json validates) with the loaded JSON Schema
   // (`schemaJson`) the kernel registers with AJV at scan boot.
+  // Step 14.5.d: each kind declares its UI presentation (label, color,
+  // dark variant, icon). The UI consumes this registry via the
+  // `kindRegistry` field embedded in REST envelopes; it derives bg/fg
+  // tints from `color` per theme via a deterministic helper, so the
+  // Provider only declares intent (one base color per theme) instead of
+  // four hex values. Colors and SVG paths transplanted verbatim from
+  // the previous static UI catalog (`ui/src/styles.css` for hex,
+  // `ui/src/app/components/kind-icon/kind-icon.html` for SVG path data,
+  // `ui/src/i18n/kinds.texts.ts` for labels).
   kinds: {
     agent: {
       schema: "./schemas/agent.schema.json",
       schemaJson: agent_schema_default,
-      defaultRefreshAction: "claude/summarize-agent"
+      defaultRefreshAction: "claude/summarize-agent",
+      ui: {
+        label: "Agents",
+        color: "#3b82f6",
+        colorDark: "#60a5fa",
+        icon: { kind: "pi", id: "pi-user" }
+      }
     },
     command: {
       schema: "./schemas/command.schema.json",
       schemaJson: command_schema_default,
-      defaultRefreshAction: "claude/summarize-command"
+      defaultRefreshAction: "claude/summarize-command",
+      ui: {
+        label: "Commands",
+        color: "#f59e0b",
+        colorDark: "#fbbf24",
+        icon: {
+          kind: "svg",
+          path: "M4 17 L10 11 L4 5 M12 19 L20 19"
+        }
+      }
     },
     hook: {
       schema: "./schemas/hook.schema.json",
       schemaJson: hook_schema_default,
-      defaultRefreshAction: "claude/summarize-hook"
+      defaultRefreshAction: "claude/summarize-hook",
+      ui: {
+        label: "Hooks",
+        color: "#8b5cf6",
+        colorDark: "#a78bfa",
+        icon: {
+          kind: "svg",
+          path: "M12 2 a3 3 0 1 0 0 6 a3 3 0 1 0 0 -6 M12 8 L12 22 M5 12 H2 a10 10 0 0 0 20 0 H19"
+        }
+      }
     },
     skill: {
       schema: "./schemas/skill.schema.json",
       schemaJson: skill_schema_default,
-      defaultRefreshAction: "claude/summarize-skill"
+      defaultRefreshAction: "claude/summarize-skill",
+      ui: {
+        label: "Skills",
+        color: "#10b981",
+        colorDark: "#34d399",
+        icon: { kind: "pi", id: "pi-bolt" }
+      }
     },
     note: {
       schema: "./schemas/note.schema.json",
       schemaJson: note_schema_default,
-      defaultRefreshAction: "claude/summarize-note"
+      defaultRefreshAction: "claude/summarize-note",
+      ui: {
+        label: "Notes",
+        color: "#5b908c",
+        colorDark: "#9bbcb8",
+        icon: {
+          kind: "svg",
+          path: "M14 2 H6 a2 2 0 0 0 -2 2 V20 a2 2 0 0 0 2 2 H18 a2 2 0 0 0 2 -2 V8 L14 2 M14 2 V8 H20 M16 13 H8 M16 17 H8 M10 9 H8"
+        }
+      }
     }
   },
   async *walk(roots, options = {}) {
@@ -6980,7 +7028,7 @@ import { Command as Command8, Option as Option8 } from "clipanion";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.10.0",
+  version: "0.11.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -9208,8 +9256,8 @@ function renderTable(rows) {
     HISTORY_TEXTS.tableHeaderTokens,
     HISTORY_TEXTS.tableHeaderNodes
   );
-  const sep4 = "-".repeat(header.length);
-  const lines = [header, sep4];
+  const sep5 = "-".repeat(header.length);
+  const lines = [header, sep5];
   for (const r of rows) {
     const tokens = `${r.tokensIn ?? 0}/${r.tokensOut ?? 0}`;
     const duration = r.durationMs === null || r.durationMs === void 0 ? "-" : formatElapsed(r.durationMs);
@@ -9618,8 +9666,8 @@ function renderTable2(nodes, issuesByNode) {
     LIST_TEXTS.tableHeaderIssues,
     LIST_TEXTS.tableHeaderBytes
   );
-  const sep4 = "-".repeat(header.length);
-  const lines = [header, sep4];
+  const sep5 = "-".repeat(header.length);
+  const lines = [header, sep5];
   for (const node of nodes) {
     lines.push(
       formatRow2(
@@ -11813,8 +11861,178 @@ import { WebSocketServer } from "ws";
 
 // server/app.ts
 import { Hono } from "hono";
+import { HTTPException as HTTPException5 } from "hono/http-exception";
+
+// server/routes/config.ts
 import { HTTPException } from "hono/http-exception";
 
+// server/envelope.ts
+var REST_ENVELOPE_SCHEMA_VERSION = "1";
+function buildListEnvelope(opts) {
+  const counts = {
+    total: opts.total,
+    returned: opts.items.length
+  };
+  if (opts.page) counts.page = opts.page;
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind: opts.kind,
+    items: opts.items,
+    filters: opts.filters,
+    counts,
+    kindRegistry: opts.kindRegistry
+  };
+}
+function buildValueEnvelope(kind, value, kindRegistry) {
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind,
+    value,
+    kindRegistry
+  };
+}
+
+// server/routes/config.ts
+function registerConfigRoute(app, deps) {
+  app.get("/api/config", (c) => {
+    let loaded;
+    try {
+      loaded = loadConfig({
+        scope: deps.options.scope,
+        cwd: deps.runtimeContext.cwd,
+        homedir: deps.runtimeContext.homedir
+      });
+    } catch (err) {
+      throw new HTTPException(500, { message: formatErrorMessage(err) });
+    }
+    for (const warn of loaded.warnings) {
+      process.stderr.write(`${warn}
+`);
+    }
+    return c.json(buildValueEnvelope("config", loaded.effective, deps.kindRegistry));
+  });
+}
+
+// server/routes/graph.ts
+import { HTTPException as HTTPException2 } from "hono/http-exception";
+
+// server/i18n/server.texts.ts
+var SERVER_TEXTS = {
+  // Boot banner — printed by the server itself when it begins to listen.
+  // The CLI verb `sm serve` formats its own boot banner separately
+  // (SERVE_TEXTS.boot) so the two surfaces can diverge if needed.
+  listening: "skill-map server listening on http://{{host}}:{{port}}\n",
+  // UI bundle missing — non-fatal when the path was auto-resolved (the
+  // server keeps running with an inline placeholder at `/`). Becomes
+  // ExitCode.Error when `--ui-dist <path>` was explicit.
+  uiBundleMissing: 'skill-map server: UI bundle not found at {{path}} \u2014 serving inline placeholder at "/" (run "npm run build --workspace=ui" to populate).\n',
+  // Loopback-only deprecation hint — Decision #119. Logged once at boot
+  // when `--host` resolves to a non-loopback address. Multi-host serve
+  // re-opens post-v0.6.0.
+  hostNonLoopbackHint: "skill-map server: --host {{host}} is non-loopback \u2014 through v0.6.0 the BFF assumes loopback-only (no auth). See Decision #119 in ROADMAP.\n",
+  // Shutdown trace — printed by the close path so test runs that bring
+  // the server up and down have a clear marker.
+  closed: "skill-map server: closed.\n",
+  // ---- error envelope messages (Step 14.2) ---------------------------------
+  // Persisted scan absent and the route can't degrade to an empty result.
+  // Hint nudges the user toward `sm scan` so the SPA can call it via the
+  // CLI side-by-side with the server.
+  dbMissingHint: "No persisted scan available at {{path}}. Run `sm scan` to populate the DB.",
+  // `?fresh=1` was requested but the server was booted with --no-built-ins
+  // or --no-plugins. A fresh scan with neither pipeline yields an empty /
+  // partial result that would surprise the SPA. Reject up front.
+  freshScanRequiresPipeline: "?fresh=1 cannot run while the server was started with --no-built-ins or --no-plugins (would yield empty / partial results).",
+  // Unknown formatter on /api/graph — the user asked for a `format` value
+  // that no registered formatter advertises. Mirrors `sm graph`'s message.
+  graphUnknownFormat: 'Unknown graph format "{{format}}". Available: {{available}}.',
+  // Pagination caps on /api/nodes.
+  paginationLimitTooLarge: "limit={{value}} exceeds the maximum of {{max}}.",
+  paginationInvalidInteger: "{{name}}={{value}} is not a non-negative integer.",
+  // Node lookup miss on /api/nodes/:pathB64. Both the missing-node and
+  // the malformed-pathB64 cases funnel here — the client experience is
+  // the same (the resource isn't there).
+  nodeNotFound: 'No node with path "{{path}}".',
+  pathB64Malformed: "Malformed pathB64 \u2014 not a valid base64url-encoded node.path.",
+  // ---- WS broadcaster + watcher (Step 14.4.a) ------------------------------
+  // Logged once on watcher boot after chokidar's initial walk completes.
+  // Marks the broadcaster as armed and the live event stream as flowing.
+  watcherReady: 'skill-map server: watcher ready (roots="{{roots}}", debounceMs={{debounceMs}}).\n',
+  // Watcher boot failure inside `createServer`. Non-fatal — the REST
+  // surface stays alive so the operator can fix the underlying issue
+  // (config, plugin, FS permission) and restart.
+  watcherBootFailed: "skill-map server: watcher boot failed \u2014 {{message}}. /api/* still serving; pass --no-watcher to silence this on the next boot.\n",
+  // Per-batch failure inside the watcher's scan+persist pipeline. The
+  // watcher loop continues — a transient FS error must not kill the
+  // broadcaster.
+  watcherBatchFailed: "skill-map server: watcher batch failed \u2014 {{message}}.\n",
+  // chokidar surfaced an error. The watcher stays open per IFsWatcher's
+  // contract; the BFF also broadcasts a `watcher.error` advisory so the
+  // SPA can surface it in the live event log.
+  watcherError: "skill-map server: watcher error \u2014 {{message}}.\n",
+  // chokidar.close() rejected during graceful shutdown. Logged but not
+  // surfaced — close() is best-effort and idempotent.
+  watcherCloseFailed: "skill-map server: watcher close failed \u2014 {{message}}.\n",
+  // A connected client's outbound buffer exceeded the backpressure
+  // threshold. The broadcaster closes the client with code 1009 and
+  // unregisters it. Logged so operators can spot a wedged consumer.
+  wsBackpressureEvicted: "skill-map server: ws client evicted (bufferedAmount={{buffered}} > threshold={{threshold}}).\n",
+  // `WebSocket.send()` threw on a registered client. The client is
+  // unregistered; the broadcast continues with the remaining clients.
+  wsClientSendFailed: "skill-map server: ws send failed \u2014 {{message}}.\n",
+  // `JSON.stringify(envelope)` threw inside `broadcast()`. The event is
+  // dropped. Per spec/job-events.md §Error handling, the right shape
+  // is a synthetic `emitter.error` event; v14.4.a does not yet route
+  // it through the broadcaster (would re-enter the same stringify
+  // path), so we degrade to a logged warning.
+  wsBroadcastSerializeFailed: "skill-map server: ws broadcast dropped \u2014 failed to serialize event: {{message}}.\n"
+};
+
+// server/routes/graph.ts
+var DEFAULT_FORMAT2 = "ascii";
+function registerGraphRoute(app, deps) {
+  app.get("/api/graph", async (c) => {
+    const format = c.req.query("format") ?? DEFAULT_FORMAT2;
+    const pluginRuntime = deps.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: deps.options.scope });
+    for (const warn of pluginRuntime.warnings) {
+      process.stderr.write(`${warn}
+`);
+    }
+    const formatters = composeFormatters({
+      noBuiltIns: deps.options.noBuiltIns,
+      pluginRuntime
+    });
+    const formatter = formatters.find((f) => f.formatId === format);
+    if (!formatter) {
+      const available = formatters.map((f) => f.formatId).sort().join(", ");
+      throw new HTTPException2(400, {
+        message: tx(SERVER_TEXTS.graphUnknownFormat, {
+          format,
+          available: available || "(none)"
+        })
+      });
+    }
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.load()
+    );
+    const scan = loaded ?? { nodes: [], links: [], issues: [] };
+    const text = formatter.format({
+      nodes: scan.nodes,
+      links: scan.links,
+      issues: scan.issues
+    });
+    const body = text.endsWith("\n") ? text : text + "\n";
+    return c.body(body, 200, { "content-type": contentTypeFor(format) });
+  });
+}
+function contentTypeFor(format) {
+  if (format === "json") return "application/json; charset=utf-8";
+  if (format === "md" || format === "markdown" || format === "mermaid") {
+    return "text/markdown; charset=utf-8";
+  }
+  return "text/plain; charset=utf-8";
+}
+
 // server/health.ts
 import { existsSync as existsSync15 } from "fs";
 var FALLBACK_SCHEMA_VERSION = "1";
@@ -11838,9 +12056,435 @@ async function resolveSpecVersion2() {
   }
 }
 
+// server/routes/health.ts
+function registerHealthRoute(app, deps) {
+  app.get("/api/health", (c) => {
+    const payload = buildHealth({
+      dbPath: deps.options.dbPath,
+      scope: deps.options.scope,
+      specVersion: deps.specVersion
+    });
+    return c.json(payload);
+  });
+}
+
+// server/routes/issues.ts
+function registerIssuesRoute(app, deps) {
+  app.get("/api/issues", async (c) => {
+    const params = new URL(c.req.url).searchParams;
+    const severityFilter = parseCsv(params.get("severity"));
+    const ruleFilter = parseRulesFilter(params.get("ruleId"));
+    const nodePath = params.get("node");
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.issues.listAll()
+    );
+    const allIssues = loaded ?? [];
+    const filtered = allIssues.filter((issue) => {
+      if (severityFilter && !severityFilter.includes(issue.severity)) return false;
+      if (ruleFilter && !matchesRuleFilter2(issue.ruleId, ruleFilter)) return false;
+      if (nodePath !== null && !issue.nodeIds.includes(nodePath)) return false;
+      return true;
+    });
+    return c.json(
+      buildListEnvelope({
+        kind: "issues",
+        items: filtered,
+        filters: {
+          severity: severityFilter ?? null,
+          ruleId: ruleFilter ? [...ruleFilter] : null,
+          node: nodePath ?? null
+        },
+        total: filtered.length,
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function parseCsv(raw) {
+  if (raw === null) return null;
+  const list = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return list.length > 0 ? list : null;
+}
+function parseRulesFilter(raw) {
+  const list = parseCsv(raw);
+  return list ? new Set(list) : null;
+}
+function matchesRuleFilter2(ruleId, filter) {
+  if (filter.has(ruleId)) return true;
+  const slashIdx = ruleId.indexOf("/");
+  if (slashIdx >= 0) {
+    const short = ruleId.slice(slashIdx + 1);
+    if (filter.has(short)) return true;
+  }
+  return false;
+}
+
+// server/routes/links.ts
+function registerLinksRoute(app, deps) {
+  app.get("/api/links", async (c) => {
+    const params = new URL(c.req.url).searchParams;
+    const kindFilter = parseCsv2(params.get("kind"));
+    const from = params.get("from");
+    const to = params.get("to");
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.load()
+    );
+    const allLinks = loaded?.links ?? [];
+    const filtered = allLinks.filter((link2) => {
+      if (kindFilter && !kindFilter.includes(link2.kind)) return false;
+      if (from !== null && link2.source !== from) return false;
+      if (to !== null && link2.target !== to) return false;
+      return true;
+    });
+    return c.json(
+      buildListEnvelope({
+        kind: "links",
+        items: filtered,
+        filters: {
+          kind: kindFilter ?? null,
+          from: from ?? null,
+          to: to ?? null
+        },
+        total: filtered.length,
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function parseCsv2(raw) {
+  if (raw === null) return null;
+  const list = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return list.length > 0 ? list : null;
+}
+
+// server/routes/nodes.ts
+import { HTTPException as HTTPException3 } from "hono/http-exception";
+
+// server/node-body.ts
+import { readFile as readFile4 } from "fs/promises";
+import { isAbsolute as isAbsolute4, resolve as resolvePath, relative as relativePath, sep as sep4 } from "path";
+async function readNodeBody(cwd, relPath) {
+  if (isAbsolute4(relPath)) return null;
+  const absRoot = resolvePath(cwd);
+  const absFile = resolvePath(absRoot, relPath);
+  const rel = relativePath(absRoot, absFile);
+  if (rel.startsWith("..") || rel.startsWith(sep4) || rel.length === 0) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = await readFile4(absFile, "utf-8");
+  } catch (err) {
+    if (isExpectedFsError(err)) return null;
+    throw err;
+  }
+  return stripFrontmatter(raw);
+}
+function stripFrontmatter(raw) {
+  if (!raw.startsWith("---")) return raw;
+  const match = raw.match(/^---\r?\n[\s\S]*?^---\r?\n?/m);
+  if (!match) return raw;
+  return raw.slice(match[0].length);
+}
+var EXPECTED_FS_ERROR_CODES = /* @__PURE__ */ new Set(["ENOENT", "EACCES", "EISDIR", "ENOTDIR"]);
+function isExpectedFsError(err) {
+  if (err === null || typeof err !== "object") return false;
+  const code = err.code;
+  return typeof code === "string" && EXPECTED_FS_ERROR_CODES.has(code);
+}
+
+// server/path-codec.ts
+var PathCodecError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PathCodecError";
+  }
+};
+function encodeNodePath(path) {
+  return Buffer.from(path, "utf8").toString("base64url");
+}
+function decodeNodePath(encoded) {
+  if (encoded.length === 0) {
+    throw new PathCodecError("empty pathB64");
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded)) {
+    throw new PathCodecError("pathB64 contains characters outside the base64url alphabet");
+  }
+  const decoded = Buffer.from(encoded, "base64url").toString("utf8");
+  if (encodeNodePath(decoded) !== encoded) {
+    throw new PathCodecError("pathB64 did not round-trip cleanly through base64url");
+  }
+  return decoded;
+}
+
+// server/query-adapter.ts
+function urlParamsToExportQuery(params) {
+  const filters = {};
+  const tokens = [];
+  const kindRaw = params.get("kind");
+  if (kindRaw !== null) {
+    const kinds = splitCsv(kindRaw);
+    if (kinds.length === 0) {
+      throw new ExportQueryError("kind: empty value list");
+    }
+    filters.kinds = kinds;
+    tokens.push(`kind=${kinds.join(",")}`);
+  }
+  const hasIssuesRaw = params.get("hasIssues");
+  if (hasIssuesRaw !== null) {
+    const lower = hasIssuesRaw.toLowerCase();
+    if (lower === "true") {
+      filters.hasIssues = true;
+      tokens.push("has=issues");
+    } else if (lower === "false") {
+      filters.hasIssues = false;
+    } else {
+      throw new ExportQueryError(`hasIssues: expected "true" or "false", got "${hasIssuesRaw}"`);
+    }
+  }
+  const pathRaw = params.get("path");
+  if (pathRaw !== null) {
+    const globs = splitCsv(pathRaw);
+    if (globs.length === 0) {
+      throw new ExportQueryError("path: empty value list");
+    }
+    filters.pathGlobs = globs;
+    tokens.push(`path=${globs.join(",")}`);
+  }
+  const raw = tokens.join(" ");
+  const query = parseExportQuery(raw);
+  return { query, filters };
+}
+function filterNodesWithoutIssues(nodes, issues) {
+  if (issues.length === 0) return nodes;
+  const nodesWithIssues = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    for (const id of issue.nodeIds) nodesWithIssues.add(id);
+  }
+  return nodes.filter((n) => !nodesWithIssues.has(n.path));
+}
+function splitCsv(raw) {
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// server/routes/nodes.ts
+var DEFAULT_LIMIT = 100;
+var MAX_LIMIT = 1e3;
+function registerNodesRoutes(app, deps) {
+  app.get("/api/nodes/:pathB64", async (c) => {
+    const pathB64 = c.req.param("pathB64");
+    let nodePath;
+    try {
+      nodePath = decodeNodePath(pathB64);
+    } catch (err) {
+      if (err instanceof PathCodecError) {
+        throw new HTTPException3(404, { message: SERVER_TEXTS.pathB64Malformed });
+      }
+      throw err;
+    }
+    const bundle = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.findNode(nodePath)
+    );
+    if (!bundle) {
+      throw new HTTPException3(404, {
+        message: tx(SERVER_TEXTS.nodeNotFound, { path: nodePath })
+      });
+    }
+    const includes = parseIncludes(new URL(c.req.url).searchParams.get("include"));
+    const item = includes.has("body") ? { ...bundle.node, body: await readNodeBody(deps.runtimeContext.cwd, nodePath) } : bundle.node;
+    return c.json({
+      schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+      kind: "node",
+      item,
+      links: { incoming: bundle.linksIn, outgoing: bundle.linksOut },
+      issues: bundle.issues,
+      kindRegistry: deps.kindRegistry
+    });
+  });
+  app.get("/api/nodes", async (c) => {
+    const params = new URL(c.req.url).searchParams;
+    const { query, filters } = urlParamsToExportQuery(params);
+    const { offset, limit } = parsePagination(params);
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      (adapter) => adapter.scans.load()
+    );
+    const scan = loaded ?? { nodes: [], links: [], issues: [] };
+    const subset = applyExportQuery(scan, query);
+    let nodes = subset.nodes;
+    if (filters.hasIssues === false) {
+      nodes = filterNodesWithoutIssues(nodes, scan.issues);
+    }
+    const total = nodes.length;
+    const items = nodes.slice(offset, offset + limit);
+    return c.json(
+      buildListEnvelope({
+        kind: "nodes",
+        items,
+        filters: {
+          kind: filters.kinds ?? null,
+          hasIssues: filters.hasIssues ?? null,
+          path: filters.pathGlobs ?? null
+        },
+        total,
+        page: { offset, limit },
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function parsePagination(params) {
+  const offset = parseNonNegativeInt(params.get("offset"), "offset", 0);
+  const limit = parseNonNegativeInt(params.get("limit"), "limit", DEFAULT_LIMIT);
+  if (limit > MAX_LIMIT) {
+    throw new HTTPException3(400, {
+      message: tx(SERVER_TEXTS.paginationLimitTooLarge, { value: limit, max: MAX_LIMIT })
+    });
+  }
+  return { offset, limit };
+}
+function parseNonNegativeInt(raw, name, fallback) {
+  if (raw === null || raw.length === 0) return fallback;
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
+    throw new HTTPException3(400, {
+      message: tx(SERVER_TEXTS.paginationInvalidInteger, { name, value: raw })
+    });
+  }
+  return parsed;
+}
+function parseIncludes(raw) {
+  if (raw === null || raw.length === 0) return /* @__PURE__ */ new Set();
+  return new Set(raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0));
+}
+
+// server/routes/plugins.ts
+function registerPluginsRoute(app, deps) {
+  app.get("/api/plugins", async (c) => {
+    const pluginRuntime = deps.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: deps.options.scope });
+    for (const warn of pluginRuntime.warnings) {
+      process.stderr.write(`${warn}
+`);
+    }
+    const items = [
+      ...deps.options.noBuiltIns ? [] : buildBuiltInItems(pluginRuntime.resolveEnabled),
+      ...buildDiscoveredItems(pluginRuntime.discovered, deps)
+    ];
+    return c.json(
+      buildListEnvelope({
+        kind: "plugins",
+        items,
+        filters: {},
+        total: items.length,
+        kindRegistry: deps.kindRegistry
+      })
+    );
+  });
+}
+function buildBuiltInItems(resolveEnabled) {
+  return builtInBundles.map((bundle) => ({
+    id: bundle.id,
+    version: firstVersion(bundle.extensions),
+    kinds: uniqueKinds(bundle.extensions.map((e) => e.kind)),
+    status: resolveEnabled(bundle.id) ? "enabled" : "disabled",
+    reason: null,
+    source: "built-in"
+  }));
+}
+function buildDiscoveredItems(discovered, deps) {
+  return discovered.map((plugin) => ({
+    id: plugin.id,
+    version: plugin.manifest?.version ?? null,
+    kinds: uniqueKinds(plugin.extensions?.map((e) => e.kind) ?? []),
+    status: plugin.status,
+    reason: plugin.reason ?? null,
+    source: classifyPluginSource(plugin.path, deps)
+  }));
+}
+function uniqueKinds(kinds) {
+  return [...new Set(kinds)].sort();
+}
+function firstVersion(extensions) {
+  for (const ext of extensions) {
+    if (ext.version) return ext.version;
+  }
+  return null;
+}
+function classifyPluginSource(pluginPath, deps) {
+  const projectDir = defaultProjectPluginsDir(deps.runtimeContext);
+  return pluginPath.startsWith(projectDir) ? "project" : "global";
+}
+
+// server/routes/scan.ts
+import { HTTPException as HTTPException4 } from "hono/http-exception";
+function registerScanRoute(app, deps) {
+  app.get("/api/scan", async (c) => {
+    const fresh = c.req.query("fresh");
+    if (fresh === "1" || fresh === "true") {
+      return c.json(await runFreshScan(deps));
+    }
+    return c.json(await loadPersistedScan(deps));
+  });
+}
+async function loadPersistedScan(deps) {
+  const loaded = await tryWithSqlite(
+    { databasePath: deps.options.dbPath, autoBackup: false },
+    (adapter) => adapter.scans.load()
+  );
+  if (loaded !== null) return loaded;
+  return emptyScanResult();
+}
+async function runFreshScan(deps) {
+  if (deps.options.noBuiltIns || deps.options.noPlugins) {
+    throw new HTTPException4(400, { message: SERVER_TEXTS.freshScanRequiresPipeline });
+  }
+  const outcome = await runScanForCommand({
+    roots: [deps.runtimeContext.cwd],
+    noBuiltIns: false,
+    noPlugins: false,
+    noTokens: false,
+    dryRun: true,
+    changed: false,
+    allowEmpty: true,
+    strict: false,
+    stderr: process.stderr,
+    ctx: deps.runtimeContext
+  });
+  if (outcome.kind !== "ok") {
+    throw new HTTPException4(500, {
+      message: outcome.kind === "guard-trip" ? `fresh scan refused (existing rows: ${outcome.existing})` : outcome.message
+    });
+  }
+  return outcome.result;
+}
+function emptyScanResult() {
+  return {
+    schemaVersion: 1,
+    scannedAt: Date.now(),
+    scope: "project",
+    roots: ["."],
+    providers: [],
+    nodes: [],
+    links: [],
+    issues: [],
+    stats: {
+      filesWalked: 0,
+      filesSkipped: 0,
+      nodesCount: 0,
+      linksCount: 0,
+      issuesCount: 0,
+      durationMs: 0
+    }
+  };
+}
+
 // server/static.ts
 import { existsSync as existsSync16 } from "fs";
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { extname, join as join13 } from "path";
 import { serveStatic } from "@hono/node-server/serve-static";
 var INDEX_HTML = "index.html";
@@ -11914,10 +12558,48 @@ function htmlResponse(c, html) {
   return c.body(html, 200, { "content-type": "text/html; charset=UTF-8" });
 }
 async function fileResponse(c, absPath) {
-  const buf = await readFile4(absPath);
+  const buf = await readFile5(absPath);
   return c.body(buf, 200, { "content-type": mimeFor(absPath) });
 }
 
+// server/ws.ts
+import { upgradeWebSocket } from "@hono/node-server";
+var WS_PATH = "/ws";
+function attachBroadcasterRoute(app, broadcaster) {
+  app.get(
+    WS_PATH,
+    upgradeWebSocket(() => ({
+      onOpen(_event, ws) {
+        const raw = ws.raw;
+        if (!raw) {
+          broadcaster.register({
+            send: (data) => ws.send(data),
+            close: (code, reason) => ws.close(code, reason),
+            bufferedAmount: 0,
+            readyState: ws.readyState
+          });
+          return;
+        }
+        broadcaster.register(raw);
+      },
+      onClose(_event, ws) {
+        const raw = ws.raw;
+        if (raw) broadcaster.unregister(raw);
+      },
+      onError(event, ws) {
+        const raw = ws.raw;
+        if (raw) broadcaster.unregister(raw);
+        const message = event?.message ?? "unknown";
+        log.warn(
+          tx(SERVER_TEXTS.wsClientSendFailed, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+      }
+    }))
+  );
+}
+
 // server/app.ts
 function createApp(deps) {
   const app = new Hono();
@@ -11930,22 +12612,27 @@ function createApp(deps) {
     });
     app.options("*", (c) => c.body(null, 204));
   }
-  app.get("/api/health", (c) => {
-    const payload = buildHealth({
-      dbPath: deps.options.dbPath,
-      scope: deps.options.scope,
-      specVersion: deps.specVersion
-    });
-    return c.json(payload);
-  });
+  registerHealthRoute(app, { options: deps.options, specVersion: deps.specVersion });
+  const routeDeps = {
+    options: deps.options,
+    runtimeContext: deps.runtimeContext,
+    kindRegistry: deps.kindRegistry
+  };
+  registerScanRoute(app, routeDeps);
+  registerNodesRoutes(app, routeDeps);
+  registerLinksRoute(app, routeDeps);
+  registerIssuesRoute(app, routeDeps);
+  registerGraphRoute(app, routeDeps);
+  registerConfigRoute(app, routeDeps);
+  registerPluginsRoute(app, routeDeps);
   app.all("/api/*", (c) => {
-    throw new HTTPException(404, { message: `Unknown API endpoint: ${c.req.path}` });
+    throw new HTTPException5(404, { message: `Unknown API endpoint: ${c.req.path}` });
   });
-  deps.attachWs(app);
+  attachBroadcasterRoute(app, deps.broadcaster);
   app.use("*", createStaticHandler(deps.options.uiDist));
   app.get("*", createSpaFallback(deps.options.uiDist));
   app.notFound((c) => {
-    throw new HTTPException(404, { message: `Not found: ${c.req.path}` });
+    throw new HTTPException5(404, { message: `Not found: ${c.req.path}` });
   });
   app.onError((err, c) => {
     return formatError2(err, c);
@@ -11958,7 +12645,7 @@ function codeForStatus(status) {
   return "internal";
 }
 function formatError2(err, c) {
-  if (err instanceof HTTPException) {
+  if (err instanceof HTTPException5) {
     const status = err.status;
     const envelope2 = {
       ok: false,
@@ -11970,6 +12657,17 @@ function formatError2(err, c) {
     };
     return c.json(envelope2, status);
   }
+  if (err instanceof ExportQueryError) {
+    const envelope2 = {
+      ok: false,
+      error: {
+        code: "bad-query",
+        message: err.message,
+        details: null
+      }
+    };
+    return c.json(envelope2, 400);
+  }
   const envelope = {
     ok: false,
     error: {
@@ -11981,19 +12679,328 @@ function formatError2(err, c) {
   return c.json(envelope, 500);
 }
 
-// server/ws.ts
-import { upgradeWebSocket } from "@hono/node-server";
-var WS_PATH = "/ws";
-var NOOP_CLOSE_CODE = 1e3;
-var NOOP_CLOSE_REASON = "no broadcaster yet";
-function noopWebSocketRoute(app) {
-  app.get(
-    WS_PATH,
-    upgradeWebSocket(() => ({
-      onOpen(_event, ws) {
-        ws.close(NOOP_CLOSE_CODE, NOOP_CLOSE_REASON);
+// server/broadcaster.ts
+var MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
+var CLOSE_CODE_GOING_AWAY = 1001;
+var CLOSE_CODE_MESSAGE_TOO_BIG = 1009;
+var READY_STATE_OPEN = 1;
+var WsBroadcaster = class {
+  #clients = /* @__PURE__ */ new Set();
+  #shutDown = false;
+  /** Number of currently-registered clients. Read-only — for tests / `/api/health`. */
+  get clientCount() {
+    return this.#clients.size;
+  }
+  /**
+   * Register a client. Called from the `/ws` `onOpen` handler with the
+   * raw `WebSocket` instance. After shutdown the broadcaster refuses
+   * new registrations and immediately closes the offered socket so a
+   * late upgrade doesn't leak.
+   */
+  register(ws) {
+    if (this.#shutDown) {
+      try {
+        ws.close(CLOSE_CODE_GOING_AWAY, "server shutdown");
+      } catch {
       }
-    }))
+      return;
+    }
+    this.#clients.add(ws);
+  }
+  /**
+   * Unregister a client. Called from the `/ws` `onClose` / `onError`
+   * handlers and from the backpressure path. Idempotent — calling on a
+   * client that was never registered (or was already removed) is a no-op.
+   */
+  unregister(ws) {
+    this.#clients.delete(ws);
+  }
+  /**
+   * Serialize the envelope once and fan out to every open client.
+   * Closed / closing clients are silently skipped (the `onClose` handler
+   * has already removed them, but we double-check `readyState` because a
+   * close in the middle of the loop is observable as a transient
+   * `OPEN → CLOSING` flip).
+   *
+   * Per-client `send()` failures are caught: one rogue socket cannot
+   * stop the rest from receiving the event. A failing socket is closed
+   * + unregistered so the next broadcast doesn't waste cycles on it.
+   *
+   * Backpressure check (per AGENTS.md §Watcher integration): if a
+   * client's `bufferedAmount` exceeds `MAX_BUFFERED_BYTES`, it's evicted
+   * with close code 1009. The check runs BEFORE `send` so the threshold
+   * acts as an admission gate, not a post-mortem.
+   */
+  broadcast(envelope) {
+    if (this.#shutDown) return;
+    let payload;
+    try {
+      payload = JSON.stringify(envelope);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        tx(SERVER_TEXTS.wsBroadcastSerializeFailed, {
+          message: sanitizeForTerminal(message)
+        })
+      );
+      return;
+    }
+    const snapshot = Array.from(this.#clients);
+    for (const client of snapshot) {
+      this.#deliver(client, payload);
+    }
+  }
+  /**
+   * Drain every connected socket with code 1001 ('going away') + reason
+   * `'server shutdown'`. Idempotent — a second call after the first
+   * `shutdown()` is a no-op. After shutdown, `register()` immediately
+   * closes any new client offered.
+   */
+  shutdown() {
+    if (this.#shutDown) return;
+    this.#shutDown = true;
+    const snapshot = Array.from(this.#clients);
+    this.#clients.clear();
+    for (const client of snapshot) {
+      try {
+        client.close(CLOSE_CODE_GOING_AWAY, "server shutdown");
+      } catch {
+      }
+    }
+  }
+  /**
+   * Per-client delivery: backpressure check, then `send()`. Eviction +
+   * unregistration on either failure mode.
+   */
+  #deliver(client, payload) {
+    if (client.readyState !== READY_STATE_OPEN) {
+      this.#clients.delete(client);
+      return;
+    }
+    if (client.bufferedAmount > MAX_BUFFERED_BYTES) {
+      this.#clients.delete(client);
+      try {
+        client.close(CLOSE_CODE_MESSAGE_TOO_BIG, "backpressure exceeded");
+      } catch {
+      }
+      log.warn(
+        tx(SERVER_TEXTS.wsBackpressureEvicted, {
+          buffered: String(client.bufferedAmount),
+          threshold: String(MAX_BUFFERED_BYTES)
+        })
+      );
+      return;
+    }
+    try {
+      client.send(payload);
+    } catch (err) {
+      this.#clients.delete(client);
+      try {
+        client.close();
+      } catch {
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        tx(SERVER_TEXTS.wsClientSendFailed, {
+          message: sanitizeForTerminal(message)
+        })
+      );
+    }
+  }
+};
+
+// server/kind-registry.ts
+function buildKindRegistry(providers) {
+  const registry = {};
+  for (const provider of providers) {
+    for (const [kindName, kindEntry] of Object.entries(provider.kinds)) {
+      if (registry[kindName]) continue;
+      const ui = kindEntry.ui;
+      const entry = {
+        providerId: provider.id,
+        label: ui.label,
+        color: ui.color
+      };
+      if (ui.colorDark !== void 0) entry.colorDark = ui.colorDark;
+      if (ui.emoji !== void 0) entry.emoji = ui.emoji;
+      if (ui.icon !== void 0) entry.icon = ui.icon;
+      registry[kindName] = entry;
+    }
+  }
+  return registry;
+}
+
+// server/events.ts
+function buildWatcherStartedEvent(data) {
+  return {
+    type: "watcher.started",
+    timestamp: Date.now(),
+    jobId: null,
+    data
+  };
+}
+function buildWatcherErrorEvent(data) {
+  return {
+    type: "watcher.error",
+    timestamp: Date.now(),
+    jobId: null,
+    data
+  };
+}
+
+// server/watcher.ts
+var WATCH_ROOT = ".";
+function createWatcherService(opts) {
+  let chokidarHandle = null;
+  let stopped = false;
+  const start = async () => {
+    const cfg = loadConfig({
+      scope: opts.options.scope,
+      cwd: opts.runtimeContext.cwd,
+      homedir: opts.runtimeContext.homedir
+    }).effective;
+    const ignoreFileText = readIgnoreFileText(opts.runtimeContext.cwd);
+    const ignoreFilterOpts = {};
+    if (cfg.ignore.length > 0) ignoreFilterOpts.configIgnore = cfg.ignore;
+    if (ignoreFileText !== void 0) ignoreFilterOpts.ignoreFileText = ignoreFileText;
+    const ignoreFilter = buildIgnoreFilter(ignoreFilterOpts);
+    const debounceMs = opts.debounceMsOverride ?? cfg.scan.watch.debounceMs;
+    const pluginRuntime = opts.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: opts.options.scope });
+    for (const warn of pluginRuntime.warnings) {
+      log.warn(sanitizeForTerminal(warn));
+    }
+    const runOneBatch = async () => {
+      const kernel = createKernel();
+      registerKernelExtensions(kernel, pluginRuntime, opts.options.noBuiltIns);
+      const emitter = buildBroadcasterEmitter(opts.broadcaster);
+      const priorState = await loadPriorState(opts.options.dbPath);
+      const composed = composeScanExtensions({
+        noBuiltIns: opts.options.noBuiltIns,
+        pluginRuntime
+      });
+      const runOptions = assembleRunOptions({
+        scope: opts.options.scope,
+        tokenize: cfg.scan.tokenize !== false,
+        strict: cfg.scan.strict === true,
+        ignoreFilter,
+        emitter,
+        composed,
+        priorState
+      });
+      const ran = await runScanWithRenames(kernel, runOptions);
+      await persistOutcome(opts.options.dbPath, ran);
+    };
+    chokidarHandle = createChokidarWatcher({
+      roots: [WATCH_ROOT],
+      cwd: opts.runtimeContext.cwd,
+      debounceMs,
+      ignoreFilter,
+      onBatch: async () => {
+        if (stopped) return;
+        try {
+          await runOneBatch();
+        } catch (err) {
+          const message = formatErrorMessage(err);
+          log.warn(
+            tx(SERVER_TEXTS.watcherBatchFailed, {
+              message: sanitizeForTerminal(message)
+            })
+          );
+        }
+      },
+      onError: (err) => {
+        const message = err.message;
+        log.warn(
+          tx(SERVER_TEXTS.watcherError, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+        opts.broadcaster.broadcast(buildWatcherErrorEvent({ message }));
+      }
+    });
+    if ("ready" in chokidarHandle && chokidarHandle.ready instanceof Promise) {
+      await chokidarHandle.ready;
+    }
+    opts.broadcaster.broadcast(
+      buildWatcherStartedEvent({ roots: [WATCH_ROOT], debounceMs })
+    );
+    log.info(
+      tx(SERVER_TEXTS.watcherReady, {
+        roots: WATCH_ROOT,
+        debounceMs: String(debounceMs)
+      })
+    );
+  };
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    if (chokidarHandle) {
+      try {
+        await chokidarHandle.close();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warn(
+          tx(SERVER_TEXTS.watcherCloseFailed, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+      }
+      chokidarHandle = null;
+    }
+  };
+  return { start, stop };
+}
+function registerKernelExtensions(kernel, pluginRuntime, noBuiltIns) {
+  if (!noBuiltIns) {
+    const enabledBuiltIns = filterBuiltInManifests(
+      listBuiltIns(),
+      pluginRuntime.resolveEnabled
+    );
+    for (const manifest of enabledBuiltIns) kernel.registry.register(manifest);
+  }
+  for (const manifest of pluginRuntime.manifests) kernel.registry.register(manifest);
+}
+function buildBroadcasterEmitter(broadcaster) {
+  return {
+    emit(event) {
+      broadcaster.broadcast(event);
+    },
+    subscribe() {
+      return () => {
+      };
+    }
+  };
+}
+async function loadPriorState(dbPath) {
+  return tryWithSqlite({ databasePath: dbPath, autoBackup: false }, async (reader) => {
+    const loaded = await reader.scans.load();
+    if (loaded.nodes.length === 0) return null;
+    const extractorRuns = await reader.scans.loadExtractorRuns();
+    return { snapshot: loaded, extractorRuns };
+  });
+}
+function assembleRunOptions(args2) {
+  const runOptions = {
+    roots: [WATCH_ROOT],
+    scope: args2.scope,
+    tokenize: args2.tokenize,
+    ignoreFilter: args2.ignoreFilter,
+    strict: args2.strict,
+    emitter: args2.emitter
+  };
+  if (args2.composed) runOptions.extensions = args2.composed;
+  if (args2.priorState) {
+    runOptions.priorSnapshot = args2.priorState.snapshot;
+    runOptions.enableCache = true;
+    runOptions.priorExtractorRuns = args2.priorState.extractorRuns;
+  }
+  return runOptions;
+}
+async function persistOutcome(dbPath, ran) {
+  const { result, renameOps, extractorRuns, enrichments } = ran;
+  await withSqlite(
+    { databasePath: dbPath },
+    (writer) => writer.scans.persist(result, { renameOps, extractorRuns, enrichments })
   );
 }
 
@@ -12013,20 +13020,26 @@ function validateServerOptions(input) {
   if (scopeError !== null) return { ok: false, error: scopeError };
   const hostError = validateHost(filled.host, filled.devCors);
   if (hostError !== null) return { ok: false, error: hostError };
-  return {
-    ok: true,
-    options: {
-      port: filled.port,
-      host: filled.host,
-      scope: filled.scope,
-      dbPath: input.dbPath,
-      uiDist: filled.uiDist,
-      noBuiltIns: filled.noBuiltIns,
-      noPlugins: filled.noPlugins,
-      open: filled.open,
-      devCors: filled.devCors
-    }
+  const watcherError = validateWatcher(filled.noWatcher, filled.noBuiltIns, filled.noPlugins);
+  if (watcherError !== null) return { ok: false, error: watcherError };
+  const debounceError = validateWatcherDebounce(input.watcherDebounceMs);
+  if (debounceError !== null) return { ok: false, error: debounceError };
+  const options = {
+    port: filled.port,
+    host: filled.host,
+    scope: filled.scope,
+    dbPath: input.dbPath,
+    uiDist: filled.uiDist,
+    noBuiltIns: filled.noBuiltIns,
+    noPlugins: filled.noPlugins,
+    open: filled.open,
+    devCors: filled.devCors,
+    noWatcher: filled.noWatcher
   };
+  if (input.watcherDebounceMs !== void 0) {
+    options.watcherDebounceMs = input.watcherDebounceMs;
+  }
+  return { ok: true, options };
 }
 function applyDefaults(input) {
   return {
@@ -12037,7 +13050,8 @@ function applyDefaults(input) {
     noBuiltIns: input.noBuiltIns ?? false,
     noPlugins: input.noPlugins ?? false,
     open: input.open ?? true,
-    devCors: input.devCors ?? false
+    devCors: input.devCors ?? false,
+    noWatcher: input.noWatcher ?? false
   };
 }
 function validatePort(port) {
@@ -12069,10 +13083,32 @@ function validateHost(host, devCors) {
   }
   return null;
 }
+function validateWatcher(noWatcher, noBuiltIns, _noPlugins) {
+  if (noWatcher) return null;
+  if (noBuiltIns) {
+    return {
+      code: "watcher-requires-pipeline",
+      message: "the watcher cannot run with --no-built-ins (would persist empty scans on every batch). Pass --no-watcher to opt out, or drop --no-built-ins.",
+      value: "no-built-ins"
+    };
+  }
+  return null;
+}
+function validateWatcherDebounce(value) {
+  if (value === void 0) return null;
+  if (!Number.isInteger(value) || value < 0) {
+    return {
+      code: "watcher-debounce-invalid",
+      message: `--watcher-debounce-ms must be a non-negative integer (got ${value})`,
+      value: String(value)
+    };
+  }
+  return null;
+}
 
 // server/paths.ts
 import { existsSync as existsSync17, statSync as statSync5 } from "fs";
-import { dirname as dirname9, isAbsolute as isAbsolute4, join as join14, resolve as resolve19 } from "path";
+import { dirname as dirname9, isAbsolute as isAbsolute5, join as join14, resolve as resolve19 } from "path";
 var DEFAULT_UI_REL = join14("ui", "dist", "browser");
 var INDEX_HTML2 = "index.html";
 function resolveDefaultUiDist(ctx) {
@@ -12087,7 +13123,7 @@ function resolveDefaultUiDist(ctx) {
   return null;
 }
 function resolveExplicitUiDist(ctx, raw) {
-  return isAbsolute4(raw) ? raw : resolve19(ctx.cwd, raw);
+  return isAbsolute5(raw) ? raw : resolve19(ctx.cwd, raw);
 }
 function isUiBundleDir(path) {
   if (!existsSync17(path)) return false;
@@ -12100,21 +13136,74 @@ function isUiBundleDir(path) {
 }
 
 // server/index.ts
-async function createServer(options) {
+async function createServer(options, extra = {}) {
   const specVersion = await resolveSpecVersion2();
-  const app = createApp({ options, specVersion, attachWs: noopWebSocketRoute });
+  const runtimeContext = extra.runtimeContext ?? defaultRuntimeContext();
+  const broadcaster = new WsBroadcaster();
+  const kindRegistry = await assembleKindRegistry(options);
+  const app = createApp({
+    options,
+    specVersion,
+    broadcaster,
+    runtimeContext,
+    kindRegistry
+  });
   const wss = new WebSocketServer({ noServer: true });
   const server = await listenAsync(app.fetch, wss, options.host, options.port);
   const addr = server.address();
   const address = normalizeAddress(addr, options.host, options.port);
+  let watcherService = null;
+  if (!options.noWatcher) {
+    const debounce = options.watcherDebounceMs;
+    const svcOpts = {
+      options,
+      runtimeContext,
+      broadcaster
+    };
+    if (debounce !== void 0) svcOpts.debounceMsOverride = debounce;
+    const candidate = createWatcherService(svcOpts);
+    try {
+      await candidate.start();
+      watcherService = candidate;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        tx(SERVER_TEXTS.watcherBootFailed, {
+          message: sanitizeForTerminal(message)
+        })
+      );
+      try {
+        await candidate.stop();
+      } catch {
+      }
+    }
+  }
   let closed = false;
   const close = async () => {
     if (closed) return;
     closed = true;
+    if (watcherService) {
+      try {
+        await watcherService.stop();
+      } catch {
+      }
+    }
+    broadcaster.shutdown();
     await closeServer(server);
     wss.close();
   };
-  return { address, close };
+  return { address, close, broadcaster };
+}
+async function assembleKindRegistry(options) {
+  const pluginRuntime = options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: options.scope });
+  for (const warn of pluginRuntime.warnings) {
+    log.warn(sanitizeForTerminal(warn));
+  }
+  const composed = composeScanExtensions({
+    noBuiltIns: options.noBuiltIns,
+    pluginRuntime
+  });
+  return buildKindRegistry(composed?.providers ?? []);
 }
 function listenAsync(fetchCallback, wss, host, port) {
   return new Promise((resolveListen, rejectListen) => {
@@ -12183,6 +13272,9 @@ var SERVE_TEXTS = {
   portOutOfRange: "sm serve: --port must be an integer in [0, 65535] (got {{value}}).\n",
   portInvalid: "sm serve: --port must be a non-negative integer (got {{value}}).\n",
   scopeInvalid: 'sm serve: --scope must be "project" or "global" (got {{value}}).\n',
+  // Watcher option failures — ExitCode.Error.
+  watcherRequiresPipeline: "sm serve: --no-built-ins is incompatible with the watcher (would persist empty scans on every batch). Pass --no-watcher to opt out, or drop --no-built-ins.\n",
+  watcherDebounceInvalid: "sm serve: --watcher-debounce-ms must be a non-negative integer (got {{value}}).\n",
   // Generic operational error — surfaced when the server itself throws
   // before the listener binds (e.g. UI bundle missing under explicit
   // --ui-dist).
@@ -12257,6 +13349,13 @@ var ServeCommand = class extends SmCommand {
   // need it). Clipanion still exposes it on the parser; the Usage
   // omission is the "hidden" contract per the 14.1 brief.
   uiDist = Option19.String("--ui-dist", { required: false, hidden: true });
+  noWatcher = Option19.Boolean("--no-watcher", false, {
+    description: "Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments."
+  });
+  // `--watcher-debounce-ms` is undocumented sugar for advanced users
+  // who want to tighten / relax the watcher's batching window without
+  // editing settings.json. Hidden flag — the Usage block omits it.
+  watcherDebounceMs = Option19.String("--watcher-debounce-ms", { required: false, hidden: true });
   // Long-running daemon — `done in <…>` after a graceful shutdown is
   // noise. Mirrors `sm watch`'s opt-out.
   emitElapsed = false;
@@ -12297,6 +13396,15 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
+    const debounceResult = parseDebounce(this.watcherDebounceMs);
+    if (!debounceResult.ok) {
+      this.context.stderr.write(
+        tx(SERVE_TEXTS.watcherDebounceInvalid, {
+          value: sanitizeForTerminal(debounceResult.value)
+        })
+      );
+      return ExitCode.Error;
+    }
     const input = {
       dbPath,
       scope,
@@ -12304,10 +13412,12 @@ var ServeCommand = class extends SmCommand {
       noBuiltIns: this.noBuiltIns,
       noPlugins: this.noPlugins,
       open: this.open,
-      devCors: this.devCors
+      devCors: this.devCors,
+      noWatcher: this.noWatcher
     };
     if (portResult.port !== void 0) input.port = portResult.port;
     if (this.host !== void 0) input.host = this.host;
+    if (debounceResult.value !== void 0) input.watcherDebounceMs = debounceResult.value;
     const validation = validateServerOptions(input);
     if (!validation.ok) {
       this.context.stderr.write(formatValidationError(validation.error));
@@ -12360,6 +13470,15 @@ function parsePort(raw) {
   }
   return { ok: true, port: parsed };
 }
+function parseDebounce(raw) {
+  if (raw === void 0) return { ok: true, value: void 0 };
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
+    return { ok: false, value: raw };
+  }
+  return { ok: true, value: parsed };
+}
 function resolveScope(rawScope, global) {
   if (rawScope === void 0) return { ok: true, scope: global ? "global" : "project" };
   if (rawScope === "project" || rawScope === "global") {
@@ -12390,6 +13509,10 @@ function formatValidationError(err) {
       return tx(SERVE_TEXTS.portInvalid, { value: sanitizeForTerminal(err.value) });
     case "scope-invalid":
       return tx(SERVE_TEXTS.scopeInvalid, { value: sanitizeForTerminal(err.value) });
+    case "watcher-requires-pipeline":
+      return tx(SERVE_TEXTS.watcherRequiresPipeline, { value: sanitizeForTerminal(err.value) });
+    case "watcher-debounce-invalid":
+      return tx(SERVE_TEXTS.watcherDebounceInvalid, { value: sanitizeForTerminal(err.value) });
     default:
       return tx(SERVE_TEXTS.startupFailed, { message: sanitizeForTerminal(err.message) });
   }