@cfbender/cesium 0.5.1 → 0.6.0

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

package/src/cli/commands/restart.ts

@@ -1,26 +1,31 @@
 // cesium restart — stop the running server and start a new one in the foreground.
 
-import { type StopContext, stopCommand } from "./stop.ts";
-import { type ServeContext, serveCommand as defaultServeCommand } from "./serve.ts";
+import { defineCommand } from "citty";
+import { type StopContext, type StopArgs, runStop } from "./stop.ts";
+import { type ServeContext, type ServeArgs, runServe, parseDuration } from "./serve.ts";
 
 export interface RestartContext extends StopContext, ServeContext {
-  /** Test injection: replace serveCommand with a mock so tests don't block. */
-  serveImpl?: (argv: string[], ctx?: Partial<RestartContext>) => Promise<number>;
+  /** Test injection: replace runServe with a mock so tests don't block. */
+  serveImpl?: (args: ServeArgs, ctx?: Partial<RestartContext>) => Promise<number>;
 }
 
+export interface RestartArgs extends StopArgs, ServeArgs {}
+
 function defaultSleep(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
-export async function restartCommand(
-  argv: string[],
-  ctx?: Partial<RestartContext>,
+export async function runRestart(
+  args: RestartArgs,
+  ctxOverride?: Partial<RestartContext>,
 ): Promise<number> {
-  const sleepFn = ctx?.sleep ?? defaultSleep;
-  const serveFn = ctx?.serveImpl ?? defaultServeCommand;
+  const sleepFn = ctxOverride?.sleep ?? defaultSleep;
+  const serveFn = ctxOverride?.serveImpl ?? runServe;
+
+  const stopArgs: StopArgs = { force: args.force, timeoutMs: args.timeoutMs };
 
   // 1. Stop any running server
-  const stopCode = await stopCommand(argv, ctx);
+  const stopCode = await runStop(stopArgs, ctxOverride);
   if (stopCode !== 0) {
     // e.g. EPERM — bail, pass through exit code
     return stopCode;
@@ -30,9 +35,92 @@ export async function restartCommand(
   await sleepFn(200);
 
   // 3. Announce restart
-  const stdout = ctx?.stdout ?? process.stdout;
+  const stdout = ctxOverride?.stdout ?? process.stdout;
   stdout.write("starting new cesium server...\n");
 
   // 4. Start the new server in foreground (blocks until Ctrl-C)
-  return serveFn(argv, ctx);
+  const serveArgs: ServeArgs = {};
+  if (args.port !== undefined) serveArgs.port = args.port;
+  if (args.hostname !== undefined) serveArgs.hostname = args.hostname;
+  if (args.stateDir !== undefined) serveArgs.stateDir = args.stateDir;
+  if (args.idleTimeoutMs !== undefined) serveArgs.idleTimeoutMs = args.idleTimeoutMs;
+
+  return serveFn(serveArgs, ctxOverride);
 }
+
+export const restartCmd = defineCommand({
+  meta: {
+    name: "restart",
+    description: "Stop the running cesium server and start a new one in the foreground.",
+  },
+  args: {
+    // Stop 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",
+    },
+    // Serve args (mirrored)
+    port: {
+      type: "string",
+      alias: "p",
+      description: "Override configured port (default: 3030)",
+    },
+    hostname: {
+      type: "string",
+      alias: "H",
+      description: "Override configured bind address",
+    },
+    "state-dir": {
+      type: "string",
+      description: "Override the cesium state directory",
+    },
+    "idle-timeout": {
+      type: "string",
+      description: 'Auto-shutdown after DUR of inactivity (e.g. "30m"). Default: never.',
+    },
+  },
+  async run({ args }) {
+    const timeoutMs = parseInt(args.timeout, 10);
+    if (isNaN(timeoutMs) || timeoutMs < 0) {
+      process.stderr.write(`cesium restart: --timeout must be a non-negative integer\n`);
+      process.exit(1);
+    }
+
+    const restartArgs: RestartArgs = {
+      force: args.force,
+      timeoutMs,
+    };
+
+    if (args.port !== undefined) {
+      const p = parseInt(args.port, 10);
+      if (isNaN(p) || p < 1 || p > 65535) {
+        process.stderr.write(`cesium restart: --port must be a number between 1 and 65535\n`);
+        process.exit(1);
+      }
+      restartArgs.port = p;
+    }
+    if (args.hostname !== undefined) restartArgs.hostname = args.hostname;
+    if (args["state-dir"] !== undefined) restartArgs.stateDir = args["state-dir"];
+
+    if (args["idle-timeout"] !== undefined) {
+      const ms = parseDuration(args["idle-timeout"]);
+      if (ms === null) {
+        process.stderr.write(
+          `cesium restart: --idle-timeout must be a duration like "30m", "2h", "90s", or "0"/"never" to disable\n`,
+        );
+        process.exit(1);
+      }
+      restartArgs.idleTimeoutMs = ms;
+    }
+
+    const code = await runRestart(restartArgs);
+    if (code !== 0) process.exit(code);
+  },
+});

package/src/cli/commands/serve.ts

@@ -1,11 +1,24 @@
 // cesium serve — start the local HTTP server in the foreground.
 
-import { parseArgs } from "node:util";
+import { defineCommand } from "citty";
 import { loadConfig, type CesiumConfig } from "../../config.ts";
 import { runServerForeground, stopRunning } from "../../server/lifecycle.ts";
 import { resolveDisplayHost } from "../../tools/publish.ts";
 import { themeFromPreset, mergeTheme } from "../../render/theme.ts";
 
+export interface ServeArgs {
+  port?: number;
+  hostname?: string;
+  stateDir?: string;
+  /**
+   * Idle timeout in milliseconds. 0 (the default for `cesium serve`) means the
+   * server runs forever until SIGINT/SIGTERM. Override with --idle-timeout to
+   * opt back into auto-shutdown — useful for long-lived dev sessions that
+   * should still recycle eventually.
+   */
+  idleTimeoutMs?: number;
+}
+
 export interface ServeContext {
   stdout: { write: (s: string) => void };
   stderr: { write: (s: string) => void };
@@ -19,21 +32,8 @@ function defaultCtx(): ServeContext {
   };
 }
 
-export interface ServeOptions {
-  port?: number;
-  hostname?: string;
-  stateDir?: string;
-  /**
-   * Idle timeout in milliseconds. 0 (the default for `cesium serve`) means the
-   * server runs forever until SIGINT/SIGTERM. Override with --idle-timeout to
-   * opt back into auto-shutdown — useful for long-lived dev sessions that
-   * should still recycle eventually.
-   */
-  idleTimeoutMs?: number;
-}
-
 /** Parse a duration string like "30m", "2h", "90s", "0", "never". Returns ms or null. */
-function parseDuration(input: string): number | null {
+export function parseDuration(input: string): number | null {
   const trimmed = input.trim().toLowerCase();
   if (trimmed === "0" || trimmed === "never" || trimmed === "off") return 0;
   const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(trimmed);
@@ -41,134 +41,82 @@ function parseDuration(input: string): number | null {
   const n = parseFloat(match[1] ?? "");
   if (!isFinite(n) || n < 0) return null;
   const unit = match[2] ?? "ms";
-  const mul =
-    unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : /* h */ 3_600_000;
+  const mul = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : /* h */ 3_600_000;
   return Math.floor(n * mul);
 }
 
-/** Parse the argv for serve. Returns null on error (already written to stderr). */
-export function parseServeArgs(
-  argv: string[],
-  ctx: Pick<ServeContext, "stdout" | "stderr">,
-): ServeOptions | null | "help" {
-  let values: {
-    port: string | undefined;
-    hostname: string | undefined;
-    "idle-timeout": string | undefined;
-    "state-dir": string | undefined;
-    help: boolean;
-  };
-
-  try {
-    const parsed = parseArgs({
-      args: argv,
-      options: {
-        port: { type: "string", short: "p" },
-        hostname: { type: "string", short: "H" },
-        "idle-timeout": { type: "string" },
-        "state-dir": { 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 serve: ${e.message}\n`);
-    ctx.stderr.write(`Usage: cesium serve [--port N] [--hostname H] [--idle-timeout DUR]\n`);
-    return null;
-  }
-
-  if (values.help) {
-    ctx.stdout.write(
-      [
-        "Usage: cesium serve [options]",
-        "",
-        "Options:",
-        "  --port, -p N        Override configured port (default: 3030)",
-        "  --hostname, -H H    Override configured bind address (default: 127.0.0.1)",
-        "  --state-dir DIR     Override the cesium state directory",
-        "  --idle-timeout DUR  Auto-shutdown after DUR of inactivity. Accepts plain",
-        "                      milliseconds or a suffixed value (90s, 30m, 2h).",
-        "                      Use 0 / never / off to disable. Default: 0 (never).",
-        "  --help, -h          Show this help message",
-        "",
-        "Starts the cesium HTTP server in the foreground. Press Ctrl-C to stop.",
-        "Uses the same config as the opencode plugin (~/.config/opencode/cesium.json).",
-        "",
-        "Note: foreground `cesium serve` ignores the configured idleTimeoutMs by",
-        "default — the timeout exists for the plugin's lazy-started server, not",
-        "for a server you launched explicitly.",
-        "",
-      ].join("\n"),
-    );
-    return "help";
-  }
+interface ValidatedServeArgs {
+  port?: number;
+  hostname?: string;
+  stateDir?: string;
+  idleTimeoutMs?: number;
+}
 
-  const opts: ServeOptions = {};
+/**
+ * Validate ServeArgs and return a ValidatedServeArgs object, or null on error.
+ * Writes the error message to ctx.stderr.
+ */
+export function validateServeArgs(args: ServeArgs, ctx: ServeContext): ValidatedServeArgs | null {
+  const out: ValidatedServeArgs = {};
 
-  if (values.port !== undefined) {
-    const p = parseInt(values.port, 10);
-    if (isNaN(p) || p < 1 || p > 65535) {
+  if (args.port !== undefined) {
+    if (!Number.isInteger(args.port) || args.port < 1 || args.port > 65535) {
       ctx.stderr.write(`cesium serve: --port must be a number between 1 and 65535\n`);
       return null;
     }
-    opts.port = p;
+    out.port = args.port;
   }
 
-  if (values.hostname !== undefined) {
-    if (values.hostname.length === 0) {
+  if (args.hostname !== undefined) {
+    if (args.hostname.length === 0) {
       ctx.stderr.write(`cesium serve: --hostname must not be empty\n`);
       return null;
     }
-    opts.hostname = values.hostname;
+    out.hostname = args.hostname;
   }
 
-  if (values["state-dir"] !== undefined) {
-    if (values["state-dir"].length === 0) {
+  if (args.stateDir !== undefined) {
+    if (args.stateDir.length === 0) {
       ctx.stderr.write(`cesium serve: --state-dir must not be empty\n`);
       return null;
     }
-    opts.stateDir = values["state-dir"];
+    out.stateDir = args.stateDir;
   }
 
-  if (values["idle-timeout"] !== undefined) {
-    const ms = parseDuration(values["idle-timeout"]);
-    if (ms === null) {
-      ctx.stderr.write(
-        `cesium serve: --idle-timeout must be a duration like "30m", "2h", "90s", or "0"/"never" to disable\n`,
-      );
+  if (args.idleTimeoutMs !== undefined) {
+    if (!Number.isFinite(args.idleTimeoutMs) || args.idleTimeoutMs < 0) {
+      ctx.stderr.write(`cesium serve: --idle-timeout must be a non-negative duration\n`);
       return null;
     }
-    opts.idleTimeoutMs = ms;
+    out.idleTimeoutMs = args.idleTimeoutMs;
   }
 
-  return opts;
+  return out;
 }
 
-export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>): Promise<number> {
-  const resolved: ServeContext = { ...defaultCtx(), ...ctx };
+export async function runServe(
+  args: ServeArgs,
+  ctxOverride?: Partial<ServeContext>,
+): Promise<number> {
+  const ctx: ServeContext = { ...defaultCtx(), ...ctxOverride };
 
-  const parseResult = parseServeArgs(argv, resolved);
-  if (parseResult === null) return 1;
-  if (parseResult === "help") return 0;
+  const validated = validateServeArgs(args, ctx);
+  if (validated === null) return 1;
 
-  const opts = parseResult;
-  const cfg = (resolved.loadConfig ?? loadConfig)();
+  const cfg = (ctx.loadConfig ?? loadConfig)();
 
   // Foreground `cesium serve` defaults to NO idle timeout — when the user
   // launches the server explicitly, they want it to live until they Ctrl-C.
   // The configured idleTimeoutMs only applies to the plugin's lazy-started
   // server. --idle-timeout opts back into auto-shutdown.
-  const effectiveIdleTimeoutMs = opts.idleTimeoutMs ?? 0;
+  const effectiveIdleTimeoutMs = validated.idleTimeoutMs ?? 0;
 
   // Apply overrides from CLI flags
   const effectiveCfg = {
     ...cfg,
-    ...(opts.stateDir !== undefined ? { stateDir: opts.stateDir } : {}),
-    ...(opts.port !== undefined ? { port: opts.port, portMax: opts.port } : {}),
-    ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+    ...(validated.stateDir !== undefined ? { stateDir: validated.stateDir } : {}),
+    ...(validated.port !== undefined ? { port: validated.port, portMax: validated.port } : {}),
+    ...(validated.hostname !== undefined ? { hostname: validated.hostname } : {}),
     idleTimeoutMs: effectiveIdleTimeoutMs,
   };
 
@@ -185,7 +133,7 @@ export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>):
     });
   } catch (err) {
     const e = err as Error;
-    resolved.stderr.write(`cesium serve: failed to start server: ${e.message}\n`);
+    ctx.stderr.write(`cesium serve: failed to start server: ${e.message}\n`);
     return 1;
   }
 
@@ -196,26 +144,24 @@ export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>):
   const home = process.env["HOME"] ?? "";
   const stateDirDisplay = home ? effectiveCfg.stateDir.replace(home, "~") : effectiveCfg.stateDir;
 
-  resolved.stdout.write(`cesium serve · ${displayUrl}\n`);
-  resolved.stdout.write(`  serving ${stateDirDisplay}\n`);
+  ctx.stdout.write(`cesium serve · ${displayUrl}\n`);
+  ctx.stdout.write(`  serving ${stateDirDisplay}\n`);
   if (effectiveIdleTimeoutMs <= 0) {
-    resolved.stdout.write(`  no idle timeout — runs until Ctrl-C\n`);
+    ctx.stdout.write(`  no idle timeout — runs until Ctrl-C\n`);
   } else {
     const minutes = Math.round(effectiveIdleTimeoutMs / 60_000);
-    resolved.stdout.write(
+    ctx.stdout.write(
       `  idle timeout: ${minutes >= 1 ? `${minutes}m` : `${effectiveIdleTimeoutMs}ms`} of inactivity\n`,
     );
   }
-  resolved.stdout.write(`  Ctrl-C to stop\n`);
+  ctx.stdout.write(`  Ctrl-C to stop\n`);
 
   // If binding on all interfaces, also print the LAN URL
   if (effectiveCfg.hostname === "0.0.0.0" || effectiveCfg.hostname === "::") {
-    // resolveDisplayHost already returns the LAN IP for 0.0.0.0
-    resolved.stdout.write(`  LAN: ${displayUrl}\n`);
+    ctx.stdout.write(`  LAN: ${displayUrl}\n`);
   }
 
-  // Run in the foreground until SIGINT/SIGTERM (handled by lifecycle module's signal handlers)
-  // Keep the process alive by returning a promise that never resolves (until signal fires)
+  // Run in the foreground until SIGINT/SIGTERM
   await new Promise<void>((resolve) => {
     const cleanup = () => {
       void stopRunning(effectiveCfg.stateDir).finally(() => {
@@ -228,3 +174,60 @@ export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>):
 
   return 0;
 }
+
+export const serveCmd = defineCommand({
+  meta: {
+    name: "serve",
+    description: "Start the cesium HTTP server in the foreground. Press Ctrl-C to stop.",
+  },
+  args: {
+    port: {
+      type: "string",
+      alias: "p",
+      description: "Override configured port (default: 3030)",
+    },
+    hostname: {
+      type: "string",
+      alias: "H",
+      description: "Override configured bind address (default: 127.0.0.1)",
+    },
+    "state-dir": {
+      type: "string",
+      description: "Override the cesium state directory",
+    },
+    "idle-timeout": {
+      type: "string",
+      description:
+        'Auto-shutdown after DUR of inactivity (e.g. "30m", "2h", "90s"). Use 0/never/off to disable. Default: never.',
+    },
+  },
+  async run({ args }) {
+    const serveArgs: ServeArgs = {};
+
+    if (args.port !== undefined) {
+      const p = parseInt(args.port, 10);
+      if (isNaN(p) || p < 1 || p > 65535) {
+        process.stderr.write(`cesium serve: --port must be a number between 1 and 65535\n`);
+        process.exit(1);
+      }
+      serveArgs.port = p;
+    }
+
+    if (args.hostname !== undefined) serveArgs.hostname = args.hostname;
+    if (args["state-dir"] !== undefined) serveArgs.stateDir = args["state-dir"];
+
+    if (args["idle-timeout"] !== undefined) {
+      const ms = parseDuration(args["idle-timeout"]);
+      if (ms === null) {
+        process.stderr.write(
+          `cesium serve: --idle-timeout must be a duration like "30m", "2h", "90s", or "0"/"never" to disable\n`,
+        );
+        process.exit(1);
+      }
+      serveArgs.idleTimeoutMs = ms;
+    }
+
+    const code = await runServe(serveArgs);
+    if (code !== 0) process.exit(code);
+  },
+});