@cfbender/cesium 0.3.5

package/src/cli/commands/prune.ts

@@ -0,0 +1,348 @@
+// cesium prune — delete artifacts older than a given duration.
+
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { readdir, unlink as fsUnlink, stat } from "node:fs/promises";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import { loadIndex, writeIndex, type IndexEntry } from "../../storage/index-cache.ts";
+import { atomicWrite } from "../../storage/write.ts";
+import {
+  renderProjectIndex,
+  renderGlobalIndex,
+  summarizeProject,
+} from "../../storage/index-gen.ts";
+import { themeFromPreset, mergeTheme } from "../../render/theme.ts";
+import { readEmbeddedMetadata } from "../../storage/write.ts";
+import { readFile } from "node:fs/promises";
+
+export interface PruneContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  loadConfig?: () => CesiumConfig;
+  now?: () => Date;
+}
+
+function defaultCtx(): PruneContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}
+
+// ─── Duration parser ──────────────────────────────────────────────────────────
+
+/** Parse a duration string like "90d", "2w", "12h", "30m" into milliseconds. */
+export function parseDuration(s: string): number | null {
+  const trimmed = s.trim().toLowerCase();
+  const match = /^(\d+)(d|w|h|m)$/.exec(trimmed);
+  if (!match) return null;
+
+  const n = parseInt(match[1] ?? "", 10);
+  const unit = match[2] ?? "";
+
+  switch (unit) {
+    case "m":
+      return n * 60 * 1000;
+    case "h":
+      return n * 60 * 60 * 1000;
+    case "d":
+      return n * 24 * 60 * 60 * 1000;
+    case "w":
+      return n * 7 * 24 * 60 * 60 * 1000;
+    default:
+      return null;
+  }
+}
+
+// ─── Prune implementation ─────────────────────────────────────────────────────
+
+interface ArtifactCandidate {
+  projectSlug: string;
+  projectDir: string;
+  filename: string;
+  filePath: string;
+  createdAt: string;
+}
+
+/** Read metadata + fallback from one artifact file. Returns null to skip. */
+async function readArtifactCandidate(
+  stateDir: string,
+  slug: string,
+  filename: string,
+): Promise<ArtifactCandidate | null> {
+  const projectsDir = join(stateDir, "projects");
+  const filePath = join(projectsDir, slug, "artifacts", filename);
+  let createdAt: string | null = null;
+  try {
+    const html = await readFile(filePath, "utf8");
+    const meta = readEmbeddedMetadata(html);
+    if (meta !== null && typeof meta["createdAt"] === "string") {
+      createdAt = meta["createdAt"];
+    }
+  } catch {
+    return null;
+  }
+  if (createdAt === null) {
+    try {
+      const s = await stat(filePath);
+      createdAt = s.mtime.toISOString();
+    } catch {
+      return null;
+    }
+  }
+  return {
+    projectSlug: slug,
+    projectDir: join(projectsDir, slug),
+    filename,
+    filePath,
+    createdAt,
+  };
+}
+
+/** Read all artifact filenames for one project slug. Returns [] on missing dir. */
+async function readProjectFilenames(stateDir: string, slug: string): Promise<string[]> {
+  const artifactsDir = join(stateDir, "projects", slug, "artifacts");
+  try {
+    const files = await readdir(artifactsDir);
+    return files.filter((f) => f.endsWith(".html"));
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+async function collectAllArtifacts(stateDir: string): Promise<ArtifactCandidate[]> {
+  const projectsDir = join(stateDir, "projects");
+  let projectSlugs: string[];
+  try {
+    projectSlugs = await readdir(projectsDir);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") return [];
+    throw err;
+  }
+
+  // Read all filenames for each project in parallel
+  const filenameLists = await Promise.all(
+    projectSlugs.map((slug) => readProjectFilenames(stateDir, slug)),
+  );
+
+  // Read each artifact's metadata in parallel
+  const perProjectCandidates = await Promise.all(
+    projectSlugs.map((slug, i) => {
+      const filenames = filenameLists[i] ?? [];
+      return Promise.all(
+        filenames.map((filename) => readArtifactCandidate(stateDir, slug, filename)),
+      );
+    }),
+  );
+
+  return perProjectCandidates.flat().filter((c): c is ArtifactCandidate => c !== null);
+}
+
+function formatTable(candidates: ArtifactCandidate[]): string {
+  const COL_PROJECT = 32;
+  const COL_ID = 8;
+
+  const header = "PROJECT".padEnd(COL_PROJECT) + "  " + "ID".padEnd(COL_ID) + "  CREATED";
+  const sep = "─".repeat(header.length);
+
+  const rows = candidates.map((c) => {
+    // Extract id from filename: <date>__<slug>__<id>.html
+    const parts = c.filename.replace(/\.html$/, "").split("__");
+    const id = parts[parts.length - 1] ?? c.filename.slice(0, 8);
+
+    const project =
+      c.projectSlug.length > COL_PROJECT
+        ? c.projectSlug.slice(0, COL_PROJECT - 1) + "…"
+        : c.projectSlug.padEnd(COL_PROJECT);
+
+    return project + "  " + id.slice(0, COL_ID).padEnd(COL_ID) + "  " + c.createdAt.slice(0, 19);
+  });
+
+  return [header, sep, ...rows].join("\n");
+}
+
+export async function pruneCommand(argv: string[], ctx?: Partial<PruneContext>): Promise<number> {
+  const resolved: PruneContext = { ...defaultCtx(), ...ctx };
+
+  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`);
+    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);
+  if (durationMs === null) {
+    resolved.stderr.write(
+      `cesium prune: invalid duration "${durationStr}". 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 cutoff = now.getTime() - durationMs;
+
+  // Collect all artifacts
+  let allArtifacts: ArtifactCandidate[];
+  try {
+    allArtifacts = await collectAllArtifacts(cfg.stateDir);
+  } catch (err) {
+    const e = err as Error;
+    resolved.stderr.write(`cesium prune: failed to scan artifacts: ${e.message}\n`);
+    return 1;
+  }
+
+  // Filter to those older than the cutoff
+  const toDelete = allArtifacts.filter((c) => {
+    const ts = new Date(c.createdAt).getTime();
+    return ts < cutoff;
+  });
+
+  if (toDelete.length === 0) {
+    resolved.stdout.write(`No artifacts older than ${durationStr} found.\n`);
+    return 0;
+  }
+
+  if (isDryRun) {
+    resolved.stdout.write(
+      `Would delete ${toDelete.length} artifact${toDelete.length !== 1 ? "s" : ""} older than ${durationStr}:\n`,
+    );
+    resolved.stdout.write(formatTable(toDelete) + "\n\n");
+    resolved.stdout.write(`Re-run with --yes to delete.\n`);
+    return 0;
+  }
+
+  // Actually delete — in parallel, track counts
+  const deleteResults = await Promise.all(
+    toDelete.map(async (candidate) => {
+      try {
+        await fsUnlink(candidate.filePath);
+        return true;
+      } 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`,
+          );
+        }
+        return false;
+      }
+    }),
+  );
+  const deletedCount = deleteResults.filter(Boolean).length;
+
+  // Regenerate indexes for affected projects — in parallel
+  const affectedSlugs = [...new Set(toDelete.map((c) => c.projectSlug))];
+  const theme = mergeTheme(themeFromPreset(cfg.themePreset), cfg.theme);
+
+  await Promise.all(
+    affectedSlugs.map(async (slug) => {
+      const projectDir = join(cfg.stateDir, "projects", slug);
+      const projectIndexJsonPath = join(projectDir, "index.json");
+      try {
+        const projectEntries = await loadIndex(projectIndexJsonPath);
+        const deletedFilenames = new Set(
+          toDelete.filter((c) => c.projectSlug === slug).map((c) => c.filename),
+        );
+        const surviving: IndexEntry[] = projectEntries.filter(
+          (e) => !deletedFilenames.has(e.filename),
+        );
+        await writeIndex(projectIndexJsonPath, surviving);
+        const projectName = surviving[0]?.projectName ?? slug;
+        const projectIndexHtml = renderProjectIndex({
+          projectSlug: slug,
+          projectName,
+          entries: surviving,
+          theme,
+        });
+        await atomicWrite(join(projectDir, "index.html"), projectIndexHtml);
+      } catch {
+        // best-effort — if project index is missing, skip
+      }
+    }),
+  );
+
+  // Regenerate global index
+  try {
+    const globalJsonPath = join(cfg.stateDir, "index.json");
+    const globalEntries = await loadIndex(globalJsonPath);
+    const deletedFilenames = new Set(toDelete.map((c) => c.filename));
+    const survivingGlobal: IndexEntry[] = globalEntries.filter(
+      (e) => !deletedFilenames.has(e.filename),
+    );
+    await writeIndex(globalJsonPath, survivingGlobal);
+
+    // Build project summaries from surviving global entries
+    const bySlug = new Map<string, { name: string; entries: IndexEntry[] }>();
+    for (const e of survivingGlobal) {
+      const g = bySlug.get(e.projectSlug) ?? { name: e.projectName, entries: [] };
+      g.entries.push(e);
+      bySlug.set(e.projectSlug, g);
+    }
+    const summaries = [...bySlug.entries()].map(([slug, { name, entries }]) =>
+      summarizeProject({ slug, name, entries }),
+    );
+    const globalIndexHtml = renderGlobalIndex({ projects: summaries, theme });
+    await atomicWrite(join(cfg.stateDir, "index.html"), globalIndexHtml);
+  } catch {
+    // best-effort
+  }
+
+  resolved.stdout.write(
+    `Deleted ${deletedCount} artifact${deletedCount !== 1 ? "s" : ""}. Indexes regenerated.\n`,
+  );
+  return 0;
+}

package/src/cli/commands/restart.ts

@@ -0,0 +1,38 @@
+// 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";
+
+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>;
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export async function restartCommand(
+  argv: string[],
+  ctx?: Partial<RestartContext>,
+): Promise<number> {
+  const sleepFn = ctx?.sleep ?? defaultSleep;
+  const serveFn = ctx?.serveImpl ?? defaultServeCommand;
+
+  // 1. Stop any running server
+  const stopCode = await stopCommand(argv, ctx);
+  if (stopCode !== 0) {
+    // e.g. EPERM — bail, pass through exit code
+    return stopCode;
+  }
+
+  // 2. Brief pause to let the port fully release
+  await sleepFn(200);
+
+  // 3. Announce restart
+  const stdout = ctx?.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);
+}

package/src/cli/commands/serve.ts

@@ -0,0 +1,214 @@
+// cesium serve — start the local HTTP server in the foreground.
+
+import { parseArgs } from "node:util";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import { ensureRunning, stopRunning } from "../../server/lifecycle.ts";
+import { resolveDisplayHost } from "../../tools/publish.ts";
+
+export interface ServeContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  loadConfig?: () => CesiumConfig;
+}
+
+function defaultCtx(): ServeContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}
+
+export interface ServeOptions {
+  port?: number;
+  hostname?: 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 {
+  const trimmed = input.trim().toLowerCase();
+  if (trimmed === "0" || trimmed === "never" || trimmed === "off") return 0;
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(trimmed);
+  if (match === null) return 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;
+  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;
+    help: boolean;
+  };
+
+  try {
+    const parsed = parseArgs({
+      args: argv,
+      options: {
+        port: { type: "string", short: "p" },
+        hostname: { type: "string", short: "H" },
+        "idle-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 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)",
+        "  --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";
+  }
+
+  const opts: ServeOptions = {};
+
+  if (values.port !== undefined) {
+    const p = parseInt(values.port, 10);
+    if (isNaN(p) || p < 1 || p > 65535) {
+      ctx.stderr.write(`cesium serve: --port must be a number between 1 and 65535\n`);
+      return null;
+    }
+    opts.port = p;
+  }
+
+  if (values.hostname !== undefined) {
+    if (values.hostname.length === 0) {
+      ctx.stderr.write(`cesium serve: --hostname must not be empty\n`);
+      return null;
+    }
+    opts.hostname = values.hostname;
+  }
+
+  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`,
+      );
+      return null;
+    }
+    opts.idleTimeoutMs = ms;
+  }
+
+  return opts;
+}
+
+export async function serveCommand(argv: string[], ctx?: Partial<ServeContext>): Promise<number> {
+  const resolved: ServeContext = { ...defaultCtx(), ...ctx };
+
+  const parseResult = parseServeArgs(argv, resolved);
+  if (parseResult === null) return 1;
+  if (parseResult === "help") return 0;
+
+  const opts = parseResult;
+  const cfg = (resolved.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;
+
+  // Apply overrides from CLI flags
+  const effectiveCfg = {
+    ...cfg,
+    ...(opts.port !== undefined ? { port: opts.port, portMax: opts.port } : {}),
+    ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+    idleTimeoutMs: effectiveIdleTimeoutMs,
+  };
+
+  let serverInfo: { port: number; url: string };
+  try {
+    serverInfo = await ensureRunning({
+      stateDir: effectiveCfg.stateDir,
+      port: effectiveCfg.port,
+      portMax: effectiveCfg.portMax,
+      idleTimeoutMs: effectiveCfg.idleTimeoutMs,
+      hostname: effectiveCfg.hostname,
+    });
+  } catch (err) {
+    const e = err as Error;
+    resolved.stderr.write(`cesium serve: failed to start server: ${e.message}\n`);
+    return 1;
+  }
+
+  const displayHost = resolveDisplayHost(effectiveCfg.hostname);
+  const displayUrl = `http://${displayHost}:${serverInfo.port}`;
+
+  // Expand home dir in stateDir for display
+  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`);
+  if (effectiveIdleTimeoutMs <= 0) {
+    resolved.stdout.write(`  no idle timeout — runs until Ctrl-C\n`);
+  } else {
+    const minutes = Math.round(effectiveIdleTimeoutMs / 60_000);
+    resolved.stdout.write(
+      `  idle timeout: ${minutes >= 1 ? `${minutes}m` : `${effectiveIdleTimeoutMs}ms`} of inactivity\n`,
+    );
+  }
+  resolved.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`);
+  }
+
+  // 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)
+  await new Promise<void>((resolve) => {
+    const cleanup = () => {
+      void stopRunning(effectiveCfg.stateDir).finally(() => {
+        resolve();
+      });
+    };
+    process.once("SIGINT", cleanup);
+    process.once("SIGTERM", cleanup);
+  });
+
+  return 0;
+}