@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/web/routes/knowledge.js

@@ -0,0 +1,772 @@
+/**
+ * /api/knowledge/* — Knowledge Base (KB) web routes.
+ *
+ * v9.4: exposes KB listing / page-detail / query / repo-map / audit / build
+ * operations to the dashboard SPA. Build progress is streamed via SSE.
+ *
+ * Auth: GET is anonymous (web server config). Non-GET goes through requireAuth.
+ *
+ * Path-traversal: page-name is validated against a strict allow-list regex
+ *   /^([A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+\.md$/
+ * Every path segment must match the safe charset [A-Za-z0-9_-]+ and the final
+ * segment must end in `.md`. Any decoded `..`, leading `/`, backslash, empty
+ * segment (`//`), null byte, or char outside [A-Za-z0-9_/-]+`.md` is rejected
+ * with 400. A defense-in-depth realpath containment check (the resolved page
+ * must stay inside the project's `.forge-knowledge/` dir) backs the regex.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import { DAY_MS } from '../../core/utils/time.js';
+import path from 'node:path';
+import { logger } from '../../core/utils/logger.js';
+import { isKnowledgeBuilt, listKnowledge, getPage, queryKnowledge, } from '../../knowledge/query.js';
+import { loadRepoMap } from '../../knowledge/repo-map.js';
+import { applyAuditResult, deriveAuditStatus } from '../../knowledge/audit-applier.js';
+import { validatePage } from '../../knowledge/validator.js';
+import * as K from '../../knowledge/constants.js';
+import { buildManager, ConflictError } from '../services/build-manager.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Project root used by all KB endpoints (v9.5: multi-project support).
+ *
+ * Resolution order:
+ *   1. req.query.project (if present and passes allowlist) → absolute path
+ *   2. process.env.CF_PROJECT_ROOT (fallback)
+ *   3. process.cwd() (final fallback)
+ *
+ * The allowlist is `storage.listKnownProjectPaths()` — only projects that
+ * have at least one session in the DB are accepted. This prevents arbitrary
+ * path traversal while still allowing multi-project workflows.
+ */
+function resolveProjectRoot(req, storage) {
+    const queryProject = typeof req?.query?.project === 'string' ? req.query.project.trim() : '';
+    if (queryProject) {
+        const resolved = path.resolve(queryProject);
+        if (isAllowedProject(resolved, storage)) {
+            return resolved;
+        }
+        logger.warn(`[Web/KB] rejected project param: ${queryProject}`);
+    }
+    return process.env.CF_PROJECT_ROOT || process.cwd();
+}
+/**
+ * Allowlist guard: only absolute paths that appear in sessions.project_path
+ * are accepted. Rejects null-byte injection and relative paths.
+ */
+function isAllowedProject(resolvedPath, storage) {
+    if (!path.isAbsolute(resolvedPath))
+        return false;
+    if (resolvedPath.includes('\0'))
+        return false;
+    return storage.listKnownProjectPaths().includes(resolvedPath);
+}
+function kbDirOf(projectRoot) {
+    return path.join(projectRoot, K.KB_DIRNAME);
+}
+/**
+ * Strict page-name validator (path-traversal hardening).
+ *
+ * Accepts multi-segment safe page names of the form `<seg>/.../<file>.md`,
+ * where EVERY path segment matches the safe charset `[A-Za-z0-9_-]+` and the
+ * final segment ends in `.md`. Phase-6 KB writeback generates multi-segment
+ * names (`agents-experience/*.md`, `modules-experience/*.md`, etc.), which the
+ * old single-`modules/`-prefix regex rejected with 400 (decision fd865966).
+ *
+ * Still a strict WHITELIST (core-belief / Decision 11: read-file endpoints are
+ * loopback-only + name-whitelisted). The anchored `^...$` regex hard-rejects:
+ *   - `..` (any dot-dot) — `.` is not in the segment charset
+ *   - absolute paths (leading `/`) — would require an empty leading segment
+ *   - backslashes `\` — not in the charset
+ *   - empty segments (`//`) — `+` requires ≥1 char per segment
+ *   - null bytes / any char outside `[A-Za-z0-9_/-]` plus trailing `.md`
+ */
+const PAGE_NAME_RE = /^([A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+\.md$/;
+function isValidPageName(raw) {
+    if (!raw)
+        return false;
+    // Belt-and-suspenders rejections (the regex already covers these, kept for
+    // grep-friendliness + explicit intent).
+    if (raw.includes('..') || raw.startsWith('/') || raw.includes('\\'))
+        return false;
+    if (raw.includes('\0'))
+        return false;
+    if (!raw.endsWith('.md'))
+        return false;
+    return PAGE_NAME_RE.test(raw);
+}
+/**
+ * modules/xxx.md → 'module'; everything else (top-level + multi-segment
+ * directory prefixes like agents-experience/*.md) → 'cross'.
+ */
+function kindOf(name) {
+    return name.startsWith(`${K.KB_MODULES_DIR}/`) ? 'module' : 'cross';
+}
+/** Load `.meta.json` (returns null when KB is not built / file unreadable). */
+function loadMetaSafe(projectRoot) {
+    try {
+        const p = path.join(kbDirOf(projectRoot), K.KB_META_FILE);
+        if (!fs.existsSync(p))
+            return null;
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Module-name regex used by /build (matches CLI accepted modules). */
+const MODULE_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function isValidModulesArg(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (!Array.isArray(value))
+        return false;
+    return value.every((v) => typeof v === 'string' && MODULE_NAME_RE.test(v));
+}
+/** Compute total KB byte size by walking files under .forge-knowledge/ (best-effort). */
+function computeKbSize(kbDir) {
+    let total = 0;
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === K.KB_BACKUPS_DIR)
+                    continue; // skip backups
+                walk(full);
+            }
+            else if (e.isFile()) {
+                try {
+                    total += fs.statSync(full).size;
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+    if (fs.existsSync(kbDir))
+        walk(kbDir);
+    return total;
+}
+/** Default window (days) over which the effective KB hit-rate is computed. */
+const KB_HIT_RATE_WINDOW_DAYS = 7;
+/** Max window the summary will honour (mirrors insights / rules window cap). */
+const KB_HIT_RATE_WINDOW_MAX = 90;
+/**
+ * Compute the effective KB hit-rate (decision d4fdfd56).
+ *
+ * Numerator   = KB injection events (countKbInjections).
+ * Denominator = `eligible` prompts from aggregateRoutingStats — the
+ *               skill-worthy predicate that strips governance / meta / ack /
+ *               framework-envelope prompts (decision 2775bd8d). This is the
+ *               honest "code-relevant prompt" count.
+ *
+ * `raw_hit_rate` (over `total` prompts) is returned alongside so the UI can
+ * show why a naive per-page 0 is not the real picture.
+ *
+ * Note: countKbInjections is not project-scoped (the injections table has no
+ * project column); aggregateRoutingStats IS project-scoped. In practice both
+ * reflect the active project's traffic, so the small scope mismatch is
+ * accepted (documented in decision d4fdfd56).
+ */
+export function computeKbHitRate(storage, projectRoot, windowDays = KB_HIT_RATE_WINDOW_DAYS) {
+    // Clamp to [1, KB_HIT_RATE_WINDOW_MAX]; non-finite → default. Mirrors the
+    // 1-90 window validation on /api/insights/* and /api/rules/hit-rate so the
+    // /context window selector (7/30/90) can drive this summary too (decision
+    // 722abf91). injections.timestamp is ISO-TEXT; routing_events.ts is INTEGER
+    // ms — each window arm computes against its own column type (handled inside
+    // countKbInjections / aggregateRoutingStats), we only derive the cutoffs here.
+    const win = Number.isFinite(windowDays)
+        ? Math.min(KB_HIT_RATE_WINDOW_MAX, Math.max(1, Math.floor(windowDays)))
+        : KB_HIT_RATE_WINDOW_DAYS;
+    const now = Date.now();
+    const sinceTs = now - win * DAY_MS;
+    const sinceIso = new Date(sinceTs).toISOString();
+    const kbInjectCount = storage.countKbInjections(sinceIso);
+    const routing = storage.aggregateRoutingStats({ since_ts: sinceTs, project_path: projectRoot });
+    const eligible = routing.eligible;
+    const total = routing.total;
+    const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+    const kbHitRate = eligible > 0 ? clamp01(kbInjectCount / eligible) : 0;
+    const rawHitRate = total > 0 ? clamp01(kbInjectCount / total) : 0;
+    return {
+        window_days: win,
+        kb_inject_count: kbInjectCount,
+        eligible_prompts: eligible,
+        total_prompts: total,
+        kb_hit_rate: kbHitRate,
+        raw_hit_rate: rawHitRate,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Route registration
+// ─────────────────────────────────────────────────────────────────────────────
+export function registerKnowledgeRoutes(app, ctx) {
+    // ─── GET /api/knowledge/list ──────────────────────────────────────────────
+    app.get('/api/knowledge/list', async (req, res) => {
+        try {
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            if (!isKnowledgeBuilt(projectRoot)) {
+                res.json({ kb_built: false, hint: 'Run cf knowledge build --apply' });
+                return;
+            }
+            const kindFilter = req.query.kind;
+            const pages = await listKnowledge(projectRoot);
+            const meta = loadMetaSafe(projectRoot);
+            const rows = pages
+                .map((p) => {
+                const kind = kindOf(p.name);
+                const m = meta?.pages?.[p.name];
+                return {
+                    name: p.name,
+                    title: p.title,
+                    kind,
+                    refs_count: p.refs.length,
+                    audit_status: m?.audit_status ?? p.audit_status ?? 'ok',
+                    source_hash: m?.source_hash ?? p.source_hash,
+                    generated_at: p.generated_at,
+                    ai_model: m?.ai_model ?? p.ai_model,
+                };
+            })
+                .filter((p) => !kindFilter || p.kind === kindFilter)
+                // cross pages first, then module pages (alphabetical inside each bucket)
+                .sort((a, b) => {
+                if (a.kind !== b.kind)
+                    return a.kind === 'cross' ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            });
+            // Aggregate stats over the full set (not filtered).
+            const all = pages.map((p) => ({
+                kind: kindOf(p.name),
+                audit_status: meta?.pages?.[p.name]?.audit_status ?? p.audit_status ?? 'ok',
+            }));
+            const stats = {
+                total: all.length,
+                by_kind: {
+                    module: all.filter((x) => x.kind === 'module').length,
+                    cross: all.filter((x) => x.kind === 'cross').length,
+                },
+                by_audit_status: {
+                    ok: all.filter((x) => x.audit_status === 'ok').length,
+                    stale: all.filter((x) => x.audit_status === 'stale').length,
+                    error: all.filter((x) => x.audit_status === 'error').length,
+                },
+            };
+            // ── Effective KB hit-rate (decision d4fdfd56) ───────────────────────
+            //
+            // The per-page `cited` counts (rendered by KbHitRateTable) show raw 0 on
+            // most pages, misleading users into thinking the KB is unused. The real
+            // story: most main-thread prompts in the window are governance / meta
+            // tasks ("批准" / "提交并推送" / images) that SHOULD NOT match code KB.
+            //
+            // We expose an honest denominator = `eligible` prompts (the same
+            // skill-worthy predicate from routing.ts / decision 2775bd8d, which
+            // strips framework envelopes + acks + ultra-short prompts), and the
+            // numerator = KB injection events (countKbInjections). The raw per-page
+            // cited counts are left untouched — this is an ADDITIVE summary block.
+            // decision 722abf91: the /context window selector (7/30/90) passes
+            // ?window= (alias ?days=). Default 7 (unchanged behaviour), cap 90 — the
+            // clamp lives in computeKbHitRate so a bad/oversized value degrades
+            // gracefully rather than 400-ing the whole /list payload.
+            const rawWindow = req.query.window ?? req.query.days;
+            const windowDays = typeof rawWindow === 'string' && rawWindow.trim() !== ''
+                ? parseInt(rawWindow, 10)
+                : KB_HIT_RATE_WINDOW_DAYS;
+            const kbHitRate = computeKbHitRate(ctx.storage, projectRoot, windowDays);
+            res.json({
+                kb_built: true,
+                pages: rows,
+                stats,
+                kb_hit_rate: kbHitRate,
+                generated_at: meta?.generated_at,
+                source_hash: meta?.source_hash,
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /list failed: ${err}`);
+            res.status(500).json({ error: 'list_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/page/:name ────────────────────────────────────────
+    // Use a single-segment ":name" param; modules/xxx.md is passed as a
+    // URL-encoded path (e.g. modules%2Fdaemon.md). Avoids Express path-to-regexp
+    // wildcards which conflict with the strict allow-list regex below.
+    app.get('/api/knowledge/page/:name', async (req, res) => {
+        try {
+            const rawName = req.params.name;
+            let decoded;
+            try {
+                decoded = decodeURIComponent(rawName);
+            }
+            catch {
+                res.status(400).json({ error: 'invalid_encoding' });
+                return;
+            }
+            if (!isValidPageName(decoded)) {
+                res.status(400).json({ error: 'invalid_name', detail: 'page name must match ([A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+\\.md' });
+                return;
+            }
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            // Defense in depth (core-belief / Decision 11): even though PAGE_NAME_RE
+            // is an airtight whitelist, verify the resolved page path stays inside
+            // the project's `.forge-knowledge/` dir. The regex is the only guard in
+            // getPage(), so a containment check here closes any future regex drift.
+            const kbDir = kbDirOf(projectRoot);
+            const resolvedPath = path.resolve(kbDir, decoded);
+            const kbDirWithSep = kbDir.endsWith(path.sep) ? kbDir : kbDir + path.sep;
+            if (resolvedPath !== kbDir && !resolvedPath.startsWith(kbDirWithSep)) {
+                res.status(400).json({ error: 'invalid_name', detail: 'page name escapes the knowledge-base directory' });
+                return;
+            }
+            const page = await getPage(decoded, projectRoot);
+            if (!page) {
+                res.status(404).json({ error: 'not_found' });
+                return;
+            }
+            const meta = loadMetaSafe(projectRoot);
+            const metaEntry = meta?.pages?.[decoded];
+            res.json({
+                ...page,
+                kind: kindOf(decoded),
+                audit_status: metaEntry?.audit_status ?? 'ok',
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /page failed: ${err}`);
+            res.status(500).json({ error: 'page_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/query ─────────────────────────────────────────────
+    app.get('/api/knowledge/query', async (req, res) => {
+        try {
+            const q = req.query.q ?? '';
+            if (!q.trim()) {
+                res.status(400).json({ error: 'missing_q' });
+                return;
+            }
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const maxRaw = req.query.max;
+            const includeContent = req.query.include_content === 'true';
+            const opts = {
+                projectRoot,
+                maxResults: maxRaw ? Math.min(Math.max(parseInt(maxRaw, 10) || 3, 1), 20) : 3,
+                storage: ctx.storage,
+            };
+            const result = await queryKnowledge(q, opts);
+            // Trim content to reduce payload unless explicitly requested.
+            if (!includeContent) {
+                result.pages = result.pages.map((h) => ({
+                    ...h,
+                    page: {
+                        ...h.page,
+                        content: h.page.content.length > 400
+                            ? h.page.content.slice(0, 400) + '...'
+                            : h.page.content,
+                    },
+                }));
+            }
+            res.json(result);
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /query failed: ${err}`);
+            res.status(500).json({ error: 'query_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/repo-map ──────────────────────────────────────────
+    app.get('/api/knowledge/repo-map', (req, res) => {
+        try {
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const symbol = req.query.symbol ?? '';
+            const contains = req.query.contains ?? '';
+            const moduleParam = req.query.module ?? '';
+            const kindParam = req.query.kind ?? '';
+            if (!symbol && !contains && !moduleParam && !kindParam) {
+                res.status(400).json({
+                    error: 'missing_filter',
+                    detail: 'at least one of symbol/contains/module/kind required',
+                });
+                return;
+            }
+            const repoMap = loadRepoMap(kbDirOf(projectRoot));
+            if (!repoMap) {
+                res.status(404).json({ error: 'repo_map_not_built' });
+                return;
+            }
+            let symbols = repoMap.symbols.slice();
+            if (symbol)
+                symbols = symbols.filter((s) => s.name === symbol);
+            if (contains) {
+                const c = contains.toLowerCase();
+                symbols = symbols.filter((s) => s.name.toLowerCase().includes(c) ||
+                    (s.docComment ?? '').toLowerCase().includes(c));
+            }
+            if (moduleParam) {
+                symbols = symbols.filter((s) => s.file.startsWith(`${moduleParam}/`));
+            }
+            if (kindParam) {
+                symbols = symbols.filter((s) => s.kind === kindParam);
+            }
+            const total = symbols.length;
+            const max = Math.min(parseInt(req.query.max || '20', 10) || 20, 200);
+            const truncated = total > max;
+            const out = symbols.slice(0, max);
+            res.json({
+                total,
+                truncated,
+                symbols: out,
+                repo_map_meta: {
+                    version: repoMap.version,
+                    generated_at: repoMap.generated_at,
+                    source_hash: repoMap.source_hash,
+                    symbol_count: repoMap.symbol_count,
+                    file_count: repoMap.file_count,
+                },
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /repo-map failed: ${err}`);
+            res.status(500).json({ error: 'repo_map_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/audit ─────────────────────────────────────────────
+    app.get('/api/knowledge/audit', (req, res) => {
+        try {
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const kbDir = kbDirOf(projectRoot);
+            if (!isKnowledgeBuilt(projectRoot)) {
+                res.json({ kb_built: false, hint: 'Run cf knowledge build --apply' });
+                return;
+            }
+            const meta = loadMetaSafe(projectRoot);
+            const perPage = meta
+                ? Object.entries(meta.pages).map(([name, p]) => ({
+                    name,
+                    kind: kindOf(name),
+                    audit_status: p.audit_status,
+                    refs_count: p.refs_count,
+                    source_hash: p.source_hash,
+                    ai_model: p.ai_model,
+                }))
+                : [];
+            const summary = {
+                total: perPage.length,
+                ok: perPage.filter((p) => p.audit_status === 'ok').length,
+                stale: perPage.filter((p) => p.audit_status === 'stale').length,
+                error: perPage.filter((p) => p.audit_status === 'error').length,
+            };
+            // Read audit log (truncated to 50KB to keep payload bounded).
+            const logPath = path.join(kbDir, '.audit-log.md');
+            let log = '';
+            let logTruncated = false;
+            if (fs.existsSync(logPath)) {
+                const raw = fs.readFileSync(logPath, 'utf-8');
+                if (raw.length > 50 * 1024) {
+                    log = raw.slice(0, 50 * 1024);
+                    logTruncated = true;
+                }
+                else {
+                    log = raw;
+                }
+            }
+            res.json({
+                kb_built: true,
+                summary,
+                per_page: perPage,
+                log,
+                log_truncated: logTruncated,
+                generated_at: meta?.generated_at,
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /audit failed: ${err}`);
+            res.status(500).json({ error: 'audit_failed', detail: String(err) });
+        }
+    });
+    // ─── POST /api/knowledge/audit/fix ────────────────────────────────────────
+    app.post('/api/knowledge/audit/fix', async (req, res) => {
+        try {
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const kbDir = kbDirOf(projectRoot);
+            if (!isKnowledgeBuilt(projectRoot)) {
+                res.status(400).json({ error: 'kb_not_built' });
+                return;
+            }
+            const meta = loadMetaSafe(projectRoot);
+            if (!meta) {
+                res.status(400).json({ error: 'meta_unreadable' });
+                return;
+            }
+            const pages = await listKnowledge(projectRoot);
+            const repoMap = loadRepoMap(kbDir);
+            const repoMapSymbols = repoMap?.symbols ?? [];
+            // Optional single-page scope: ?page=modules/skills.md
+            const pageScope = typeof req.query.page === 'string' ? req.query.page : '';
+            const scopedPages = pageScope
+                ? pages.filter((p) => p.name === pageScope)
+                : pages;
+            if (pageScope && scopedPages.length === 0) {
+                res.status(404).json({ error: 'page_not_found', page: pageScope });
+                return;
+            }
+            const results = scopedPages.map((page) => {
+                const validation = validatePage(page, {
+                    projectRoot,
+                    repoMap: repoMapSymbols,
+                });
+                const status = deriveAuditStatus(validation.issues);
+                return { name: page.name, status, issues: validation.issues };
+            });
+            const outcome = applyAuditResult({
+                kbDir,
+                results,
+                sourceHash: meta.source_hash,
+            });
+            res.json({
+                ok: true,
+                outcome,
+                scope: pageScope || null,
+                summary: {
+                    total: results.length,
+                    ok: results.filter((r) => r.status === 'ok').length,
+                    stale: results.filter((r) => r.status === 'stale').length,
+                    error: results.filter((r) => r.status === 'error').length,
+                },
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /audit/fix failed: ${err}`);
+            res.status(500).json({ error: 'audit_fix_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/stats ─────────────────────────────────────────────
+    app.get('/api/knowledge/stats', (req, res) => {
+        try {
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const kbDir = kbDirOf(projectRoot);
+            const built = isKnowledgeBuilt(projectRoot);
+            const meta = built ? loadMetaSafe(projectRoot) : null;
+            const size = computeKbSize(kbDir);
+            // v9.5: prefer kb_build_log (persisted) over buildManager (in-memory)
+            const lastBuild = ctx.storage.queryLastKbBuild(projectRoot);
+            const lastBuildStats = lastBuild?.stats_json ? JSON.parse(lastBuild.stats_json) : null;
+            const lastBuildAt = lastBuild?.ts
+                ? new Date(lastBuild.ts).toISOString()
+                : meta?.generated_at ?? null;
+            // v9.5: real telemetry
+            const kbStats = ctx.storage.queryKbStats(projectRoot);
+            res.json({
+                kb_built: built,
+                kb_size_bytes: size,
+                page_count: meta ? Object.keys(meta.pages).length : 0,
+                last_build_at: lastBuildAt,
+                last_build_stats: lastBuildStats,
+                last_build_status: lastBuild?.status ?? null,
+                total_queries: kbStats.total_queries,
+                total_ai_calls: kbStats.total_ai_calls,
+                total_tokens: {
+                    input: kbStats.total_ai_input_tokens,
+                    output: kbStats.total_ai_output_tokens,
+                },
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /stats failed: ${err}`);
+            res.status(500).json({ error: 'stats_failed', detail: String(err) });
+        }
+    });
+    const projectsCache = new Map();
+    const PROJECTS_TTL_MS = 30_000;
+    app.get('/api/knowledge/projects', (req, res) => {
+        try {
+            const currentProject = resolveProjectRoot(req, ctx.storage);
+            const now = Date.now();
+            const hit = projectsCache.get(currentProject);
+            if (hit && now - hit.ts < PROJECTS_TTL_MS) {
+                res.json(hit.data);
+                return;
+            }
+            const paths = ctx.storage.listKnownProjectPaths();
+            // v9.5.2: real last_event_at aggregated from sessions.last_event_time
+            const lastEventMap = ctx.storage.queryLastEventAtPerProject();
+            const projects = paths.map((p) => {
+                const kbBuilt = isKnowledgeBuilt(p);
+                const meta = kbBuilt ? loadMetaSafe(p) : null;
+                return {
+                    path: p,
+                    name: path.basename(p),
+                    kb_built: kbBuilt,
+                    last_event_at: lastEventMap.get(p) ?? null,
+                    // Guard meta.pages: a malformed .meta.json with `pages: null` (seen
+                    // on other projects whose KB never built cleanly) would make
+                    // Object.keys(null) throw and crash the WHOLE /projects endpoint —
+                    // wiping every project from the switcher ("no project").
+                    page_count: meta?.pages ? Object.keys(meta.pages).length : 0,
+                    is_current: p === currentProject,
+                };
+            });
+            // Sort: is_current desc, then alpha by name
+            projects.sort((a, b) => {
+                if (a.is_current !== b.is_current)
+                    return a.is_current ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            });
+            const data = { current: currentProject, projects };
+            projectsCache.set(currentProject, { ts: now, data });
+            res.json(data);
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /projects failed: ${err}`);
+            res.status(500).json({ error: 'projects_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/usage-stats ────────────────────────────────────────
+    app.get('/api/knowledge/usage-stats', (req, res) => {
+        try {
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const days = parseInt(req.query.days || '7', 10);
+            const stats = ctx.storage.queryKbUsageStats(projectRoot, days);
+            res.json({
+                total_calls: stats.total,
+                by_tool: stats.byTool,
+                recent_sessions: stats.recentSessions,
+                last_used_at: stats.lastUsedAt,
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /usage-stats failed: ${err}`);
+            res.status(500).json({ error: 'usage_stats_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/build-report ──────────────────────────────────────
+    // Returns the contents of ~/.claude-forge/knowledge-build-report.md (global,
+    // not per-project). The report is regenerated by every `cf knowledge build`
+    // run; missing file is reported with exists=false (200, not 404) so the
+    // dashboard can render a friendly empty state.
+    app.get('/api/knowledge/build-report', (_req, res) => {
+        try {
+            const reportPath = path.join(os.homedir(), '.claude-forge', 'knowledge-build-report.md');
+            if (!fs.existsSync(reportPath)) {
+                res.json({ exists: false, content: null });
+                return;
+            }
+            const content = fs.readFileSync(reportPath, 'utf-8');
+            const stat = fs.statSync(reportPath);
+            res.json({
+                exists: true,
+                content,
+                generated_at: stat.mtime.toISOString(),
+                size_bytes: stat.size,
+            });
+        }
+        catch (err) {
+            logger.warn(`[Web/KB] /build-report failed: ${err}`);
+            res.status(500).json({ error: 'report_read_failed', detail: String(err) });
+        }
+    });
+    // ─── POST /api/knowledge/build ────────────────────────────────────────────
+    app.post('/api/knowledge/build', (req, res) => {
+        try {
+            const body = (req.body ?? {});
+            // modules: must be null/undefined or string[] matching MODULE_NAME_RE
+            const modulesRaw = body.modules ?? null;
+            if (!isValidModulesArg(modulesRaw)) {
+                res
+                    .status(400)
+                    .json({ error: 'invalid_modules', detail: 'modules must be null or string[] of /^[a-z][a-z0-9-]*$/' });
+                return;
+            }
+            const modules = Array.isArray(modulesRaw) ? modulesRaw : undefined;
+            const projectRoot = resolveProjectRoot(req, ctx.storage);
+            const buildOpts = {
+                projectRoot,
+                apply: body.apply !== false, // default true
+                force: !!body.force,
+                skipCrossModule: !!body.skipCrossModule,
+                ...(modules && modules.length > 0 ? { modules } : {}),
+            };
+            const { buildId } = buildManager.start(buildOpts);
+            res.status(202).json({
+                buildId,
+                streamUrl: `/api/knowledge/build/${buildId}/stream`,
+            });
+        }
+        catch (err) {
+            if (err instanceof ConflictError) {
+                res.status(409).json({ error: 'build_in_progress', detail: err.message });
+                return;
+            }
+            logger.warn(`[Web/KB] /build failed: ${err}`);
+            res.status(500).json({ error: 'build_failed', detail: String(err) });
+        }
+    });
+    // ─── GET /api/knowledge/build/:buildId/stream  (SSE) ──────────────────────
+    app.get('/api/knowledge/build/:buildId/stream', (req, res) => {
+        const { buildId } = req.params;
+        const session = buildManager.getSession(buildId);
+        if (!session) {
+            res.status(404).json({ error: 'unknown_build_id' });
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        res.write('event: connected\ndata: {}\n\n');
+        // v9.5 SSE heartbeat: emit `:heartbeat\n\n` (SSE comment frame, browsers
+        // ignore) every 30s to keep proxies (typical 60-120s idle timeout) and
+        // intermediate L4 boxes from closing the connection mid-build.
+        //
+        // Cleared in three places: 'done'/'error' event → res.end, req 'close',
+        // and any write throw (client disconnect). unref() prevents the timer
+        // from blocking Node process exit.
+        const heartbeatInterval = setInterval(() => {
+            if (!res.writableEnded) {
+                try {
+                    res.write(':heartbeat\n\n');
+                }
+                catch {
+                    // Client disconnected; rely on req 'close' to cleanup.
+                }
+            }
+        }, 30_000);
+        heartbeatInterval.unref?.();
+        // Replay history
+        for (const ev of session.events) {
+            res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+        }
+        // Already finished → close after replay
+        if (session.doneAt != null) {
+            clearInterval(heartbeatInterval);
+            res.end();
+            return;
+        }
+        const send = (ev) => {
+            try {
+                res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+                if (ev.type === 'done' || ev.type === 'error') {
+                    clearInterval(heartbeatInterval);
+                    res.end();
+                }
+            }
+            catch {
+                /* client disconnected */
+            }
+        };
+        const unsubscribe = buildManager.subscribe(buildId, send);
+        req.on('close', () => {
+            clearInterval(heartbeatInterval);
+            unsubscribe();
+        });
+    });
+}
+//# sourceMappingURL=knowledge.js.map