omp-conductor 0.15.10 → 0.15.12

package/src/dashboard/server.ts

@@ -0,0 +1,481 @@
+/**
+ * The fleet dashboard server (epic #292, slice 1/5): a separate `Bun.serve`
+ * process that renders the fleet in a browser.
+ *
+ * Deliberately NOT a route on the daemon port: that surface is unauthenticated
+ * and loopback-only by design, and `verbs/server.test.ts` pins every non-daemon
+ * path (and every mutating method) to 404. The dashboard is its own process
+ * with its own bearer token, and it only ever *reads* fleet state — it never
+ * starts, stops or mutates a daemon.
+ *
+ * The token is minted once at `<stateDir()>/dashboard-token` — the same
+ * 0700-dir / 0600-file atomic discipline `writeConfigRaw` uses — and reused on
+ * every later start. Every `/api/*` request must present it as
+ * `Authorization: Bearer <token>`; anything else is a bare 401 with no body
+ * detail. Static assets ship on disk next to this module and are served
+ * unauthenticated; the UI asks for the token once and keeps it in
+ * localStorage.
+ *
+ * Project liveness is the one membership convention `status` and `board`
+ * already share (#379): `livingDaemon()` + `healthCheck(port)`, classified by
+ * `classifyDaemonProjectHealth`. A project whose record is absent, whose
+ * daemon will not answer `/healthz`, or whose record is pinned to another
+ * project renders as down — never as an empty healthy fleet.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig, stateDir } from "../config.ts";
+import { healthCheck, livingDaemon, type DaemonRecord } from "../lifecycle.ts";
+import { classifyDaemonProjectHealth, fleetLayers, type FleetLayers } from "../fleet.ts";
+import { statusSnapshot, type StatusSnapshot } from "../daemon.ts";
+import { boardJson, boardSnapshotOnce } from "../board.ts";
+import { dbPath, openStore } from "../store.ts";
+import type { ProjectConfig } from "../types.ts";
+import type { BaseHealth, DigestBacklog, HeldNotice, ReportRecord, RunRecord, TurnOverride, VerbLedgerEntry } from "../types.ts";
+
+/** The dashboard's default bind address — loopback, like the daemon port. */
+export const DASHBOARD_HOST = "127.0.0.1";
+/** The dashboard's default port. Away from the daemon's 8787 and the verbs. */
+export const DASHBOARD_PORT = 8788;
+
+const TOKEN_FILE = "dashboard-token";
+
+/** Where the bearer token lives, next to config.json under `$OMP_CONDUCTOR_HOME`. */
+export function tokenPath(): string {
+  return join(stateDir(), TOKEN_FILE);
+}
+
+/** The stored token, or undefined when the dashboard has never been started. */
+export function readDashboardToken(): string | undefined {
+  try {
+    const raw = readFileSync(tokenPath(), "utf8").trim();
+    return raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function hashToken(value: string): Buffer {
+  return createHash("sha256").update(value).digest();
+}
+
+/**
+ * Constant-time bearer check. Both sides are hashed to fixed length first so a
+ * wrong-length candidate cannot leak the stored token's length through the
+ * compare — the arm-challenge spirit: verify by hash, never by a plaintext
+ * comparison that leaks shape in timing.
+ */
+export function verifyDashboardToken(presented: string | undefined, stored: string): boolean {
+  if (presented === undefined || presented.length === 0) return false;
+  return timingSafeEqual(hashToken(presented), hashToken(stored));
+}
+
+/**
+ * Mints `<stateDir()>/dashboard-token` on first start; later starts reuse the
+ * existing token. The write discipline is `writeConfigRaw`'s: the state dir is
+ * created 0700 (chmod only what this call created, so an operator-chosen mode
+ * survives), the file is written 0600 through a same-directory temp file and
+ * an atomic rename so a crash mid-write leaves the previous token intact
+ * rather than a truncated one.
+ */
+export function ensureDashboardToken(): string {
+  const existing = readDashboardToken();
+  if (existing !== undefined) return existing;
+
+  const token = randomBytes(32).toString("base64url");
+  const dir = stateDir();
+  const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // mkdir's mode is masked by umask; chmod only what we just created so an
+  // existing directory keeps whatever the user chose for it.
+  if (created !== undefined) chmodSync(dir, 0o700);
+
+  const target = tokenPath();
+  const tmp = join(dir, `.dashboard-token.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`);
+  try {
+    writeFileSync(tmp, `${token}\n`, { mode: 0o600 });
+    renameSync(tmp, target);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  // The rename preserves the temp's 0600; state it anyway so the promise never
+  // leans on umask moods.
+  chmodSync(target, 0o600);
+  return token;
+}
+
+/** One configured project as `/api/projects` reports it. */
+export interface DashboardProjectView {
+  name: string;
+  /** `tracker.repo` — the issue source the project dispatches. */
+  repo: string;
+  daemon: {
+    /** The shared verdict every viewer uses (#379). */
+    state: "ok" | "stopped" | "unreachable" | "other-project";
+    /** The living daemon's port when a record exists; null when there is none. */
+    port: number | null;
+    /** The raw `/healthz` body, parsed, when this project's daemon answered it. */
+    healthz?: unknown;
+    /** Which project a foreign living record is pinned to, when state is other-project. */
+    serves?: string;
+  };
+}
+
+/**
+ * One project against a record already read for the request. The record is
+ * shared across projects so one pidfile read serves one whole request.
+ */
+async function probeProject(project: ProjectConfig, record: DaemonRecord | undefined): Promise<DashboardProjectView> {
+  // The status/board gate (#379): never health-check a record pinned to
+  // another project — its `/healthz` would describe a daemon that does not
+  // serve this one, and mixing the two is how an empty fleet reads as healthy.
+  const pinnedElsewhere =
+    record !== undefined && record.project !== undefined && record.project !== project.name;
+  const health =
+    record !== undefined && !pinnedElsewhere ? await healthCheck(record.port) : undefined;
+  const classified = classifyDaemonProjectHealth(record, health, project.name);
+
+  const view: DashboardProjectView = {
+    name: project.name,
+    repo: project.tracker.repo,
+    daemon: { state: classified.kind, port: record?.port ?? null },
+  };
+  if (classified.kind === "ok") {
+    let healthz: unknown;
+    try {
+      healthz = JSON.parse(health?.body ?? "null") as unknown;
+    } catch {
+      healthz = undefined;
+    }
+    view.daemon.healthz = healthz;
+  } else if (classified.kind === "other-project") {
+    view.daemon.serves = classified.serves;
+  }
+  return view;
+}
+
+/**
+ * Every configured project, annotated for the dashboard. Read-only: never
+ * starts a daemon, never touches a pidfile beyond `livingDaemon()`'s read.
+ */
+export async function dashboardProjects(): Promise<DashboardProjectView[]> {
+  const cfg = loadConfig();
+  const record = livingDaemon();
+  return Promise.all(cfg.projects.map((project) => probeProject(project, record)));
+}
+
+/**
+ * One project on the fleet-overview row (epic #292, slice 2/5). Every field is
+ * the existing producer's own number — `statusSnapshot` for workers, spend and
+ * base health, `fleetLayers` for the dispatch verdict — so a row can never
+ * disagree with `omp-conductor status` read at the same moment.
+ */
+export interface FleetOverviewRow {
+  name: string;
+  repo: string;
+  /** The same shared daemon-health verdict `/api/projects` reports (#379). */
+  daemon: DashboardProjectView["daemon"];
+  /** The dispatch layer: `stopped` | `paused` | `running`. */
+  dispatch: FleetLayers["dispatch"];
+  liveWorkers: number;
+  spendTodayUsd: number;
+  baseHealth: BaseHealth[];
+  /**
+   * True when the daemon this project is pinned to is unreachable or serves
+   * another project. The UI renders DEGRADED instead of a fabricated healthy
+   * empty row — never zeros that read as a working fleet.
+   */
+  degraded: boolean;
+}
+
+/**
+ * Every configured project as a fleet-overview row. Reuses `dashboardProjects`
+ * for the membership verdict (one pidfile + one `/healthz` read serves the
+ * whole call), then `statusSnapshot` and `fleetLayers` per project for the
+ * numbers the `status` CLI renders from the very same producers.
+ */
+export async function fleetOverview(): Promise<FleetOverviewRow[]> {
+  const views = await dashboardProjects();
+  return views.map((view) => {
+    const snap = statusSnapshot(view.name);
+    const layers = fleetLayers(view.name);
+    return {
+      name: view.name,
+      repo: view.repo,
+      daemon: view.daemon,
+      dispatch: layers.dispatch,
+      liveWorkers: snap.liveWorkers,
+      spendTodayUsd: snap.spendTodayUsd,
+      baseHealth: snap.baseHealth,
+      degraded: view.daemon.state === "unreachable" || view.daemon.state === "other-project",
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// The read-only monitoring surface (epic #292, slice 2/5). Each handler hands
+// the existing CLI producer its arguments and returns what it already computes
+// verbatim — nothing here re-derives a lane, a spend figure or a hold.
+// ---------------------------------------------------------------------------
+
+/** `/api/projects/:name/board` — the exact lanes `omp-conductor board --json`
+ *  prints for the same project at the same moment, parsed so the UI consumes
+ *  them as an object. */
+async function boardProducer(name: string): Promise<unknown> {
+  const snapshot = await boardSnapshotOnce(name);
+  return JSON.parse(boardJson(snapshot)) as unknown;
+}
+
+/** `/api/projects/:name/status` — the `StatusSnapshot` plus the `fleetLayers`
+ *  verdict, structured (not the rendered text). */
+async function statusProducer(name: string): Promise<{ status: StatusSnapshot; fleetLayers: FleetLayers }> {
+  return { status: statusSnapshot(name), fleetLayers: fleetLayers(name) };
+}
+
+/** `/api/projects/:name/ledger` — the verb ledger + turn-override ledger, with
+ *  the CLI's own defaults (limit 50) so the two cannot disagree. */
+async function ledgerProducer(
+  name: string,
+  opts: { issue?: number; limit: number },
+): Promise<{ verb: VerbLedgerEntry[]; turnOverrides: TurnOverride[] }> {
+  const store = openStore(dbPath());
+  try {
+    return {
+      verb: store.verbLedger(name, opts),
+      turnOverrides: store.turnOverrideLedger(name, opts),
+    };
+  } finally {
+    store.close();
+  }
+}
+
+/** `/api/projects/:name/reports` — the store readers `status` already uses:
+ *  open reports, the digest backlog, and the held notices awaiting a digest. */
+async function reportsProducer(
+  name: string,
+): Promise<{ openReports: ReportRecord[]; digestBacklog: DigestBacklog; heldNotices: HeldNotice[] }> {
+  const store = openStore(dbPath());
+  try {
+    return {
+      openReports: store.openReports(name),
+      digestBacklog: store.digestBacklog(name),
+      heldNotices: store.undigestedNotices(name),
+    };
+  } finally {
+    store.close();
+  }
+}
+
+/** `/api/projects/:name/runs/:issue` — every run row for the issue: attempts,
+ *  states, spend, failure classes, PR URLs. */
+async function runsProducer(name: string, issue: number): Promise<{ runs: RunRecord[] }> {
+  const store = openStore(dbPath());
+  try {
+    return { runs: store.runsForIssue(name, issue) };
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * The deps a live dashboard is wired with. Every endpoint defaults to the real
+ * producer above; a test overrides only the slice it exercises.
+ */
+export interface DashboardHttpDeps {
+  /** The bearer token every `/api/*` request must carry. */
+  token: string;
+  /** The `/api/projects` payload. */
+  projects(): Promise<DashboardProjectView[]>;
+  /** The `/api/overview` fleet rows. */
+  overview(): Promise<FleetOverviewRow[]>;
+  board(name: string): Promise<unknown>;
+  status(name: string): Promise<{ status: StatusSnapshot; fleetLayers: FleetLayers }>;
+  ledger(
+    name: string,
+    opts: { issue?: number; limit: number },
+  ): Promise<{ verb: VerbLedgerEntry[]; turnOverrides: TurnOverride[] }>;
+  reports(
+    name: string,
+  ): Promise<{ openReports: ReportRecord[]; digestBacklog: DigestBacklog; heldNotices: HeldNotice[] }>;
+  runs(name: string, issue: number): Promise<{ runs: RunRecord[] }>;
+}
+
+/** The deps bound to the real producers — what `startDashboard` serves with. */
+export function defaultDashboardDeps(token: string): DashboardHttpDeps {
+  return {
+    token,
+    projects: dashboardProjects,
+    overview: fleetOverview,
+    board: boardProducer,
+    status: statusProducer,
+    ledger: ledgerProducer,
+    reports: reportsProducer,
+    runs: runsProducer,
+  };
+}
+
+const STATIC_FILES: Record<string, string> = {
+  "/": "index.html",
+  "/index.html": "index.html",
+  "/app.js": "app.js",
+  "/style.css": "style.css",
+};
+
+const STATIC_MIME: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+};
+
+/** The value of `Authorization: Bearer <token>`, or undefined for any other form. */
+function bearerToken(req: Request): string | undefined {
+  const header = req.headers.get("authorization");
+  if (header === null) return undefined;
+  const prefix = "Bearer ";
+  return header.startsWith(prefix) ? header.slice(prefix.length).trim() : undefined;
+}
+
+/**
+ * The ledger's query params. `limit` defaults to 50 — the CLI's own default —
+ * so the endpoint and `omp-conductor ledger` cannot disagree. An explicit
+ * non-positive or non-integral limit or issue is a client error (400), never a
+ * silent fallback that hides a typo'd URL.
+ */
+function parseLedgerParams(url: URL): { issue?: number; limit: number } | null {
+  const issueParam = url.searchParams.get("issue");
+  const limitParam = url.searchParams.get("limit");
+  // `Number`, not `parseInt`: `1.5` and `-1` must be rejected, never truncated
+  // down to a valid-seeming value.
+  const issueNumber = issueParam === null ? undefined : Number(issueParam);
+  const issue = issueNumber !== undefined && Number.isInteger(issueNumber) ? issueNumber : undefined;
+  const limitParamValue = limitParam === null ? 50 : Number(limitParam);
+  const limit = Number.isInteger(limitParamValue) ? limitParamValue : Number.NaN;
+  if (issueParam !== null && (issue === undefined || issue < 1)) return null;
+  if (!Number.isSafeInteger(limit) || limit < 1) return null;
+  return { ...(issue === undefined ? {} : { issue }), limit };
+}
+
+/**
+ * The dashboard's whole HTTP surface, separated from the socket exactly like
+ * `daemonHttpResponse` so a test can drive it without binding a port. The UI
+ * ships on disk and is served without auth; `/api/*` is bearer-authenticated.
+ */
+export async function dashboardResponse(req: Request, d: DashboardHttpDeps): Promise<Response> {
+  const url = new URL(req.url);
+  const path = url.pathname;
+  if (path.startsWith("/api/")) {
+    const presented = bearerToken(req);
+    if (presented === undefined || !verifyDashboardToken(presented, d.token)) {
+      // Bare 401: no body, no scheme hint — nothing about the token leaks.
+      return new Response("", { status: 401 });
+    }
+    // Read-only surface: every /api route is a GET. Everything else stays
+    // 404 (after the auth check, so the surface cannot be probed).
+    if (req.method !== "GET") return new Response("", { status: 404 });
+
+    if (path === "/api/projects") return Response.json(await d.projects());
+    if (path === "/api/overview") return Response.json(await d.overview());
+
+    // `/api/projects/:name/{board,status,ledger,reports}` and
+    // `/api/projects/:name/runs/:issue`. Project names are matched against the
+    // configured set so an unknown name is a 404, never the producer's throw.
+    const name = (m: RegExpExecArray): string | undefined => {
+      try {
+        return decodeURIComponent(m[1]!);
+      } catch {
+        return undefined;
+      }
+    };
+    const known = (project: string | undefined): project is string =>
+      project !== undefined && loadConfig().projects.some((p) => p.name === project);
+
+    const proj = /^\/api\/projects\/([^/]+)\/(board|status|ledger|reports)$/.exec(path);
+    if (proj !== null) {
+      const project = name(proj);
+      if (!known(project)) return new Response("", { status: 404 });
+      switch (proj[2]) {
+        case "board":
+          return Response.json(await d.board(project!));
+        case "status":
+          return Response.json(await d.status(project!));
+        case "ledger": {
+          const opts = parseLedgerParams(url);
+          if (opts === null) return new Response("", { status: 400 });
+          return Response.json(await d.ledger(project!, opts));
+        }
+        case "reports":
+          return Response.json(await d.reports(project!));
+      }
+    }
+
+    const runs = /^\/api\/projects\/([^/]+)\/runs\/(\d+)$/.exec(path);
+    if (runs !== null) {
+      const project = name(runs);
+      const issue = Number.parseInt(runs[2]!, 10);
+      if (!known(project) || !Number.isSafeInteger(issue)) {
+        return new Response("", { status: 404 });
+      }
+      return Response.json(await d.runs(project!, issue));
+    }
+
+    return new Response("", { status: 404 });
+  }
+  // Everything outside /api is static UI, unauthenticated by contract.
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    return new Response("", { status: 405 });
+  }
+  const name = STATIC_FILES[path];
+  if (name === undefined) return new Response("not found", { status: 404 });
+  // Small fixed set of files, read on demand like the config: no cache to go
+  // stale when an operator edits the UI beside a running dashboard.
+  const body = readFileSync(join(import.meta.dir, name));
+  const mime = STATIC_MIME[name.slice(name.lastIndexOf("."))] ?? "application/octet-stream";
+  return new Response(body, { headers: { "content-type": mime } });
+}
+
+export interface DashboardStartOpts {
+  port?: number;
+  /** Bind address; defaults to loopback. A non-loopback host still starts,
+   *  with a one-line warning naming the token file. */
+  host?: string;
+}
+
+/** Loopback is the safe posture; anything else gets the token warning. */
+function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "::1" || host.startsWith("127.");
+}
+
+/**
+ * Runs the dashboard until SIGINT/SIGTERM, like the foreground daemon. Mints
+ * the token on first start and prints where the server is listening.
+ */
+export async function startDashboard(opts: DashboardStartOpts = {}): Promise<void> {
+  const token = ensureDashboardToken();
+  const host = opts.host ?? DASHBOARD_HOST;
+  const server = Bun.serve({
+    hostname: host,
+    port: opts.port ?? DASHBOARD_PORT,
+    fetch: (req) => dashboardResponse(req, defaultDashboardDeps(token)),
+  });
+  // An IPv6 literal needs brackets to be a clickable URL.
+  const displayHost = host.includes(":") ? `[${host}]` : host;
+  process.stdout.write(`dashboard on http://${displayHost}:${server.port}\n`);
+  if (!isLoopbackHost(host)) {
+    // The one-line warning the contract promises: the token file is the only
+    // door onto the project list, so say where it is before a request arrives.
+    process.stderr.write(
+      `warning: dashboard bound to ${host} — anyone who can reach it can use the token at ${tokenPath()}; keep it secret\n`,
+    );
+  }
+  await new Promise<void>((resolve) => {
+    const stop = (): void => {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      void server.stop(true).finally(() => resolve());
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}