@runuai/host 0.1.0

package/src/ui/server.ts

@@ -0,0 +1,343 @@
+/**
+ * Local host UI HTTP server (ADR-028, docs/host-ui.md).
+ *
+ * Bound to 127.0.0.1 ONLY — never 0.0.0.0, never the tailnet. No auth (the
+ * localhost binding is the perimeter — see ADR-028 security stance), no CORS,
+ * read-only. Serves the static UI from `host-agent/ui/` and a small JSON API
+ * under `/api/*`. Every JSON body is parsed through its zod schema before send
+ * so the API can never emit an off-contract shape.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+import { desc, isNull } from "drizzle-orm";
+import type { ZodType } from "zod";
+
+import { schema, type Db } from "../../lib/db";
+import { parsePreviewPortRuntimes } from "../../lib/preview-ports";
+import { getCloudState } from "../../lib/cloud-state";
+import {
+  CloudResponse,
+  EventsResponse,
+  StatusResponse,
+  TasksResponse,
+  UsersResponse,
+  type TaskRow,
+} from "./types";
+
+const HOST = "127.0.0.1";
+const MAX_PORT_ATTEMPTS = 10;
+
+export interface UiServerOptions {
+  /** Host runtime DB (read-only here). */
+  db: Db;
+  /** Static asset directory (`host-agent/ui`). */
+  uiDir: string;
+  /** File to persist the chosen port to (`$UAI_DATA_DIR/host.port`). */
+  portFilePath: string;
+  /** First port to try (5876 or UAI_HOST_UI_PORT). 0 lets the OS pick (tests). */
+  startPort: number;
+  // Facts for /api/status:
+  version: string;
+  cloudUrl: string;
+  hostId: string;
+  logPath: string;
+  /** Best-effort container memory by compose project; null on failure. */
+  taskMemory?: (composeProject: string) => Promise<number | null>;
+}
+
+export interface UiServerHandle {
+  server: Server;
+  port: number;
+  close: () => Promise<void>;
+}
+
+/** Start the local UI server, binding to 127.0.0.1 with port fallback. */
+export async function startUiServer(
+  opts: UiServerOptions,
+): Promise<UiServerHandle> {
+  const server = createServer((req, res) => {
+    void handle(req, res, opts);
+  });
+  const port = await listenWithFallback(server, opts.startPort);
+  await writeFile(opts.portFilePath, `${port}\n`, "utf8");
+  return {
+    server,
+    port,
+    close: () =>
+      new Promise<void>((resolve) => server.close(() => resolve())),
+  };
+}
+
+async function listenWithFallback(
+  server: Server,
+  startPort: number,
+): Promise<number> {
+  let lastErr: NodeJS.ErrnoException | null = null;
+  for (let i = 0; i < MAX_PORT_ATTEMPTS; i += 1) {
+    const port = startPort === 0 ? 0 : startPort + i;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (err: NodeJS.ErrnoException): void => {
+          server.removeListener("listening", onListening);
+          reject(err);
+        };
+        const onListening = (): void => {
+          server.removeListener("error", onError);
+          resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        // 127.0.0.1 ONLY. Binding to 0.0.0.0 here would expose the UI off-box.
+        server.listen(port, HOST);
+      });
+      return (server.address() as AddressInfo).port;
+    } catch (err) {
+      lastErr = err as NodeJS.ErrnoException;
+      if (lastErr.code === "EADDRINUSE" && startPort !== 0) continue;
+      throw lastErr;
+    }
+  }
+  throw new Error(
+    `no free UI port in [${startPort}, ${startPort + MAX_PORT_ATTEMPTS - 1}]` +
+      (lastErr ? `: ${lastErr.message}` : ""),
+  );
+}
+
+async function handle(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const path = (req.url ?? "/").split("?")[0] ?? "/";
+  try {
+    if (req.method !== "GET") {
+      return sendError(res, 405, "method not allowed");
+    }
+    switch (path) {
+      case "/api/status":
+        return sendJson(res, StatusResponse, {
+          pid: process.pid,
+          uptime: process.uptime(),
+          version: opts.version,
+          logPath: opts.logPath,
+          cloudUrl: opts.cloudUrl,
+          hostName: hostname(),
+          hostId: opts.hostId,
+        });
+      case "/api/cloud":
+        return sendJson(res, CloudResponse, getCloudState());
+      case "/api/tasks":
+        return sendJson(res, TasksResponse, await tasksBody(opts));
+      case "/api/events":
+        return sendJson(res, EventsResponse, eventsBody(opts));
+      case "/api/users":
+        return sendJson(res, UsersResponse, usersBody(opts));
+    }
+    if (path.startsWith("/api/")) {
+      return sendError(res, 404, `no such endpoint: ${path}`);
+    }
+    return await serveStatic(res, opts.uiDir, path);
+  } catch (err) {
+    return sendError(res, 500, err instanceof Error ? err.message : "internal error");
+  }
+}
+
+// --- handlers ---------------------------------------------------------------
+
+async function tasksBody(opts: UiServerOptions): Promise<TasksResponse> {
+  const rows = opts.db
+    .select()
+    .from(schema.hostTasks)
+    .where(isNull(schema.hostTasks.endedAt))
+    .all();
+  const now = Date.now();
+  const tasks: TaskRow[] = await Promise.all(
+    rows.map(async (r) => ({
+      taskId: r.taskId,
+      status: r.statusMirror,
+      ownerEmail: r.ownerEmail,
+      projectSlugs: parseSlugs(r.projectSlugs),
+      startedAt: r.startedAt,
+      ageMs: r.startedAt != null ? now - r.startedAt : null,
+      composeProject: r.composeProject,
+      codeServerPort: r.codeServerPort,
+      previewPorts: parsePreviewPortRuntimes(r.previewPorts).map((p) => ({
+        name: p.name,
+        hostPort: p.hostPort ?? null,
+      })),
+      memoryBytes:
+        r.composeProject && opts.taskMemory
+          ? await opts.taskMemory(r.composeProject)
+          : null,
+    })),
+  );
+  return { tasks };
+}
+
+function eventsBody(opts: UiServerOptions): EventsResponse {
+  const rows = opts.db
+    .select()
+    .from(schema.hostEvents)
+    .orderBy(desc(schema.hostEvents.ts))
+    .limit(50)
+    .all();
+  return {
+    events: rows
+      .filter((r) => isKnownEventKind(r.kind))
+      .map((r) => ({
+        id: r.id,
+        taskId: r.taskId,
+        kind: r.kind as EventsResponse["events"][number]["kind"],
+        ts: r.ts,
+        detail: r.detail,
+      })),
+  };
+}
+
+function usersBody(opts: UiServerOptions): UsersResponse {
+  const rows = opts.db
+    .select()
+    .from(schema.hostTasks)
+    .where(isNull(schema.hostTasks.endedAt))
+    .all();
+  const byUser = new Map<string, { email: string | null; count: number }>();
+  for (const r of rows) {
+    if (!r.ownerUserId) continue;
+    const cur = byUser.get(r.ownerUserId) ?? { email: r.ownerEmail, count: 0 };
+    cur.count += 1;
+    if (!cur.email && r.ownerEmail) cur.email = r.ownerEmail;
+    byUser.set(r.ownerUserId, cur);
+  }
+  return {
+    users: [...byUser].map(([userId, v]) => ({
+      userId,
+      email: v.email,
+      activeTasks: v.count,
+    })),
+  };
+}
+
+// --- static -----------------------------------------------------------------
+
+const STATIC_FILES: Record<string, string> = {
+  "/": "index.html",
+  "/index.html": "index.html",
+  "/style.css": "style.css",
+  "/app.js": "app.js",
+  "/uai-logo-black.svg": "uai-logo-black.svg",
+};
+
+async function serveStatic(
+  res: ServerResponse,
+  uiDir: string,
+  path: string,
+): Promise<void> {
+  const file = STATIC_FILES[path];
+  if (!file) return sendError(res, 404, `not found: ${path}`);
+  const full = join(uiDir, file);
+  if (!existsSync(full)) return sendError(res, 404, `not found: ${path}`);
+  const body = await readFile(full);
+  res.writeHead(200, { "content-type": contentType(file) });
+  res.end(body);
+}
+
+function contentType(file: string): string {
+  if (file.endsWith(".html")) return "text/html; charset=utf-8";
+  if (file.endsWith(".css")) return "text/css; charset=utf-8";
+  if (file.endsWith(".js")) return "text/javascript; charset=utf-8";
+  if (file.endsWith(".svg")) return "image/svg+xml";
+  return "application/octet-stream";
+}
+
+// --- response helpers -------------------------------------------------------
+
+function sendJson<T>(res: ServerResponse, shape: ZodType<T>, body: T): void {
+  // Parse before send: the API can never emit an off-contract body.
+  const validated = shape.parse(body);
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(validated));
+}
+
+function sendError(res: ServerResponse, status: number, message: string): void {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify({ error: message }));
+}
+
+// --- misc -------------------------------------------------------------------
+
+function parseSlugs(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed)
+      ? parsed.filter((s): s is string => typeof s === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+function isKnownEventKind(kind: string): boolean {
+  return (
+    kind === "task.created" ||
+    kind === "task.started" ||
+    kind === "task.ended" ||
+    kind === "task.ship"
+  );
+}
+
+/**
+ * Best-effort container memory for a task's compose project via `docker stats`.
+ * Returns null on any failure (docker down, container gone, parse miss).
+ */
+export async function dockerMemoryBytes(
+  composeProject: string,
+): Promise<number | null> {
+  try {
+    const res = spawnSync(
+      "docker",
+      [
+        "stats",
+        "--no-stream",
+        "--format",
+        "{{.MemUsage}}",
+        `${composeProject}-app-1`,
+      ],
+      { encoding: "utf8", timeout: 3_000 },
+    );
+    if (res.status !== 0 || !res.stdout) return null;
+    const used = res.stdout.trim().split("/")[0]?.trim();
+    return used ? parseMemUsage(used) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseMemUsage(text: string): number | null {
+  const m = /^([\d.]+)\s*([a-zA-Z]+)$/.exec(text);
+  if (!m || !m[1] || !m[2]) return null;
+  const value = Number(m[1]);
+  const unit = m[2].toLowerCase();
+  const scale: Record<string, number> = {
+    b: 1,
+    kb: 1e3,
+    mb: 1e6,
+    gb: 1e9,
+    kib: 1024,
+    mib: 1024 ** 2,
+    gib: 1024 ** 3,
+  };
+  const factor = scale[unit];
+  return factor ? Math.round(value * factor) : null;
+}

package/src/ui/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Zod schemas for every local JSON API response (ADR-028, docs/host-ui.md).
+ *
+ * The server parses each response body through these before sending, so the
+ * API can never emit an off-contract shape. This file is the single source of
+ * truth for the wire shapes; the static UI assumes them.
+ */
+
+import { z } from "zod";
+
+// GET /api/status — process + config facts.
+export const StatusResponse = z.object({
+  pid: z.number().int(),
+  uptime: z.number(), // seconds, process.uptime()
+  version: z.string(), // @runuai/host package version
+  logPath: z.string(), // service log file path (per-OS)
+  cloudUrl: z.string(), // UAI_CLOUD_URL
+  hostName: z.string(), // os.hostname()
+  hostId: z.string(), // UAI_HOST_ID
+});
+export type StatusResponse = z.infer<typeof StatusResponse>;
+
+// GET /api/cloud — live WSS connection state (in-memory, from the bridge).
+export const CloudResponse = z.object({
+  state: z.enum(["connected", "reconnecting", "disconnected"]),
+  lastConnectedAt: z.number().nullable(), // epoch ms
+  reconnectCount: z.number().int(),
+  lastError: z.string().nullable(),
+});
+export type CloudResponse = z.infer<typeof CloudResponse>;
+
+// One active task. Runtime fields come from host.sqlite; owner/slugs are
+// persisted at task-up; memory is best-effort docker.
+export const TaskRow = z.object({
+  taskId: z.string(),
+  status: z.string().nullable(), // statusMirror
+  ownerEmail: z.string().nullable(),
+  projectSlugs: z.array(z.string()),
+  startedAt: z.number().nullable(), // epoch ms
+  ageMs: z.number().nullable(), // now - startedAt
+  composeProject: z.string().nullable(),
+  codeServerPort: z.number().int().nullable(),
+  previewPorts: z.array(
+    z.object({ name: z.string(), hostPort: z.number().int().nullable() }),
+  ),
+  memoryBytes: z.number().nullable(), // docker stats, null on failure
+});
+export type TaskRow = z.infer<typeof TaskRow>;
+
+export const TasksResponse = z.object({ tasks: z.array(TaskRow) });
+export type TasksResponse = z.infer<typeof TasksResponse>;
+
+// GET /api/events — last 50 host-recorded lifecycle events, newest first.
+export const EventRow = z.object({
+  id: z.string(),
+  taskId: z.string(),
+  kind: z.enum(["task.created", "task.started", "task.ended", "task.ship"]),
+  ts: z.number(), // epoch ms
+  detail: z.string().nullable(),
+});
+export type EventRow = z.infer<typeof EventRow>;
+
+export const EventsResponse = z.object({ events: z.array(EventRow) });
+export type EventsResponse = z.infer<typeof EventsResponse>;
+
+// GET /api/users — distinct owners across active tasks. v1: the single operator.
+export const UserRow = z.object({
+  userId: z.string(),
+  email: z.string().nullable(),
+  activeTasks: z.number().int(),
+});
+export type UserRow = z.infer<typeof UserRow>;
+
+export const UsersResponse = z.object({ users: z.array(UserRow) });
+export type UsersResponse = z.infer<typeof UsersResponse>;
+
+export const ErrorResponse = z.object({ error: z.string() });
+export type ErrorResponse = z.infer<typeof ErrorResponse>;

package/ui/app.js

@@ -0,0 +1,264 @@
+/* Local host UI (ADR-028). Vanilla JS, no framework, no build step.
+   Polls the read-only JSON API every 2s and renders four panels. */
+
+"use strict";
+
+const $ = (id) => document.getElementById(id);
+const expanded = new Set(); // task ids whose events are expanded (persist across polls)
+let latestTasks = [];
+let latestEvents = [];
+
+const KIND_CLASS = {
+  "task.created": "created",
+  "task.started": "started",
+  "task.ended": "ended",
+  "task.ship": "ship",
+};
+
+async function getJSON(path) {
+  const res = await fetch(path, { cache: "no-store" });
+  if (!res.ok) throw new Error(`${path} → ${res.status}`);
+  return res.json();
+}
+
+async function poll() {
+  try {
+    const [status, cloud, tasks, events] = await Promise.all([
+      getJSON("/api/status"),
+      getJSON("/api/cloud"),
+      getJSON("/api/tasks"),
+      getJSON("/api/events"),
+    ]);
+    renderStatus(status);
+    renderCloud(cloud);
+    renderEvents(events.events);
+    renderTasks(tasks.tasks, events.events);
+    $("foot-note").textContent =
+      `read-only · 127.0.0.1 · updated ${new Date().toLocaleTimeString()}`;
+  } catch {
+    setBadge("bad", "unreachable");
+  }
+}
+
+// --- service ----------------------------------------------------------------
+
+function renderStatus(s) {
+  $("host-name").textContent = s.hostName;
+  $("host-sub").textContent = `host monitor · v${s.version}`;
+  const kv = $("service-kv");
+  kv.replaceChildren();
+  addKv(kv, "PID", String(s.pid));
+  addKv(kv, "Uptime", fmtDuration(s.uptime * 1000));
+  addKv(kv, "Cloud", s.cloudUrl);
+  addKv(kv, "Host ID", s.hostId);
+  addKv(kv, "Log", s.logPath);
+}
+
+function addKv(dl, key, value) {
+  const dt = document.createElement("dt");
+  dt.textContent = key;
+  const dd = document.createElement("dd");
+  dd.textContent = value;
+  dl.append(dt, dd);
+}
+
+// --- connection badge -------------------------------------------------------
+
+function renderCloud(c) {
+  const map = {
+    connected: ["ok", "connected"],
+    reconnecting: ["warn", "reconnecting"],
+    disconnected: ["bad", "disconnected"],
+  };
+  const [cls, label] = map[c.state] || ["bad", c.state];
+  setBadge(cls, label);
+
+  const d = $("badge-detail");
+  d.replaceChildren();
+  d.append(detailRow("Last connected", c.lastConnectedAt ? fmtTime(c.lastConnectedAt) : "never"));
+  d.append(detailRow("Reconnects", String(c.reconnectCount)));
+  if (c.lastError) {
+    const e = document.createElement("div");
+    e.className = "err";
+    e.textContent = c.lastError;
+    d.append(e);
+  }
+}
+
+function setBadge(cls, label) {
+  $("badge-dot").className = "dot " + cls;
+  $("badge-label").textContent = label;
+}
+
+function detailRow(key, value) {
+  const row = document.createElement("div");
+  row.className = "row";
+  const k = document.createElement("span");
+  k.textContent = key;
+  const v = document.createElement("span");
+  v.textContent = value;
+  row.append(k, v);
+  return row;
+}
+
+// --- tasks ------------------------------------------------------------------
+
+function renderTasks(tasks, events) {
+  latestTasks = tasks;
+  latestEvents = events;
+  const wrap = $("tasks");
+  $("tasks-count").textContent = tasks.length ? `(${tasks.length})` : "";
+  $("tasks-empty").hidden = tasks.length > 0;
+  wrap.querySelectorAll(".task").forEach((n) => n.remove());
+  for (const t of tasks) wrap.append(taskNode(t, events));
+}
+
+function taskNode(t, events) {
+  const open = expanded.has(t.taskId);
+  const node = document.createElement("div");
+  node.className = "task" + (open ? " open" : "");
+
+  const head = document.createElement("div");
+  head.className = "task-head";
+  head.addEventListener("click", () => {
+    if (expanded.has(t.taskId)) expanded.delete(t.taskId);
+    else expanded.add(t.taskId);
+    renderTasks(latestTasks, latestEvents);
+  });
+
+  const main = document.createElement("div");
+  main.className = "task-main";
+
+  const title = document.createElement("div");
+  title.className = "task-title";
+  const owner = document.createElement("span");
+  owner.className = "task-owner";
+  owner.textContent = t.ownerEmail || "unknown owner";
+  title.append(owner);
+  for (const slug of t.projectSlugs) {
+    const s = document.createElement("span");
+    s.className = "slug";
+    s.textContent = slug;
+    title.append(s);
+  }
+  if (t.projectSlugs.length === 0) {
+    const s = document.createElement("span");
+    s.className = "slug";
+    s.textContent = "scratchpad";
+    title.append(s);
+  }
+  main.append(title);
+
+  const meta = document.createElement("div");
+  meta.className = "task-meta";
+  const bits = [
+    t.status || "—",
+    t.ageMs != null ? `up ${fmtDuration(t.ageMs)}` : null,
+    t.memoryBytes != null ? fmtBytes(t.memoryBytes) : null,
+  ].filter(Boolean);
+  meta.append(document.createTextNode(bits.join(" · ") + "  "));
+  const id = document.createElement("span");
+  id.className = "task-id";
+  id.textContent = t.taskId;
+  meta.append(id);
+  main.append(meta);
+
+  const chev = document.createElement("span");
+  chev.className = "chev";
+  chev.textContent = "›";
+
+  head.append(main, chev);
+  node.append(head);
+
+  if (open) {
+    const ev = document.createElement("div");
+    ev.className = "task-events";
+    const list = document.createElement("ol");
+    const mine = events.filter((e) => e.taskId === t.taskId);
+    if (mine.length === 0) {
+      const li = document.createElement("li");
+      li.className = "empty";
+      li.textContent = "No events for this task.";
+      list.append(li);
+    } else {
+      for (const e of mine) {
+        const li = document.createElement("li");
+        li.textContent = `${e.kind} — ${fmtTime(e.ts)}${e.detail ? " · " + e.detail : ""}`;
+        list.append(li);
+      }
+    }
+    ev.append(list);
+    node.append(ev);
+  }
+  return node;
+}
+
+// --- events -----------------------------------------------------------------
+
+function renderEvents(events) {
+  latestEvents = events;
+  const ol = $("events");
+  ol.querySelectorAll("li:not(.empty)").forEach((n) => n.remove());
+  $("events-empty").hidden = events.length > 0;
+  for (const e of events) {
+    const li = document.createElement("li");
+    const kind = document.createElement("span");
+    kind.className = "ev-kind " + (KIND_CLASS[e.kind] || "");
+    kind.textContent = e.kind;
+    const time = document.createElement("span");
+    time.className = "ev-time";
+    time.textContent = fmtAgo(e.ts);
+    const task = document.createElement("span");
+    task.className = "ev-task";
+    task.textContent = e.taskId;
+    li.append(kind, time, task);
+    ol.append(li);
+  }
+}
+
+// --- formatting -------------------------------------------------------------
+
+function fmtDuration(ms) {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+function fmtAgo(epochMs) {
+  const diff = Date.now() - epochMs;
+  if (diff < 60_000) return "just now";
+  return fmtDuration(diff) + " ago";
+}
+
+function fmtTime(epochMs) {
+  return new Date(epochMs).toLocaleString();
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i += 1;
+  }
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+// --- wire up ----------------------------------------------------------------
+
+$("badge").addEventListener("click", () => {
+  const detail = $("badge-detail");
+  const show = detail.hidden;
+  detail.hidden = !show;
+  $("badge").setAttribute("aria-expanded", String(show));
+});
+
+poll();
+setInterval(poll, 2000);