@jmcombs/pi-steward 0.0.0

package/server/api.ts

@@ -0,0 +1,216 @@
+/**
+ * The JSON and SSE routes.
+ *
+ * The browser polls `/api/snapshot` for everything it repaints and holds one
+ * `/api/logs/stream` connection open for the console. Actions are POSTs that
+ * return no body — the client re-polls rather than trusting an optimistic
+ * result, because a load or a restart can take tens of seconds and can fail.
+ *
+ * Every route reads and writes through the {@link StewardDataSource} it is
+ * given; nothing here knows whether that source is simulated or live.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { StewardDataSource } from "../core/source.js";
+import type { LogLine, LogStreamStatus, ModelAction, ServiceAction } from "../core/types.js";
+
+/** Lines replayed to a client that connects mid-run, matching the UI's buffer. */
+const BACKLOG_LINES = 200;
+
+/**
+ * How often the stream re-reads the source's health.
+ *
+ * Source state is not a line and cannot ride the line stream: a source that has
+ * nothing to say is exactly the case the console has to report on. The file can
+ * also vanish mid-session (macOS unlinks `/tmp` files untouched for three days)
+ * and come back on its own, so it is polled rather than sent once at open.
+ */
+const SOURCE_POLL_MS = 2000;
+
+function isServiceAction(value: string): value is ServiceAction {
+  return value === "start" || value === "stop" || value === "restart";
+}
+
+function isModelAction(value: string): value is ModelAction {
+  return value === "load" || value === "unload";
+}
+
+function sendJson(res: ServerResponse, status: number, payload: unknown): void {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(body),
+    "Cache-Control": "no-store",
+  });
+  res.end(body);
+}
+
+function sendStatus(res: ServerResponse, status: number): void {
+  res.writeHead(status, { "Cache-Control": "no-store" });
+  res.end();
+}
+
+/**
+ * Opens the log stream: the buffered backlog first, as individual events, then
+ * every line as it arrives. The subscription is released when the client goes
+ * away — a browser that reloads must not leave a listener behind.
+ */
+function streamLogs(req: IncomingMessage, res: ServerResponse, source: StewardDataSource): void {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream; charset=utf-8",
+    "Cache-Control": "no-store",
+    Connection: "keep-alive",
+  });
+  res.flushHeaders();
+  // Log lines are small and latency matters more than packet count here.
+  req.socket.setNoDelay(true);
+
+  /** Set once the socket is gone, which the guard alone cannot see in time. */
+  let gone = false;
+  /**
+   * Set while the client is behind. Lines that arrive then are dropped rather
+   * than queued: this is a live tail, and an unbounded write buffer would cost
+   * the server memory to deliver a backlog no operator is reading. The gap is
+   * visible in the sequence numbers, which is the honest outcome.
+   */
+  let saturated = false;
+
+  const write = (frame: string): void => {
+    if (gone || res.writableEnded || res.destroyed) return;
+    // The socket can end between that guard and this write — a race the
+    // stream cannot avoid, only absorb.
+    const flushed = res.write(frame, (error) => {
+      if (error) gone = true;
+    });
+    if (!flushed) saturated = true;
+  };
+
+  const send = (line: LogLine): void => {
+    if (saturated) return;
+    write(`data: ${JSON.stringify(line)}\n\n`);
+  };
+
+  /**
+   * Source health, on its own named event so a `message` listener never sees
+   * it. Sent on open and again only when it CHANGES — a console that re-heard
+   * "the file is gone" every two seconds would announce it every two seconds.
+   *
+   * A saturated socket does not suppress this one: it is a handful of bytes and
+   * the state it carries is exactly what an operator needs when things are
+   * going wrong.
+   */
+  let lastStatus = "";
+  const sendStatusFrame = (): void => {
+    const read = source.logStatus;
+    if (read === undefined) return;
+    let status: LogStreamStatus;
+    try {
+      status = read.call(source);
+    } catch {
+      // A source that cannot report on itself is not a reason to drop the tail.
+      return;
+    }
+    const encoded = JSON.stringify(status);
+    if (encoded === lastStatus) return;
+    lastStatus = encoded;
+    write(`event: source\ndata: ${encoded}\n\n`);
+  };
+
+  res.on("drain", () => {
+    saturated = false;
+  });
+  res.on("error", () => {
+    gone = true;
+  });
+
+  // Backlog and subscription are taken together, so a line that arrives while
+  // the stream is opening lands in one of them rather than neither. Sources that
+  // predate `attachLogs` fall back to the two calls, which are safe only because
+  // nothing awaits between them — do not insert one here.
+  const attach = source.attachLogs;
+  const attached =
+    attach === undefined
+      ? { backlog: source.recentLogs(BACKLOG_LINES), unsubscribe: source.subscribeLogs(send) }
+      : attach.call(source, send, BACKLOG_LINES);
+
+  // Health first, so a client that opens onto an unavailable source knows it
+  // before it has read a single (simulated) line.
+  sendStatusFrame();
+  for (const line of attached.backlog) send(line);
+
+  const statusTimer = setInterval(sendStatusFrame, SOURCE_POLL_MS);
+  statusTimer.unref?.();
+
+  res.on("close", () => {
+    gone = true;
+    clearInterval(statusTimer);
+    attached.unsubscribe();
+    res.end();
+  });
+}
+
+/**
+ * Handles `/api/**`, returning `false` when the request is not one of these
+ * routes so the caller can fall through to the asset route (and, failing that,
+ * a 404).
+ */
+export async function handleApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  source: StewardDataSource,
+  pathname: string,
+): Promise<boolean> {
+  const method = req.method ?? "GET";
+
+  if (method === "GET" && pathname === "/api/snapshot") {
+    sendJson(res, 200, await source.snapshot());
+    return true;
+  }
+
+  if (method === "GET" && pathname === "/api/logs/stream") {
+    streamLogs(req, res, source);
+    return true;
+  }
+
+  if (method === "POST") {
+    const service = /^\/api\/service\/([^/]+)$/.exec(pathname);
+    if (service !== null) {
+      const action = decodeURIComponent(service[1] ?? "");
+      if (!isServiceAction(action)) {
+        sendStatus(res, 400);
+        return true;
+      }
+      try {
+        await source.setService(action);
+      } catch (error) {
+        // A control command that was refused is the operator's business, not a
+        // crash: the reason ("launchctl: permission denied") goes back as a
+        // body so the dashboard can show it inline instead of a bare 500.
+        sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+        return true;
+      }
+      sendStatus(res, 204);
+      return true;
+    }
+
+    const model = /^\/api\/models\/([^/]+)\/([^/]+)$/.exec(pathname);
+    if (model !== null) {
+      const modelId = decodeURIComponent(model[1] ?? "");
+      const action = decodeURIComponent(model[2] ?? "");
+      if (!isModelAction(action)) {
+        sendStatus(res, 400);
+        return true;
+      }
+      const snapshot = await source.snapshot();
+      if (!snapshot.models.some((entry) => entry.id === modelId)) {
+        sendStatus(res, 404);
+        return true;
+      }
+      await source.setModel(modelId, action);
+      sendStatus(res, 204);
+      return true;
+    }
+  }
+
+  return false;
+}

package/server/assets.ts

@@ -0,0 +1,198 @@
+/**
+ * The static asset route.
+ *
+ * Steward has no build step: the browser modules are authored as TypeScript
+ * and shipped as TypeScript. A request for `/ui/main.js` reads `ui/main.ts`
+ * off disk and hands it to `node:module`'s `stripTypeScriptTypes`, which
+ * blanks the type annotations in place and leaves runnable JavaScript. Because
+ * only erasable syntax is allowed in `ui/` and `core/`, that is the whole
+ * toolchain.
+ *
+ * Everything else (`.html`, `.css`, `.svg`) is served verbatim. Nothing is
+ * cached: this is a live operator tool, and a stale module is worse than a
+ * re-read.
+ */
+
+import { readFile, realpath } from "node:fs/promises";
+// `stripTypeScriptTypes` landed in Node 22.13. Reaching it through a namespace
+// import keeps a runtime without it from failing the module link, so the guard
+// below can report the real requirement instead of a link error.
+import * as nodeModule from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** One file, ready to write to the response. */
+export interface Asset {
+  body: string;
+  contentType: string;
+}
+
+/**
+ * Resolved from this module's own URL rather than `process.cwd()`, so the
+ * routes work the same from the repo and from an installed npm package.
+ */
+const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const UI_ROOT = path.join(PACKAGE_ROOT, "ui");
+const CORE_ROOT = path.join(PACKAGE_ROOT, "core");
+
+const JAVASCRIPT = "text/javascript; charset=utf-8";
+const CSS = "text/css; charset=utf-8";
+const HTML = "text/html; charset=utf-8";
+const SVG = "image/svg+xml";
+
+const CONTENT_TYPES: Record<string, string | undefined> = {
+  ".js": JAVASCRIPT,
+  ".css": CSS,
+  ".html": HTML,
+  ".svg": SVG,
+};
+
+const NODE_REQUIREMENT =
+  "Steward needs Node >= 22.13: this runtime has no node:module stripTypeScriptTypes(), " +
+  "so the browser modules cannot be served.";
+
+/**
+ * Test sources ship inside the package but are not part of the dashboard.
+ * Matches `format.test.js` and `format.test.ts` alike.
+ */
+const TEST_SOURCE = /\.test\.[^./]+$/;
+
+interface ResolvedAsset {
+  file: string;
+  /** Directory the request was routed to; the file must resolve inside it. */
+  root: string;
+  contentType: string;
+  /** Whether the file on disk is TypeScript that must be stripped first. */
+  strip: boolean;
+}
+
+/**
+ * Throws unless the host can strip TypeScript types. Defaults to this runtime,
+ * and is called at server start so the requirement reaches the operator rather
+ * than surfacing as a blank page once the shell asks for its first module.
+ */
+export function assertTypeStripping(host: { stripTypeScriptTypes?: unknown } = nodeModule): void {
+  if (typeof host.stripTypeScriptTypes !== "function") throw new Error(NODE_REQUIREMENT);
+}
+
+/** True when `candidate` is `root` itself or lives underneath it. */
+function isInside(root: string, candidate: string): boolean {
+  return candidate === root || candidate.startsWith(root + path.sep);
+}
+
+/**
+ * The roots with every symlink already resolved, so the containment check
+ * below compares like with like. Resolved once: they cannot move under a
+ * running server. A root that cannot be resolved falls back to its lexical
+ * path, which is the strictest answer available.
+ */
+const realRoots = new Map<string, Promise<string>>();
+
+function realRoot(root: string): Promise<string> {
+  const cached = realRoots.get(root);
+  if (cached !== undefined) return cached;
+  const pending = realpath(root).catch(() => root);
+  realRoots.set(root, pending);
+  return pending;
+}
+
+/**
+ * Maps a request path to a file, or `null` when the path is not served.
+ *
+ * The lexical check here rejects traversal — including percent-encoded
+ * segments, which are decoded first — before anything touches the disk.
+ * Symlinks are dealt with in {@link readAsset}, where the real path is known.
+ */
+function resolveAsset(pathname: string): ResolvedAsset | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\0")) return null;
+
+  if (decoded === "/" || decoded === "") {
+    return {
+      file: path.join(UI_ROOT, "index.html"),
+      root: UI_ROOT,
+      contentType: HTML,
+      strip: false,
+    };
+  }
+  if (decoded === "/favicon.svg") {
+    return {
+      file: path.join(UI_ROOT, "favicon.svg"),
+      root: UI_ROOT,
+      contentType: SVG,
+      strip: false,
+    };
+  }
+
+  const match = /^\/(ui|core)\/(.+)$/.exec(decoded);
+  const area = match?.[1];
+  const rest = match?.[2];
+  if (rest === undefined) return null;
+  if (TEST_SOURCE.test(rest)) return null;
+
+  const extension = path.extname(rest);
+  const contentType = CONTENT_TYPES[extension];
+  if (contentType === undefined) return null;
+
+  const root = area === "core" ? CORE_ROOT : UI_ROOT;
+  // Import specifiers are written `.js` (NodeNext style); the source is `.ts`.
+  const strip = extension === ".js";
+  const file = path.resolve(root, strip ? `${rest.slice(0, -".js".length)}.ts` : rest);
+  if (!isInside(root, file)) return null;
+
+  return { file, root, contentType, strip };
+}
+
+function stripTypes(source: string): string {
+  const strip = nodeModule.stripTypeScriptTypes;
+  if (typeof strip !== "function") throw new Error(NODE_REQUIREMENT);
+  // Default 'strip' mode only: it erases types without rewriting anything, so
+  // line numbers survive and no source map is needed.
+  return strip(source);
+}
+
+/** True for the errno codes that mean "there is no such file", not "it broke". */
+function isMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  const code = (error as { code?: unknown }).code;
+  return code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR";
+}
+
+/**
+ * Reads the asset a request path maps to, or resolves `null` when the path is
+ * unroutable or the file is absent — both of which the caller answers with a
+ * 404.
+ */
+export async function readAsset(pathname: string): Promise<Asset | null> {
+  const resolved = resolveAsset(pathname);
+  if (resolved === null) return null;
+
+  // `path.resolve` cannot see through a symlink but `readFile` follows one, so
+  // containment is re-checked against the path the filesystem actually means.
+  let file: string;
+  try {
+    file = await realpath(resolved.file);
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+  if (!isInside(await realRoot(resolved.root), file)) return null;
+
+  let source: string;
+  try {
+    source = await readFile(file, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+
+  return {
+    body: resolved.strip ? stripTypes(source) : source,
+    contentType: resolved.contentType,
+  };
+}