@monster-orange/den 0.2.8 → 0.3.0

package/src/ui/server/daemon-reaper.ts

@@ -15,7 +15,9 @@
  * to any workspace/catalog service is process-death-equivalent evidence and
  * is removed directly. Records another root registered (all roots of a
  * product share the file) are never touched, and an unstamped legacy record
- * is not removed for being unresolvable.
+ * is not removed for being unresolvable. A record whose checkout is gone, or
+ * whose service moved to another checkout with nothing of it running
+ * (`staleReason`), is removed whatever the address's health says.
  */
 
 import type { ServiceHealthResult } from "../../shared/environment-manager/health.js";
@@ -49,6 +51,19 @@ export interface DaemonReaperDeps {
    * and an unstamped (pre-0.2.7) one is not dropped for being unresolvable.
    */
   rootOf: (daemon: DaemonRecord) => "here" | "other" | "unstamped";
+  /**
+   * Why a record describes nothing that can be running whatever its health
+   * (service-runner's daemonStaleReason: its checkout is gone, or the
+   * service moved to another checkout and none of its containers run), or
+   * null. Injected; omitted, no record is dropped for it. `running` is the
+   * container listing, taken once per sweep by `runningContainers`.
+   */
+  staleReason?: (
+    daemon: DaemonRecord,
+    running: Set<string> | null,
+  ) => string | null;
+  /** The running container base names (null: unverifiable), once a sweep. */
+  runningContainers?: () => Promise<Set<string> | null>;
 }
 
 export interface DaemonReapResult {
@@ -96,6 +111,11 @@ export async function reapDeadDaemons(
 ): Promise<DaemonReapResult> {
   const removed: string[] = [];
   const kept: string[] = [];
+  const running = deps.staleReason
+    ? await (deps.runningContainers?.() ?? Promise.resolve(null)).catch(
+        () => null,
+      )
+    : null;
 
   await Promise.allSettled(
     deps.listDaemons().map(async (daemon) => {
@@ -105,6 +125,14 @@ export async function reapDeadDaemons(
           kept.push(daemon.address);
           return;
         }
+        // Its checkout is gone, or the service has moved and nothing of
+        // the record's runs: whatever the address's health says (it is
+        // another checkout's), the record is stale.
+        if (deps.staleReason?.(daemon, running)) {
+          deps.unregisterDaemon(daemon.address);
+          removed.push(daemon.address);
+          return;
+        }
         const service = resolveForDaemon(deps, daemon);
         if (!service) {
           // No longer in any owning workspace/catalog — nothing could restart

package/src/ui/server/engine-stamp.ts

@@ -0,0 +1,83 @@
+/**
+ * MD-2 (0.3.0-dev.38): the engine a running web server loaded against the
+ * engine on disk. A pin that upgrades Den rewrites node_modules under a
+ * server that keeps the old code in memory while it serves the new pages
+ * from disk, so the new pages' routes 404. The server records the engine's
+ * version and build id at startup; page requests compare them with the
+ * engine's package.json now (cached for a few seconds).
+ *
+ * The build id is a short hash of that package.json: it changes with any
+ * re-pin, even one that keeps the version string (a git-sha pin).
+ */
+import { createHash } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+export interface EngineStamp {
+  version: string | null;
+  buildId: string | null;
+}
+
+/** The engine's version and build id from its package.json, now. */
+export function readEngineStamp(engineRoot: string): EngineStamp {
+  try {
+    const raw = fs.readFileSync(path.join(engineRoot, "package.json"));
+    const pkg = JSON.parse(raw.toString("utf-8")) as { version?: unknown };
+    return {
+      version: typeof pkg.version === "string" ? pkg.version : null,
+      buildId: createHash("sha256").update(raw).digest("hex").slice(0, 12),
+    };
+  } catch {
+    return { version: null, buildId: null };
+  }
+}
+
+export interface EngineCheck {
+  loaded: EngineStamp;
+  onDisk: EngineStamp;
+  /** The engine on disk is not the one this server runs. */
+  stale: boolean;
+}
+
+/** How long a comparison is reused. */
+export const ENGINE_CHECK_TTL_MS = 3_000;
+
+/**
+ * The loaded stamp (read once, now) and a cached comparison with the disk.
+ * An unreadable package.json on disk is never "stale": nothing is known.
+ */
+export function engineWatch(
+  engineRoot: () => string,
+  opts: { ttlMs?: number; now?: () => number } = {},
+): { loaded: EngineStamp; check(): EngineCheck } {
+  const ttl = opts.ttlMs ?? ENGINE_CHECK_TTL_MS;
+  const now = opts.now ?? Date.now;
+  const loaded = readEngineStamp(engineRoot());
+  let cache: { at: number; value: EngineCheck } | null = null;
+  return {
+    loaded,
+    check() {
+      const t = now();
+      if (cache && t - cache.at < ttl) return cache.value;
+      const onDisk = readEngineStamp(engineRoot());
+      const stale =
+        onDisk.buildId !== null &&
+        loaded.buildId !== null &&
+        onDisk.buildId !== loaded.buildId;
+      cache = { at: t, value: { loaded, onDisk, stale } };
+      return cache.value;
+    },
+  };
+}
+
+/** The restart message (pages, 404s, MCP): both versions and the command. */
+export function engineStaleMessage(c: EngineCheck, cli: string): string {
+  const same = c.onDisk.version === c.loaded.version;
+  const v = (s: EngineStamp) =>
+    (s.version ?? "an unknown version") +
+    (same && s.buildId ? ` (build ${s.buildId})` : "");
+  return (
+    `Den was updated to ${v(c.onDisk)}. This server is still running ${v(c.loaded)}. ` +
+    `Restart it: ${cli} web restart (or your service restart).`
+  );
+}

package/src/ui/server/github-service.ts

@@ -7,12 +7,15 @@
 
 import { execFileSync, execSync } from "child_process";
 import * as path from "path";
-import { readDenConfig } from "../../shared/den-config.js";
+import {
+  configuredGithubOrg,
+  isPlaceholderGithubOrg,
+  readDenConfig,
+} from "../../shared/den-config.js";
 import { readCatalog } from "../../shared/environment-manager/catalog.js";
 import { githubOwnersOf } from "../../shared/org-sources.js";
 import {
   GH_API_TIMEOUT_MS,
-  GIT_REMOTE_TIMEOUT_MS,
   BRANCH_CACHE_TTL_MS,
   REPO_CACHE_TTL_MS,
 } from "../../shared/constants.js";
@@ -40,6 +43,7 @@ export class GitHubService {
     { names: string[]; fetchedAt: number }
   >();
   private reposCache: { data: GitHubRepo[]; fetchedAt: number } | null = null;
+  private warnedNotConfigured = false;
 
   /**
    * List branches for a GitHub repo slug ("owner/repo").
@@ -96,11 +100,13 @@ export class GitHubService {
 
     const orgs = this.resolveOrgs();
     if (orgs.length === 0) {
-      console.warn(
-        "[github-service] listOrgRepos: no GitHub org resolvable — " +
-          `add \`github_org: <slug>\` to ${product().configFile}, or register at least ` +
-          "one catalog entry with a slashed `gh:` field",
-      );
+      if (!this.warnedNotConfigured) {
+        this.warnedNotConfigured = true;
+        console.log(
+          "[github-service] GitHub repos not configured: set `github_org: <your-org>` in " +
+            `${product().configFile} to list them (no gh is run until then)`,
+        );
+      }
       return [];
     }
     const data = orgs.flatMap((org) => this.listOneOrg(org));
@@ -172,18 +178,16 @@ export class GitHubService {
 
   /**
    * Every GitHub org Den lists repos from: `github_org`, then the orgs in
-   * config/den.yml `orgs:`, then every owner in the catalog (several orgs'
-   * repos can sit side by side). With none of those, fall back to
-   * the den repo's own `origin` URL — makes upgraded installs Just
-   *      Work without anyone editing config/den.yml. Existing users
-   *      who pre-date `github_org` or had it commented out still get
-   *      the right value as long as den itself was cloned from the
-   *      same org as their services (the common case).
+   * the org config's `orgs:`, then every owner in the catalog (several
+   * orgs' repos can sit side by side). With `github_org` unset or still a
+   * placeholder (`your-github-org`), none: GitHub is not configured, and Den
+   * runs no gh for it.
    */
   private resolveOrgs(): string[] {
     const config = readDenConfig();
-    const orgs = new Set<string>();
-    if (config.github_org) orgs.add(config.github_org);
+    const primary = configuredGithubOrg(config);
+    if (!primary) return [];
+    const orgs = new Set<string>([primary]);
     // A legacy `orgs:` key is a GitHub owner; an ORG-1d org lists its GitHub
     // sources' owners, and one with no GitHub source adds none (discovery is
     // hidden for it).
@@ -196,33 +200,8 @@ export class GitHubService {
     }
     // Org names reach a shell command: GitHub owners are letters, digits and
     // hyphens, so anything else is dropped.
-    const valid = [...orgs].filter((o) => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(o));
-    if (valid.length > 0) return valid;
-    const fallback = this.originOrg();
-    return fallback ? [fallback] : [];
-  }
-
-  private originOrg(): string | null {
-    // Fall back to the den repo's origin. Works for:
-    //   SSH:   git@github.com:ORG/den.git
-    //   HTTPS: https://github.com/ORG/den.git
-    //          https://github.com/ORG/den
-    try {
-      const url = execFileSync(
-        "git",
-        ["-C", ROOT, "config", "--get", "remote.origin.url"],
-        {
-          encoding: "utf-8",
-          timeout: GIT_REMOTE_TIMEOUT_MS,
-          stdio: ["ignore", "pipe", "ignore"],
-        },
-      ).trim();
-      const m = url.match(/[:/]([^/:]+)\/[^/]+?(?:\.git)?$/);
-      if (m) return m[1];
-    } catch {
-      /* no git remote available */
-    }
-
-    return null;
+    return [...orgs].filter(
+      (o) => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(o) && !isPlaceholderGithubOrg(o),
+    );
   }
 }

package/src/ui/server/graph-page.ts

@@ -0,0 +1,20 @@
+/**
+ * The Graph page (R22, 0.3.0-dev.32, Ward 2026-11-05): the workspace graph
+ * alone, full width, at /graph. It is served from local-dev.html (the
+ * Workspaces page, R24) with the shell's page id and the <title> swapped:
+ * the same graph, actions and details panel, no second copy of them. With
+ * page id "graph" the page hides the workspace list and draws only the
+ * graph.
+ */
+
+const SHELL = '<div id="den-shell" data-page="local-dev"';
+const TITLE = "· Workspaces</title>";
+
+/** local-dev.html → the Graph page. Throws when the markers are gone. */
+export function graphPageHtml(localDev: string): string {
+  if (!localDev.includes(SHELL) || !localDev.includes(TITLE))
+    throw new Error("local-dev.html: the Graph page's markers are missing");
+  return localDev
+    .replace(SHELL, '<div id="den-shell" data-page="graph"')
+    .replace(TITLE, "· Graph</title>");
+}

package/src/ui/server/graph-prefs.ts

@@ -1,5 +1,6 @@
 /**
- * Graph preferences: how the Local Dev graph is laid out for this engineer.
+ * Graph preferences: how the graph is laid out for this engineer, and the
+ * Workspaces page's own view prefs (its list, its table's grouping).
  * Stored in the user config as `graph:` and served by /api/settings, so the
  * layout is remembered between sessions (the page mirrors it to localStorage
  * so the first paint does not wait on the server).
@@ -14,6 +15,16 @@ export interface GraphPrefs {
   density: "detailed" | "compact";
   /** Details panel width in px. */
   panelWidth: number;
+  /**
+   * The Workspaces page's workspace list: open, or collapsed to a 40px strip (R23,
+   * 0.3.0-dev.30, Ward QA 2026-11-05), so the graph gets the width.
+   */
+  workspaces: "open" | "collapsed";
+  /**
+   * The Workspaces page's repo table (R24d, 0.3.0-dev.35): grouped by
+   * nothing, by application (as `<cli> apps`) or by org.
+   */
+  groupBy: "none" | "app" | "org";
 }
 
 export const GRAPH_DEFAULTS: GraphPrefs = {
@@ -21,12 +32,16 @@ export const GRAPH_DEFAULTS: GraphPrefs = {
   group: "org",
   density: "detailed",
   panelWidth: 440,
+  workspaces: "open",
+  groupBy: "none",
 };
 
 const CHOICES = {
   direction: ["down", "right"],
   group: ["org", "app"],
   density: ["detailed", "compact"],
+  workspaces: ["open", "collapsed"],
+  groupBy: ["none", "app", "org"],
 } as const;
 
 const PANEL_MIN = 360;
@@ -87,3 +102,31 @@ export function mergeGraphPrefs(
   }
   return { ok: true, value: out };
 }
+
+/**
+ * The stored block after a POSTed patch (0.3.0-dev.32, a consumer's nit):
+ * only the keys someone set are kept, and a key set to null is removed, so
+ * setting a pref and clearing it again leaves user.yml as it was. Nothing
+ * left: undefined (the caller drops `graph:`). Any bad field fails it.
+ */
+export function patchStoredGraph(
+  stored: unknown,
+  patch: unknown,
+):
+  | { ok: true; value: Record<string, unknown> | undefined }
+  | { ok: false; error: string } {
+  if (!isObject(patch)) return { ok: false, error: "graph must be an object" };
+  const out: Record<string, unknown> = isObject(stored) ? { ...stored } : {};
+  for (const [key, v] of Object.entries(patch)) {
+    if (!(key in GRAPH_DEFAULTS))
+      return { ok: false, error: `unknown graph setting "${key}"` };
+    if (v === null) {
+      delete out[key];
+      continue;
+    }
+    const c = check(key as keyof GraphPrefs, v);
+    if (!c.ok) return c;
+    out[key] = c.value;
+  }
+  return { ok: true, value: Object.keys(out).length ? out : undefined };
+}

package/src/ui/server/http-errors.ts

@@ -0,0 +1,293 @@
+/**
+ * Errors people can see and act on (R26, 0.3.0-dev.38).
+ *
+ *   R26a  a page request (a browser navigation: GET/HEAD, Accept text/html,
+ *         not /api/*) that fails gets the shell frame around an error page
+ *         (public/error.html, drawn by error-page.js): 404 "Page not found"
+ *         or 500 "Something went wrong", with the request id (422 "Config
+ *         is invalid" for a ConfigError).
+ *   R26b  every /api/* error is JSON, one shape:
+ *         { ok: false, error, code, requestId }. jsonApiErrors() makes that
+ *         true for every route at the response, whatever the route sent
+ *         (send400's text, a route's own { ok: false, error } body, …).
+ *
+ * Each request gets a short id (X-Request-Id on every response); the
+ * server log line of a failure carries it, so a person's "request a1b2c3d4"
+ * finds the stack trace.
+ */
+import { randomBytes } from "crypto";
+import * as fs from "fs";
+import * as http from "http";
+import * as path from "path";
+import { PLUGIN_FILE, PLUGIN_ID } from "../../shared/plugins/manifest.js";
+import { PLUGINS_DIR, readLock } from "../../shared/plugins/store.js";
+
+/** A short request id: 8 hex characters. */
+export function newRequestId(): string {
+  return randomBytes(4).toString("hex");
+}
+
+/** The stable `code` for an HTTP status. */
+export function codeForStatus(status: number): string {
+  const codes: Record<number, string> = {
+    400: "bad_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    405: "method_not_allowed",
+    408: "timeout",
+    409: "conflict",
+    410: "gone",
+    413: "too_large",
+    415: "unsupported_media_type",
+    422: "invalid",
+    423: "locked",
+    429: "rate_limited",
+    500: "internal",
+    501: "not_implemented",
+    502: "bad_gateway",
+    503: "unavailable",
+    504: "timeout",
+  };
+  return codes[status] ?? (status >= 500 ? "internal" : `http_${status}`);
+}
+
+export interface ApiErrorBody {
+  ok: false;
+  error: string;
+  code: string;
+  requestId: string;
+  [field: string]: unknown;
+}
+
+/**
+ * The R26b body for an error response: `raw` is what the route sent. A JSON
+ * object keeps its fields (a route's own `runCmd`, `reason`, …) and gains
+ * ok, error, code and requestId; text becomes the message.
+ */
+export function apiErrorBody(
+  status: number,
+  raw: string,
+  requestId: string,
+): ApiErrorBody {
+  const fallback = http.STATUS_CODES[status] ?? `HTTP ${status}`;
+  let obj: Record<string, unknown> | null = null;
+  const text = raw.trim();
+  if (text.startsWith("{")) {
+    try {
+      const v = JSON.parse(text) as unknown;
+      if (v && typeof v === "object" && !Array.isArray(v))
+        obj = v as Record<string, unknown>;
+    } catch {
+      /* text that looks like JSON: the message */
+    }
+  }
+  if (obj) {
+    const error =
+      typeof obj.error === "string" && obj.error
+        ? obj.error
+        : typeof obj.message === "string" && obj.message
+          ? obj.message
+          : fallback;
+    return {
+      ...obj,
+      ok: false,
+      error,
+      code:
+        typeof obj.code === "string" && obj.code
+          ? obj.code
+          : codeForStatus(status),
+      requestId,
+    };
+  }
+  return {
+    ok: false,
+    error: text || fallback,
+    code: codeForStatus(status),
+    requestId,
+  };
+}
+
+/**
+ * Make every error status this response ends with a JSON R26b body. A 2xx
+ * or 3xx (an SSE stream among them) passes through untouched; an error's
+ * body is held until end() and rewritten. Call once per /api request,
+ * before the route runs.
+ */
+export function jsonApiErrors(
+  res: http.ServerResponse,
+  requestId: string,
+): void {
+  const origWriteHead = res.writeHead.bind(res) as (
+    ...a: unknown[]
+  ) => http.ServerResponse;
+  const origWrite = res.write.bind(res) as (...a: unknown[]) => boolean;
+  const origEnd = res.end.bind(res) as (...a: unknown[]) => http.ServerResponse;
+  let held: { status: number; headers: http.OutgoingHttpHeaders } | null = null;
+  const chunks: Buffer[] = [];
+  const isError = (s: number): boolean => s >= 400;
+
+  const hold = (status: number, headers: unknown): void => {
+    const h: http.OutgoingHttpHeaders = {};
+    if (Array.isArray(headers)) {
+      for (let i = 0; i + 1 < headers.length; i += 2)
+        h[String(headers[i]).toLowerCase()] = headers[i + 1] as string;
+    } else if (headers && typeof headers === "object") {
+      for (const [k, v] of Object.entries(headers))
+        h[k.toLowerCase()] = v as string;
+    }
+    held = { status, headers: h };
+  };
+
+  (res as unknown as { writeHead: unknown }).writeHead = (
+    status: number,
+    ...rest: unknown[]
+  ) => {
+    if (!isError(status)) return origWriteHead(status, ...rest);
+    const headers =
+      typeof rest[0] === "string" ? rest[1] : (rest[0] as unknown);
+    hold(status, headers);
+    return res;
+  };
+  (res as unknown as { write: unknown }).write = (
+    chunk: unknown,
+    ...rest: unknown[]
+  ) => {
+    if (!held && !res.headersSent && isError(res.statusCode))
+      hold(res.statusCode, {});
+    if (!held) return origWrite(chunk, ...rest);
+    if (chunk != null && typeof chunk !== "function")
+      chunks.push(
+        Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf-8"),
+      );
+    return true;
+  };
+  (res as unknown as { end: unknown }).end = (...args: unknown[]) => {
+    if (!held && !res.headersSent && isError(res.statusCode))
+      hold(res.statusCode, {});
+    if (!held) return origEnd(...args);
+    const chunk = args[0];
+    if (chunk != null && typeof chunk !== "function")
+      chunks.push(
+        Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf-8"),
+      );
+    const h = held as { status: number; headers: http.OutgoingHttpHeaders };
+    held = null;
+    const body = JSON.stringify(
+      apiErrorBody(
+        h.status,
+        Buffer.concat(chunks).toString("utf-8"),
+        requestId,
+      ),
+    );
+    const headers: http.OutgoingHttpHeaders = { ...h.headers };
+    delete headers["content-length"];
+    headers["content-type"] = "application/json";
+    headers["cache-control"] = "no-store";
+    origWriteHead(h.status, headers);
+    return origEnd(body);
+  };
+}
+
+/** A browser navigation to a page: what gets the shell's error page. */
+export function wantsHtmlPage(
+  req: http.IncomingMessage,
+  pathname: string,
+): boolean {
+  if (req.method !== "GET" && req.method !== "HEAD") return false;
+  if (pathname === "/api" || pathname.startsWith("/api/")) return false;
+  return String(req.headers.accept ?? "").includes("text/html");
+}
+
+/**
+ * What failed, for a person and the log, never with query values: the
+ * path, with id-like segments (numbers, long hex, uuids) as `:id`.
+ */
+export function routeTemplate(pathname: string): string {
+  return (
+    pathname
+      .split("/")
+      .map((seg) =>
+        /^\d+$/.test(seg) ||
+        /^[0-9a-f]{12,}$/i.test(seg) ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(seg)
+          ? ":id"
+          : seg,
+      )
+      .join("/") || "/"
+  );
+}
+
+export interface PluginRoute {
+  id: string;
+  /** Its name from its manifest, when it is installed. */
+  name: string | null;
+  installed: boolean;
+  /** In plugins.lock.json (added, but its files are missing). */
+  locked: boolean;
+}
+
+/**
+ * The plugin a page path belongs to: plugin pages live under
+ * /plugins/<id>/ (PL-SPEC §4: served from plugins/<id>/). Null for any
+ * other path.
+ */
+export function pluginForPath(
+  pathname: string,
+  distRoot: string,
+): PluginRoute | null {
+  const m = pathname.match(/^\/plugins\/([^/]+)(?:\/|$)/);
+  if (!m || !PLUGIN_ID.test(m[1])) return null;
+  const id = m[1];
+  const dir = path.join(distRoot, PLUGINS_DIR, id);
+  let name: string | null = null;
+  let installed = false;
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(dir, PLUGIN_FILE), "utf-8"),
+    ) as { name?: unknown };
+    installed = true;
+    if (typeof manifest.name === "string") name = manifest.name;
+  } catch {
+    installed = fs.existsSync(path.join(dir, "den-theme.json"));
+  }
+  let locked = false;
+  try {
+    locked = Object.prototype.hasOwnProperty.call(readLock(distRoot), id);
+  } catch {
+    /* no lock */
+  }
+  return { id, name, installed, locked };
+}
+
+/** What error.html is told: everything error-page.js draws from. */
+export interface ErrorPageData {
+  /** 422: the config fails validation (a ConfigError). */
+  status: 404 | 422 | 500;
+  /** 404 and 422: the path asked for (no query). */
+  path?: string;
+  /** 422: the ConfigError's message (it names config keys, never values). */
+  message?: string;
+  /** 422: each problem: its file, key path and message (0.3.0-dev.40). */
+  issues?: Array<{ file: string; key: string; message: string }>;
+  /** 422: the distribution's CLI, for "`<cli> validate`". */
+  cli?: string;
+  /** 500: what failed. */
+  method?: string;
+  route?: string;
+  requestId: string;
+  time: string;
+  version: string | null;
+  plugin?: PluginRoute | null;
+  /** MD-2: the restart message, when the engine on disk is newer. */
+  engine?: { loaded: string | null; onDisk: string | null; message: string };
+}
+
+/**
+ * error.html with its data in a JSON script (a `<` in any value can't
+ * close the script: it is escaped).
+ */
+export function fillErrorPage(html: string, data: ErrorPageData): string {
+  const json = JSON.stringify(data).replace(/</g, "\\u003c");
+  return html.replace("@@DEN_ERROR@@", () => json);
+}

package/src/ui/server/http-helpers.ts

@@ -65,21 +65,40 @@ export function sendJson(
   res.end(body);
 }
 
-export function serveFile(res: http.ServerResponse, filePath: string): void {
+/**
+ * A last fill for every served page, set by the server: the appearance
+ * placeholders the pre-paint script reads (@@DEN_MODE@@, @@DEN_DEFAULT_MODE@@).
+ */
+let htmlFill: ((html: string) => string) | null = null;
+export function setHtmlFill(fn: ((html: string) => string) | null): void {
+  htmlFill = fn;
+}
+
+export function serveFile(
+  res: http.ServerResponse,
+  filePath: string,
+  /** A page served from another's file (the Graph page): its raw text in, out. */
+  transform?: (html: string) => string,
+  /** The status to answer with (an error page's: R26a). */
+  status = 200,
+): void {
   try {
     let data: Buffer | string = fs.readFileSync(filePath);
+    if (transform) data = transform(data.toString("utf-8"));
     // Pages are static and product-neutral: their product names are
     // placeholders (__DEN_CLI__, …) filled from the running profile.
     if (filePath.endsWith(".html") || filePath.endsWith(".js"))
       data = fillProductTokens(data.toString("utf-8"));
-    if (filePath.endsWith(".html"))
+    if (filePath.endsWith(".html")) {
       data = addDenUiMarker(brandHtmlTitle(String(data), readBrand()));
+      if (htmlFill) data = htmlFill(data);
+    }
     const headers: Record<string, string> = { "Content-Type": mime(filePath) };
     // App code must never be stale (no ETag/Last-Modified validators are sent,
     // so any heuristic caching would have no way to revalidate).
     if (filePath.endsWith(".html") || filePath.endsWith(".js"))
       headers["Cache-Control"] = "no-store";
-    res.writeHead(200, headers);
+    res.writeHead(status, headers);
     res.end(data);
   } catch {
     res.writeHead(404, { "Content-Type": "text/plain" });