@homeostat/dashboard 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @homeostat/dashboard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local dashboard for [homeostat](https://www.npmjs.com/package/homeostat): knowledge-base health, agent liveness, impact, document usage and settings forms, served on localhost. Start it with `homeostat dashboard`.
+
+Apache-2.0. Source: <https://github.com/ysugarmen/homeostat>.

package/dist/src/automation.d.ts

@@ -0,0 +1,44 @@
+import { type Config, type DecisionRecord, type DecisionsFile, type Heartbeat, type RunReport } from "@homeostat/core";
+/**
+ * The Automation page reads the `homeostat/state` branch the daily run writes. It reads the
+ * clone's copy (`origin/homeostat/state`), which every sync fetches, so the page makes no network
+ * call: it is as current as this clone's last sync.
+ */
+export interface AutomationState {
+    /** False when no daily run has written the state branch yet (or this clone never fetched it). */
+    present: boolean;
+    runs: RunReport[];
+    heartbeats: Heartbeat[];
+    decisions: DecisionsFile[];
+}
+export declare function readAutomation(kbRoot: string, maxRuns?: number): AutomationState;
+export interface SyncHealth {
+    member: string;
+    role: string;
+    heartbeat?: Heartbeat;
+    /** "ok", "stale" (no report for STALE_HEARTBEAT_HOURS), "never" (no sync has reported) */
+    state: "ok" | "stale" | "never";
+    ageHours?: number;
+    today?: RunReport["members"][number];
+}
+export interface QueueItem extends DecisionRecord {
+    member: string;
+    ageDays: number;
+    overdue: boolean;
+}
+export interface AutomationView {
+    present: boolean;
+    lastRun?: RunReport;
+    runs: RunReport[];
+    health: SyncHealth[];
+    queue: QueueItem[];
+    /** Lessons decided per day, by outcome, over the runs on record. */
+    byDay: {
+        day: string;
+        merged: number;
+        review: number;
+        declined: number;
+    }[];
+}
+export declare function automationView(state: AutomationState, config: Config, now: Date): AutomationView;
+export declare function automationPage(v: AutomationView): string;

package/dist/src/automation.js

@@ -0,0 +1,142 @@
+import { execFileSync } from "node:child_process";
+import { REVIEW_REMINDER_DAYS, STALE_HEARTBEAT_HOURS, STATE_BRANCH, } from "@homeostat/core";
+import { columns, dataTable, esc } from "./charts.js";
+const REF = `refs/remotes/origin/${STATE_BRANCH}`;
+function git(dir, ...args) {
+    try {
+        return execFileSync("git", ["-C", dir, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 32 * 1024 * 1024,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function json(dir, path) {
+    try {
+        return JSON.parse(git(dir, "show", `${REF}:${path}`) ?? "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readAutomation(kbRoot, maxRuns = 30) {
+    const listing = git(kbRoot, "ls-tree", "-r", "--name-only", REF);
+    if (listing === undefined)
+        return { present: false, runs: [], heartbeats: [], decisions: [] };
+    const paths = listing.split("\n").filter(Boolean);
+    const under = (dir) => paths.filter((p) => p.startsWith(`${dir}/`) && p.endsWith(".json"));
+    const runs = under("runs")
+        .sort()
+        .slice(-maxRuns)
+        .flatMap((p) => json(kbRoot, p) ?? []);
+    const heartbeats = under("heartbeats").flatMap((p) => json(kbRoot, p) ?? []);
+    const decisions = under("decisions").flatMap((p) => json(kbRoot, p) ?? []);
+    return { present: true, runs, heartbeats, decisions };
+}
+export function automationView(state, config, now) {
+    const lastRun = state.runs.at(-1);
+    const health = config.team.members.map((m) => {
+        const heartbeat = state.heartbeats.find((h) => h.member === m.id);
+        const ageHours = heartbeat ? (now.getTime() - Date.parse(heartbeat.at)) / 3_600_000 : undefined;
+        const today = lastRun?.members.find((r) => r.member === m.id);
+        return {
+            member: m.id,
+            role: m.role,
+            ...(heartbeat ? { heartbeat } : {}),
+            ...(ageHours !== undefined ? { ageHours } : {}),
+            ...(today ? { today } : {}),
+            state: !heartbeat ? "never" : (ageHours ?? 0) > STALE_HEARTBEAT_HOURS ? "stale" : "ok",
+        };
+    });
+    const queue = state.decisions
+        .flatMap((d) => d.decided
+        .filter((r) => r.decision === "review")
+        .map((r) => {
+        const ageDays = (now.getTime() - Date.parse(r.at)) / 86_400_000;
+        return { ...r, member: d.member, ageDays, overdue: ageDays > REVIEW_REMINDER_DAYS };
+    }))
+        .sort((a, b) => b.ageDays - a.ageDays);
+    const byDay = state.runs.map((r) => ({
+        day: r.at.slice(0, 10),
+        merged: r.members.reduce((n, m) => n + m.merged, 0),
+        review: r.members.reduce((n, m) => n + m.review, 0),
+        declined: r.members.reduce((n, m) => n + m.declined, 0),
+    }));
+    return {
+        present: state.present,
+        ...(lastRun ? { lastRun } : {}),
+        runs: state.runs,
+        health,
+        queue,
+        byDay,
+    };
+}
+const age = (hours) => hours === undefined
+    ? "—"
+    : hours < 1
+        ? "under 1h"
+        : hours < 48
+            ? `${Math.round(hours)}h`
+            : `${Math.round(hours / 24)}d`;
+const prLink = (url, label = "PR") => url && /^https:\/\//.test(url) ? `<a href="${esc(url)}">${esc(label)}</a>` : "";
+function healthRow(h) {
+    const lamp = h.state === "ok" ? "good" : h.state === "stale" ? "warning" : "";
+    const state = h.state === "ok"
+        ? "Syncing"
+        : h.state === "stale"
+            ? `Not syncing for ${age(h.ageHours)}`
+            : "No sync yet";
+    const hb = h.heartbeat;
+    const kb = !hb ? "—" : hb.behind > 0 ? `${hb.behind} behind` : "current";
+    const t = h.today;
+    const outcome = t
+        ? `${t.merged} merged · ${t.review} to review · ${t.declined} declined${t.mergeError ? " · merge refused" : ""}`
+        : "—";
+    return `<tr><td class="mono">${esc(h.member)}</td><td>${esc(h.role)}</td><td><span class="lamp ${lamp}" aria-hidden="true" style="display:inline-block;vertical-align:middle;margin-right:6px"></span>${esc(state)}</td><td class="num">${age(h.ageHours)}</td><td class="mono">${esc(kb)}</td><td class="num">${hb?.pending ?? "—"}</td><td class="mono">${esc(hb?.version ?? "—")}</td><td>${esc(outcome)} ${prLink(t?.dailyPr, "daily")} ${prLink(t?.reviewPr, "review")}</td></tr>`;
+}
+export function automationPage(v) {
+    if (!v.present) {
+        return `<section class="panel"><h2>Automation</h2><p class="lede">No daily run on record in this clone yet. The daily run (<code>homeostat daily</code>, scheduled in the KB repo's CI) writes its decisions to the <code>${STATE_BRANCH}</code> branch, and each developer's sync fetches it. Once the first run has happened and this clone has synced, its runs, every developer's sync health and the review queue show up here.</p></section>`;
+    }
+    const r = v.lastRun;
+    const stat = (n, k) => `<div class="stat"><span class="n">${n}</span><span class="k">${k}</span></div>`;
+    const total = (k) => r?.members.reduce((n, m) => n + m[k], 0) ?? 0;
+    const notSyncing = v.health.filter((h) => h.state !== "ok");
+    const overdue = v.queue.filter((q) => q.overdue).length;
+    const daily = v.byDay.map((d) => ({
+        label: d.day.slice(5),
+        value: d.merged + d.review + d.declined,
+        title: `${d.day}: ${d.merged} merged, ${d.review} to review, ${d.declined} declined`,
+    }));
+    return `<div class="grid">
+<section class="panel span-8" aria-labelledby="last"><h2 id="last">Last daily run</h2>
+${r ? `<p class="lede mono">${esc(r.at.replace("T", " ").slice(0, 16))} UTC</p>` : ""}
+<div class="stats" style="--cols: 4">${stat(total("merged"), "merged")}${stat(total("review"), "to review")}${stat(total("declined"), "declined")}${stat(r?.settled ?? 0, "settled by reviewers")}</div>
+${daily.length > 1 ? `<div style="margin-top:14px"><span class="label">Lessons decided per run</span>${columns(daily, { title: "Lessons decided per run", labelled: "ends", tickEvery: 7 })}${dataTable(daily, ["Run", "Lessons"])}</div>` : ""}</section>
+<section class="panel span-4" aria-labelledby="attention"><h2 id="attention">Needs attention</h2>
+<div class="stats" style="--cols: 2">${stat(v.queue.length, "in review")}${stat(overdue, `waiting &gt; ${REVIEW_REMINDER_DAYS} days`)}${stat(notSyncing.length, "not syncing")}${stat(r?.members.filter((m) => m.mergeError).length ?? 0, "merges refused")}</div>
+${notSyncing.length ? `<p class="lede">Not syncing: ${notSyncing.map((h) => `<span class="mono">${esc(h.member)}</span>`).join(", ")}. Their lessons reach the daily run only after a session syncs; check that the Homeostat plugin is installed for them.</p>` : ""}</section>
+<section class="panel span-12" aria-labelledby="queue"><h2 id="queue">Review queue</h2><p class="lede">Lessons the daily run could not decide on its own. Merging the review PR accepts them; closing it declines them. The next daily run records the outcome, and the developer's sync picks it up.</p>
+${v.queue.length
+        ? `<div class="table-wrap"><table><thead><tr><th>Lesson</th><th>Developer</th><th class="num">Confidence</th><th>Why it waits</th><th class="num">Waiting</th><th>PR branch</th></tr></thead><tbody>${v.queue
+            .map((q) => `<tr><td class="mono">${esc(q.id)}</td><td class="mono">${esc(q.member)}</td><td class="num">${q.confidence ?? "—"}</td><td>${esc(q.reason)}</td><td class="num">${q.overdue ? '<span class="chip disputed">' : ""}${Math.floor(q.ageDays)}d${q.overdue ? "</span>" : ""}</td><td class="mono">${esc(q.pr ?? "—")}</td></tr>`)
+            .join("")}</tbody></table></div>`
+        : '<p class="empty">Nothing waiting for a reviewer.</p>'}</section>
+<section class="panel span-12" aria-labelledby="health"><h2 id="health">Developer sync</h2><p class="lede">Each developer's sessions sync their clone in the background and report a heartbeat; the daily run collects them. "Not syncing" means no report for ${STALE_HEARTBEAT_HOURS} hours: normal over a weekend, worth a look after that.</p>
+<div class="table-wrap"><table><thead><tr><th>Member</th><th>Role</th><th>Sync</th><th class="num">Last report</th><th>KB clone</th><th class="num">Pending</th><th>Version</th><th>Last daily run</th></tr></thead><tbody>${v.health.map(healthRow).join("")}</tbody></table></div></section>
+<section class="panel span-12" aria-labelledby="runs"><h2 id="runs">Runs</h2>
+<div class="table-wrap"><table><thead><tr><th>Run</th><th class="num">Merged</th><th class="num">To review</th><th class="num">Declined</th><th class="num">Settled</th><th>Merge refused</th></tr></thead><tbody>${[
+        ...v.runs,
+    ]
+        .reverse()
+        .map((run) => {
+        const sum = (k) => run.members.reduce((n, m) => n + m[k], 0);
+        const refused = run.members.filter((m) => m.mergeError).map((m) => m.member);
+        return `<tr><td class="mono">${esc(run.at.replace("T", " ").slice(0, 16))}</td><td class="num">${sum("merged")}</td><td class="num">${sum("review")}</td><td class="num">${sum("declined")}</td><td class="num">${run.settled}</td><td class="mono">${esc(refused.join(", ") || "—")}</td></tr>`;
+    })
+        .join("")}</tbody></table></div></section>
+</div>`;
+}

package/dist/src/charts.d.ts

@@ -0,0 +1,33 @@
+/** Escapes text for HTML and SVG. */
+export declare const esc: (s: unknown) => string;
+export interface Datum {
+    label: string;
+    value: number;
+    /** Shown in the hover tooltip; defaults to "label: value". */
+    title?: string;
+}
+/**
+ * Vertical bars for one series over categories or days. Labels only the bars named in
+ * `labelled` (selective direct labels); every bar has a hover tooltip.
+ */
+export declare function columns(data: readonly Datum[], opts: {
+    title: string;
+    height?: number;
+    labelled?: "all" | "ends";
+    tickEvery?: number;
+}): string;
+/** Horizontal bars for one series, each labelled at its data end. */
+export declare function rows(data: readonly Datum[], opts: {
+    title: string;
+    labelWidth?: number;
+}): string;
+/**
+ * The homeostat's dial: a half-circle meter with a needle at `value` (0..1). Ashby's machine
+ * showed each unit's state on a needle; here it is the share of the KB that is healthy.
+ */
+export declare function dial(value: number, opts: {
+    title: string;
+    caption: string;
+}): string;
+/** The table view every chart offers, for screen readers and exact numbers. */
+export declare function dataTable(data: readonly Datum[], headers: [string, string]): string;

package/dist/src/charts.js

@@ -0,0 +1,112 @@
+/** Escapes text for HTML and SVG. */
+export const esc = (s) => String(s ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+/** A bar whose data end (top) is rounded 4px and whose base sits square on the baseline. */
+function columnPath(x, y, w, h) {
+    if (h <= 0)
+        return "";
+    const r = Math.min(4, w / 2, h);
+    return `M${x},${y + h}V${y + r}Q${x},${y} ${x + r},${y}H${x + w - r}Q${x + w},${y} ${x + w},${y + r}V${y + h}Z`;
+}
+/** The same, lying down: rounded on the right (data) end, square on the left baseline. */
+function rowPath(x, y, w, h) {
+    if (w <= 0)
+        return "";
+    const r = Math.min(4, h / 2, w);
+    return `M${x},${y}H${x + w - r}Q${x + w},${y} ${x + w},${y + r}V${y + h - r}Q${x + w},${y + h} ${x + w - r},${y + h}H${x}Z`;
+}
+/**
+ * Vertical bars for one series over categories or days. Labels only the bars named in
+ * `labelled` (selective direct labels); every bar has a hover tooltip.
+ */
+export function columns(data, opts) {
+    const width = 560;
+    const height = opts.height ?? 140;
+    const pad = { top: 18, bottom: 22, left: 4, right: 4 };
+    const max = Math.max(1, ...data.map((d) => d.value));
+    const inner = height - pad.top - pad.bottom;
+    const slot = (width - pad.left - pad.right) / Math.max(data.length, 1);
+    const gap = 2;
+    const bar = Math.max(2, Math.min(36, slot - gap));
+    const maxIndex = data.findIndex((d) => d.value === max);
+    const show = (i) => opts.labelled === "all" ||
+        (opts.labelled === "ends" && (i === data.length - 1 || i === maxIndex));
+    const marks = data
+        .map((d, i) => {
+        const h = (d.value / max) * inner;
+        const x = pad.left + i * slot + (slot - bar) / 2;
+        const y = pad.top + inner - h;
+        const label = show(i) && d.value > 0
+            ? `<text class="v" x="${x + bar / 2}" y="${y - 5}" text-anchor="middle">${d.value}</text>`
+            : "";
+        const tick = opts.tickEvery && i % opts.tickEvery === 0
+            ? `<text class="t" x="${x + bar / 2}" y="${height - 6}" text-anchor="middle">${esc(d.label)}</text>`
+            : !opts.tickEvery
+                ? `<text class="t" x="${x + bar / 2}" y="${height - 6}" text-anchor="middle">${esc(d.label)}</text>`
+                : "";
+        // The hit target spans the whole slot, taller and wider than the mark.
+        return `<g class="m"><rect class="hit" x="${pad.left + i * slot}" y="${pad.top}" width="${slot}" height="${inner}"/><path d="${columnPath(x, y, bar, h)}"/>${label}${tick}<title>${esc(d.title ?? `${d.label}: ${d.value}`)}</title></g>`;
+    })
+        .join("");
+    return `<svg class="chart" viewBox="0 0 ${width} ${height}" role="img" aria-label="${esc(opts.title)}"><line class="base" x1="0" x2="${width}" y1="${pad.top + inner}" y2="${pad.top + inner}"/>${marks}</svg>`;
+}
+/** Horizontal bars for one series, each labelled at its data end. */
+export function rows(data, opts) {
+    const width = 560;
+    const rowH = 22;
+    const labelW = opts.labelWidth ?? 220;
+    const height = Math.max(rowH, data.length * rowH) + 4;
+    const max = Math.max(1, ...data.map((d) => d.value));
+    const track = width - labelW - 40;
+    const marks = data
+        .map((d, i) => {
+        const y = i * rowH + 4;
+        const w = (d.value / max) * track;
+        return `<g class="m"><rect class="hit" x="0" y="${y - 2}" width="${width}" height="${rowH}"/><text class="t" x="${labelW - 8}" y="${y + 12}" text-anchor="end">${esc(d.label)}</text><path d="${rowPath(labelW, y + 2, w, rowH - 8)}"/><text class="v" x="${labelW + w + 6}" y="${y + 12}">${d.value}</text><title>${esc(d.title ?? `${d.label}: ${d.value}`)}</title></g>`;
+    })
+        .join("");
+    return `<svg class="chart" viewBox="0 0 ${width} ${height}" role="img" aria-label="${esc(opts.title)}"><line class="base" x1="${labelW}" x2="${labelW}" y1="0" y2="${height}"/>${marks}</svg>`;
+}
+/**
+ * The homeostat's dial: a half-circle meter with a needle at `value` (0..1). Ashby's machine
+ * showed each unit's state on a needle; here it is the share of the KB that is healthy.
+ */
+export function dial(value, opts) {
+    const v = Math.max(0, Math.min(1, value));
+    const cx = 110;
+    const cy = 104;
+    const r = 86;
+    const point = (t, radius) => {
+        const a = Math.PI * (1 - t);
+        return [cx + radius * Math.cos(a), cy - radius * Math.sin(a)];
+    };
+    const ticks = Array.from({ length: 11 }, (_, i) => {
+        const [x1, y1] = point(i / 10, r - (i % 5 === 0 ? 12 : 7));
+        const [x2, y2] = point(i / 10, r);
+        return `<line class="tick${i % 5 === 0 ? " major" : ""}" x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}"/>`;
+    }).join("");
+    const [ax, ay] = point(0, r);
+    const [bx, by] = point(1, r);
+    const [nx, ny] = point(v, r - 18);
+    const [vx, vy] = point(v, r);
+    const large = 0;
+    return `<svg class="dial" viewBox="0 0 220 158" role="img" aria-label="${esc(opts.title)}: ${Math.round(v * 100)}%">
+<path class="track" d="M${ax},${ay} A${r},${r} 0 ${large} 1 ${bx},${by}"/>
+<path class="fill" d="M${ax},${ay} A${r},${r} 0 ${large} 1 ${vx},${vy}"/>
+${ticks}
+<line class="needle" x1="${cx}" y1="${cy}" x2="${nx}" y2="${ny}"/>
+<circle class="hub" cx="${cx}" cy="${cy}" r="5"/>
+<text class="dial-value" x="${cx}" y="${cy + 34}" text-anchor="middle">${Math.round(v * 100)}%</text>
+<text class="dial-caption" x="${cx}" y="${cy + 52}" text-anchor="middle">${esc(opts.caption)}</text>
+<title>${esc(opts.title)}: ${Math.round(v * 100)}%</title>
+</svg>`;
+}
+/** The table view every chart offers, for screen readers and exact numbers. */
+export function dataTable(data, headers) {
+    return `<details class="table-view"><summary>Table</summary><table><thead><tr><th>${esc(headers[0])}</th><th class="num">${esc(headers[1])}</th></tr></thead><tbody>${data
+        .map((d) => `<tr><td>${esc(d.label)}</td><td class="num">${d.value}</td></tr>`)
+        .join("")}</tbody></table></details>`;
+}

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export { type DashboardOptions, startDashboard } from "./server.ts";

package/dist/src/index.js

@@ -0,0 +1 @@
+export { startDashboard } from "./server.js";

package/dist/src/metrics.d.ts

@@ -0,0 +1,91 @@
+import { type AgentName, type Config, type ContextDoc, type Entry, type Event, type Status } from "@homeostat/core";
+export interface Snapshot {
+    config: Config;
+    entries: readonly Entry[];
+    /** Knowledge documents (K1); absent in older callers. */
+    docs?: readonly ContextDoc[];
+    events: readonly Event[];
+    now: Date;
+}
+export interface AgentLiveness {
+    agent: AgentName;
+    enabled: boolean;
+    schedule: string;
+    nextRun?: string;
+    lastRun?: {
+        ts: string;
+        ok: boolean;
+        summary: string;
+    };
+    lastSuccess?: string;
+    failures7d: number;
+}
+export declare function agentLiveness({ config, events, now }: Snapshot): AgentLiveness[];
+export interface Health {
+    total: number;
+    byStatus: Record<Status, number>;
+    /** Days since last confirmed, averaged over accepted entries. */
+    averageAgeDays: number;
+    stale: string[];
+    disputed: string[];
+    flagged: string[];
+    possibleDuplicates: [string, string][];
+    /** Share of all entries that are accepted, not stale and not flagged: the dial on the overview. */
+    stability: number;
+}
+export declare function health({ config, entries, now }: Snapshot): Health;
+export interface Contribution {
+    member: string;
+    role: string;
+    authored: number;
+    accepted: number;
+    /** Accepted share of what they authored; undefined with nothing authored. */
+    acceptedRatio?: number;
+    flagsRaised: number;
+    captured30d: number;
+}
+export declare function contributions({ config, entries, events, now }: Snapshot): Contribution[];
+export interface AreaCoverage {
+    area: string;
+    globs: readonly string[];
+    accepted: number;
+    candidates: number;
+}
+export interface SourceCoverage {
+    repo: string;
+    /** Entries whose source review comment came from this repo. */
+    entries: number;
+}
+export declare function coverage({ config, entries }: Snapshot): {
+    areas: AreaCoverage[];
+    sources: SourceCoverage[];
+};
+export interface DailyCount {
+    day: string;
+    count: number;
+}
+export interface Impact {
+    injectionsByDay: DailyCount[];
+    mcpCallsByDay: DailyCount[];
+    sessions: number;
+    rulesPerInjection: number;
+    tokensPerInjection: number;
+    topRules: {
+        id: string;
+        injections: number;
+    }[];
+    toolUse: {
+        tool: string;
+        calls: number;
+    }[];
+}
+export declare function impact({ events, now }: Snapshot, days?: number): Impact;
+export interface DesirePath {
+    name: string;
+    /** The real tool it resolved to, or undefined when nothing did. */
+    resolved?: string;
+    count: number;
+    last: string;
+}
+/** Tool names agents guessed: the ones to consider implementing (execution plan 3.2). */
+export declare function desirePaths({ events }: Snapshot): DesirePath[];