@homeostat/dashboard 0.0.0-stage → 0.1.1

package/dist/src/metrics.js

@@ -0,0 +1,143 @@
+import { CORE_AREA, detectConflicts, nextRun, STATUSES, } from "@homeostat/core";
+const DAY = 86_400_000;
+const day = (d) => d.toISOString().slice(0, 10);
+const daysSince = (iso, now) => Math.floor((now.getTime() - Date.parse(iso)) / DAY);
+export function agentLiveness({ config, events, now }) {
+    const week = new Date(now.getTime() - 7 * DAY).toISOString();
+    return ["curator", "deepDive"].map((agent) => {
+        const runs = events.filter((e) => e.type === "agent-run" && e.agent === agent);
+        const last = runs.at(-1);
+        const success = runs.filter((r) => r.ok === true).at(-1);
+        const next = config.agents[agent].enabled
+            ? nextRun(config.agents[agent].schedule, now)
+            : undefined;
+        return {
+            agent,
+            enabled: config.agents[agent].enabled,
+            schedule: config.agents[agent].schedule,
+            ...(next ? { nextRun: next.toISOString() } : {}),
+            ...(last
+                ? { lastRun: { ts: last.ts, ok: last.ok === true, summary: String(last.summary ?? "") } }
+                : {}),
+            ...(success ? { lastSuccess: success.ts } : {}),
+            failures7d: runs.filter((r) => r.ok === false && r.ts >= week).length,
+        };
+    });
+}
+export function health({ config, entries, now }) {
+    const byStatus = Object.fromEntries(STATUSES.map((s) => [s, 0]));
+    for (const e of entries)
+        byStatus[e.frontmatter.status]++;
+    const accepted = entries.filter((e) => e.frontmatter.status === "accepted");
+    const staleAfter = config.agents.deepDive.staleAfterDays;
+    const stale = accepted.filter((e) => daysSince(e.frontmatter.lastConfirmed, now) > staleAfter);
+    const flagged = entries.filter((e) => e.frontmatter.flags?.length);
+    const healthy = accepted.filter((e) => !stale.includes(e) && !e.frontmatter.flags?.length);
+    return {
+        total: entries.length,
+        byStatus,
+        averageAgeDays: accepted.length
+            ? Math.round(accepted.reduce((n, e) => n + daysSince(e.frontmatter.lastConfirmed, now), 0) /
+                accepted.length)
+            : 0,
+        stale: stale.map((e) => e.frontmatter.id),
+        disputed: entries
+            .filter((e) => e.frontmatter.status === "disputed")
+            .map((e) => e.frontmatter.id),
+        flagged: flagged.map((e) => e.frontmatter.id),
+        possibleDuplicates: detectConflicts(entries.map((e) => e.frontmatter))
+            .filter((c) => c.kind === "possible-duplicate")
+            .map((c) => [c.ids[0] ?? "", c.ids[1] ?? ""]),
+        stability: entries.length ? healthy.length / entries.length : 0,
+    };
+}
+export function contributions({ config, entries, events, now }) {
+    const month = new Date(now.getTime() - 30 * DAY).toISOString();
+    return [...config.team.members]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((m) => {
+        const authored = entries.filter((e) => e.frontmatter.source.author === m.id);
+        const accepted = authored.filter((e) => e.frontmatter.status === "accepted").length;
+        return {
+            member: m.id,
+            role: m.role,
+            authored: authored.length,
+            accepted,
+            ...(authored.length ? { acceptedRatio: accepted / authored.length } : {}),
+            flagsRaised: entries.reduce((n, e) => n + (e.frontmatter.flags ?? []).filter((f) => f.by === m.id).length, 0),
+            captured30d: events.filter((e) => e.type === "entry-created" && e.author === m.id && e.ts >= month).length,
+        };
+    });
+}
+export function coverage({ config, entries }) {
+    const areas = [CORE_AREA, ...Object.keys(config.areas)].map((area) => {
+        const inArea = entries.filter((e) => e.frontmatter.area === area);
+        return {
+            area,
+            globs: area === CORE_AREA ? ["**"] : (config.areas[area] ?? []),
+            accepted: inArea.filter((e) => e.frontmatter.status === "accepted").length,
+            candidates: inArea.filter((e) => e.frontmatter.status === "candidate").length,
+        };
+    });
+    const sources = (config.sources?.repos ?? []).map((repo) => ({
+        repo,
+        entries: entries.filter((e) => e.frontmatter.source.url?.toLowerCase().includes(`/${repo.toLowerCase()}/`)).length,
+    }));
+    return { areas, sources };
+}
+function byDay(events, type, now, days) {
+    const out = [];
+    for (let i = days - 1; i >= 0; i--) {
+        const d = day(new Date(now.getTime() - i * DAY));
+        out.push({
+            day: d,
+            count: events.filter((e) => e.type === type && e.ts.slice(0, 10) === d).length,
+        });
+    }
+    return out;
+}
+export function impact({ events, now }, days = 14) {
+    const injections = events.filter((e) => e.type === "injection");
+    const ids = injections.flatMap((e) => (e.entries ?? []).map((x) => x.id));
+    const counts = new Map();
+    for (const id of ids)
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    const tools = new Map();
+    for (const e of events.filter((x) => x.type === "mcp-call"))
+        tools.set(String(e.tool), (tools.get(String(e.tool)) ?? 0) + 1);
+    return {
+        injectionsByDay: byDay(events, "injection", now, days),
+        mcpCallsByDay: byDay(events, "mcp-call", now, days),
+        sessions: new Set(injections.map((e) => e.session).filter(Boolean)).size,
+        rulesPerInjection: injections.length
+            ? Math.round((ids.length / injections.length) * 10) / 10
+            : 0,
+        tokensPerInjection: injections.length
+            ? Math.round(injections.reduce((n, e) => n + (Number(e.tokens) || 0), 0) / injections.length)
+            : 0,
+        topRules: [...counts]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .slice(0, 8)
+            .map(([id, n]) => ({ id, injections: n })),
+        toolUse: [...tools].sort((a, b) => b[1] - a[1]).map(([tool, calls]) => ({ tool, calls })),
+    };
+}
+/** Tool names agents guessed: the ones to consider implementing (execution plan 3.2). */
+export function desirePaths({ events }) {
+    const paths = new Map();
+    for (const e of events) {
+        if (e.type !== "mcp-alias" && e.type !== "mcp-unknown-tool")
+            continue;
+        const name = String(e.name);
+        const p = paths.get(name) ?? {
+            name,
+            count: 0,
+            last: e.ts,
+            ...(e.resolved ? { resolved: String(e.resolved) } : {}),
+        };
+        p.count++;
+        p.last = e.ts > p.last ? e.ts : p.last;
+        paths.set(name, p);
+    }
+    return [...paths.values()].sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}

package/dist/src/server.d.ts

@@ -0,0 +1,17 @@
+import { type Server } from "node:http";
+export interface DashboardOptions {
+    kbRoot: string;
+    port?: number;
+    /** Interface to bind; loopback by default so the dashboard is never on the network. */
+    host?: string;
+    now?: () => Date;
+}
+/**
+ * The local dashboard: setup forms and metrics, rendered on the server from the KB checkout and
+ * its event log on every request, so it is always live. Binds to loopback and rejects requests
+ * whose Host or Origin is not this server, so other web pages cannot drive its forms.
+ */
+export declare function startDashboard(opts: DashboardOptions): Promise<{
+    server: Server;
+    url: string;
+}>;

package/dist/src/server.js

@@ -0,0 +1,180 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { CONFIG_FILE, readEvents, readKbFiles, sectionUsage, validate, } from "@homeostat/core";
+import { automationPage, automationView, readAutomation } from "./automation.js";
+import { agentLiveness, contributions, coverage, desirePaths, health, impact, } from "./metrics.js";
+import { applySection, SECTIONS } from "./settings.js";
+import { coveragePage, desirePathsPage, documentsPage, entriesPage, entryPage, eventsPage, impactPage, layout, membersPage, messagePage, overviewPage, settingsIndex, settingsPage, } from "./views.js";
+const MAX_BODY = 256 * 1024;
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_BODY) {
+                reject(new Error("body too large"));
+                req.destroy();
+            }
+            else
+                chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+const sameToken = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/**
+ * The local dashboard: setup forms and metrics, rendered on the server from the KB checkout and
+ * its event log on every request, so it is always live. Binds to loopback and rejects requests
+ * whose Host or Origin is not this server, so other web pages cannot drive its forms.
+ */
+export function startDashboard(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const token = randomBytes(24).toString("hex");
+    const now = opts.now ?? (() => new Date());
+    // DNS-rebinding protection keys on the hostname: a browser only sends one of these when it
+    // really is talking to this machine. Any port, so a container's port mapping still works.
+    const allowedNames = new Set([
+        "localhost",
+        "127.0.0.1",
+        "[::1]",
+        ...(host === "0.0.0.0" ? [] : [host]),
+    ]);
+    const sameSite = (origin) => {
+        try {
+            return allowed(new URL(origin).host);
+        }
+        catch {
+            return false;
+        }
+    };
+    const allowed = (hostPort) => {
+        try {
+            return Boolean(hostPort) && allowedNames.has(new URL(`http://${hostPort}`).hostname);
+        }
+        catch {
+            return false;
+        }
+    };
+    const snapshot = () => {
+        const kb = validate(readKbFiles(opts.kbRoot));
+        if (!kb.config)
+            return undefined;
+        const since = new Date(now().getTime() - 90 * 86_400_000).toISOString();
+        return {
+            config: kb.config,
+            entries: kb.entries.map((e) => e.entry),
+            docs: kb.docs,
+            events: readEvents(opts.kbRoot, { since }),
+            now: now(),
+        };
+    };
+    const send = (res, status, html) => {
+        res.writeHead(status, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; form-action 'self'; frame-ancestors 'none'",
+            "x-content-type-options": "nosniff",
+            // same-origin, not no-referrer: under no-referrer Chrome sends "Origin: null" on this
+            // page's own form posts, which the write check below must refuse.
+            "referrer-policy": "same-origin",
+        });
+        res.end(html);
+    };
+    const handler = async (req, res) => {
+        // DNS-rebinding and cross-site protection: only our own Host, and our own Origin on writes.
+        if (!allowed(req.headers.host))
+            return send(res, 421, "Misdirected request");
+        const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+        const t = url.searchParams.get("theme");
+        const theme = t === "light" || t === "dark" ? { theme: t } : {};
+        const page = (title, body, status = 200) => send(res, status, layout({ title, path: url.pathname, kbRoot: opts.kbRoot, body, ...theme }));
+        const snap = snapshot();
+        if (!snap) {
+            return page("No knowledge base", messagePage("No knowledge base", `${CONFIG_FILE} is missing or invalid in ${opts.kbRoot}. Run homeostat validate there.`), 500);
+        }
+        if (req.method === "POST") {
+            // Our own pages send their origin; "null" or anything unreadable is refused, never parsed blind.
+            const origin = req.headers.origin;
+            if (origin && !sameSite(origin))
+                return send(res, 403, "Cross-origin request refused");
+            const m = /^\/settings\/([a-z]+)$/.exec(url.pathname);
+            const section = m && SECTIONS.find((s) => s.id === m[1]);
+            if (!section)
+                return page("Not found", messagePage("Not found", "No such settings section."), 404);
+            let form;
+            try {
+                form = new URLSearchParams(await readBody(req));
+            }
+            catch {
+                return send(res, 413, "Too large");
+            }
+            if (!sameToken(form.get("_token") ?? "", token))
+                return send(res, 403, "Stale form: reload the page and try again");
+            const path = join(opts.kbRoot, CONFIG_FILE);
+            const result = applySection(readFileSync(path, "utf8"), section.id, form);
+            if (!result.text)
+                return page(section.title, settingsPage(section, snap.config, token, { issues: result.issues }), 422);
+            writeFileSync(path, result.text);
+            const fresh = snapshot();
+            return page(section.title, settingsPage(section, fresh?.config ?? snap.config, token, { saved: true }));
+        }
+        if (req.method !== "GET")
+            return send(res, 405, "Method not allowed");
+        const week = new Date(snap.now.getTime() - 7 * 86_400_000).toISOString();
+        switch (url.pathname) {
+            case "/": {
+                const recent = snap.events.slice(-12).reverse();
+                return page("Overview", overviewPage(health(snap), agentLiveness(snap), impact(snap), recent));
+            }
+            case "/automation":
+                return page("Automation", automationPage(automationView(readAutomation(opts.kbRoot), snap.config, snap.now)));
+            case "/entries":
+                return page("Entries", entriesPage(snap.entries, url.searchParams.get("status")));
+            case "/members":
+                return page("Members", membersPage(contributions(snap)));
+            case "/coverage":
+                return page("Coverage", coveragePage(coverage(snap)));
+            case "/impact":
+                return page("Impact", impactPage(impact(snap)));
+            case "/documents":
+                return page("Documents", documentsPage(sectionUsage(snap.docs ?? [], snap.events, snap.now)));
+            case "/desire-paths":
+                return page("Desire paths", desirePathsPage(desirePaths(snap)));
+            case "/events":
+                return page("Events", eventsPage(snap.events.filter((e) => e.ts >= week).reverse()));
+            case "/settings":
+                return page("Settings", settingsIndex());
+        }
+        const entry = /^\/entries\/([a-z0-9-]+)$/.exec(url.pathname);
+        if (entry) {
+            const found = snap.entries.find((e) => e.frontmatter.id === entry[1]);
+            return found
+                ? page(found.frontmatter.title, entryPage(found, snap.config))
+                : page("Not found", messagePage("Not found", `No entry with id ${entry[1]}.`), 404);
+        }
+        const settings = /^\/settings\/([a-z]+)$/.exec(url.pathname);
+        const section = settings && SECTIONS.find((s) => s.id === settings[1]);
+        if (section)
+            return page(section.title, settingsPage(section, snap.config, token));
+        return page("Not found", messagePage("Not found", "Nothing here."), 404);
+    };
+    const server = createServer((req, res) => {
+        handler(req, res).catch((e) => {
+            send(res, 500, `Dashboard error: ${String(e.message).replace(/</g, "&lt;")}`);
+        });
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port ?? 4747, host, () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : (opts.port ?? 4747);
+            resolve({
+                server,
+                url: `http://${host === "127.0.0.1" || host === "0.0.0.0" ? "localhost" : host}:${port}`,
+            });
+        });
+    });
+}

package/dist/src/settings.d.ts

@@ -0,0 +1,32 @@
+import { type Config, type Issue } from "@homeostat/core";
+/** One editable config key. `path` is its location in homeostat.yaml. */
+export interface Field {
+    path: string[];
+    label: string;
+    kind: "text" | "number" | "select" | "checkbox" | "checks" | "lines";
+    options?: readonly string[];
+    help?: string;
+    /** Empty means "remove the key" rather than an empty value. */
+    optional?: boolean;
+}
+export interface Section {
+    id: string;
+    title: string;
+    intro: string;
+    fields?: Field[];
+    /** Row editors for the two keyed lists. */
+    rows?: "team" | "areas" | "teams";
+}
+/** Every section of homeostat.yaml, so every key is editable without touching YAML (4.2). */
+export declare const SECTIONS: Section[];
+/** The current value of a field, from the parsed (defaulted) config. */
+export declare function currentValue(config: Config, field: Field): unknown;
+export interface ApplyResult {
+    text?: string;
+    issues: Issue[];
+}
+/**
+ * Applies one submitted section to the YAML text, keeping comments and untouched keys, and
+ * validates the result. Returns the new text only when it is valid.
+ */
+export declare function applySection(yamlText: string, sectionId: string, form: URLSearchParams): ApplyResult;