@cfbender/cesium 0.5.2 → 0.6.1

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,26 @@
 #!/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),
+    export: () => import("./commands/export.ts").then((m) => m.exportCmd),
+    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/render/wrap.ts

@@ -1,7 +1,7 @@
 // Assembles the full <!doctype html> document from a body fragment + metadata.
 
 import { type ThemeTokens } from "./theme.ts";
-import { fallbackCss } from "./fallback.ts";
+import { buildThemeCss } from "../storage/theme-write.ts";
 import { renderControl, renderAnswered } from "./controls.ts";
 import { getClientJs } from "./client-js.ts";
 import { faviconLinkTag } from "./favicon.ts";
@@ -131,7 +131,7 @@ function renderFooter(meta: ArtifactMeta): string {
 }
 
 export function wrapDocument(opts: WrapOptions): string {
-  const { body, meta, warnings = [], interactive } = opts;
+  const { body, meta, theme, warnings = [], interactive } = opts;
   // Default href: artifact context (three levels deep from stateDir)
   const href =
     opts.themeCssHref === undefined
@@ -142,7 +142,12 @@ export function wrapDocument(opts: WrapOptions): string {
   // Suppress <link> when null is explicitly passed
   const suppressLink = opts.themeCssHref === null;
 
-  const fallback = fallbackCss();
+  // Bake the full theme CSS into every artifact so it's genuinely
+  // self-contained when opened standalone. When served by the cesium HTTP
+  // server, the <link> below still loads and overrides the inline rules in
+  // cascade order — so theme upgrades retroactively apply to served artifacts
+  // while standalone copies retain their generation-time look.
+  const themeCss = buildThemeCss(theme);
   // Embed interactive into the cesium-meta JSON block when present
   const metaPayload: Record<string, unknown> = { ...meta };
   if (interactive !== undefined) {
@@ -172,8 +177,7 @@ export function wrapDocument(opts: WrapOptions): string {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${titleEsc} · cesium</title>
-  <style>/* fallback — standalone-readable; full styles served from /theme.css */
-${fallback}</style>${linkTag}${faviconTag}
+  <style>${themeCss}</style>${linkTag}${faviconTag}
   <script type="application/json" id="cesium-meta">${metaJson}</script>
 </head>
 <body>