@cfbender/cesium 0.5.2 → 0.6.0

package/src/cli/commands/theme.ts

@@ -1,6 +1,6 @@
 // cesium theme — show or apply the configured theme.
 
-import { parseArgs } from "node:util";
+import { defineCommand } from "citty";
 import { readFile } from "node:fs/promises";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
 import {
@@ -9,9 +9,8 @@ import {
   type ThemeTokens,
   type ThemePalette,
 } from "../../render/theme.ts";
-import { writeThemeCss, themeCssPath } from "../../storage/theme-write.ts";
+import { writeThemeCss, themeCssPath, buildThemeCss } from "../../storage/theme-write.ts";
 import { writeFaviconSvg } from "../../storage/favicon-write.ts";
-import { themeTokensCss } from "../../render/theme.ts";
 import { atomicWrite } from "../../storage/write.ts";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
@@ -75,7 +74,7 @@ function printTokenTable(
 }
 
 async function isWriteNeeded(cssPath: string, theme: ThemeTokens): Promise<boolean> {
-  const expected = themeTokensCss(theme) + "\n";
+  const expected = buildThemeCss(theme);
   try {
     const existing = await readFile(cssPath, "utf8");
     return existing !== expected;
@@ -205,61 +204,12 @@ async function retrofitAll(
 
 // ─── Command ──────────────────────────────────────────────────────────────────
 
-export async function themeCommand(argv: string[], ctx?: Partial<ThemeContext>): Promise<number> {
-  const resolved: ThemeContext = { ...defaultCtx(), ...ctx };
-
-  const subcommand = argv[0];
-  const rest = argv.slice(1);
-
-  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-    resolved.stdout.write(
-      [
-        "Usage: cesium theme <subcommand> [options]",
-        "",
-        "Subcommands:",
-        "  show                        Print resolved theme tokens",
-        "  apply [--rewrite-artifacts] Write theme.css from current config",
-        "",
-        "Options:",
-        "  --help, -h  Show this help message",
-        "",
-      ].join("\n"),
-    );
-    return subcommand ? 0 : 1;
-  }
-
-  if (subcommand === "show") {
-    return themeShowCommand(rest, resolved);
-  }
-
-  if (subcommand === "apply") {
-    return themeApplyCommand(rest, resolved);
-  }
-
-  resolved.stderr.write(`cesium theme: unknown subcommand: ${subcommand}\n`);
-  return 1;
+export interface ThemeApplyArgs {
+  rewriteArtifacts: boolean;
 }
 
-async function themeShowCommand(argv: string[], ctx: ThemeContext): Promise<number> {
-  let values: { help: boolean };
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: { help: { type: "boolean", short: "h", default: false } },
-      allowPositionals: false,
-      strict: true,
-    });
-    values = parsed.values as typeof values;
-  } catch (err) {
-    const e = err as Error;
-    ctx.stderr.write(`cesium theme show: ${e.message}\n`);
-    return 1;
-  }
-
-  if (values.help) {
-    ctx.stdout.write("Usage: cesium theme show\n\nPrint resolved theme tokens.\n\n");
-    return 0;
-  }
+export async function runThemeShow(ctxOverride?: Partial<ThemeContext>): Promise<number> {
+  const ctx: ThemeContext = { ...defaultCtx(), ...ctxOverride };
 
   const cfg = (ctx.loadConfig ?? loadConfig)();
   const { theme, presetLabel } = resolveTheme(cfg);
@@ -270,47 +220,18 @@ async function themeShowCommand(argv: string[], ctx: ThemeContext): Promise<numb
   return 0;
 }
 
-async function themeApplyCommand(argv: string[], ctx: ThemeContext): Promise<number> {
-  let values: { "rewrite-artifacts": boolean; help: boolean };
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: {
-        "rewrite-artifacts": { type: "boolean", default: false },
-        help: { type: "boolean", short: "h", default: false },
-      },
-      allowPositionals: false,
-      strict: true,
-    });
-    values = parsed.values as typeof values;
-  } catch (err) {
-    const e = err as Error;
-    ctx.stderr.write(`cesium theme apply: ${e.message}\n`);
-    return 1;
-  }
-
-  if (values.help) {
-    ctx.stdout.write(
-      [
-        "Usage: cesium theme apply [--rewrite-artifacts]",
-        "",
-        "Write theme.css from the current config.",
-        "",
-        "Options:",
-        "  --rewrite-artifacts  Retrofit existing artifacts and index pages with the theme link",
-        "  --help, -h           Show this help message",
-        "",
-      ].join("\n"),
-    );
-    return 0;
-  }
+export async function runThemeApply(
+  args: ThemeApplyArgs,
+  ctxOverride?: Partial<ThemeContext>,
+): Promise<number> {
+  const ctx: ThemeContext = { ...defaultCtx(), ...ctxOverride };
 
   const cfg = (ctx.loadConfig ?? loadConfig)();
   const { theme, presetLabel } = resolveTheme(cfg);
   const cssPath = await writeThemeCss(cfg.stateDir, theme);
   await writeFaviconSvg(cfg.stateDir);
 
-  if (values["rewrite-artifacts"]) {
+  if (args.rewriteArtifacts) {
     const { artifacts, indexes } = await retrofitAll(cfg.stateDir, ctx.stdout);
     ctx.stdout.write(
       [
@@ -333,3 +254,44 @@ async function themeApplyCommand(argv: string[], ctx: ThemeContext): Promise<num
 
   return 0;
 }
+
+const themeShowCmd = defineCommand({
+  meta: {
+    name: "show",
+    description: "Print resolved theme tokens.",
+  },
+  args: {},
+  async run() {
+    const code = await runThemeShow();
+    if (code !== 0) process.exit(code);
+  },
+});
+
+const themeApplyCmd = defineCommand({
+  meta: {
+    name: "apply",
+    description: "Write theme.css from the current config.",
+  },
+  args: {
+    "rewrite-artifacts": {
+      type: "boolean",
+      default: false,
+      description: "Retrofit existing artifacts and index pages with the theme link",
+    },
+  },
+  async run({ args }) {
+    const code = await runThemeApply({ rewriteArtifacts: args["rewrite-artifacts"] });
+    if (code !== 0) process.exit(code);
+  },
+});
+
+export const themeCmd = defineCommand({
+  meta: {
+    name: "theme",
+    description: "Show or apply the configured theme.",
+  },
+  subCommands: {
+    show: themeShowCmd,
+    apply: themeApplyCmd,
+  },
+});

package/src/cli/index.ts

@@ -1,78 +1,25 @@
 #!/usr/bin/env bun
 
-import { parseArgs as _parseArgs } from "node:util";
+import { defineCommand, runMain } from "citty";
 import pkg from "../../package.json" with { type: "json" };
-import { lsCommand } from "./commands/ls.ts";
-import { openCommand } from "./commands/open.ts";
-import { serveCommand } from "./commands/serve.ts";
-import { stopCommand } from "./commands/stop.ts";
-import { restartCommand } from "./commands/restart.ts";
-import { pruneCommand } from "./commands/prune.ts";
-import { themeCommand } from "./commands/theme.ts";
-
-const subcommand = process.argv[2];
-const rest = process.argv.slice(3);
 
 export const CESIUM_VERSION: string = pkg.version;
 
-const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
-  ls: lsCommand,
-  open: openCommand,
-  serve: serveCommand,
-  stop: stopCommand,
-  restart: restartCommand,
-  prune: pruneCommand,
-  theme: themeCommand,
-  version: async () => {
-    process.stdout.write(`cesium ${CESIUM_VERSION}\n`);
-    return 0;
+const main = defineCommand({
+  meta: {
+    name: "cesium",
+    version: pkg.version,
+    description: "artifact manager for opencode sessions",
   },
-};
-
-function printHelp(): void {
-  process.stdout.write(
-    [
-      "cesium — artifact manager for opencode sessions",
-      "",
-      "Usage: cesium <command> [options]",
-      "",
-      "Commands:",
-      "  ls       List artifacts in the current project (or all with --all)",
-      "  open     Open an artifact by id prefix in the browser",
-      "  serve    Start the local HTTP server in the foreground",
-      "  stop     Stop the running cesium server",
-      "  restart  Stop and re-start the cesium server",
-      "  prune    Delete artifacts older than a given duration",
-      "  theme    Show or apply the configured theme",
-      "  version  Print the cesium version",
-      "",
-      "Options:",
-      "  --help, -h     Show this help message",
-      "  --version, -v  Print the cesium version",
-      "",
-      "Run 'cesium <command> --help' for command-specific options.",
-      "",
-    ].join("\n"),
-  );
-}
-
-async function main(): Promise<void> {
-  if (subcommand === "--version" || subcommand === "-v") {
-    process.stdout.write(`cesium ${CESIUM_VERSION}\n`);
-    process.exit(0);
-  }
-  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-    printHelp();
-    process.exit(subcommand ? 0 : 1);
-  }
-  const fn = COMMANDS[subcommand];
-  if (!fn) {
-    process.stderr.write(`cesium: unknown command: ${subcommand}\n`);
-    printHelp();
-    process.exit(1);
-  }
-  const code = await fn(rest);
-  process.exit(code);
-}
+  subCommands: {
+    ls: () => import("./commands/ls.ts").then((m) => m.lsCmd),
+    open: () => import("./commands/open.ts").then((m) => m.openCmd),
+    serve: () => import("./commands/serve.ts").then((m) => m.serveCmd),
+    stop: () => import("./commands/stop.ts").then((m) => m.stopCmd),
+    restart: () => import("./commands/restart.ts").then((m) => m.restartCmd),
+    prune: () => import("./commands/prune.ts").then((m) => m.pruneCmd),
+    theme: () => import("./commands/theme.ts").then((m) => m.themeCmd),
+  },
+});
 
-await main();
+await runMain(main);

package/src/render/theme.ts

@@ -318,6 +318,13 @@ h1, h2, h3, h4, h5, h6 {
   border-radius: 12px;
   padding: 18px 22px;
   margin-bottom: 1.5em;
+  /* contain wide children (tables, long URLs, code) inside the card.
+   * min-width:0 lets the card shrink in grid/flex contexts (.cards-grid)
+   * so it actually obeys its track instead of growing to its widest child.
+   * overflow-x:auto then scrolls any content that's STILL too wide
+   * (e.g. a many-column table) rather than bursting the card border. */
+  min-width: 0;
+  overflow-x: auto;
 }
 
 /* tldr */
@@ -329,6 +336,8 @@ h1, h2, h3, h4, h5, h6 {
   margin-bottom: 1.5em;
   font-size: 1.05rem;
   color: var(--ink-soft);
+  min-width: 0;
+  overflow-x: auto;
 }
 
 /* callout */
@@ -340,6 +349,8 @@ h1, h2, h3, h4, h5, h6 {
   background: var(--surface-2);
   color: var(--ink-soft);
   font-size: 0.95rem;
+  min-width: 0;
+  overflow-x: auto;
 }
 .callout.note { border-color: var(--olive); background: color-mix(in srgb, var(--olive) 10%, var(--surface)); }
 .callout.warn { border-color: var(--accent); background: color-mix(in srgb, var(--accent) 10%, var(--surface)); }
@@ -573,6 +584,11 @@ figure.code figcaption {
   padding: 10px 14px;
   text-align: left;
   vertical-align: top;
+  /* let long URLs / identifiers / paths wrap inside the cell instead of
+   * pushing the table beyond its container. Many-column tables that are
+   * still wider than the card fall through to the card's overflow-x. */
+  overflow-wrap: anywhere;
+  word-break: break-word;
 }
 .compare-table th {
   background: var(--surface-2);
@@ -594,6 +610,8 @@ figure.code figcaption {
   padding: 10px 14px;
   text-align: left;
   vertical-align: top;
+  overflow-wrap: anywhere;
+  word-break: break-word;
 }
 .risk-table th {
   background: var(--surface-2);

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;
 }