@cfbender/cesium 0.5.2 → 0.6.1

package/src/server/api.ts

@@ -1,12 +1,15 @@
-// API route handler for interactive artifact submissions and state queries.
+// API routes for interactive artifact submissions and state queries, exposed
+// as a Hono sub-app. Mounted by lifecycle.ts via `handle.app.route("/", apiApp)`.
 //
 // Routes:
 //   POST /api/sessions/:projectSlug/:filename/answers/:questionId
 //   GET  /api/sessions/:projectSlug/:filename/state
 //
-// Wire into startServer via handle.addHandler() before the static file fallback.
+// Any other /api/* path returns a JSON 404 (rather than falling through to the
+// static file handler, which would return the HTML 404 page).
 
 import { join, resolve, relative } from "node:path";
+import { Hono } from "hono";
 import { submitAnswer, getState } from "../storage/mutate.ts";
 import type { AnswerValue } from "../render/validate.ts";
 
@@ -19,148 +22,133 @@ export interface ApiHandlerOptions {
 const FILENAME_RE = /^[^/\\]+\.html$/;
 const DANGEROUS_RE = /[/\\]|\.\./;
 
-function jsonResponse(body: unknown, status: number): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: {
-      "Content-Type": "application/json; charset=utf-8",
-      "Cache-Control": "no-store",
-    },
-  });
+interface ResolvedArtifact {
+  /** Absolute path to the artifact file. */
+  artifactPath: string;
+}
+
+/**
+ * Validate the slug/filename pair and resolve the artifact's absolute path,
+ * enforcing containment under <stateDir>/projects/<slug>/artifacts/. Returns
+ * a Hono `Response` on validation failure, or the resolved path on success.
+ */
+function resolveArtifact(
+  stateDir: string,
+  projectSlug: string,
+  filename: string,
+): ResolvedArtifact | Response {
+  if (DANGEROUS_RE.test(projectSlug) || DANGEROUS_RE.test(filename)) {
+    return Response.json({ ok: false, error: "invalid path component" }, { status: 400 });
+  }
+  if (!FILENAME_RE.test(filename)) {
+    return Response.json({ ok: false, error: "filename must end with .html" }, { status: 400 });
+  }
+
+  const artifactsDir = join(stateDir, "projects", projectSlug, "artifacts");
+  const artifactPath = join(artifactsDir, filename);
+  const resolvedArtifactsDir = resolve(artifactsDir);
+  const resolvedArtifact = resolve(artifactPath);
+  const rel = relative(resolvedArtifactsDir, resolvedArtifact);
+  if (rel.startsWith("..") || rel.includes("/")) {
+    return Response.json({ ok: false, error: "invalid path" }, { status: 400 });
+  }
+  return { artifactPath: resolvedArtifact };
 }
 
-export function createApiHandler(
-  options: ApiHandlerOptions,
-): (req: Request) => Promise<Response | undefined> {
+export function createApiApp(options: ApiHandlerOptions): Hono {
   const { stateDir } = options;
+  const app = new Hono();
 
-  return async (req: Request): Promise<Response | undefined> => {
-    const url = new URL(req.url);
-    const { pathname } = url;
+  // All API responses are dynamic — never let intermediaries cache them.
+  app.use("/api/*", async (c, next) => {
+    await next();
+    c.header("Cache-Control", "no-store");
+  });
 
-    // Only handle /api/ routes
-    if (!pathname.startsWith("/api/")) {
-      return undefined;
-    }
+  // POST /api/sessions/:projectSlug/:filename/answers/:questionId
+  app.post("/api/sessions/:projectSlug/:filename/answers/:questionId", async (c) => {
+    const { projectSlug, filename, questionId } = c.req.param();
 
-    // ─── Route matching ────────────────────────────────────────────────────
-    // POST /api/sessions/:projectSlug/:filename/answers/:questionId
-    const answerMatch = /^\/api\/sessions\/([^/]+)\/([^/]+)\/answers\/([^/]+)$/.exec(pathname);
-    // GET  /api/sessions/:projectSlug/:filename/state
-    const stateMatch = /^\/api\/sessions\/([^/]+)\/([^/]+)\/state$/.exec(pathname);
+    const resolved = resolveArtifact(stateDir, projectSlug, filename);
+    if (resolved instanceof Response) return resolved;
 
-    if (answerMatch === null && stateMatch === null) {
-      // Unrecognized /api/ path
-      return jsonResponse({ ok: false, error: "not found" }, 404);
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ ok: false, error: "invalid JSON body" }, 400);
     }
 
-    const match = (answerMatch ?? stateMatch)!;
-    const projectSlug = match[1]!;
-    const filename = match[2]!;
-
-    // ─── Input validation ──────────────────────────────────────────────────
-    if (DANGEROUS_RE.test(projectSlug) || DANGEROUS_RE.test(filename)) {
-      return jsonResponse({ ok: false, error: "invalid path component" }, 400);
+    if (
+      body === null ||
+      typeof body !== "object" ||
+      Array.isArray(body) ||
+      !("value" in (body as Record<string, unknown>))
+    ) {
+      return c.json({ ok: false, error: 'body must contain a "value" field' }, 400);
     }
 
-    if (!FILENAME_RE.test(filename)) {
-      return jsonResponse({ ok: false, error: "filename must end with .html" }, 400);
-    }
+    const value = (body as Record<string, unknown>)["value"] as AnswerValue;
 
-    // ─── Path traversal defense ────────────────────────────────────────────
-    const artifactsDir = join(stateDir, "projects", projectSlug, "artifacts");
-    const artifactPath = join(artifactsDir, filename);
+    const outcome = await submitAnswer({
+      artifactPath: resolved.artifactPath,
+      questionId,
+      value,
+    });
 
-    const resolvedArtifactsDir = resolve(artifactsDir);
-    const resolvedArtifact = resolve(artifactPath);
-    const rel = relative(resolvedArtifactsDir, resolvedArtifact);
-    if (rel.startsWith("..") || rel.includes("/")) {
-      return jsonResponse({ ok: false, error: "invalid path" }, 400);
+    if (outcome.ok) {
+      return c.json(
+        {
+          ok: true,
+          status: outcome.status,
+          remaining: outcome.remaining,
+          replacementHtml: outcome.replacementHtml,
+        },
+        200,
+      );
     }
 
-    // ─── Route dispatch ────────────────────────────────────────────────────
-
-    if (answerMatch !== null) {
-      // POST /api/sessions/:projectSlug/:filename/answers/:questionId
-      if (req.method !== "POST") {
-        return jsonResponse({ ok: false, error: "method not allowed" }, 404);
-      }
-
-      const questionId = answerMatch[3]!;
-
-      // Parse body
-      let body: unknown;
-      try {
-        body = await req.json();
-      } catch {
-        return jsonResponse({ ok: false, error: "invalid JSON body" }, 400);
-      }
-
-      if (
-        body === null ||
-        typeof body !== "object" ||
-        Array.isArray(body) ||
-        !("value" in (body as Record<string, unknown>))
-      ) {
-        return jsonResponse({ ok: false, error: 'body must contain a "value" field' }, 400);
-      }
-
-      const value = (body as Record<string, unknown>)["value"] as AnswerValue;
-
-      const outcome = await submitAnswer({ artifactPath: resolvedArtifact, questionId, value });
-
-      if (outcome.ok) {
-        return jsonResponse(
-          {
-            ok: true,
-            status: outcome.status,
-            remaining: outcome.remaining,
-            replacementHtml: outcome.replacementHtml,
-          },
-          200,
-        );
-      }
-
-      switch (outcome.reason) {
-        case "not-found":
-        case "not-interactive":
-        case "unknown-question":
-          return jsonResponse({ ok: false, reason: outcome.reason }, 404);
-        case "session-ended":
-          return jsonResponse({ ok: false, status: outcome.status }, 410);
-        case "expired":
-          return jsonResponse({ ok: false, status: "expired" }, 410);
-        case "invalid-value":
-          return jsonResponse({ ok: false, message: outcome.message }, 422);
-      }
-
-      // Fallback (should not reach)
-      return jsonResponse({ ok: false, error: "internal error" }, 500);
+    switch (outcome.reason) {
+      case "not-found":
+      case "not-interactive":
+      case "unknown-question":
+        return c.json({ ok: false, reason: outcome.reason }, 404);
+      case "session-ended":
+        return c.json({ ok: false, status: outcome.status }, 410);
+      case "expired":
+        return c.json({ ok: false, status: "expired" }, 410);
+      case "invalid-value":
+        return c.json({ ok: false, message: outcome.message }, 422);
     }
 
-    if (stateMatch !== null) {
-      // GET /api/sessions/:projectSlug/:filename/state
-      if (req.method !== "GET") {
-        return jsonResponse({ ok: false, error: "method not allowed" }, 404);
-      }
+    return c.json({ ok: false, error: "internal error" }, 500);
+  });
 
-      const outcome = await getState(resolvedArtifact);
+  // GET /api/sessions/:projectSlug/:filename/state
+  app.get("/api/sessions/:projectSlug/:filename/state", async (c) => {
+    const { projectSlug, filename } = c.req.param();
 
-      if (!outcome.ok) {
-        return jsonResponse({ ok: false, reason: outcome.reason }, 404);
-      }
+    const resolved = resolveArtifact(stateDir, projectSlug, filename);
+    if (resolved instanceof Response) return resolved;
 
-      return jsonResponse(
-        {
-          status: outcome.status,
-          answers: outcome.answers,
-          remaining: outcome.remaining,
-        },
-        200,
-      );
+    const outcome = await getState(resolved.artifactPath);
+    if (!outcome.ok) {
+      return c.json({ ok: false, reason: outcome.reason }, 404);
     }
 
-    // Should not reach here
-    return jsonResponse({ ok: false, error: "not found" }, 404);
-  };
+    return c.json(
+      {
+        status: outcome.status,
+        answers: outcome.answers,
+        remaining: outcome.remaining,
+      },
+      200,
+    );
+  });
+
+  // Catch-all under /api/* — keeps unmatched API paths as JSON 404 instead of
+  // falling through to the static file handler.
+  app.all("/api/*", (c) => c.json({ ok: false, error: "not found" }, 404));
+
+  return app;
 }

package/src/server/favicon.ts

@@ -7,22 +7,14 @@
 // (written by writeFaviconSvg on every publish). This shim covers the .ico
 // fallback so users don't see a 404 in DevTools.
 
+import { Hono } from "hono";
 import { FAVICON_SVG } from "../render/favicon.ts";
 
-const SVG_RESPONSE_HEADERS: Record<string, string> = {
-  "Content-Type": "image/svg+xml; charset=utf-8",
-  "Cache-Control": "public, max-age=86400",
-};
-
-export function createFaviconHandler(): (req: Request) => Promise<Response | undefined> {
-  return async (req: Request): Promise<Response | undefined> => {
-    const url = new URL(req.url);
-    if (url.pathname !== "/favicon.ico") {
-      return undefined;
-    }
-    if (req.method !== "GET" && req.method !== "HEAD") {
-      return undefined;
-    }
-    return new Response(FAVICON_SVG, { status: 200, headers: SVG_RESPONSE_HEADERS });
-  };
+export function createFaviconApp(): Hono {
+  const app = new Hono();
+  app.on(["GET", "HEAD"], "/favicon.ico", (c) => {
+    c.header("Cache-Control", "public, max-age=86400");
+    return c.body(FAVICON_SVG, 200, { "Content-Type": "image/svg+xml; charset=utf-8" });
+  });
+  return app;
 }

package/src/server/http.ts

@@ -1,15 +1,25 @@
 // Bun HTTP server bound to 127.0.0.1 (default), serving the cesium state directory.
+//
+// Routing is owned by a Hono app exposed on the returned ServerHandle. Callers
+// (e.g. lifecycle.ts) mount sub-apps for /api/* and /favicon.ico via
+// `handle.app.route("/", subApp)`. Any path that does not match a registered
+// route falls through to the static file handler installed here via
+// `app.notFound` — this preserves the cesium-specific behavior (custom 404 page,
+// 1MB streaming threshold, MIME table) without forcing callers to think about
+// registration order.
 
 import { resolve, extname } from "node:path";
 import { readFile } from "node:fs/promises";
+import { Hono } from "hono";
 
 export interface ServerHandle {
   port: number;
   url: string; // "http://127.0.0.1:<port>"
+  /** Hono app — register routes via `handle.app.route(...)` before requests arrive. */
+  app: Hono;
   stop(): Promise<void>;
-  onRequest(handler: () => void): void; // for idle-tracking; lifecycle attaches a callback
-  /** Register a pre-static handler. Returns a Response to short-circuit, or undefined to fall through. */
-  addHandler(handler: (req: Request) => Promise<Response | undefined>): void;
+  /** Register an idle-tracker callback fired on every request. */
+  onRequest(handler: () => void): void;
 }
 
 export interface StartServerArgs {
@@ -57,119 +67,106 @@ const FORBIDDEN_HTML = `<!doctype html>
 <body><div class="box"><h1>403</h1><p>forbidden</p></div></body>
 </html>`;
 
+const ONE_MB = 1024 * 1024;
+
 function mimeFor(filePath: string): string {
   const ext = extname(filePath).toLowerCase();
   return MIME_TYPES[ext] ?? "application/octet-stream";
 }
 
+function htmlResponse(body: string, status: number): Response {
+  return new Response(body, {
+    status,
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+}
+
+// Static file handler: resolves the request path under stateDir, enforces
+// traversal containment, falls back to index.html for directories, streams
+// files >= 1MB, and returns the cesium 404 page on miss.
+async function serveStatic(req: Request, stateDirResolved: string): Promise<Response> {
+  if (req.method !== "GET") {
+    return new Response("Method Not Allowed", { status: 405 });
+  }
+
+  const url = new URL(req.url);
+  let reqPath: string;
+  try {
+    reqPath = decodeURIComponent(url.pathname);
+  } catch {
+    return htmlResponse(NOT_FOUND_HTML, 404);
+  }
+
+  const joined = resolve(stateDirResolved, "." + reqPath);
+
+  // Path traversal defense: resolved path must be rooted at stateDir
+  if (!joined.startsWith(stateDirResolved + "/") && joined !== stateDirResolved) {
+    return htmlResponse(FORBIDDEN_HTML, 403);
+  }
+
+  const filePath = joined;
+  const trailingSlash = reqPath.endsWith("/");
+  const indexPath = filePath.endsWith("/") ? filePath + "index.html" : filePath + "/index.html";
+
+  let fileToServe = filePath;
+  let isDir = false;
+  if (trailingSlash || extname(filePath) === "") {
+    isDir = true;
+    fileToServe = filePath.endsWith("/") ? filePath + "index.html" : filePath + "/index.html";
+  }
+
+  const bunFile = Bun.file(fileToServe);
+  let exists = await bunFile.exists();
+
+  if (!exists && !isDir) {
+    // Try as directory index (e.g. /sub → /sub/index.html)
+    fileToServe = indexPath;
+    exists = await Bun.file(fileToServe).exists();
+    if (!exists) return htmlResponse(NOT_FOUND_HTML, 404);
+  } else if (!exists) {
+    return htmlResponse(NOT_FOUND_HTML, 404);
+  }
+
+  const contentType = mimeFor(fileToServe);
+  const finalFile = Bun.file(fileToServe);
+  const size = finalFile.size;
+
+  // Large files: stream; small files: read fully.
+  if (size >= ONE_MB) {
+    return new Response(finalFile.stream(), {
+      status: 200,
+      headers: { "Content-Type": contentType },
+    });
+  }
+
+  const buf = await readFile(fileToServe);
+  return new Response(buf, { status: 200, headers: { "Content-Type": contentType } });
+}
+
 export async function startServer(args: StartServerArgs): Promise<ServerHandle> {
   const { stateDir, port, hostname = "127.0.0.1" } = args;
   const stateDirResolved = resolve(stateDir);
   const requestHandlers: Array<() => void> = [];
-  const preHandlers: Array<(req: Request) => Promise<Response | undefined>> = [];
+
+  const app = new Hono();
+
+  // Idle-tracker middleware: fires registered callbacks on every request before
+  // dispatching to routes. Used by lifecycle.ts to reset the idle-shutdown timer.
+  app.use("*", async (_c, next) => {
+    for (const h of requestHandlers) {
+      h();
+    }
+    await next();
+  });
+
+  // Anything that doesn't match a registered route falls through to static
+  // file serving rooted at stateDir.
+  app.notFound((c) => serveStatic(c.req.raw, stateDirResolved));
 
   const server = Bun.serve({
     hostname,
     port,
-    async fetch(req) {
-      // Notify idle tracker
-      for (const h of requestHandlers) {
-        h();
-      }
-
-      // Run pre-static handlers (e.g. API routes) before serving static files
-      for (const handler of preHandlers) {
-        const result = await handler(req);
-        if (result !== undefined) {
-          return result;
-        }
-      }
-
-      if (req.method !== "GET") {
-        return new Response("Method Not Allowed", { status: 405 });
-      }
-
-      const url = new URL(req.url);
-      // Decode and normalize the request path
-      let reqPath: string;
-      try {
-        reqPath = decodeURIComponent(url.pathname);
-      } catch {
-        return new Response(NOT_FOUND_HTML, {
-          status: 404,
-          headers: { "Content-Type": "text/html; charset=utf-8" },
-        });
-      }
-
-      // Resolve the absolute path under stateDir
-      // Use resolve with stateDir as root to prevent traversal
-      const joined = resolve(stateDirResolved, "." + reqPath);
-
-      // Path traversal defense: resolved path must be rooted at stateDir
-      if (!joined.startsWith(stateDirResolved + "/") && joined !== stateDirResolved) {
-        return new Response(FORBIDDEN_HTML, {
-          status: 403,
-          headers: { "Content-Type": "text/html; charset=utf-8" },
-        });
-      }
-
-      // Determine final file path: if directory, try index.html
-      let filePath = joined;
-      const trailingSlash = reqPath.endsWith("/");
-
-      // Check if it's a directory by trying index.html
-      const indexPath = filePath.endsWith("/") ? filePath + "index.html" : filePath + "/index.html";
-
-      // Try as-is first, then as directory index
-      let fileToServe = filePath;
-      let isDir = false;
-
-      // If path has no extension or trailing slash, it might be a directory
-      if (trailingSlash || extname(filePath) === "") {
-        isDir = true;
-        fileToServe = filePath.endsWith("/") ? filePath + "index.html" : filePath + "/index.html";
-      }
-
-      const bunFile = Bun.file(fileToServe);
-      let exists = await bunFile.exists();
-
-      if (!exists && !isDir) {
-        // Try as directory index (e.g. /sub → /sub/index.html)
-        fileToServe = indexPath;
-        const bunFileIdx = Bun.file(fileToServe);
-        exists = await bunFileIdx.exists();
-        if (!exists) {
-          return new Response(NOT_FOUND_HTML, {
-            status: 404,
-            headers: { "Content-Type": "text/html; charset=utf-8" },
-          });
-        }
-      } else if (!exists) {
-        return new Response(NOT_FOUND_HTML, {
-          status: 404,
-          headers: { "Content-Type": "text/html; charset=utf-8" },
-        });
-      }
-
-      const contentType = mimeFor(fileToServe);
-      const finalFile = Bun.file(fileToServe);
-      const size = finalFile.size;
-
-      // Large files (>= 1MB): stream; small files: read fully
-      const ONE_MB = 1024 * 1024;
-      if (size >= ONE_MB) {
-        return new Response(finalFile.stream(), {
-          status: 200,
-          headers: { "Content-Type": contentType },
-        });
-      }
-
-      const buf = await readFile(fileToServe);
-      return new Response(buf, {
-        status: 200,
-        headers: { "Content-Type": contentType },
-      });
-    },
+    fetch: app.fetch,
   });
 
   const actualPort = server.port;
@@ -182,14 +179,12 @@ export async function startServer(args: StartServerArgs): Promise<ServerHandle>
   return {
     port: actualPort,
     url: serverUrl,
+    app,
     stop: async () => {
       await server.stop();
     },
     onRequest: (handler: () => void) => {
       requestHandlers.push(handler);
     },
-    addHandler: (handler: (req: Request) => Promise<Response | undefined>) => {
-      preHandlers.push(handler);
-    },
   };
 }

package/src/server/lifecycle.ts

@@ -8,8 +8,8 @@ import { dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { startServer, type ServerHandle } from "./http.ts";
 import { acquireLock } from "../storage/lock.ts";
-import { createApiHandler } from "./api.ts";
-import { createFaviconHandler } from "./favicon.ts";
+import { createApiApp } from "./api.ts";
+import { createFaviconApp } from "./favicon.ts";
 import { ensureThemeCss } from "../storage/assets.ts";
 import { defaultTheme, type ThemeTokens } from "../render/theme.ts";
 
@@ -279,11 +279,11 @@ export async function runServerForeground(cfg: LifecycleConfig): Promise<Running
     // Materialize theme.css before serving — self-heals on plugin upgrade
     await ensureThemeCss(stateDir, theme);
 
-    // Wire API handler before static file fallback
-    handle.addHandler(createApiHandler({ stateDir }));
+    // Mount API routes; unmatched paths fall through to the static handler
+    handle.app.route("/", createApiApp({ stateDir }));
     // /favicon.ico shim — browsers auto-request this even when the page
     // declares an SVG favicon. Serve the SVG bytes inline so we don't 404.
-    handle.addHandler(createFaviconHandler());
+    handle.app.route("/", createFaviconApp());
 
     const startedAt = new Date().toISOString();
 
@@ -452,11 +452,13 @@ export async function ensureServerRunning(cfg: LifecycleConfig): Promise<Running
   while (Date.now() < deadline) {
     const waitMs = POLL_SCHEDULE[scheduleIdx] ?? 1000;
     scheduleIdx = Math.min(scheduleIdx + 1, POLL_SCHEDULE.length - 1);
+    // eslint-disable-next-line no-await-in-loop -- poll-with-backoff requires sequential sleeps
     await sleep(waitMs);
 
     const pidContent = readPidFile(pidFilePath);
     if (pidContent !== null && isAlive(pidContent.pid)) {
       const probeUrl = `http://${pidContent.hostname}:${pidContent.port}/`;
+      // eslint-disable-next-line no-await-in-loop -- probe runs per-iteration after sleep; cannot parallelize
       const alive = await httpProbe(probeUrl);
       if (alive) {
         return {

package/src/storage/assets.ts

@@ -1,14 +1,9 @@
 // Materializes /theme.css in the state directory, atomically and idempotently.
 
 import { createHash } from "node:crypto";
-import { join } from "node:path";
-import {
-  frameworkRulesCss,
-  themeTokensCss,
-  defaultTheme,
-  type ThemeTokens,
-} from "../render/theme.ts";
+import { defaultTheme, type ThemeTokens } from "../render/theme.ts";
 import { atomicWrite } from "./write.ts";
+import { buildThemeCss, themeCssPath } from "./theme-write.ts";
 import { readFile } from "node:fs/promises";
 
 /** Per-theme CSS cache: built CSS string keyed by theme content hash. */
@@ -19,19 +14,22 @@ function themeKey(theme: ThemeTokens): string {
   return createHash("sha256").update(JSON.stringify(theme)).digest("hex");
 }
 
-/** Build the full theme.css string for a given theme (tokens + framework rules). */
+/** Build the full theme.css string for a given theme (tokens + framework rules).
+ *  Delegates to buildThemeCss so cesium-theme-apply and ensureThemeCss agree on
+ *  byte-exact output. Caches by theme identity to avoid re-string-concat on the
+ *  hot publish path. */
 function buildCss(theme: ThemeTokens): string {
   const key = themeKey(theme);
   const cached = cssCache.get(key);
   if (cached !== undefined) return cached;
-  const css = themeTokensCss(theme) + "\n" + frameworkRulesCss();
+  const css = buildThemeCss(theme);
   cssCache.set(key, css);
   return css;
 }
 
 /** Returns the absolute path to theme.css in stateDir. */
 export function themeCssAssetPath(stateDir: string): string {
-  return join(stateDir, "theme.css");
+  return themeCssPath(stateDir);
 }
 
 /**