@cfbender/cesium 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## v0.6.0 — 2026-05-13
+
+Internal cleanup release. Two hand-rolled server and CLI layers swapped
+for small, well-fit libraries (Hono and Citty) that delete the regex and
+dispatcher boilerplate without changing user-visible behavior. No new
+features and no protocol changes — artifacts written by older versions
+continue rendering unchanged.
+
+- **refactor:** Migrate the cesium HTTP server from a hand-rolled
+  `Bun.serve` fetch handler with a custom `preHandlers` middleware chain
+  to a Hono app fronted by Bun.serve. Routes for `/api/sessions/*` and
+  `/favicon.ico` now use Hono's typed `:param` syntax instead of regex
+  match + manual narrowing. The static file handler is preserved verbatim
+  and mounted as `app.notFound` so all 11 existing static-serve tests
+  pass unchanged. `ServerHandle.app: Hono` replaces `addHandler` for
+  callers that need to register additional routes.
+- **refactor:** Migrate the `cesium` CLI from `node:util parseArgs` +
+  a hand-rolled subcommand dispatcher to Citty. Each command file now
+  exports a typed `runX(args, ctx)` inner function (kept directly
+  testable with injected `{stdout, stderr, loadConfig}`) plus an outer
+  `xxxCmd = defineCommand(...)` that Citty consumes. Subcommands load
+  lazily via dynamic `import()` so cold-start cost is paid only for the
+  command the user actually invoked. `cesium theme show|apply` is now
+  expressed as native Citty sub-subcommands rather than the previous
+  manual routing.
+- **fix:** `cesium restart` no longer fails on serve-only flags. The
+  previous implementation passed argv through to both `stopCommand` and
+  `serveCommand` under `strict: true`, so `cesium restart --port 4000`
+  would have errored. Restart now defines its own arg schema covering
+  both stop and serve options.
+- **chore:** Clean up all 25 oxlint warnings:
+  - Restructure `src/server/api.ts` regex matching to remove four
+    `!` non-null assertions.
+  - Replace `match![1]!` patterns in tests with a local `unwrap(value,
+    name)` helper for proper type narrowing.
+  - Replace `handle!.url` in tests with an explicit null check.
+  - Add targeted `eslint-disable-next-line no-await-in-loop` comments
+    (with `--` reason annotations matching the existing repo convention)
+    in places where sequential execution is required: middleware chain,
+    poll-with-backoff retry, short-circuit search.
+- **chore:** Add `hono@4.12.18` and `citty@0.2.2` to dependencies.
+  Removes a meaningful amount of hand-rolled routing / arg-parsing code
+  for ~50KB total install footprint.
+- **chore:** `cesium --version` output format changes from
+  `cesium 0.6.0` to plain `0.6.0` (Citty's default). The `cesium version`
+  subcommand is removed — use `cesium --version` or `cesium -v`. Auto-
+  generated help text for each command also follows Citty's formatting
+  (uppercase USAGE/OPTIONS, color codes, default annotations) rather
+  than the previous hand-aligned `Usage: cesium ls` strings.
+
 ## v0.5.2 — 2026-05-12
 
 A 16th block type — `diff` — that renders a beautiful side-by-side

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "keywords": [
     "agent",
@@ -46,6 +46,8 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "latest",
+    "citty": "^0.2.2",
+    "hono": "^4.12.18",
     "nanoid": "^5.0.0",
     "parse5": "^7.1.0",
     "shiki": "^4.0.2"

package/src/cli/commands/ls.ts

@@ -1,12 +1,18 @@
 // cesium ls — list artifacts for current project (or all).
 
-import { parseArgs } from "node:util";
+import { defineCommand } from "citty";
 import { join } from "node:path";
 import { execSync } from "node:child_process";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
 import { loadIndex, type IndexEntry } from "../../storage/index-cache.ts";
 import { deriveProjectIdentity } from "../../storage/paths.ts";
 
+export interface LsArgs {
+  all: boolean;
+  json: boolean;
+  limit: number;
+}
+
 export interface LsContext {
   stdout: { write: (s: string) => void };
   stderr: { write: (s: string) => void };
@@ -58,69 +64,27 @@ function getGitRemote(cwd: string): string | null {
   }
 }
 
-export async function lsCommand(argv: string[], ctx?: Partial<LsContext>): Promise<number> {
-  const resolved: LsContext = { ...defaultCtx(), ...ctx };
-
-  let values: {
-    all: boolean;
-    json: boolean;
-    limit: string | undefined;
-    help: boolean;
-  };
-
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: {
-        all: { type: "boolean", short: "a", default: false },
-        json: { type: "boolean", default: false },
-        limit: { type: "string", short: "n" },
-        help: { type: "boolean", short: "h", default: false },
-      },
-      allowPositionals: false,
-      strict: true,
-    });
-    values = parsed.values as typeof values;
-  } catch (err) {
-    const e = err as Error;
-    resolved.stderr.write(`cesium ls: ${e.message}\n`);
-    resolved.stderr.write(`Usage: cesium ls [--all] [--json] [--limit N]\n`);
-    return 1;
-  }
-
-  if (values.help) {
-    resolved.stdout.write(
-      [
-        "Usage: cesium ls [options]",
-        "",
-        "Options:",
-        "  --all, -a      Show artifacts for all projects (default: current project only)",
-        "  --json         Output as JSON array",
-        "  --limit, -n N  Show at most N most recent artifacts (default: 50)",
-        "  --help, -h     Show this help message",
-        "",
-      ].join("\n"),
-    );
-    return 0;
-  }
+/**
+ * Inner command logic. Tests call this directly with typed args + injected
+ * context for fast feedback; the Citty wrapper handles argv parsing.
+ */
+export async function runLs(args: LsArgs, ctxOverride?: Partial<LsContext>): Promise<number> {
+  const ctx: LsContext = { ...defaultCtx(), ...ctxOverride };
 
-  const limitRaw = values.limit !== undefined ? parseInt(values.limit, 10) : 50;
-  if (isNaN(limitRaw) || limitRaw < 1) {
-    resolved.stderr.write(`cesium ls: --limit must be a positive integer\n`);
+  if (args.limit < 1) {
+    ctx.stderr.write(`cesium ls: --limit must be a positive integer\n`);
     return 1;
   }
-  const limit = limitRaw;
 
-  // Load config
-  const cfg = (resolved.loadConfig ?? loadConfig)();
+  const cfg = (ctx.loadConfig ?? loadConfig)();
 
   // Determine which index.json to read
   let jsonPath: string;
-  if (values.all) {
+  if (args.all) {
     jsonPath = join(cfg.stateDir, "index.json");
   } else {
-    const gitRemote = getGitRemote(resolved.cwd);
-    const identity = deriveProjectIdentity({ cwd: resolved.cwd, gitRemote });
+    const gitRemote = getGitRemote(ctx.cwd);
+    const identity = deriveProjectIdentity({ cwd: ctx.cwd, gitRemote });
     jsonPath = join(cfg.stateDir, "projects", identity.slug, "index.json");
   }
 
@@ -129,21 +93,19 @@ export async function lsCommand(argv: string[], ctx?: Partial<LsContext>): Promi
     entries = await loadIndex(jsonPath);
   } catch (err) {
     const e = err as Error;
-    resolved.stderr.write(`cesium ls: failed to read index: ${e.message}\n`);
+    ctx.stderr.write(`cesium ls: failed to read index: ${e.message}\n`);
     return 1;
   }
 
-  // Already sorted newest-first by loadIndex / appendEntry; apply limit
-  const limited = entries.slice(0, limit);
+  const limited = entries.slice(0, args.limit);
 
-  if (values.json) {
-    resolved.stdout.write(JSON.stringify(limited, null, 2) + "\n");
+  if (args.json) {
+    ctx.stdout.write(JSON.stringify(limited, null, 2) + "\n");
     return 0;
   }
 
-  // Table output
   if (limited.length === 0) {
-    resolved.stdout.write("No artifacts found.\n");
+    ctx.stdout.write("No artifacts found.\n");
     return 0;
   }
 
@@ -165,8 +127,8 @@ export async function lsCommand(argv: string[], ctx?: Partial<LsContext>): Promi
 
   const sep = "─".repeat(header.length);
 
-  resolved.stdout.write(header + "\n");
-  resolved.stdout.write(sep + "\n");
+  ctx.stdout.write(header + "\n");
+  ctx.stdout.write(sep + "\n");
 
   for (const e of limited) {
     const row =
@@ -179,8 +141,43 @@ export async function lsCommand(argv: string[], ctx?: Partial<LsContext>): Promi
       fmtDate(e.createdAt).padEnd(COL_DATE) +
       "  " +
       superCol(e);
-    resolved.stdout.write(row + "\n");
+    ctx.stdout.write(row + "\n");
   }
 
   return 0;
 }
+
+export const lsCmd = defineCommand({
+  meta: {
+    name: "ls",
+    description: "List artifacts in the current project (or all with --all).",
+  },
+  args: {
+    all: {
+      type: "boolean",
+      alias: "a",
+      default: false,
+      description: "Show artifacts for all projects (default: current project only)",
+    },
+    json: {
+      type: "boolean",
+      default: false,
+      description: "Output as JSON array",
+    },
+    limit: {
+      type: "string",
+      alias: "n",
+      default: "50",
+      description: "Show at most N most recent artifacts",
+    },
+  },
+  async run({ args }) {
+    const limit = parseInt(args.limit, 10);
+    if (isNaN(limit) || limit < 1) {
+      process.stderr.write(`cesium ls: --limit must be a positive integer\n`);
+      process.exit(1);
+    }
+    const code = await runLs({ all: args.all, json: args.json, limit });
+    if (code !== 0) process.exit(code);
+  },
+});

package/src/cli/commands/open.ts

@@ -1,6 +1,6 @@
 // cesium open — find an artifact by id prefix and open it in the browser.
 
-import { parseArgs } from "node:util";
+import { defineCommand } from "citty";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { platform } from "node:os";
@@ -15,6 +15,11 @@ import {
 } from "../../server/lifecycle.ts";
 import { resolveDisplayHost } from "../../tools/publish.ts";
 
+export interface OpenArgs {
+  idPrefix: string;
+  print: boolean;
+}
+
 export interface OpenContext {
   stdout: { write: (s: string) => void };
   stderr: { write: (s: string) => void };
@@ -90,59 +95,16 @@ async function tryGetHttpUrl(
   return null;
 }
 
-export async function openCommand(argv: string[], ctx?: Partial<OpenContext>): Promise<number> {
-  const resolved: OpenContext = { ...defaultCtx(), ...ctx };
-
-  let values: { print: boolean; help: boolean };
-  let positionals: string[];
-
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: {
-        print: { type: "boolean", default: false },
-        help: { type: "boolean", short: "h", default: false },
-      },
-      allowPositionals: true,
-      strict: true,
-    });
-    values = parsed.values as typeof values;
-    positionals = parsed.positionals;
-  } catch (err) {
-    const e = err as Error;
-    resolved.stderr.write(`cesium open: ${e.message}\n`);
-    resolved.stderr.write(`Usage: cesium open <id-prefix> [--print]\n`);
-    return 1;
-  }
-
-  if (values.help) {
-    resolved.stdout.write(
-      [
-        "Usage: cesium open <id-prefix> [options]",
-        "",
-        "Options:",
-        "  --print     Print the URL instead of opening in the browser",
-        "  --help, -h  Show this help message",
-        "",
-        "Notes:",
-        "  Browser launch is supported on macOS (open) and Linux (xdg-open).",
-        "  On Windows, use --print to get the URL.",
-        "",
-      ].join("\n"),
-    );
-    return 0;
-  }
+export async function runOpen(args: OpenArgs, ctxOverride?: Partial<OpenContext>): Promise<number> {
+  const ctx: OpenContext = { ...defaultCtx(), ...ctxOverride };
 
-  const idPrefix = positionals[0];
-  if (idPrefix === undefined || idPrefix.length === 0) {
-    resolved.stderr.write(`cesium open: missing required argument <id-prefix>\n`);
-    resolved.stderr.write(`Usage: cesium open <id-prefix> [--print]\n`);
+  if (args.idPrefix.length === 0) {
+    ctx.stderr.write(`cesium open: missing required argument <id-prefix>\n`);
     return 1;
   }
 
-  const prefixLower = idPrefix.toLowerCase();
-
-  const cfg = (resolved.loadConfig ?? loadConfig)();
+  const prefixLower = args.idPrefix.toLowerCase();
+  const cfg = (ctx.loadConfig ?? loadConfig)();
 
   // Search global index for matches
   const globalJsonPath = join(cfg.stateDir, "index.json");
@@ -151,23 +113,23 @@ export async function openCommand(argv: string[], ctx?: Partial<OpenContext>): P
     allEntries = await loadIndex(globalJsonPath);
   } catch (err) {
     const e = err as Error;
-    resolved.stderr.write(`cesium open: failed to read index: ${e.message}\n`);
+    ctx.stderr.write(`cesium open: failed to read index: ${e.message}\n`);
     return 1;
   }
 
   const matches = allEntries.filter((e) => e.id.toLowerCase().startsWith(prefixLower));
 
   if (matches.length === 0) {
-    resolved.stderr.write(`cesium open: no artifact found with id prefix "${idPrefix}"\n`);
+    ctx.stderr.write(`cesium open: no artifact found with id prefix "${args.idPrefix}"\n`);
     return 1;
   }
 
   if (matches.length > 1) {
-    resolved.stderr.write(
-      `cesium open: ambiguous prefix "${idPrefix}" — ${matches.length} matches:\n`,
+    ctx.stderr.write(
+      `cesium open: ambiguous prefix "${args.idPrefix}" — ${matches.length} matches:\n`,
     );
     for (const m of matches) {
-      resolved.stderr.write(`  ${m.id}  ${m.title}  (${m.kind})\n`);
+      ctx.stderr.write(`  ${m.id}  ${m.title}  (${m.kind})\n`);
     }
     return 2;
   }
@@ -175,7 +137,7 @@ export async function openCommand(argv: string[], ctx?: Partial<OpenContext>): P
   const entry = matches[0];
   if (entry === undefined) {
     // Unreachable: guarded by matches.length === 1, but satisfies the type checker
-    resolved.stderr.write(`cesium open: internal error — no match\n`);
+    ctx.stderr.write(`cesium open: internal error — no match\n`);
     return 1;
   }
   const paths = pathsFor({
@@ -185,24 +147,47 @@ export async function openCommand(argv: string[], ctx?: Partial<OpenContext>): P
   });
 
   // Resolve URL
-  const runEnsureRunning = resolved.ensureRunning ?? ensureRunning;
+  const runEnsureRunning = ctx.ensureRunning ?? ensureRunning;
   const httpUrl = await tryGetHttpUrl(cfg, paths.serverPath, runEnsureRunning);
   const url = httpUrl ?? paths.fileUrl;
 
-  if (values.print) {
-    resolved.stdout.write(url + "\n");
+  if (args.print) {
+    ctx.stdout.write(url + "\n");
     return 0;
   }
 
-  const open = resolved.opener ?? defaultOpener;
+  const open = ctx.opener ?? defaultOpener;
   try {
     await open(url);
   } catch (err) {
     const e = err as Error;
-    resolved.stderr.write(`cesium open: ${e.message}\n`);
-    resolved.stdout.write(`URL: ${url}\n`);
+    ctx.stderr.write(`cesium open: ${e.message}\n`);
+    ctx.stdout.write(`URL: ${url}\n`);
     return 1;
   }
 
   return 0;
 }
+
+export const openCmd = defineCommand({
+  meta: {
+    name: "open",
+    description: "Open an artifact by id prefix in the browser.",
+  },
+  args: {
+    idPrefix: {
+      type: "positional",
+      description: "Artifact id prefix (any unique substring of the id)",
+      required: true,
+    },
+    print: {
+      type: "boolean",
+      default: false,
+      description: "Print the URL instead of opening in the browser",
+    },
+  },
+  async run({ args }) {
+    const code = await runOpen({ idPrefix: args.idPrefix, print: args.print });
+    if (code !== 0) process.exit(code);
+  },
+});

package/src/cli/commands/prune.ts

@@ -1,6 +1,6 @@
 // cesium prune — delete artifacts older than a given duration.
 
-import { parseArgs } from "node:util";
+import { defineCommand } from "citty";
 import { join } from "node:path";
 import { readdir, unlink as fsUnlink, stat } from "node:fs/promises";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
@@ -15,6 +15,11 @@ import { themeFromPreset, mergeTheme } from "../../render/theme.ts";
 import { readEmbeddedMetadata } from "../../storage/write.ts";
 import { readFile } from "node:fs/promises";
 
+export interface PruneArgs {
+  olderThan: string;
+  yes: boolean;
+}
+
 export interface PruneContext {
   stdout: { write: (s: string) => void };
   stderr: { write: (s: string) => void };
@@ -164,75 +169,28 @@ function formatTable(candidates: ArtifactCandidate[]): string {
   return [header, sep, ...rows].join("\n");
 }
 
-export async function pruneCommand(argv: string[], ctx?: Partial<PruneContext>): Promise<number> {
-  const resolved: PruneContext = { ...defaultCtx(), ...ctx };
+export async function runPrune(
+  args: PruneArgs,
+  ctxOverride?: Partial<PruneContext>,
+): Promise<number> {
+  const ctx: PruneContext = { ...defaultCtx(), ...ctxOverride };
 
-  let values: {
-    "older-than": string | undefined;
-    "dry-run": boolean;
-    yes: boolean;
-    help: boolean;
-  };
-
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: {
-        "older-than": { type: "string" },
-        "dry-run": { type: "boolean", default: false },
-        yes: { type: "boolean", short: "y", 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;
-    resolved.stderr.write(`cesium prune: ${e.message}\n`);
-    resolved.stderr.write(`Usage: cesium prune --older-than <duration> [--yes]\n`);
+  if (args.olderThan.length === 0) {
+    ctx.stderr.write(`cesium prune: --older-than is required\n`);
     return 1;
   }
 
-  if (values.help) {
-    resolved.stdout.write(
-      [
-        "Usage: cesium prune --older-than <duration> [options]",
-        "",
-        "Options:",
-        "  --older-than <dur>  Delete artifacts older than this duration (e.g. 90d, 2w, 12h, 30m)",
-        "  --yes, -y           Actually delete (default is dry-run)",
-        "  --dry-run           Explicit dry-run (same as omitting --yes)",
-        "  --help, -h          Show this help message",
-        "",
-        "Duration format: <N><unit> where unit is d (days), w (weeks), h (hours), m (minutes).",
-        "",
-        "Note: prune deletes by age only. It does not check revision chains.",
-        "      Deleting an early version in a supersedes chain does not affect the newer version.",
-        "",
-      ].join("\n"),
-    );
-    return 0;
-  }
-
-  const durationStr = values["older-than"];
-  if (durationStr === undefined || durationStr.length === 0) {
-    resolved.stderr.write(`cesium prune: --older-than is required\n`);
-    resolved.stderr.write(`Usage: cesium prune --older-than <duration> [--yes]\n`);
-    return 1;
-  }
-
-  const durationMs = parseDuration(durationStr);
+  const durationMs = parseDuration(args.olderThan);
   if (durationMs === null) {
-    resolved.stderr.write(
-      `cesium prune: invalid duration "${durationStr}". Use format like 90d, 2w, 12h, 30m\n`,
+    ctx.stderr.write(
+      `cesium prune: invalid duration "${args.olderThan}". Use format like 90d, 2w, 12h, 30m\n`,
     );
     return 1;
   }
 
-  const isDryRun = !values.yes;
-  const cfg = (resolved.loadConfig ?? loadConfig)();
-  const now = (resolved.now ?? (() => new Date()))();
+  const isDryRun = !args.yes;
+  const cfg = (ctx.loadConfig ?? loadConfig)();
+  const now = (ctx.now ?? (() => new Date()))();
   const cutoff = now.getTime() - durationMs;
 
   // Collect all artifacts
@@ -241,7 +199,7 @@ export async function pruneCommand(argv: string[], ctx?: Partial<PruneContext>):
     allArtifacts = await collectAllArtifacts(cfg.stateDir);
   } catch (err) {
     const e = err as Error;
-    resolved.stderr.write(`cesium prune: failed to scan artifacts: ${e.message}\n`);
+    ctx.stderr.write(`cesium prune: failed to scan artifacts: ${e.message}\n`);
     return 1;
   }
 
@@ -252,16 +210,16 @@ export async function pruneCommand(argv: string[], ctx?: Partial<PruneContext>):
   });
 
   if (toDelete.length === 0) {
-    resolved.stdout.write(`No artifacts older than ${durationStr} found.\n`);
+    ctx.stdout.write(`No artifacts older than ${args.olderThan} found.\n`);
     return 0;
   }
 
   if (isDryRun) {
-    resolved.stdout.write(
-      `Would delete ${toDelete.length} artifact${toDelete.length !== 1 ? "s" : ""} older than ${durationStr}:\n`,
+    ctx.stdout.write(
+      `Would delete ${toDelete.length} artifact${toDelete.length !== 1 ? "s" : ""} older than ${args.olderThan}:\n`,
     );
-    resolved.stdout.write(formatTable(toDelete) + "\n\n");
-    resolved.stdout.write(`Re-run with --yes to delete.\n`);
+    ctx.stdout.write(formatTable(toDelete) + "\n\n");
+    ctx.stdout.write(`Re-run with --yes to delete.\n`);
     return 0;
   }
 
@@ -274,9 +232,7 @@ export async function pruneCommand(argv: string[], ctx?: Partial<PruneContext>):
       } catch (err) {
         const e = err as NodeJS.ErrnoException;
         if (e.code !== "ENOENT") {
-          resolved.stderr.write(
-            `cesium prune: failed to delete ${candidate.filePath}: ${e.message}\n`,
-          );
+          ctx.stderr.write(`cesium prune: failed to delete ${candidate.filePath}: ${e.message}\n`);
         }
         return false;
       }
@@ -341,8 +297,40 @@ export async function pruneCommand(argv: string[], ctx?: Partial<PruneContext>):
     // best-effort
   }
 
-  resolved.stdout.write(
+  ctx.stdout.write(
     `Deleted ${deletedCount} artifact${deletedCount !== 1 ? "s" : ""}. Indexes regenerated.\n`,
   );
   return 0;
 }
+
+export const pruneCmd = defineCommand({
+  meta: {
+    name: "prune",
+    description: "Delete artifacts older than a given duration.",
+  },
+  args: {
+    "older-than": {
+      type: "string",
+      required: true,
+      description: "Delete artifacts older than this duration (e.g. 90d, 2w, 12h, 30m)",
+    },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      default: false,
+      description: "Actually delete (default is dry-run)",
+    },
+    "dry-run": {
+      type: "boolean",
+      default: false,
+      description: "Explicit dry-run (same as omitting --yes)",
+    },
+  },
+  async run({ args }) {
+    const code = await runPrune({
+      olderThan: args["older-than"],
+      yes: args.yes,
+    });
+    if (code !== 0) process.exit(code);
+  },
+});