@celilo/console-server 0.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@celilo/console-server",
+  "version": "0.1.0",
+  "description": "HTTP surface for the celilo web console. Serves the SPA and hosts the tsrpc API. Holds no database: it reaches celilo-mgr over the SSH remote API as a read-only principal.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test --timeout 30000"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@celilo/console-protocol": "*",
+    "@celilo/core": "*",
+    "@celilo/cli-display": "*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * The console server's public surface.
+ *
+ * `serve` and `createHandler` are the two ways in: one binds a port, the other
+ * returns a handler a test can drive with a `Request`. The verbs are exported
+ * because the e2e suite asserts against their output directly rather than
+ * through HTTP, which keeps a shape assertion from also being a routing test.
+ */
+export { serve, createHandler, type ServeOptions, type AuthGate, type AuthSubject } from './serve';
+export { Upstream, UpstreamUnavailable, type UnavailableReason } from './upstream';
+export {
+  readTopology,
+  readModules,
+  readClosure,
+  readAlerts,
+  readBackupsWithCoverage,
+} from './verbs';

package/src/serve.ts

@@ -0,0 +1,236 @@
+/**
+ * The console's HTTP surface: the tsrpc API, the SPA, and the gate in front.
+ *
+ * Holds no database handle. Every fact it serves comes from `Upstream`, which
+ * reaches celilo-mgr over the SSH remote API as a principal granted read ops
+ * only. That is a security boundary, not a deployment preference: a console
+ * sharing celilo's process would hold the whole database including the
+ * encrypted secret store, and would be constrained only by its own code.
+ *
+ * It is a Bun server rather than tsrpc's own `HttpServer` for one reason worth
+ * stating. This process serves two things on one port — an RPC surface and a
+ * single-page app — and the SPA needs a catch-all that returns `index.html` for
+ * any path the router owns. Running tsrpc's server alongside a static server
+ * means two ports, and two ports behind one VPN-only ingress is two things to
+ * get wrong. So the RPC calls are dispatched by hand onto the same handlers.
+ */
+
+import type { ServiceType } from '@celilo/console-protocol';
+import { Upstream, type UpstreamOptions, UpstreamUnavailable } from './upstream';
+import {
+  readAlerts,
+  readBackupsWithCoverage,
+  readClosure,
+  readModules,
+  readTopology,
+} from './verbs';
+
+export interface ServeOptions {
+  port: number;
+  /** `celilo-api@<server>`. */
+  dest: string;
+  identityFile: string;
+  /** Directory holding the built SPA. */
+  spaDir: string;
+  /** Decides who is asking. See `AuthGate`. */
+  authenticate: AuthGate;
+  cacheTtlMs?: number;
+  /**
+   * Injectable so tests drive the whole surface without SSH, matching
+   * `UpstreamOptions`. Absent in production, where the real SSH transport is
+   * selected by `identityFile`.
+   */
+  openTransport?: UpstreamOptions['openTransport'];
+}
+
+/**
+ * Who is asking, decided before any handler runs.
+ *
+ * Returns the authenticated subject, or null to refuse. This is a function
+ * rather than baked-in OIDC so the e2e suite can drive the server with a stub
+ * and so the identity provider can change without touching request routing.
+ *
+ * There is no default. A server constructed without one would answer to
+ * anybody, and "we forgot to pass the gate" must not be a thing that silently
+ * works (Rule 6.4: deny by default).
+ */
+export type AuthGate = (request: Request) => Promise<AuthSubject | null>;
+
+export interface AuthSubject {
+  /** Stable identifier from the identity provider. */
+  subject: string;
+  /** Display name, when the provider supplied one. */
+  name?: string;
+}
+
+/** Every RPC path the protocol declares, and nothing else. */
+type ApiName = keyof ServiceType['api'];
+
+const READ_VERBS: ApiName[] = ['Topology', 'Modules', 'Closure', 'Alerts', 'Backups'];
+
+/**
+ * Map an upstream failure onto an HTTP status and a tsrpc-shaped error.
+ *
+ * Every reason is REPORTED. None becomes an empty success. A panel that receives
+ * `{ alerts: [] }` because the read was denied shows a quiet fleet, and a quiet
+ * fleet is the one answer this console must never give by accident.
+ */
+function unavailableResponse(error: UpstreamUnavailable): Response {
+  const status = error.reason === 'denied' ? 403 : error.reason === 'unknown-verb' ? 501 : 502;
+  return Response.json(
+    {
+      isSucc: false,
+      err: {
+        message: error.message,
+        type: 'ApiError',
+        code: error.reason,
+      },
+    },
+    { status },
+  );
+}
+
+/** The MIME types the SPA build actually emits. */
+const CONTENT_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+  '.json': 'application/json',
+};
+
+function contentType(path: string): string {
+  const dot = path.lastIndexOf('.');
+  return (dot >= 0 ? CONTENT_TYPES[path.slice(dot)] : undefined) ?? 'application/octet-stream';
+}
+
+/**
+ * Dispatch one RPC call.
+ *
+ * The request body is the tsrpc request object. Only the five read verbs are
+ * routed. `AckAlert` is declared in the protocol and deliberately NOT wired
+ * here: it is a write, it needs an authenticated subject that maps to a real
+ * `people` row, and the grant to perform it does not exist yet. An unrouted
+ * verb 404s, which is honest. Wiring it to something that silently no-ops
+ * would be worse than not having it.
+ */
+async function callApi(
+  name: ApiName,
+  body: Record<string, unknown>,
+  upstream: Upstream,
+): Promise<Response> {
+  switch (name) {
+    case 'Topology':
+      return Response.json({ isSucc: true, res: await readTopology(upstream) });
+    case 'Modules':
+      return Response.json({ isSucc: true, res: await readModules(upstream) });
+    case 'Closure': {
+      const moduleId = body.moduleId;
+      if (typeof moduleId !== 'string' || moduleId.length === 0) {
+        return Response.json(
+          { isSucc: false, err: { message: 'moduleId is required', type: 'ApiError' } },
+          { status: 400 },
+        );
+      }
+      const depth = typeof body.depth === 'number' ? body.depth : undefined;
+      return Response.json({ isSucc: true, res: await readClosure(upstream, moduleId, depth) });
+    }
+    case 'Alerts': {
+      const moduleId = typeof body.moduleId === 'string' ? body.moduleId : undefined;
+      return Response.json({ isSucc: true, res: await readAlerts(upstream, moduleId) });
+    }
+    case 'Backups':
+      return Response.json({ isSucc: true, res: await readBackupsWithCoverage(upstream) });
+    default:
+      return Response.json(
+        { isSucc: false, err: { message: `${name} is not served here`, type: 'ApiError' } },
+        { status: 404 },
+      );
+  }
+}
+
+/**
+ * Build the request handler. Exported separately from `serve` so tests can
+ * drive it with a `Request` and no listening socket.
+ */
+export function createHandler(options: ServeOptions): (request: Request) => Promise<Response> {
+  const upstream = new Upstream({
+    dest: options.dest,
+    identityFile: options.identityFile,
+    ...(options.cacheTtlMs === undefined ? {} : { cacheTtlMs: options.cacheTtlMs }),
+    ...(options.openTransport === undefined ? {} : { openTransport: options.openTransport }),
+  });
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+
+    // The gate runs FIRST, for every path including the SPA. Serving the shell
+    // to an unauthenticated caller would leak the fleet's shape through the
+    // bundle even with every API call refused.
+    const subject = await options.authenticate(request);
+    if (subject === null) {
+      return new Response('Unauthorized', {
+        status: 401,
+        headers: { 'WWW-Authenticate': 'Bearer' },
+      });
+    }
+
+    if (url.pathname.startsWith('/api/')) {
+      const name = url.pathname.slice('/api/'.length) as ApiName;
+      if (!READ_VERBS.includes(name)) {
+        return Response.json(
+          { isSucc: false, err: { message: `Unknown verb: ${name}`, type: 'ApiError' } },
+          { status: 404 },
+        );
+      }
+
+      let body: Record<string, unknown> = {};
+      try {
+        body = (await request.json()) as Record<string, unknown>;
+      } catch {
+        // A verb taking no arguments is called with an empty body by some
+        // clients and `{}` by others. Both are fine; only a malformed body
+        // with content is not, and that fails on the field check below.
+      }
+
+      try {
+        return await callApi(name, body, upstream);
+      } catch (error) {
+        if (error instanceof UpstreamUnavailable) return unavailableResponse(error);
+        throw error;
+      }
+    }
+
+    // Static, then the SPA catch-all. The order matters: a request for
+    // `/assets/index.js` must find the file, and a request for `/backups` must
+    // find `index.html`, because the route belongs to the client-side router.
+    const asset = Bun.file(`${options.spaDir}${url.pathname}`);
+    if (url.pathname !== '/' && (await asset.exists())) {
+      return new Response(asset, { headers: { 'content-type': contentType(url.pathname) } });
+    }
+
+    const shell = Bun.file(`${options.spaDir}/index.html`);
+    if (!(await shell.exists())) {
+      // Said out loud rather than 404ing. A console server with no SPA built
+      // into it is a packaging failure, and a bare 404 sends the reader looking
+      // for a routing bug instead.
+      return new Response(
+        `No SPA found at ${options.spaDir}. The console server ships the built client inside its package, and this one was started without it.`,
+        { status: 500 },
+      );
+    }
+    return new Response(shell, { headers: { 'content-type': CONTENT_TYPES['.html'] as string } });
+  };
+}
+
+export function serve(options: ServeOptions): { port: number; stop: () => void } {
+  const handler = createHandler(options);
+  const server = Bun.serve({ port: options.port, fetch: handler });
+  // `server.port` is optional in the type because a unix-socket server has
+  // none. This one always binds a port, and asserting that is better than
+  // defaulting to 0 and reporting a port nothing is listening on.
+  const bound = server.port;
+  if (bound === undefined) throw new Error('console server started without a port');
+  return { port: bound, stop: () => server.stop(true) };
+}

package/src/upstream.ts

@@ -0,0 +1,173 @@
+/**
+ * How the console reaches celilo.
+ *
+ * The console server holds NO database handle. Every fact it serves arrives over
+ * the SSH remote API as a principal whose grants are read-only, the same way
+ * `@celilo/mcp` reaches celilo-mgr. That is a security boundary rather than a
+ * deployment preference: a console sharing celilo's process would hold the whole
+ * database including the encrypted secret store, and would be constrained only
+ * by its own code.
+ *
+ * Two policies here differ deliberately from the MCP's client.
+ *
+ * An interview is a FAILURE, not something to answer. A browser has no
+ * interview responder attached, so a command that parks on a question would hang
+ * forever. The console is specified never to invoke an operation that can raise
+ * one, and this is where that is enforced rather than assumed.
+ *
+ * An unavailable verb is reported, never blanked. The console and the management
+ * server upgrade by different paths and are expected to run at different
+ * versions, so a verb the server does not recognise or has not granted is
+ * ordinary. Returning an empty result for it would be indistinguishable from
+ * "nothing is wrong", and only one of those means the fleet is fine.
+ */
+
+import type { DisplayWriter } from '@celilo/cli-display';
+import { type RemoteTransport, runRemoteClient, sshTransportWith } from '@celilo/core';
+
+/** Why a read could not be served. Every case is renderable; none is silence. */
+export type UnavailableReason =
+  | 'denied' // the principal is not granted this op
+  | 'unknown-verb' // an older management server does not have it
+  | 'unreachable' // ssh or the server itself did not answer
+  | 'interview' // the command parked on a question nothing here can answer
+  | 'malformed'; // it answered, but not with the JSON we asked for
+
+export class UpstreamUnavailable extends Error {
+  constructor(
+    readonly reason: UnavailableReason,
+    readonly argv: readonly string[],
+    message: string,
+  ) {
+    super(message);
+    this.name = 'UpstreamUnavailable';
+  }
+}
+
+export interface UpstreamOptions {
+  /** `celilo-api@<server>`. */
+  dest: string;
+  /** Private key selecting the console's read-only principal. */
+  identityFile: string;
+  /** Injectable so tests exercise the round trip without SSH. */
+  openTransport?: (dest: string) => RemoteTransport;
+  /** How long a cached read stays fresh, in ms. */
+  cacheTtlMs?: number;
+  /** Injected so tests control time rather than sleeping. */
+  now?: () => number;
+}
+
+/** Exit code the API uses for "this principal may not do that". */
+const EXIT_DENIED = 126;
+
+interface CacheEntry {
+  at: number;
+  value: unknown;
+}
+
+export class Upstream {
+  private readonly cache = new Map<string, CacheEntry>();
+  private readonly ttl: number;
+  private readonly now: () => number;
+
+  constructor(private readonly options: UpstreamOptions) {
+    this.ttl = options.cacheTtlMs ?? 2_000;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * Run one read verb and parse its JSON.
+   *
+   * Cached by argv, so a poll that changes nothing costs one round trip rather
+   * than one per browser tab. The TTL is short because this is a liveness
+   * display: stale-by-seconds is fine, stale-by-minutes is a lie.
+   */
+  async read<T>(argv: readonly string[]): Promise<T> {
+    const key = argv.join(' ');
+    const hit = this.cache.get(key);
+    if (hit && this.now() - hit.at < this.ttl) return hit.value as T;
+
+    const value = await this.runJson<T>(argv);
+    this.cache.set(key, { at: this.now(), value });
+    return value;
+  }
+
+  /** Drop everything cached. Used when the operator asks for a hard refresh. */
+  invalidate(): void {
+    this.cache.clear();
+  }
+
+  private async runJson<T>(argv: readonly string[]): Promise<T> {
+    const lines: string[] = [];
+    const out: DisplayWriter = {
+      write: (s: string) => {
+        lines.push(s);
+      },
+      // No ANSI animation to strip back out of the payload.
+      isTTY: false,
+    };
+
+    let outcome: Awaited<ReturnType<typeof runRemoteClient>>;
+    try {
+      outcome = await runRemoteClient(this.options.dest, [...argv], {
+        openTransport: this.options.openTransport ?? sshTransportWith(this.options.identityFile),
+        out,
+        // Reached only if celilo asks the console a question. Nothing here can
+        // answer one, so say so loudly rather than parking a request forever.
+        renderInterview: () => {
+          throw new UpstreamUnavailable(
+            'interview',
+            argv,
+            `\`${argv.join(' ')}\` raised an interview question. The console has no responder and never invokes operations that can ask one.`,
+          );
+        },
+        onBlocked: 'return',
+      });
+    } catch (error) {
+      if (error instanceof UpstreamUnavailable) throw error;
+      throw new UpstreamUnavailable(
+        'unreachable',
+        argv,
+        `Could not reach ${this.options.dest}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    if (outcome.status === 'blocked') {
+      throw new UpstreamUnavailable(
+        'interview',
+        argv,
+        `\`${argv.join(' ')}\` parked on a question the console cannot answer.`,
+      );
+    }
+
+    const output = lines.join('').trim();
+    if (outcome.exitCode !== 0) {
+      throw new UpstreamUnavailable(classifyFailure(outcome.exitCode, output), argv, output);
+    }
+
+    try {
+      return JSON.parse(output) as T;
+    } catch {
+      throw new UpstreamUnavailable(
+        'malformed',
+        argv,
+        `\`${argv.join(' ')}\` succeeded but did not return JSON.`,
+      );
+    }
+  }
+}
+
+/**
+ * Tell "you may not" from "I do not have that" from "something else broke".
+ *
+ * These render differently and an operator needs to tell them apart: a denial is
+ * a grant to fix, an unknown verb is a management server to upgrade, and
+ * anything else is a fault.
+ */
+function classifyFailure(exitCode: number, output: string): UnavailableReason {
+  if (exitCode === EXIT_DENIED || /permission denied|not granted/i.test(output)) return 'denied';
+  if (/unknown command|subcommand required|not a celilo command/i.test(output)) {
+    return 'unknown-verb';
+  }
+  return 'unreachable';
+}

package/src/verbs.ts

@@ -0,0 +1,379 @@
+/**
+ * The six read verbs, as pure mappings from celilo's CLI JSON to the protocol.
+ *
+ * Pure on purpose. Each one takes an `Upstream` and returns a response, and
+ * every judgement in the file is about a shape rather than about HTTP, so the
+ * whole surface is testable with a fake upstream and no server, no socket and
+ * no SSH.
+ *
+ * Two rules run through all of them.
+ *
+ * A failed read THROWS. It never returns an empty list. `UpstreamUnavailable`
+ * carries why (denied, unknown verb, unreachable, interview, malformed), the
+ * tsrpc layer turns it into an error the client renders as "unavailable", and
+ * the console draws that differently from "nothing is wrong". Returning `[]` for
+ * a read that did not happen is the bug this console was specified around.
+ *
+ * Nothing here writes. The console's API principal is granted read ops only, so
+ * a mutating verb added to this file would be refused at the API boundary rather
+ * than running — but it would still be a lie in the source, so it stays absent.
+ */
+
+import type {
+  AlertProjection,
+  BackupProjection,
+  BackupRunProjection,
+  ClosureNode,
+  ModuleProjection,
+  ResAlerts,
+  ResBackups,
+  ResClosure,
+  ResModules,
+  ResTopology,
+} from '@celilo/console-protocol';
+import type { Upstream } from './upstream';
+
+/**
+ * How far back the backups read asks for.
+ *
+ * The grid draws days, and days past this are drawn as "not captured" rather
+ * than as missed backups. Thirty is a month of context at a payload the poll can
+ * afford: a module failing hourly produces ~720 rows in that window, which is
+ * large but bounded, where an unbounded read of the live fleet is 586 rows today
+ * and grows forever.
+ */
+const BACKUP_WINDOW_DAYS = 30;
+
+/** `celilo console status --json`, verbatim. */
+interface CliConsoleStatus {
+  zones: string[];
+  modules: {
+    id: string;
+    version: string;
+    state: string;
+    health: { cell: string; monitored: boolean; firingCount: number; suppressed: boolean };
+    systems: { hostname: string; address: string; zone: string }[];
+    lastBackupAt: number | null;
+    lastBackupFailed: boolean;
+    unwatched: boolean;
+    pagesNobody: boolean;
+    backupStale: boolean;
+  }[];
+}
+
+/**
+ * `celilo console get <id> --json`, verbatim.
+ *
+ * Note what is NOT here: delegation chains. D6 establishes that the firewall
+ * chain is derivable (a provider's capability data names the zone it delegates
+ * to) and that the derivation must be verified against a live
+ * `celilo capability info firewall` before anything is built on it. That
+ * verification has not happened and `computeClosure` does not produce chains,
+ * so this server has none to serve.
+ */
+interface CliClosure {
+  nodes: { moduleId: string; hop: number; optional: boolean; via: string[] }[];
+  depth: number;
+  truncated: boolean;
+}
+
+/** `celilo alerts --json`, verbatim. */
+interface CliAlert {
+  id: string;
+  key: string;
+  state: string;
+  severity: string;
+  monitor: string | null;
+  escalationPolicy: string | null;
+  escalationStep: number;
+  nextEscalationAt: number | null;
+  firstFiredAt: number;
+  lastSeenAt: number;
+  suppressedByAlertId: string | null;
+  suppressedByWindowId: string | null;
+  awaitingConfirmation: boolean;
+  ackedBy: string | null;
+  ackedAt: number | null;
+  silencedUntil: number | null;
+  message: string;
+}
+
+/** `celilo backup list --json`, verbatim. */
+interface CliBackups {
+  asOf: number;
+  windowDays: number | null;
+  backups: {
+    id: string;
+    shortId: string;
+    moduleId: string | null;
+    backupType: string;
+    status: string;
+    sizeBytes: number | null;
+    startedAt: number;
+    completedAt: number | null;
+    storage: string;
+    storagePath: string;
+    moduleVersion: string | null;
+    schemaVersion: string | null;
+    name: string | null;
+    error: string | null;
+  }[];
+  modules: {
+    moduleId: string;
+    lastSuccessAt: number | null;
+    lastAttemptAt: number | null;
+    consecutiveFailures: number;
+  }[];
+}
+
+/**
+ * The health cell, narrowed to the four the protocol names.
+ *
+ * `not deployed` is a real cell celilo emits for a module it has installed but
+ * placed nowhere, and it maps to `not observed` rather than to `ok`: there is
+ * nothing running to be healthy. Anything unrecognised also becomes
+ * `not observed`, never `ok`, because an unknown state is not evidence that a
+ * module is fine and a newer celilo may name one this console has not seen.
+ */
+function healthCell(cell: string): ModuleProjection['health']['cell'] {
+  if (cell === 'firing') return 'firing';
+  if (cell === 'suppressed') return 'suppressed';
+  if (cell === 'ok') return 'ok';
+  return 'not observed';
+}
+
+function toModule(row: CliConsoleStatus['modules'][number]): ModuleProjection {
+  return {
+    id: row.id,
+    version: row.version,
+    state: row.state,
+    health: { cell: healthCell(row.health.cell), firingCount: row.health.firingCount },
+    systems: row.systems.map((system) => ({
+      hostname: system.hostname,
+      address: system.address,
+      zone: system.zone,
+    })),
+    lastBackupAt: row.lastBackupAt,
+    backupStale: row.backupStale,
+    unwatched: row.unwatched,
+    pagesNobody: row.pagesNobody,
+  };
+}
+
+export async function readTopology(upstream: Upstream): Promise<ResTopology> {
+  const status = await upstream.read<CliConsoleStatus>(['console', 'status', '--json']);
+  return { zones: status.zones, modules: status.modules.map(toModule) };
+}
+
+/** The same read as the topology. The roster and the map are one poll (D9). */
+export async function readModules(upstream: Upstream): Promise<ResModules> {
+  const status = await upstream.read<CliConsoleStatus>(['console', 'status', '--json']);
+  return { modules: status.modules.map(toModule) };
+}
+
+/**
+ * A module's bounded closure, joined against the roster.
+ *
+ * celilo's closure names modules by id; the protocol carries the whole
+ * projection on each node, so the console can draw a dependency without a second
+ * lookup per node. The join happens here rather than in the browser because both
+ * reads are cached upstream and doing it there would mean shipping the roster
+ * twice.
+ *
+ * A node naming a module the roster does not have is DROPPED, not faked. That
+ * only happens if the two reads straddle an uninstall, and inventing a
+ * projection for it would draw a module that no longer exists.
+ */
+export async function readClosure(
+  upstream: Upstream,
+  moduleId: string,
+  depth?: number,
+): Promise<ResClosure> {
+  const argv = ['console', 'get', moduleId, '--json'];
+  if (depth !== undefined) argv.push('--depth', String(depth));
+
+  const [closure, status] = await Promise.all([
+    upstream.read<CliClosure>(argv),
+    upstream.read<CliConsoleStatus>(['console', 'status', '--json']),
+  ]);
+
+  const byId = new Map(status.modules.map((row) => [row.id, toModule(row)]));
+  const nodes: ClosureNode[] = [];
+  for (const node of closure.nodes) {
+    const module = byId.get(node.moduleId);
+    if (!module) continue;
+    nodes.push({ module, hop: node.hop, optional: node.optional, via: node.via });
+  }
+
+  return {
+    nodes,
+    // EMPTY BECAUSE THERE IS NO PRODUCER, not because this fleet has no
+    // delegation. On the live fleet `iptables` delegates upstream to `axon`, so
+    // an empty list here is wrong rather than merely unpopulated. It is left
+    // empty rather than faked, and no console surface renders it today — the
+    // moment one does, it must say "not computed" rather than "none".
+    chains: [],
+    depth: closure.depth,
+    truncated: closure.truncated,
+  };
+}
+
+/** Severity, narrowed. An unknown one is `critical`: never quieter than told. */
+function severity(value: string): AlertProjection['severity'] {
+  return value === 'warning' ? 'warning' : 'critical';
+}
+
+/** Alert state, narrowed. An unknown one is `firing`, for the same reason. */
+function alertState(value: string): AlertProjection['state'] {
+  const known = ['pending', 'firing', 'acked', 'suppressed', 'resolved'] as const;
+  return (known as readonly string[]).includes(value)
+    ? (value as AlertProjection['state'])
+    : 'firing';
+}
+
+/**
+ * The module an alert is about, from its key.
+ *
+ * Keys are structured `module:caddy/check:cert-validity`, so the subject is the
+ * first segment's value. A key that names something other than a module (a
+ * machine, a builtin check) yields null rather than a guess, and the console
+ * renders those against the fleet rather than against a module.
+ */
+function moduleOfKey(key: string): string | null {
+  const [head] = key.split('/');
+  if (!head?.startsWith('module:')) return null;
+  return head.slice('module:'.length) || null;
+}
+
+export async function readAlerts(upstream: Upstream, moduleId?: string): Promise<ResAlerts> {
+  // `alerts list`, not bare `alerts`. The API authorises `command:subcommand`,
+  // and the read-only grant this console holds is `alerts:list` — a bare
+  // `alerts` carries no subcommand token and is refused, which would have
+  // rendered as an unexplained 403 on the first real deploy.
+  const rows = await upstream.read<CliAlert[]>(['alerts', 'list', '--json']);
+  const asOf = Date.now();
+
+  // Filtered HERE rather than by asking celilo for a filtered list. The whole
+  // fleet's alerts are one cached read shared by every browser tab, and the
+  // dashboard's dock re-scopes on every selection change.
+  const wanted = moduleId ? rows.filter((row) => moduleOfKey(row.key) === moduleId) : rows;
+
+  return {
+    asOf,
+    alerts: wanted.map(
+      (row): AlertProjection => ({
+        id: row.id,
+        key: row.key,
+        moduleId: moduleOfKey(row.key),
+        message: row.message,
+        state: alertState(row.state),
+        severity: severity(row.severity),
+        policy: row.escalationPolicy,
+        firstFiredAt: row.firstFiredAt,
+        lastSeenAt: row.lastSeenAt,
+        suppressedByAlertId: row.suppressedByAlertId,
+        suppressedByWindowId: row.suppressedByWindowId,
+        silencedUntil: row.silencedUntil,
+        // `alerts --json` resolves the person to a name. There is no id on the
+        // wire, so the name serves as both — which is what the console shows.
+        ackedBy: row.ackedBy ? { id: row.ackedBy, name: row.ackedBy } : null,
+        ackedAt: row.ackedAt,
+        escalationStep: row.escalationStep,
+        nextEscalationAt: row.nextEscalationAt,
+      }),
+    ),
+  };
+}
+
+export async function readBackups(upstream: Upstream): Promise<ResBackups> {
+  const data = await upstream.read<CliBackups>([
+    'backup',
+    'list',
+    '--json',
+    '--since',
+    String(BACKUP_WINDOW_DAYS),
+  ]);
+
+  // Every module celilo reports a backup ATTEMPT for is hooked, by definition:
+  // nothing else can produce one. Modules with no attempts are not listed here
+  // at all, and the console pairs this against the roster to find them.
+  const backups: BackupProjection[] = data.modules.map((row) => ({
+    moduleId: row.moduleId,
+    coverage: 'hooked',
+    lastSuccessAt: row.lastSuccessAt,
+    lastAttemptAt: row.lastAttemptAt,
+    lastAttemptFailed:
+      row.lastAttemptAt !== null &&
+      (row.lastSuccessAt === null || row.lastAttemptAt > row.lastSuccessAt),
+    failuresSinceSuccess: row.consecutiveFailures,
+    // celilo resolves the cadence and reports staleness on the roster read, so
+    // it is not re-derived here. Null says "this read does not carry it".
+    scheduleHours: null,
+    stale: false,
+  }));
+
+  const runs: BackupRunProjection[] = data.backups
+    // A system-state backup belongs to no module and has no row in the grid.
+    .filter((row) => row.moduleId !== null)
+    .map((row) => ({
+      id: row.shortId,
+      moduleId: row.moduleId as string,
+      at: row.startedAt,
+      completed: row.status === 'completed',
+      sizeBytes: row.sizeBytes,
+      storage: row.storage,
+      moduleVersion: row.moduleVersion,
+      name: row.name,
+      error: row.error,
+    }));
+
+  return {
+    asOf: data.asOf,
+    windowDays: data.windowDays ?? BACKUP_WINDOW_DAYS,
+    backups,
+    runs,
+  };
+}
+
+/**
+ * Which module ids the roster knows about, paired with the backup summary.
+ *
+ * Exported because the coverage answer needs BOTH reads and neither alone is
+ * enough: `backup list` cannot name a module that has never attempted a backup,
+ * and the roster cannot say whether a module declares the hook. A module in the
+ * roster with no attempts is `unhooked` here, which is right for the eighteen
+ * modules on the live fleet that declare no `on_backup` (celilo#1131) and wrong
+ * only for a hooked module whose very first backup has not run yet. That case
+ * corrects itself on the first attempt, and the alternative — reporting eighteen
+ * modules as overdue — does not.
+ */
+export async function readBackupsWithCoverage(upstream: Upstream): Promise<ResBackups> {
+  const [backups, status] = await Promise.all([
+    readBackups(upstream),
+    upstream.read<CliConsoleStatus>(['console', 'status', '--json']),
+  ]);
+
+  const attempted = new Set(backups.backups.map((row) => row.moduleId));
+  const staleByModule = new Map(status.modules.map((row) => [row.id, row.backupStale]));
+
+  const withStaleness = backups.backups.map((row) => ({
+    ...row,
+    stale: staleByModule.get(row.moduleId) ?? false,
+  }));
+
+  const unhooked: BackupProjection[] = status.modules
+    .filter((row) => !attempted.has(row.id))
+    .map((row) => ({
+      moduleId: row.id,
+      coverage: 'unhooked' as const,
+      lastSuccessAt: null,
+      lastAttemptAt: null,
+      lastAttemptFailed: false,
+      failuresSinceSuccess: 0,
+      scheduleHours: null,
+      // Not overdue. There is nothing to run.
+      stale: false,
+    }));
+
+  return { ...backups, backups: [...withStaleness, ...unhooked] };
+}