brains-mcp 1.61.2

package/dist/governance/accessControl.d.ts

@@ -0,0 +1,87 @@
+/**
+ * accessControl.ts
+ *
+ * Runtime governance for Hive (team) brains.
+ *
+ * When BRAINS_HIVE_MODE=true, all read paths filter pages by:
+ *   1. access_level — page must have access_level ≤ requesting user's level
+ *   2. audience     — when session_audience is set, page audience must match
+ *
+ * Solo (non-Hive) brains: isHiveModeEnabled() returns false, userLevel is
+ * effectively 5 (owner), and no filtering occurs.
+ *
+ * Access level hierarchy:
+ *   1 = contributor (default)
+ *   2 = team
+ *   3 = manager
+ *   4 = exec
+ *   5 = owner
+ */
+export declare const ACCESS_LEVEL_CONTRIBUTOR = 1;
+export declare const ACCESS_LEVEL_TEAM = 2;
+export declare const ACCESS_LEVEL_MANAGER = 3;
+export declare const ACCESS_LEVEL_EXEC = 4;
+export declare const ACCESS_LEVEL_OWNER = 5;
+/** Default access level assigned to pages with no explicit access_level field. */
+export declare const DEFAULT_PAGE_ACCESS_LEVEL = 1;
+/** Default audience assigned to pages with no explicit audience field. */
+export declare const DEFAULT_PAGE_AUDIENCE: "internal";
+/** Access context passed through all read paths. */
+export interface AccessContext {
+    /** The requesting user's access level (1–5). 5 = full access (solo / owner). */
+    userAccessLevel: number;
+    /**
+     * Optional audience constraint declared by the caller for this session.
+     * "client-safe" → only return pages with audience client-safe or public.
+     * "public"       → only return pages with audience public.
+     * Omitted / undefined → no audience filter applied.
+     */
+    sessionAudience?: string;
+}
+/** Default context used when governance is not applicable (solo brains). */
+export declare const DEFAULT_ACCESS_CONTEXT: AccessContext;
+/**
+ * Returns true only when BRAINS_HIVE_MODE=true is set.
+ * Solo (non-Hive) brains are a no-op for access control.
+ */
+export declare function isHiveModeEnabled(): boolean;
+/**
+ * Coerce an unknown frontmatter value to a valid access level integer (1–5).
+ * Returns DEFAULT_PAGE_ACCESS_LEVEL when the value is absent or invalid.
+ */
+export declare function parseAccessLevel(raw: unknown): number;
+/**
+ * Coerce an unknown frontmatter value to a valid audience string.
+ * Returns DEFAULT_PAGE_AUDIENCE when the value is absent or invalid.
+ */
+export declare function parseAudience(raw: unknown): string;
+/**
+ * Returns true when the page should be visible to the requesting user.
+ *
+ * Rules:
+ *   - page.access_level ≤ user.access_level  (numeric gate)
+ *   - if sessionAudience = "public"       → page.audience must be "public"
+ *   - if sessionAudience = "client-safe"  → page.audience must be "client-safe" or "public"
+ *   - otherwise no audience gate applies
+ */
+export declare function pagePassesFilter(pageAccessLevel: number, pageAudience: string | undefined, userAccessLevel: number, sessionAudience?: string): boolean;
+/**
+ * Retrieves the access level for a given user from the `user_access_levels`
+ * Supabase table.
+ *
+ * - Returns ACCESS_LEVEL_OWNER (5) when Hive mode is disabled (solo brains).
+ * - Returns DEFAULT_PAGE_ACCESS_LEVEL (1) when the user has no entry.
+ * - Falls back to DEFAULT_PAGE_ACCESS_LEVEL on any network/parse error.
+ */
+export declare function getUserAccessLevel(userId: string): Promise<number>;
+/**
+ * Fire-and-forget: write a governance filter event to Supabase.
+ * Never throws — failures are silently ignored.
+ */
+export declare function writeGovernanceAuditEntry(userId: string, pageName: string, pageAccessLevel: number, userAccessLevel: number, sessionAudience?: string, reason?: string): void;
+/**
+ * Read governance audit log entries.
+ * Only exec+ users (access_level ≥ 4) may call this.
+ */
+export declare function readGovernanceAuditLog(requestingUserId: string, limit?: number): Promise<object>;
+//# sourceMappingURL=accessControl.d.ts.map

package/dist/governance/accessControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessControl.d.ts","sourceRoot":"","sources":["../../src/governance/accessControl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,iBAAiB,IAAW,CAAC;AAC1C,eAAO,MAAM,oBAAoB,IAAQ,CAAC;AAC1C,eAAO,MAAM,iBAAiB,IAAW,CAAC;AAC1C,eAAO,MAAM,kBAAkB,IAAU,CAAC;AAE1C,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAG,UAAmB,CAAC;AAEzD,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,EAAE,aAAuD,CAAC;AAI7F;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAyBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAGlD;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,eAAe,EAAE,MAAM,EACvB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAUT;AAID;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAexE;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,eAAe,CAAC,EAAE,MAAM,EACxB,MAAM,SAA0B,GAC/B,IAAI,CAmBN;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,gBAAgB,EAAE,MAAM,EACxB,KAAK,SAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAyBjB"}

package/dist/governance/accessControl.js

@@ -0,0 +1,179 @@
+/**
+ * accessControl.ts
+ *
+ * Runtime governance for Hive (team) brains.
+ *
+ * When BRAINS_HIVE_MODE=true, all read paths filter pages by:
+ *   1. access_level — page must have access_level ≤ requesting user's level
+ *   2. audience     — when session_audience is set, page audience must match
+ *
+ * Solo (non-Hive) brains: isHiveModeEnabled() returns false, userLevel is
+ * effectively 5 (owner), and no filtering occurs.
+ *
+ * Access level hierarchy:
+ *   1 = contributor (default)
+ *   2 = team
+ *   3 = manager
+ *   4 = exec
+ *   5 = owner
+ */
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const ACCESS_LEVEL_CONTRIBUTOR = 1;
+export const ACCESS_LEVEL_TEAM = 2;
+export const ACCESS_LEVEL_MANAGER = 3;
+export const ACCESS_LEVEL_EXEC = 4;
+export const ACCESS_LEVEL_OWNER = 5;
+/** Default access level assigned to pages with no explicit access_level field. */
+export const DEFAULT_PAGE_ACCESS_LEVEL = 1;
+/** Default audience assigned to pages with no explicit audience field. */
+export const DEFAULT_PAGE_AUDIENCE = "internal";
+/** Default context used when governance is not applicable (solo brains). */
+export const DEFAULT_ACCESS_CONTEXT = { userAccessLevel: ACCESS_LEVEL_OWNER };
+// ─── Environment ──────────────────────────────────────────────────────────────
+/**
+ * Returns true only when BRAINS_HIVE_MODE=true is set.
+ * Solo (non-Hive) brains are a no-op for access control.
+ */
+export function isHiveModeEnabled() {
+    return (process.env.BRAINS_HIVE_MODE ?? "").toLowerCase() === "true";
+}
+function supabaseUrl() {
+    return (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+}
+function serviceRoleKey() {
+    return (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+}
+function pgHeaders() {
+    const key = serviceRoleKey();
+    return {
+        "content-type": "application/json",
+        "apikey": key,
+        "authorization": `Bearer ${key}`,
+    };
+}
+function isPostgresConfigured() {
+    return supabaseUrl().length > 0 && serviceRoleKey().length > 0;
+}
+// ─── Access level parsing ─────────────────────────────────────────────────────
+/**
+ * Coerce an unknown frontmatter value to a valid access level integer (1–5).
+ * Returns DEFAULT_PAGE_ACCESS_LEVEL when the value is absent or invalid.
+ */
+export function parseAccessLevel(raw) {
+    const n = typeof raw === "number" ? raw : parseInt(String(raw ?? ""), 10);
+    if (Number.isInteger(n) && n >= 1 && n <= 5)
+        return n;
+    return DEFAULT_PAGE_ACCESS_LEVEL;
+}
+/**
+ * Coerce an unknown frontmatter value to a valid audience string.
+ * Returns DEFAULT_PAGE_AUDIENCE when the value is absent or invalid.
+ */
+export function parseAudience(raw) {
+    if (raw === "client-safe" || raw === "public" || raw === "internal")
+        return raw;
+    return DEFAULT_PAGE_AUDIENCE;
+}
+// ─── Filtering ────────────────────────────────────────────────────────────────
+/**
+ * Returns true when the page should be visible to the requesting user.
+ *
+ * Rules:
+ *   - page.access_level ≤ user.access_level  (numeric gate)
+ *   - if sessionAudience = "public"       → page.audience must be "public"
+ *   - if sessionAudience = "client-safe"  → page.audience must be "client-safe" or "public"
+ *   - otherwise no audience gate applies
+ */
+export function pagePassesFilter(pageAccessLevel, pageAudience, userAccessLevel, sessionAudience) {
+    if (pageAccessLevel > userAccessLevel)
+        return false;
+    if (sessionAudience) {
+        const aud = parseAudience(pageAudience);
+        if (sessionAudience === "public" && aud !== "public")
+            return false;
+        if (sessionAudience === "client-safe" && aud === "internal")
+            return false;
+    }
+    return true;
+}
+// ─── User access level lookup ─────────────────────────────────────────────────
+/**
+ * Retrieves the access level for a given user from the `user_access_levels`
+ * Supabase table.
+ *
+ * - Returns ACCESS_LEVEL_OWNER (5) when Hive mode is disabled (solo brains).
+ * - Returns DEFAULT_PAGE_ACCESS_LEVEL (1) when the user has no entry.
+ * - Falls back to DEFAULT_PAGE_ACCESS_LEVEL on any network/parse error.
+ */
+export async function getUserAccessLevel(userId) {
+    if (!isHiveModeEnabled())
+        return ACCESS_LEVEL_OWNER;
+    if (!userId || !isPostgresConfigured())
+        return DEFAULT_PAGE_ACCESS_LEVEL;
+    try {
+        const url = `${supabaseUrl()}/rest/v1/user_access_levels?user_id=eq.${encodeURIComponent(userId)}&select=access_level&limit=1`;
+        const res = await fetch(url, { headers: pgHeaders() });
+        if (!res.ok)
+            return DEFAULT_PAGE_ACCESS_LEVEL;
+        const rows = (await res.json());
+        if (rows.length === 0)
+            return DEFAULT_PAGE_ACCESS_LEVEL;
+        return parseAccessLevel(rows[0].access_level);
+    }
+    catch {
+        return DEFAULT_PAGE_ACCESS_LEVEL;
+    }
+}
+// ─── Audit log ────────────────────────────────────────────────────────────────
+/**
+ * Fire-and-forget: write a governance filter event to Supabase.
+ * Never throws — failures are silently ignored.
+ */
+export function writeGovernanceAuditEntry(userId, pageName, pageAccessLevel, userAccessLevel, sessionAudience, reason = "access_level_exceeded") {
+    if (!isPostgresConfigured())
+        return;
+    const row = {
+        user_id: userId,
+        page_name: pageName,
+        page_access_level: pageAccessLevel,
+        user_access_level: userAccessLevel,
+        session_audience: sessionAudience ?? null,
+        reason,
+    };
+    fetch(`${supabaseUrl()}/rest/v1/governance_audit_log`, {
+        method: "POST",
+        headers: { ...pgHeaders(), prefer: "return=minimal" },
+        body: JSON.stringify(row),
+    }).catch((err) => {
+        console.error("[governance] audit log write failed:", err instanceof Error ? err.message : String(err));
+    });
+}
+/**
+ * Read governance audit log entries.
+ * Only exec+ users (access_level ≥ 4) may call this.
+ */
+export async function readGovernanceAuditLog(requestingUserId, limit = 100) {
+    if (!isHiveModeEnabled()) {
+        return { ok: false, error: "Hive mode is not enabled" };
+    }
+    const requestingLevel = await getUserAccessLevel(requestingUserId);
+    if (requestingLevel < ACCESS_LEVEL_EXEC) {
+        return { ok: false, error: "Insufficient access level — exec (4) or higher required" };
+    }
+    if (!isPostgresConfigured()) {
+        return { ok: false, error: "Supabase not configured" };
+    }
+    try {
+        const url = `${supabaseUrl()}/rest/v1/governance_audit_log?select=*&order=created_at.desc&limit=${limit}`;
+        const res = await fetch(url, { headers: pgHeaders() });
+        if (!res.ok) {
+            return { ok: false, error: `Failed to fetch audit log: ${res.status}` };
+        }
+        const entries = await res.json();
+        return { ok: true, entries, count: entries.length };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=accessControl.js.map

package/dist/governance/accessControl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessControl.js","sourceRoot":"","sources":["../../src/governance/accessControl.ts"],"names":[],"mappings":"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"}

package/dist/html/components.d.ts

@@ -0,0 +1,8 @@
+export declare function renderWordmark(subtitle?: string): string;
+export declare function renderErrorBox(message?: string): string;
+export declare function renderMetaRows(rows: Array<{
+    label: string;
+    value: string;
+}>): string;
+export declare function renderStatusBadge(variant: "ok" | "err", text: string): string;
+//# sourceMappingURL=components.d.ts.map

package/dist/html/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/html/components.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAMpF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7E"}

package/dist/html/components.js

@@ -0,0 +1,19 @@
+export function renderWordmark(subtitle) {
+    const subtitleHtml = subtitle ? `<p class="brand-subtitle">${subtitle}</p>` : "";
+    return `<a class="brand-header" href="/" aria-label="Brains home"><img class="brand-logo" src="/assets/img/brains-logo.svg" alt="" /><span class="brand-wordmark">br<span class="brand-ai">ai</span>ns</span></a>${subtitleHtml}`;
+}
+export function renderErrorBox(message) {
+    if (!message)
+        return "";
+    return `<div class="alert alert-error">${message}</div>`;
+}
+export function renderMetaRows(rows) {
+    const rowHtml = rows
+        .map((row) => `<div><strong>${row.label}:</strong> ${row.value}</div>`)
+        .join("");
+    return `<section class="meta-box">${rowHtml}</section>`;
+}
+export function renderStatusBadge(variant, text) {
+    return `<div class="status-pill status-pill--${variant}">${text}</div>`;
+}
+//# sourceMappingURL=components.js.map

package/dist/html/components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../src/html/components.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,cAAc,CAAC,QAAiB;IAC9C,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,6BAA6B,QAAQ,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,OAAO,4MAA4M,YAAY,EAAE,CAAC;AACpO,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,kCAAkC,OAAO,QAAQ,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAA6C;IAC1E,MAAM,OAAO,GAAG,IAAI;SACjB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,GAAG,CAAC,KAAK,cAAc,GAAG,CAAC,KAAK,QAAQ,CAAC;SACtE,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO,6BAA6B,OAAO,YAAY,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAqB,EAAE,IAAY;IACnE,OAAO,wCAAwC,OAAO,KAAK,IAAI,QAAQ,CAAC;AAC1E,CAAC"}

package/dist/html/layout.d.ts

@@ -0,0 +1,7 @@
+export declare function renderPageShell(params: {
+    title: string;
+    body: string;
+    cssPaths: string[];
+    bodyClass?: string;
+}): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/html/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/html/layout.ts"],"names":[],"mappings":"AAMA,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAkBT"}

package/dist/html/layout.js

@@ -0,0 +1,24 @@
+function renderStylesheetLinks(cssPaths) {
+    return cssPaths
+        .map((href) => `<link rel="stylesheet" href="${href}" />`)
+        .join("\n  ");
+}
+export function renderPageShell(params) {
+    const bodyClass = params.bodyClass ? ` class="${params.bodyClass}"` : "";
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${params.title}</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Pacifico&family=Eczar:wght@400;500;600&family=Open+Sans:wght@400;500;600&family=Caveat:wght@600&display=swap" rel="stylesheet" />
+  ${renderStylesheetLinks(params.cssPaths)}
+</head>
+<body${bodyClass}>
+${params.body}
+</body>
+</html>`;
+}
+//# sourceMappingURL=layout.js.map

package/dist/html/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/html/layout.ts"],"names":[],"mappings":"AAAA,SAAS,qBAAqB,CAAC,QAAkB;IAC/C,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gCAAgC,IAAI,MAAM,CAAC;SACzD,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAK/B;IACC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEzE,OAAO;;;;;WAKE,MAAM,CAAC,KAAK;;;;IAInB,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC;;OAEnC,SAAS;EACd,MAAM,CAAC,IAAI;;QAEL,CAAC;AACT,CAAC"}

package/dist/html/metricsUi.d.ts

@@ -0,0 +1,8 @@
+/**
+ * metricsUi.ts
+ *
+ * Self-contained HTML dashboard for /metrics-ui.
+ * Polls /api/v1/metrics every 30 s. Chart.js loaded via CDN — no npm install.
+ */
+export declare function metricsUiHtml(): string;
+//# sourceMappingURL=metricsUi.d.ts.map

package/dist/html/metricsUi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metricsUi.d.ts","sourceRoot":"","sources":["../../src/html/metricsUi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,aAAa,IAAI,MAAM,CAuQtC"}

package/dist/html/metricsUi.js

@@ -0,0 +1,271 @@
+/**
+ * metricsUi.ts
+ *
+ * Self-contained HTML dashboard for /metrics-ui.
+ * Polls /api/v1/metrics every 30 s. Chart.js loaded via CDN — no npm install.
+ */
+export function metricsUiHtml() {
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>brains Metrics</title>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, sans-serif; background: #0f1117; color: #e2e8f0; min-height: 100vh; padding: 1.5rem; }
+    h1 { font-size: 1.5rem; font-weight: 700; margin-bottom: 0.25rem; }
+    .subtitle { color: #94a3b8; font-size: 0.875rem; margin-bottom: 1.5rem; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 1rem; }
+    .card { background: #1e2130; border: 1px solid #2d3148; border-radius: 0.75rem; padding: 1.25rem; }
+    .card h2 { font-size: 0.875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; color: #94a3b8; margin-bottom: 1rem; }
+    .stat-row { display: flex; gap: 1.5rem; margin-bottom: 1rem; }
+    .stat { display: flex; flex-direction: column; }
+    .stat-value { font-size: 1.75rem; font-weight: 700; color: #f8fafc; line-height: 1; }
+    .stat-label { font-size: 0.75rem; color: #64748b; margin-top: 0.25rem; }
+    .chart-wrap { position: relative; height: 120px; }
+    .queries { list-style: none; }
+    .queries li { display: flex; justify-content: space-between; padding: 0.375rem 0; border-bottom: 1px solid #2d3148; font-size: 0.875rem; }
+    .queries li:last-child { border-bottom: none; }
+    .q-text { color: #cbd5e1; font-family: monospace; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 200px; }
+    .status-bar { display: flex; align-items: center; gap: 0.5rem; font-size: 0.75rem; color: #64748b; margin-top: 1.5rem; }
+    .dot { width: 8px; height: 8px; border-radius: 50%; background: #22c55e; flex-shrink: 0; }
+    .dot.error { background: #ef4444; }
+    /* ── Fallback rate SLI panel ─────────────────────── */
+    .sli-ok   { color: #22c55e; }
+    .sli-warn { color: #ef4444; }
+    .sli-label { font-size: 0.75rem; color: #64748b; margin-top: 0.25rem; }
+    .sli-threshold { font-size: 0.75rem; color: #64748b; margin-top: 0.5rem; }
+    select { background: #1e2130; color: #e2e8f0; border: 1px solid #2d3148; border-radius: 0.375rem; padding: 0.25rem 0.5rem; font-size: 0.875rem; margin-left: 0.5rem; }
+    .header-row { display: flex; align-items: center; justify-content: space-between; margin-bottom: 1.5rem; flex-wrap: wrap; gap: 0.5rem; }
+  </style>
+</head>
+<body>
+  <div class="header-row">
+    <div>
+      <h1>brains Metrics</h1>
+      <p class="subtitle">Live request telemetry from <code>request_events</code></p>
+    </div>
+    <div>
+      <label for="win-select" style="font-size:0.875rem;color:#94a3b8;">Window</label>
+      <select id="win-select">
+        <option value="1h" selected>Last 1h</option>
+        <option value="6h">Last 6h</option>
+        <option value="24h">Last 24h</option>
+        <option value="7d">Last 7d</option>
+      </select>
+    </div>
+  </div>
+
+  <div class="grid">
+    <!-- Search latency -->
+    <div class="card">
+      <h2>Search Latency</h2>
+      <div class="stat-row">
+        <div class="stat"><span class="stat-value" id="s-p50">—</span><span class="stat-label">p50 ms</span></div>
+        <div class="stat"><span class="stat-value" id="s-p95">—</span><span class="stat-label">p95 ms</span></div>
+        <div class="stat"><span class="stat-value" id="s-p99">—</span><span class="stat-label">p99 ms</span></div>
+      </div>
+      <div class="chart-wrap"><canvas id="latency-chart"></canvas></div>
+    </div>
+
+    <!-- Backend breakdown -->
+    <div class="card">
+      <h2>Backend Breakdown</h2>
+      <div class="chart-wrap"><canvas id="backend-chart"></canvas></div>
+    </div>
+
+    <!-- Error & zero-result rates -->
+    <div class="card">
+      <h2>Rates</h2>
+      <div class="stat-row">
+        <div class="stat"><span class="stat-value" id="err-rate">—</span><span class="stat-label">Error rate</span></div>
+        <div class="stat"><span class="stat-value" id="zero-rate">—</span><span class="stat-label">Zero-result rate</span></div>
+      </div>
+      <div class="stat-row">
+        <div class="stat"><span class="stat-value" id="s-total">—</span><span class="stat-label">Search requests</span></div>
+        <div class="stat"><span class="stat-value" id="w-total">—</span><span class="stat-label">Write requests</span></div>
+      </div>
+    </div>
+
+    <!-- Fallback rate SLI -->
+    <div class="card">
+      <h2>Fallback Rate SLI</h2>
+      <div class="stat-row">
+        <div class="stat">
+          <span class="stat-value" id="fallback-rate">—</span>
+          <span class="sli-label">scan-fallback rate</span>
+        </div>
+        <div class="stat">
+          <span class="stat-value sli-ok" id="sli-status">—</span>
+          <span class="sli-label">SLI status</span>
+        </div>
+      </div>
+      <div class="sli-threshold">Target: &lt; 2% over window · Above 2% = index stale or corrupt</div>
+    </div>
+
+    <!-- Write latency -->
+    <div class="card">
+      <h2>Write Latency</h2>
+      <div class="stat-row">
+        <div class="stat"><span class="stat-value" id="w-p50">—</span><span class="stat-label">p50 ms</span></div>
+        <div class="stat"><span class="stat-value" id="w-p95">—</span><span class="stat-label">p95 ms</span></div>
+      </div>
+      <div class="stat-row">
+        <div class="stat"><span class="stat-value" id="overall-p95">—</span><span class="stat-label">Overall p95 ms</span></div>
+        <div class="stat"><span class="stat-value" id="overall-err">—</span><span class="stat-label">Overall error rate</span></div>
+      </div>
+    </div>
+
+    <!-- Top queries -->
+    <div class="card" style="grid-column: span 2;">
+      <h2>Top Queries by Volume</h2>
+      <ul class="queries" id="top-queries"><li><span class="q-text" style="color:#64748b;">Loading…</span></li></ul>
+    </div>
+  </div>
+
+  <div class="status-bar">
+    <span class="dot" id="status-dot"></span>
+    <span id="status-text">Initializing…</span>
+  </div>
+
+  <script>
+    let latencyChart = null;
+    let backendChart = null;
+    const latencyHistory = [];
+    const MAX_HISTORY = 30;
+
+    function pct(v) { return (v * 100).toFixed(1) + '%'; }
+    function ms(v) { return v === 0 ? '0' : String(v); }
+
+    function setStatus(ok, msg) {
+      document.getElementById('status-dot').className = 'dot' + (ok ? '' : ' error');
+      document.getElementById('status-text').textContent = msg;
+    }
+
+    function initLatencyChart() {
+      const ctx = document.getElementById('latency-chart').getContext('2d');
+      latencyChart = new Chart(ctx, {
+        type: 'line',
+        data: {
+          labels: [],
+          datasets: [
+            { label: 'p50', data: [], borderColor: '#22c55e', backgroundColor: 'transparent', tension: 0.3, pointRadius: 2 },
+            { label: 'p95', data: [], borderColor: '#f59e0b', backgroundColor: 'transparent', tension: 0.3, pointRadius: 2 },
+            { label: 'p99', data: [], borderColor: '#ef4444', backgroundColor: 'transparent', tension: 0.3, pointRadius: 2 },
+          ],
+        },
+        options: {
+          responsive: true, maintainAspectRatio: false,
+          plugins: { legend: { labels: { color: '#94a3b8', boxWidth: 12, font: { size: 10 } } } },
+          scales: {
+            x: { display: false },
+            y: { ticks: { color: '#64748b', font: { size: 10 } }, grid: { color: '#2d3148' }, beginAtZero: true },
+          },
+        },
+      });
+    }
+
+    function initBackendChart() {
+      const ctx = document.getElementById('backend-chart').getContext('2d');
+      backendChart = new Chart(ctx, {
+        type: 'doughnut',
+        data: { labels: [], datasets: [{ data: [], backgroundColor: ['#6366f1','#22c55e','#f59e0b','#ef4444','#a78bfa'], borderWidth: 0 }] },
+        options: {
+          responsive: true, maintainAspectRatio: false,
+          plugins: { legend: { position: 'right', labels: { color: '#94a3b8', font: { size: 10 }, boxWidth: 12 } } },
+        },
+      });
+    }
+
+    function updateCharts(metrics) {
+      const s = metrics.search;
+      const now = new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+      latencyHistory.push({ t: now, p50: s.p50, p95: s.p95, p99: s.p99 });
+      if (latencyHistory.length > MAX_HISTORY) latencyHistory.shift();
+
+      latencyChart.data.labels = latencyHistory.map(h => h.t);
+      latencyChart.data.datasets[0].data = latencyHistory.map(h => h.p50);
+      latencyChart.data.datasets[1].data = latencyHistory.map(h => h.p95);
+      latencyChart.data.datasets[2].data = latencyHistory.map(h => h.p99);
+      latencyChart.update('none');
+
+      const bd = s.backendBreakdown;
+      const labels = Object.keys(bd);
+      const values = labels.map(k => bd[k]);
+      backendChart.data.labels = labels.length ? labels : ['(no data)'];
+      backendChart.data.datasets[0].data = values.length ? values : [1];
+      backendChart.update('none');
+    }
+
+    function updateStats(metrics) {
+      const s = metrics.search;
+      const w = metrics.writes;
+      const o = metrics.overall;
+      document.getElementById('s-p50').textContent = ms(s.p50);
+      document.getElementById('s-p95').textContent = ms(s.p95);
+      document.getElementById('s-p99').textContent = ms(s.p99);
+      document.getElementById('err-rate').textContent = pct(s.errorRate);
+      document.getElementById('zero-rate').textContent = pct(s.zeroResultRate);
+      document.getElementById('s-total').textContent = String(s.totalRequests);
+      document.getElementById('w-total').textContent = String(w.totalRequests);
+      document.getElementById('w-p50').textContent = ms(w.p50);
+      document.getElementById('w-p95').textContent = ms(w.p95);
+      document.getElementById('overall-p95').textContent = ms(o.p95);
+      document.getElementById('overall-err').textContent = pct(o.errorRate);
+
+      // Fallback rate SLI (target < 2%)
+      const fbRate = s.fallbackRate ?? 0;
+      const fbEl = document.getElementById('fallback-rate');
+      const sliEl = document.getElementById('sli-status');
+      fbEl.textContent = pct(fbRate);
+      if (fbRate >= 0.02) {
+        fbEl.className = 'stat-value sli-warn';
+        sliEl.textContent = 'BREACH';
+        sliEl.className = 'stat-value sli-warn';
+      } else {
+        fbEl.className = 'stat-value sli-ok';
+        sliEl.textContent = 'OK';
+        sliEl.className = 'stat-value sli-ok';
+      }
+
+      const ul = document.getElementById('top-queries');
+      if (!s.topQueries.length) {
+        ul.innerHTML = '<li><span class="q-text" style="color:#64748b;">(no queries yet)</span></li>';
+      } else {
+        ul.innerHTML = s.topQueries.map(q => \`<li><span class="q-text">\${q}</span></li>\`).join('');
+      }
+    }
+
+    async function fetchMetrics() {
+      const win = document.getElementById('win-select').value;
+      try {
+        const headers = {};
+        const apiKey = window.__brainsApiKey;
+        if (apiKey) headers['x-api-key'] = apiKey;
+        const res = await fetch('/api/v1/metrics?window=' + win, { headers });
+        if (!res.ok) {
+          setStatus(false, 'Error ' + res.status + ' — ' + new Date().toLocaleTimeString());
+          return;
+        }
+        const data = await res.json();
+        updateStats(data);
+        updateCharts(data);
+        setStatus(true, 'Updated ' + new Date().toLocaleTimeString() + '  ·  window=' + win);
+      } catch (e) {
+        setStatus(false, 'Fetch error: ' + String(e));
+      }
+    }
+
+    initLatencyChart();
+    initBackendChart();
+    fetchMetrics();
+    setInterval(fetchMetrics, 30000);
+
+    document.getElementById('win-select').addEventListener('change', fetchMetrics);
+  </script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=metricsUi.js.map

package/dist/html/metricsUi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metricsUi.js","sourceRoot":"","sources":["../../src/html/metricsUi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,UAAU,aAAa;IAC3B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAqQD,CAAC;AACT,CAAC"}