@cfbender/cesium 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # 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
+before/after code diff with curved SVG bezier connectors between the two
+columns. JetBrains diff-viewer aesthetic. Plus tooling improvements for
+hot-reload visual iteration during plugin development.
+
+- **feat:** New `diff` block type. Two input arms (XOR):
+  - `patch`: literal unified diff string (e.g. from `git diff` output)
+  - `before`/`after`: paired text strings; server runs Myers O(ND) line
+    diff to compute the change set
+- **feat:** Per-line shiki syntax highlighting is preserved through the
+  diff. The renderer recomposes before-side and after-side text, runs each
+  through `highlightCode`, then zips the styled line spans back into the
+  diff line list — so multi-line constructs (template strings, block
+  comments) tokenize correctly.
+- **feat:** Visual rendering:
+  - Three-column grid (1fr | 60px | 1fr) with line numbers per side
+  - Subtle red/green line-tint backgrounds on remove/add lines
+  - 60px-wide SVG connector column draws semi-transparent cubic-bezier
+    ribbons connecting each remove region on the left to the corresponding
+    add region on the right; pure adds collapse to a teardrop pointing
+    into the left, pure removes mirror
+  - Optional file-header strip with filename + `+N -M` stats
+  - Optional caption strip below
+  - 720px breakpoint collapses to single-column with connector hidden
+- **feat:** Theme tokens `--diff-add`, `--diff-remove`, `--diff-change`
+  added to all seven palette presets so colors fit each preset's character
+  (claret rose, warm clay, cool blue, etc.).
+- **fix:** Diff connector SVG now matches the `padding: 8px 0` of the
+  side columns so the bezier paths line up exactly with their target
+  regions instead of sitting 8px high.
+- **chore:** Project-local opencode config tracked: `.opencode/opencode.json`,
+  `.opencode/plugins/cesium.ts` (dev-loop shim that loads the working
+  tree's source instead of the published npm package), and
+  `.opencode/skills/cesium-preview/SKILL.md` (hot-reload visual iteration
+  workflow that bypasses the stale plugin host by importing render code
+  directly via bun and writing to /tmp).
+- **chore:** `scripts/dogfood-diff.ts` reference preview script for the
+  diff block. Useful template for previewing other block work.
+- **chore:** Apply oxfmt to 30 files that drifted out of format compliance
+  in v0.5.1 (no CI lint gate caught it). Pure cosmetic — line-wrapping,
+  italic style normalization, key ordering. No behavior changes.
+
 ## v0.5.1 — 2026-05-12
 
 Server-side syntax highlighting for `code` blocks via shiki, custom claret
@@ -10,11 +104,11 @@ longer kill the plugin host process.
 - **fix (critical):** Lazy-started cesium server now runs as a detached
   subprocess. Previously `ensureRunning` (called from publish/ask plugin
   paths) ran `Bun.serve()` in-process and wrote `pid: process.pid` to the PID
-  file — meaning that PID was the *plugin host* (e.g. opencode). Any
+  file — meaning that PID was the _plugin host_ (e.g. opencode). Any
   invocation of `cesium stop` (CLI, tool, or test) would signal the host
   process and kill it. Now lazy-start spawns `bun run cli serve` as a
   detached child; the PID file points at that child. Foreground `cesium
-  serve` still runs in-process (correct for its semantics).
+serve` still runs in-process (correct for its semantics).
 - **api:** Split `ensureRunning` into `runServerForeground` (in-process, for
   the foreground CLI) and `ensureServerRunning` (detached subprocess, for
   plugins). `ensureRunning` is kept as a backward-compat alias for
@@ -82,7 +176,7 @@ tokens, more on heavily structured artifacts.
   surfaced as a small badge on index cards.
 - **feat:** Framework CSS extended with rules for every block-renderer
   pattern: `dl.kv` (2-column grid), `.pill-row`, `.check-list`, `<hr
-  data-label>`, `figure.code`, timeline-item internals, `.lede`, plus
+data-label>`, `figure.code`, timeline-item internals, `.lede`, plus
   `.diagram svg text { fill: currentColor }` so SVGs inherit theme color.
 - **feat:** `escapeHtml` and `escapeAttr` throw a clear error on non-string
   input instead of crashing inside `.replace()`.

package/README.md

@@ -382,15 +382,15 @@ state directory, hostname, and theme settings flow through.
 
 Optional `~/.config/opencode/cesium.json`:
 
-| Key             | Type   | Default                 | Description                                                                              |
-| --------------- | ------ | ----------------------- | ---------------------------------------------------------------------------------------- |
-| `stateDir`      | string | `~/.local/state/cesium` | Where artifacts and indexes live                                                         |
-| `port`          | number | `3030`                  | First port to try for the local HTTP server                                              |
-| `portMax`       | number | `3050`                  | Upper bound when scanning for free ports                                                 |
-| `hostname`      | string | `127.0.0.1`             | Bind address. Use `0.0.0.0` to expose on the LAN                                         |
+| Key             | Type   | Default                 | Description                                                                                 |
+| --------------- | ------ | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `stateDir`      | string | `~/.local/state/cesium` | Where artifacts and indexes live                                                            |
+| `port`          | number | `3030`                  | First port to try for the local HTTP server                                                 |
+| `portMax`       | number | `3050`                  | Upper bound when scanning for free ports                                                    |
+| `hostname`      | string | `127.0.0.1`             | Bind address. Use `0.0.0.0` to expose on the LAN                                            |
 | `idleTimeoutMs` | number | `1800000`               | Plugin server idle-shutdown threshold (30 min). Does not apply to foreground `cesium serve` |
-| `themePreset`   | string | `"claret-dark"`         | Named color palette (`claret-dark`/`claret-light`/`claret`/`warm`/`cool`/`mono`/`paper`) |
-| `theme`         | object | (claret-dark palette)   | Per-token color overrides (stacked on preset)                                            |
+| `themePreset`   | string | `"claret-dark"`         | Named color palette (`claret-dark`/`claret-light`/`claret`/`warm`/`cool`/`mono`/`paper`)    |
+| `theme`         | object | (claret-dark palette)   | Per-token color overrides (stacked on preset)                                               |
 
 Environment overrides: `CESIUM_PORT`, `CESIUM_STATE_DIR`, `CESIUM_HOSTNAME`, `CESIUM_THEME_PRESET`.
 

package/package.json

@@ -1,29 +1,27 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
-  "license": "MIT",
-  "author": "Cody Bender",
+  "keywords": [
+    "agent",
+    "artifact",
+    "claret",
+    "cli",
+    "html",
+    "opencode",
+    "plugin"
+  ],
   "homepage": "https://github.com/cfbender/cesium#readme",
   "bugs": "https://github.com/cfbender/cesium/issues",
+  "license": "MIT",
+  "author": "Cody Bender",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cfbender/cesium.git"
   },
-  "keywords": [
-    "opencode",
-    "agent",
-    "html",
-    "artifact",
-    "plugin",
-    "cli",
-    "claret"
-  ],
   "bin": {
     "cesium": "./src/cli/index.ts"
   },
-  "type": "module",
-  "main": "src/index.ts",
   "files": [
     "src",
     "assets/styleguide.html",
@@ -31,12 +29,11 @@
     "ARCHITECTURE.md",
     "CHANGELOG.md"
   ],
+  "type": "module",
+  "main": "src/index.ts",
   "publishConfig": {
     "access": "public"
   },
-  "engines": {
-    "bun": ">=1.0.0"
-  },
   "scripts": {
     "test": "bun test",
     "typecheck": "tsc --noEmit",
@@ -49,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"
@@ -58,5 +57,8 @@
     "oxfmt": "^0.48.0",
     "oxlint": "^1.63.0",
     "typescript": "^5.4.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
   }
 }

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);
+  },
+});