@homeostat/dashboard 0.0.0-stage → 0.1.0

package/dist/src/server.js

@@ -0,0 +1,166 @@
+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 { 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 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",
+            "referrer-policy": "no-referrer",
+        });
+        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") {
+            const origin = req.headers.origin;
+            if (origin && !allowed(new URL(origin).host))
+                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 "/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;

package/dist/src/settings.js

@@ -0,0 +1,358 @@
+import { DEFAULT_AGENT_MODEL, DEFAULT_WEIGHTS, EXPORT_TARGETS, parseConfig, } from "@homeostat/core";
+import { isMap, parseDocument } from "yaml";
+const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+const agentFields = (agent, label) => [
+    { path: ["agents", agent, "enabled"], label: `${label}: enabled`, kind: "checkbox" },
+    {
+        path: ["agents", agent, "schedule"],
+        label: `${label}: schedule`,
+        kind: "text",
+        help: "Five-field cron, UTC",
+    },
+    {
+        path: ["agents", agent, "model"],
+        label: `${label}: model`,
+        kind: "text",
+        help: `Claude model id, e.g. ${DEFAULT_AGENT_MODEL}`,
+    },
+    {
+        path: ["agents", agent, "effort"],
+        label: `${label}: effort`,
+        kind: "select",
+        options: EFFORTS,
+    },
+    {
+        path: ["agents", agent, "lookbackHours"],
+        label: `${label}: look back (hours)`,
+        kind: "number",
+    },
+];
+/** Every section of homeostat.yaml, so every key is editable without touching YAML (4.2). */
+export const SECTIONS = [
+    {
+        id: "team",
+        title: "Team and members",
+        intro: "Who contributes and reviews. Seniors own the config and areas nobody claims; handles feed CODEOWNERS.",
+        rows: "team",
+    },
+    {
+        id: "areas",
+        title: "Areas",
+        intro: "Parts of your code repos, as path globs. Core is implicit and applies everywhere.",
+        rows: "areas",
+    },
+    {
+        id: "teams",
+        title: "Teams",
+        intro: "Which team owns which areas: it approves their rules and documents. Every session still reads every team's rules for the files it touches.",
+        rows: "teams",
+    },
+    {
+        id: "sources",
+        title: "Repos and sources",
+        intro: "Where the curator reads merged pull requests, and the knowledge-base repo it opens PRs on.",
+        fields: [
+            {
+                path: ["sources", "host"],
+                label: "Git host",
+                kind: "select",
+                options: ["", "bitbucket", "github"],
+                help: "Empty removes the section",
+            },
+            {
+                path: ["sources", "kbRepo"],
+                label: "Knowledge-base repo",
+                kind: "text",
+                help: "owner/name",
+            },
+            { path: ["sources", "baseBranch"], label: "Base branch", kind: "text" },
+            {
+                path: ["sources", "repos"],
+                label: "Code repos",
+                kind: "lines",
+                help: "One owner/name per line",
+            },
+            {
+                path: ["sources", "exclude", "repos"],
+                label: "Never read these repos",
+                kind: "lines",
+                help: "One owner/name per line",
+            },
+            {
+                path: ["sources", "exclude", "paths"],
+                label: "Never read comments on these files",
+                kind: "lines",
+                help: "One glob per line, e.g. **/secrets/**",
+            },
+        ],
+    },
+    {
+        id: "scoring",
+        title: "Scoring rules",
+        intro: "Points per signal and the threshold at which a curator's entry is accepted without a reviewer.",
+        fields: [
+            ...Object.keys(DEFAULT_WEIGHTS).map((k) => ({ path: ["scoring", "weights", k], label: `Weight: ${k}`, kind: "number" })),
+            { path: ["scoring", "autoMergeThreshold"], label: "Auto-merge threshold", kind: "number" },
+            { path: ["scoring", "autoMerge", "enabled"], label: "Auto-merge", kind: "checkbox" },
+            {
+                path: ["scoring", "autoMerge", "areas"],
+                label: "Auto-merge areas",
+                kind: "lines",
+                help: "One per line; empty means every area",
+            },
+            {
+                path: ["scoring", "autoMerge", "excludeAreas"],
+                label: "Areas that always need a reviewer",
+                kind: "lines",
+                help: "One per line, e.g. core",
+            },
+            { path: ["scoring", "autoMerge", "maxPerRun"], label: "Auto-merges per run", kind: "number" },
+            {
+                path: ["scoring", "reviewCadence"],
+                label: "Review cadence",
+                kind: "select",
+                options: ["daily", "weekly", "biweekly"],
+            },
+        ],
+    },
+    {
+        id: "agents",
+        title: "Agent schedules",
+        intro: "How the agents reach Claude, when they run, and with which model.",
+        fields: [
+            {
+                path: ["agents", "runtime"],
+                label: "Claude runtime",
+                kind: "select",
+                options: ["api", "claude-code", "bedrock", "vertex"],
+                help: "api: Console key. claude-code: a Claude Code login (personal use, or a Team/Enterprise plan). bedrock / vertex: your own AWS or Google Cloud account",
+            },
+            {
+                path: ["agents", "bedrock", "region"],
+                label: "Bedrock region",
+                kind: "text",
+                optional: true,
+                help: "e.g. eu-west-1; empty uses AWS_REGION",
+            },
+            {
+                path: ["agents", "vertex", "projectId"],
+                label: "Vertex project",
+                kind: "text",
+                optional: true,
+                help: "Google Cloud project id",
+            },
+            {
+                path: ["agents", "vertex", "region"],
+                label: "Vertex region",
+                kind: "text",
+                optional: true,
+                help: "global, us, eu or a region",
+            },
+            ...agentFields("curator", "Curator"),
+            ...agentFields("deepDive", "Deep dive"),
+            {
+                path: ["agents", "deepDive", "staleAfterDays"],
+                label: "Deep dive: retire after (days unconfirmed)",
+                kind: "number",
+            },
+            { path: ["agents", "handoff", "enabled"], label: "Handoff notes: enabled", kind: "checkbox" },
+            {
+                path: ["agents", "handoff", "minEdits"],
+                label: "Handoff notes: edits before asking",
+                kind: "number",
+            },
+        ],
+    },
+    {
+        id: "distribution",
+        title: "Distribution",
+        intro: "Which agents receive the rules as files, and how much context each session gets.",
+        fields: [
+            {
+                path: ["distribution", "exports"],
+                label: "Export targets",
+                kind: "checks",
+                options: EXPORT_TARGETS,
+            },
+            { path: ["distribution", "tokenBudget"], label: "Token budget per session", kind: "number" },
+            {
+                path: ["distribution", "docTokenBudget"],
+                label: "Token budget for documents",
+                kind: "number",
+            },
+        ],
+    },
+    {
+        id: "notifications",
+        title: "Notifications",
+        intro: "The weekly digest. The webhook URL stays in your CI secrets; only its variable name lives here.",
+        fields: [
+            {
+                path: ["notifications", "slackWebhookEnv"],
+                label: "Slack webhook variable",
+                kind: "text",
+                optional: true,
+                help: "e.g. HOMEOSTAT_SLACK_WEBHOOK",
+            },
+            {
+                path: ["notifications", "digestDay"],
+                label: "Digest day",
+                kind: "select",
+                options: ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"],
+            },
+        ],
+    },
+    {
+        id: "security",
+        title: "Security",
+        intro: "Domains rules may link to. Any other URL in a rule fails validation until a member signs the entry off; the git host is always allowed.",
+        fields: [
+            {
+                path: ["security", "allowedDomains"],
+                label: "Allowed domains",
+                kind: "lines",
+                help: "One domain per line, e.g. docs.example.com",
+            },
+            {
+                path: ["security", "teamOnlyAreas"],
+                label: "Team-only areas",
+                kind: "lines",
+                help: "Never exported; only their members' sessions see them",
+            },
+            {
+                path: ["security", "mcpWrites"],
+                label: "Let agents save and flag through MCP",
+                kind: "checkbox",
+            },
+            { path: ["security", "mcpWriteLimit"], label: "MCP writes per session", kind: "number" },
+            {
+                path: ["security", "eventRetentionDays"],
+                label: "Keep local events for (days)",
+                kind: "number",
+            },
+        ],
+    },
+];
+/** The current value of a field, from the parsed (defaulted) config. */
+export function currentValue(config, field) {
+    let v = config;
+    for (const k of field.path)
+        v = v?.[k];
+    return v;
+}
+const lines = (s) => s
+    .split(/[\n,]/)
+    .map((x) => x.trim())
+    .filter(Boolean);
+/**
+ * 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 function applySection(yamlText, sectionId, form) {
+    const section = SECTIONS.find((s) => s.id === sectionId);
+    if (!section)
+        return {
+            issues: [
+                { code: "settings.section", severity: "error", message: `unknown section ${sectionId}` },
+            ],
+        };
+    const doc = parseDocument(yamlText);
+    if (section.rows === "team") {
+        const members = rowIndices(form, "member").flatMap((i) => {
+            const id = form.get(`member.${i}.id`)?.trim();
+            if (!id || form.get(`member.${i}.remove`))
+                return [];
+            const handle = form.get(`member.${i}.handle`)?.trim();
+            const areas = lines(form.get(`member.${i}.areas`) ?? "");
+            return [
+                {
+                    id,
+                    ...(handle ? { handle } : {}),
+                    role: form.get(`member.${i}.role`) ?? "member",
+                    areas,
+                    ...(form.get(`member.${i}.optOut`) ? { optOut: true } : {}),
+                },
+            ];
+        });
+        doc.setIn(["team", "members"], doc.createNode(members));
+    }
+    else if (section.rows === "teams") {
+        const teams = {};
+        for (const i of rowIndices(form, "teamrow")) {
+            const name = form.get(`teamrow.${i}.name`)?.trim();
+            if (!name || form.get(`teamrow.${i}.remove`))
+                continue;
+            const handle = form.get(`teamrow.${i}.handle`)?.trim();
+            teams[name] = {
+                ...(handle ? { handle } : {}),
+                members: lines(form.get(`teamrow.${i}.members`) ?? ""),
+                areas: lines(form.get(`teamrow.${i}.areas`) ?? ""),
+                repos: lines(form.get(`teamrow.${i}.repos`) ?? ""),
+            };
+        }
+        if (Object.keys(teams).length)
+            doc.setIn(["teams"], doc.createNode(teams));
+        else if (doc.has("teams"))
+            doc.delete("teams");
+    }
+    else if (section.rows === "areas") {
+        const areas = {};
+        for (const i of rowIndices(form, "area")) {
+            const name = form.get(`area.${i}.name`)?.trim();
+            if (!name || form.get(`area.${i}.remove`))
+                continue;
+            areas[name] = lines(form.get(`area.${i}.globs`) ?? "");
+        }
+        doc.setIn(["areas"], doc.createNode(areas));
+    }
+    else {
+        for (const field of section.fields ?? []) {
+            const name = field.path.join(".");
+            const raw = form.get(name);
+            if (field.path.join(".") === "sources.host" && !raw) {
+                doc.deleteIn(["sources"]);
+                break;
+            }
+            if (field.kind === "checkbox")
+                doc.setIn(field.path, form.get(name) === "on");
+            else if (field.kind === "checks")
+                doc.setIn(field.path, doc.createNode(form.getAll(name)));
+            else if (field.kind === "lines")
+                doc.setIn(field.path, doc.createNode(lines(raw ?? "")));
+            else if (field.kind === "number") {
+                // An empty or missing number means "use the default", so the key is removed.
+                if (raw === null || raw === "") {
+                    if (doc.hasIn(field.path))
+                        doc.deleteIn(field.path);
+                }
+                else
+                    doc.setIn(field.path, Number(raw));
+            }
+            else if (field.optional && !raw?.trim()) {
+                if (doc.hasIn(field.path))
+                    doc.deleteIn(field.path);
+            }
+            else if (raw !== null)
+                doc.setIn(field.path, raw.trim());
+        }
+    }
+    // Drop sections that became empty maps, so the defaults apply.
+    for (const key of ["notifications", "distribution", "scoring", "security"]) {
+        const node = doc.get(key, true);
+        if (isMap(node) && node.items.length === 0)
+            doc.delete(key);
+    }
+    const text = doc.toString();
+    const { config, issues } = parseConfig(text);
+    return config ? { text, issues: [] } : { issues };
+}
+/** Row numbers present in the form for a row editor (`member.0.id`, `member.3.id`, ...). */
+function rowIndices(form, prefix) {
+    const seen = new Set();
+    for (const key of form.keys()) {
+        const m = new RegExp(`^${prefix}\\.(\\d+)\\.`).exec(key);
+        if (m)
+            seen.add(Number(m[1]));
+    }
+    return [...seen].sort((a, b) => a - b);
+}

package/dist/src/views.d.ts

@@ -0,0 +1,36 @@
+import { type Config, type Entry, type Event, type Issue, type SectionUsage } from "@homeostat/core";
+import type { AgentLiveness, Contribution, DesirePath, Health, Impact } from "./metrics.ts";
+import { type Section } from "./settings.ts";
+export declare function layout(opts: {
+    title: string;
+    path: string;
+    kbRoot: string;
+    body: string;
+    theme?: "light" | "dark";
+}): string;
+export declare function overviewPage(h: Health, agents: AgentLiveness[], imp: Impact, recent: Event[]): string;
+export declare function entriesPage(entries: readonly Entry[], status: string | null): string;
+export declare function entryPage(entry: Entry, config: Config): string;
+export declare function membersPage(rowsData: Contribution[]): string;
+export declare function coveragePage(cov: {
+    areas: {
+        area: string;
+        globs: readonly string[];
+        accepted: number;
+        candidates: number;
+    }[];
+    sources: {
+        repo: string;
+        entries: number;
+    }[];
+}): string;
+export declare function impactPage(imp: Impact): string;
+export declare function documentsPage(usage: readonly SectionUsage[]): string;
+export declare function desirePathsPage(paths: DesirePath[]): string;
+export declare function eventsPage(events: Event[]): string;
+export declare function settingsIndex(): string;
+export declare function settingsPage(section: Section, config: Config, token: string, notice?: {
+    saved?: boolean;
+    issues?: Issue[];
+}): string;
+export declare function messagePage(title: string, text: string): string;