@cfbender/cesium 0.5.1 → 0.6.0

package/src/cli/commands/stop.ts

@@ -1,10 +1,15 @@
 // cesium stop — kill the running cesium server cross-process via PID file.
 
-import { parseArgs } from "node:util";
+import { defineCommand } from "citty";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
 import { stopServer } from "../../server/stop.ts";
 import type { StopServerArgs } from "../../server/stop.ts";
 
+export interface StopArgs {
+  force: boolean;
+  timeoutMs: number;
+}
+
 export interface StopContext {
   stdout: { write: (s: string) => void };
   stderr: { write: (s: string) => void };
@@ -22,109 +27,71 @@ function defaultCtx(): StopContext {
   };
 }
 
-export interface StopOptions {
-  force: boolean;
-  timeout: number;
-}
-
-/** Parse stop-command argv. Returns null on parse error. */
-export function parseStopArgs(
-  argv: string[],
-  ctx: Pick<StopContext, "stdout" | "stderr">,
-): StopOptions | null | "help" {
-  let values: { force: boolean; timeout: string | undefined; help: boolean };
+export async function runStop(args: StopArgs, ctxOverride?: Partial<StopContext>): Promise<number> {
+  const ctx: StopContext = { ...defaultCtx(), ...ctxOverride };
 
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: {
-        force: { type: "boolean", short: "f", default: false },
-        timeout: { type: "string" },
-        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 stop: ${e.message}\n`);
-    ctx.stderr.write(`Usage: cesium stop [--force] [--timeout <ms>]\n`);
-    return null;
-  }
-
-  if (values.help) {
-    ctx.stdout.write(
-      [
-        "Usage: cesium stop [options]",
-        "",
-        "Options:",
-        "  --force, -f        SIGKILL immediately — skip the SIGTERM grace period",
-        "  --timeout <ms>     Grace period in ms before SIGKILL (default: 3000)",
-        "  --help, -h         Show this help message",
-        "",
-        "Stops the running cesium server via its PID file. Idempotent when no",
-        "server is running.",
-        "",
-      ].join("\n"),
-    );
-    return "help";
-  }
-
-  let timeout = 3000;
-  if (values.timeout !== undefined) {
-    const t = parseInt(values.timeout, 10);
-    if (isNaN(t) || t < 0) {
-      ctx.stderr.write(`cesium stop: --timeout must be a non-negative integer\n`);
-      return null;
-    }
-    timeout = t;
+  if (!Number.isInteger(args.timeoutMs) || args.timeoutMs < 0) {
+    ctx.stderr.write(`cesium stop: --timeout must be a non-negative integer\n`);
+    return 1;
   }
 
-  return { force: values.force, timeout };
-}
-
-export async function stopCommand(argv: string[], ctx?: Partial<StopContext>): Promise<number> {
-  const resolved: StopContext = { ...defaultCtx(), ...ctx };
-
-  const parseResult = parseStopArgs(argv, resolved);
-  if (parseResult === null) return 1;
-  if (parseResult === "help") return 0;
-
-  const opts = parseResult;
-  const cfg = (resolved.loadConfig ?? loadConfig)();
+  const cfg = (ctx.loadConfig ?? loadConfig)();
 
   const stopArgs: StopServerArgs = {
     stateDir: cfg.stateDir,
-    force: opts.force,
-    timeoutMs: opts.timeout,
+    force: args.force,
+    timeoutMs: args.timeoutMs,
   };
-  if (resolved.isAlive !== undefined) {
-    stopArgs.isAlive = resolved.isAlive;
-  }
-  if (resolved.killProcess !== undefined) {
-    stopArgs.killProcess = resolved.killProcess;
-  }
-  if (resolved.sleep !== undefined) {
-    stopArgs.sleep = resolved.sleep;
-  }
+  if (ctx.isAlive !== undefined) stopArgs.isAlive = ctx.isAlive;
+  if (ctx.killProcess !== undefined) stopArgs.killProcess = ctx.killProcess;
+  if (ctx.sleep !== undefined) stopArgs.sleep = ctx.sleep;
 
   const outcome = await stopServer(stopArgs);
 
   switch (outcome.kind) {
     case "not-running":
-      resolved.stdout.write("no cesium server running\n");
+      ctx.stdout.write("no cesium server running\n");
       return 0;
     case "stale":
-      resolved.stdout.write("server not running (stale PID file removed)\n");
+      ctx.stdout.write("server not running (stale PID file removed)\n");
       return 0;
     case "stopped":
-      resolved.stdout.write(`stopped cesium server (pid ${outcome.pid}, port ${outcome.port})\n`);
+      ctx.stdout.write(`stopped cesium server (pid ${outcome.pid}, port ${outcome.port})\n`);
       return 0;
     case "permission-denied":
-      resolved.stderr.write(
+      ctx.stderr.write(
         `cesium stop: permission denied — process ${outcome.pid} is owned by another user\n`,
       );
       return 2;
   }
 }
+
+export const stopCmd = defineCommand({
+  meta: {
+    name: "stop",
+    description:
+      "Stop the running cesium server via its PID file. Idempotent when no server is running.",
+  },
+  args: {
+    force: {
+      type: "boolean",
+      alias: "f",
+      default: false,
+      description: "SIGKILL immediately — skip the SIGTERM grace period",
+    },
+    timeout: {
+      type: "string",
+      default: "3000",
+      description: "Grace period in ms before SIGKILL",
+    },
+  },
+  async run({ args }) {
+    const t = parseInt(args.timeout, 10);
+    if (isNaN(t) || t < 0) {
+      process.stderr.write(`cesium stop: --timeout must be a non-negative integer\n`);
+      process.exit(1);
+    }
+    const code = await runStop({ force: args.force, timeoutMs: t });
+    if (code !== 0) process.exit(code);
+  },
+});

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/index.ts

@@ -17,7 +17,10 @@ const rawFragment = await readFile(
   "utf8",
 );
 
-const PROMPT_FRAGMENT = rawFragment.replace("{{BLOCK_FIELD_REFERENCE}}", generateBlockFieldReference());
+const PROMPT_FRAGMENT = rawFragment.replace(
+  "{{BLOCK_FIELD_REFERENCE}}",
+  generateBlockFieldReference(),
+);
 
 export const CesiumPlugin: Plugin = async (ctx): Promise<Hooks> => {
   return {

package/src/prompt/field-reference.ts

@@ -86,8 +86,8 @@ export function generateBlockFieldReference(): string {
   lines.push("");
   lines.push(
     "All `markdown` fields support `**bold**`, `*italic*`, `` `code` ``, lists, blockquotes, " +
-    "and the safelisted inline tags `<kbd>`, `<span class=\"pill\">`, `<span class=\"tag\">`. " +
-    "External URLs in links render as plain text.",
+      'and the safelisted inline tags `<kbd>`, `<span class="pill">`, `<span class="tag">`. ' +
+      "External URLs in links render as plain text.",
   );
 
   return lines.join("\n");

package/src/prompt/system-fragment.md

@@ -20,22 +20,52 @@ You have access to six tools:
 ### Example
 
 ```json
-{ "title": "Migration Guide", "kind": "plan", "blocks": [
-  { "type": "hero", "eyebrow": "v2", "title": "Migration Guide",
-    "meta": [{ "k": "Status", "v": "Draft" }, { "k": "Owner", "v": "platform" }] },
-  { "type": "tldr", "markdown": "**Summary:** Update one import path and bump the SDK." },
-  { "type": "section", "title": "What Changed", "children": [
-    { "type": "prose", "markdown": "The `auth` module is now a standalone package." },
-    { "type": "callout", "variant": "warn", "markdown": "Change `sdk/auth` imports before upgrading." }
-  ]},
-  { "type": "risk_table", "rows": [
-    { "risk": "Missed imports", "likelihood": "medium", "impact": "high", "mitigation": "Run codemods." }
-  ]},
-  { "type": "timeline", "items": [
-    { "label": "Phase 1", "text": "Audit existing imports", "date": "2026-06-01" },
-    { "label": "Phase 2", "text": "Run migration script" }
-  ]}
-]}
+{
+  "title": "Migration Guide",
+  "kind": "plan",
+  "blocks": [
+    {
+      "type": "hero",
+      "eyebrow": "v2",
+      "title": "Migration Guide",
+      "meta": [
+        { "k": "Status", "v": "Draft" },
+        { "k": "Owner", "v": "platform" }
+      ]
+    },
+    { "type": "tldr", "markdown": "**Summary:** Update one import path and bump the SDK." },
+    {
+      "type": "section",
+      "title": "What Changed",
+      "children": [
+        { "type": "prose", "markdown": "The `auth` module is now a standalone package." },
+        {
+          "type": "callout",
+          "variant": "warn",
+          "markdown": "Change `sdk/auth` imports before upgrading."
+        }
+      ]
+    },
+    {
+      "type": "risk_table",
+      "rows": [
+        {
+          "risk": "Missed imports",
+          "likelihood": "medium",
+          "impact": "high",
+          "mitigation": "Run codemods."
+        }
+      ]
+    },
+    {
+      "type": "timeline",
+      "items": [
+        { "label": "Phase 1", "text": "Audit existing imports", "date": "2026-06-01" },
+        { "label": "Phase 2", "text": "Run migration script" }
+      ]
+    }
+  ]
+}
 ```
 
 ## Quick block reference

package/src/render/blocks/catalog.ts

@@ -17,6 +17,7 @@ import { meta as pillRowMeta } from "./renderers/pill-row.ts";
 import { meta as dividerMeta } from "./renderers/divider.ts";
 import { meta as diagramMeta } from "./renderers/diagram.ts";
 import { meta as rawHtmlMeta } from "./renderers/raw-html.ts";
+import { meta as diffMeta } from "./renderers/diff.ts";
 
 export const blockCatalog: Record<Block["type"], BlockMeta> = {
   hero: heroMeta,
@@ -34,6 +35,7 @@ export const blockCatalog: Record<Block["type"], BlockMeta> = {
   divider: dividerMeta,
   diagram: diagramMeta,
   raw_html: rawHtmlMeta,
+  diff: diffMeta,
 };
 
 export const blockTypes = Object.keys(blockCatalog) as Array<Block["type"]>;