@cfbender/cesium 0.3.5

package/src/cli/commands/stop.ts

@@ -0,0 +1,130 @@
+// cesium stop — kill the running cesium server cross-process via PID file.
+
+import { parseArgs } from "node:util";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import { stopServer } from "../../server/stop.ts";
+import type { StopServerArgs } from "../../server/stop.ts";
+
+export interface StopContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  loadConfig?: () => CesiumConfig;
+  // Test injection points:
+  isAlive?: (pid: number) => boolean;
+  killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+function defaultCtx(): StopContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}
+
+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 };
+
+  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;
+  }
+
+  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 stopArgs: StopServerArgs = {
+    stateDir: cfg.stateDir,
+    force: opts.force,
+    timeoutMs: opts.timeout,
+  };
+  if (resolved.isAlive !== undefined) {
+    stopArgs.isAlive = resolved.isAlive;
+  }
+  if (resolved.killProcess !== undefined) {
+    stopArgs.killProcess = resolved.killProcess;
+  }
+  if (resolved.sleep !== undefined) {
+    stopArgs.sleep = resolved.sleep;
+  }
+
+  const outcome = await stopServer(stopArgs);
+
+  switch (outcome.kind) {
+    case "not-running":
+      resolved.stdout.write("no cesium server running\n");
+      return 0;
+    case "stale":
+      resolved.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`);
+      return 0;
+    case "permission-denied":
+      resolved.stderr.write(
+        `cesium stop: permission denied — process ${outcome.pid} is owned by another user\n`,
+      );
+      return 2;
+  }
+}

package/src/cli/commands/theme.ts

@@ -0,0 +1,333 @@
+// cesium theme — show or apply the configured theme.
+
+import { parseArgs } from "node:util";
+import { readFile } from "node:fs/promises";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import {
+  themeFromPreset,
+  mergeTheme,
+  type ThemeTokens,
+  type ThemePalette,
+} from "../../render/theme.ts";
+import { writeThemeCss, themeCssPath } from "../../storage/theme-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";
+
+export interface ThemeContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  loadConfig?: () => CesiumConfig;
+}
+
+function defaultCtx(): ThemeContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}
+
+function resolveTheme(cfg: CesiumConfig): { theme: ThemeTokens; presetLabel: string } {
+  const theme = mergeTheme(themeFromPreset(cfg.themePreset), cfg.theme);
+  let presetLabel: string;
+  if (cfg.themePreset === undefined) {
+    presetLabel = "claret-dark (default)";
+  } else if (cfg.themePreset === "claret") {
+    presetLabel = "claret-dark (alias for claret)";
+  } else {
+    presetLabel = cfg.themePreset;
+  }
+  return { theme, presetLabel };
+}
+
+function printTokenTable(
+  out: { write: (s: string) => void },
+  theme: ThemeTokens,
+  presetLabel: string,
+  cssPath: string,
+  writeNeeded: boolean,
+): void {
+  out.write(`Resolved theme: ${presetLabel}\n\n`);
+  out.write("Tokens:\n");
+  const { colors } = theme;
+  const keys: (keyof ThemePalette)[] = [
+    "bg",
+    "surface",
+    "surface2",
+    "oat",
+    "rule",
+    "ink",
+    "inkSoft",
+    "muted",
+    "accent",
+    "olive",
+    "codeBg",
+    "codeFg",
+  ];
+  for (const key of keys) {
+    out.write(`  ${key.padEnd(12)}${colors[key]}\n`);
+  }
+  out.write("\n");
+  const suffix = writeNeeded ? "  (write needed)" : "";
+  out.write(`theme.css path: ${cssPath}${suffix}\n`);
+}
+
+async function isWriteNeeded(cssPath: string, theme: ThemeTokens): Promise<boolean> {
+  const expected = themeTokensCss(theme) + "\n";
+  try {
+    const existing = await readFile(cssPath, "utf8");
+    return existing !== expected;
+  } catch {
+    return true;
+  }
+}
+
+// ─── Retrofit logic ───────────────────────────────────────────────────────────
+
+/**
+ * Compute the relative path to theme.css from a given file path within stateDir.
+ * - artifact:       <stateDir>/projects/<slug>/artifacts/<file>.html → ../../../theme.css
+ * - project index:  <stateDir>/projects/<slug>/index.html            → ../../theme.css
+ * - global index:   <stateDir>/index.html                            → theme.css
+ */
+function relThemeCssPath(filePath: string, stateDir: string): string {
+  // Normalize: strip stateDir prefix
+  const norm = stateDir.endsWith("/") ? stateDir : stateDir + "/";
+  const rel = filePath.startsWith(norm) ? filePath.slice(norm.length) : filePath;
+  const parts = rel.split("/");
+  // parts.length - 1 = directory depth
+  const depth = parts.length - 1;
+  if (depth === 0) return "theme.css"; // root = global index
+  if (depth === 2) return "../../theme.css"; // projects/<slug>/index.html
+  if (depth === 3) return "../../../theme.css"; // projects/<slug>/artifacts/*.html
+  // Fallback: go up depth directories
+  return "../".repeat(depth) + "theme.css";
+}
+
+async function retrofitFile(
+  filePath: string,
+  stateDir: string,
+  out: { write: (s: string) => void },
+): Promise<boolean> {
+  let html: string;
+  try {
+    html = await readFile(filePath, "utf8");
+  } catch {
+    return false;
+  }
+
+  const relPath = relThemeCssPath(filePath, stateDir);
+  const linkTag = `<link rel="stylesheet" href="${relPath}">`;
+
+  // Check if already has this exact link
+  if (html.includes(linkTag)) return false;
+
+  // Insert before </head>
+  const newHtml = html.replace("</head>", `${linkTag}\n</head>`);
+  if (newHtml === html) return false; // no </head> found — skip
+
+  try {
+    await atomicWrite(filePath, newHtml);
+    out.write(`  retrofitted ${filePath}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function retrofitAll(
+  stateDir: string,
+  out: { write: (s: string) => void },
+): Promise<{ artifacts: number; indexes: number }> {
+  // Collect all file paths to potentially retrofit
+  const tasks: Array<{ filePath: string; kind: "artifact" | "index" }> = [];
+
+  // Global index
+  tasks.push({ filePath: join(stateDir, "index.html"), kind: "index" });
+
+  // Walk projects
+  const projectsDir = join(stateDir, "projects");
+  let slugs: string[] = [];
+  try {
+    slugs = await readdir(projectsDir);
+  } catch {
+    // No projects dir yet
+  }
+
+  const perSlugFiles = await Promise.all(
+    slugs.map(async (slug) => {
+      const projectDir = join(projectsDir, slug);
+      const results: Array<{ filePath: string; kind: "artifact" | "index" }> = [];
+
+      results.push({ filePath: join(projectDir, "index.html"), kind: "index" });
+
+      const artifactsDir = join(projectDir, "artifacts");
+      let files: string[] = [];
+      try {
+        files = (await readdir(artifactsDir)).filter((f) => f.endsWith(".html"));
+      } catch {
+        // No artifacts dir yet
+      }
+      for (const filename of files) {
+        results.push({ filePath: join(artifactsDir, filename), kind: "artifact" });
+      }
+      return results;
+    }),
+  );
+
+  for (const batch of perSlugFiles) {
+    for (const item of batch) {
+      tasks.push(item);
+    }
+  }
+
+  // Retrofit all files in parallel
+  const results = await Promise.all(
+    tasks.map(async ({ filePath, kind }) => {
+      const changed = await retrofitFile(filePath, stateDir, out);
+      return { changed, kind };
+    }),
+  );
+
+  let artifacts = 0;
+  let indexes = 0;
+  for (const { changed, kind } of results) {
+    if (changed) {
+      if (kind === "artifact") artifacts++;
+      else indexes++;
+    }
+  }
+
+  return { artifacts, indexes };
+}
+
+// ─── 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;
+}
+
+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;
+  }
+
+  const cfg = (ctx.loadConfig ?? loadConfig)();
+  const { theme, presetLabel } = resolveTheme(cfg);
+  const cssPath = themeCssPath(cfg.stateDir);
+  const writeNeeded = await isWriteNeeded(cssPath, theme);
+
+  printTokenTable(ctx.stdout, theme, presetLabel, cssPath, writeNeeded);
+  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;
+  }
+
+  const cfg = (ctx.loadConfig ?? loadConfig)();
+  const { theme, presetLabel } = resolveTheme(cfg);
+  const cssPath = await writeThemeCss(cfg.stateDir, theme);
+
+  if (values["rewrite-artifacts"]) {
+    const { artifacts, indexes } = await retrofitAll(cfg.stateDir, ctx.stdout);
+    ctx.stdout.write(
+      [
+        `Wrote ${cssPath} (${presetLabel} preset).`,
+        `Retrofitted ${artifacts} artifact${artifacts !== 1 ? "s" : ""} and ${indexes} index${indexes !== 1 ? "es" : ""} with the theme link.`,
+        "Files without prior theme links now pick up theme.css.",
+        "",
+      ].join("\n"),
+    );
+  } else {
+    ctx.stdout.write(
+      [
+        `Wrote ${cssPath} (${presetLabel} preset).`,
+        "Existing artifacts continue rendering with their inline fallback theme.",
+        "Run with --rewrite-artifacts to retrofit them.",
+        "",
+      ].join("\n"),
+    );
+  }
+
+  return 0;
+}

package/src/cli/index.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env bun
+
+import { parseArgs as _parseArgs } from "node:util";
+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;
+  },
+};
+
+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);
+}
+
+await main();

package/src/config.ts

@@ -0,0 +1,94 @@
+// Config loader — reads and validates ~/.config/opencode/cesium.json.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ThemePalette } from "./render/theme.ts";
+
+export interface CesiumConfig {
+  stateDir: string;
+  port: number;
+  portMax: number;
+  idleTimeoutMs: number;
+  hostname: string;
+  themePreset?: string;
+  theme?: Partial<ThemePalette>;
+}
+
+export function defaultConfig(env?: NodeJS.ProcessEnv): CesiumConfig {
+  const e = env ?? process.env;
+  const xdgState = e["XDG_STATE_HOME"];
+  const stateDir = xdgState
+    ? join(xdgState, "cesium")
+    : join(homedir(), ".local", "state", "cesium");
+  return {
+    stateDir,
+    port: 3030,
+    portMax: 3050,
+    idleTimeoutMs: 30 * 60 * 1000,
+    hostname: "127.0.0.1",
+  };
+}
+
+interface RawConfig {
+  stateDir?: unknown;
+  port?: unknown;
+  portMax?: unknown;
+  idleTimeoutMs?: unknown;
+  hostname?: unknown;
+  themePreset?: unknown;
+  theme?: unknown;
+}
+
+export function loadConfig(opts?: { configPath?: string; env?: NodeJS.ProcessEnv }): CesiumConfig {
+  const env = opts?.env ?? process.env;
+  const base = defaultConfig(env);
+
+  const configPath =
+    opts?.configPath ??
+    join(env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config"), "opencode", "cesium.json");
+
+  let fileConfig: RawConfig = {};
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      fileConfig = parsed as RawConfig;
+    }
+  } catch {
+    // File missing or unreadable — use defaults
+  }
+
+  const merged: CesiumConfig = { ...base };
+
+  if (typeof fileConfig.stateDir === "string") merged.stateDir = fileConfig.stateDir;
+  if (typeof fileConfig.port === "number") merged.port = fileConfig.port;
+  if (typeof fileConfig.portMax === "number") merged.portMax = fileConfig.portMax;
+  if (typeof fileConfig.idleTimeoutMs === "number") merged.idleTimeoutMs = fileConfig.idleTimeoutMs;
+  if (typeof fileConfig.hostname === "string" && fileConfig.hostname.length > 0) {
+    merged.hostname = fileConfig.hostname;
+  }
+  if (
+    fileConfig.theme !== null &&
+    typeof fileConfig.theme === "object" &&
+    !Array.isArray(fileConfig.theme)
+  ) {
+    merged.theme = fileConfig.theme as Partial<ThemePalette>;
+  }
+  if (typeof fileConfig.themePreset === "string") merged.themePreset = fileConfig.themePreset;
+
+  // Env overrides
+  const envPort = env["CESIUM_PORT"];
+  if (envPort !== undefined) {
+    const p = parseInt(envPort, 10);
+    if (!isNaN(p)) merged.port = p;
+  }
+  const envStateDir = env["CESIUM_STATE_DIR"];
+  if (envStateDir !== undefined) merged.stateDir = envStateDir;
+  const envHost = env["CESIUM_HOSTNAME"];
+  if (envHost !== undefined && envHost.length > 0) merged.hostname = envHost;
+  const envThemePreset = env["CESIUM_THEME_PRESET"];
+  if (envThemePreset !== undefined) merged.themePreset = envThemePreset;
+
+  return merged;
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Plugin entry point — registers cesium tools and injects the system-prompt fragment.
+
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Plugin, Hooks } from "@opencode-ai/plugin";
+import { createPublishTool } from "./tools/publish.ts";
+import { createAskTool } from "./tools/ask.ts";
+import { createWaitTool } from "./tools/wait.ts";
+import { createStyleguideTool } from "./tools/styleguide.ts";
+import { createCritiqueTool } from "./tools/critique.ts";
+import { createStopTool } from "./tools/stop.ts";
+
+const PROMPT_FRAGMENT = await readFile(
+  join(dirname(fileURLToPath(import.meta.url)), "prompt/system-fragment.md"),
+  "utf8",
+);
+
+export const CesiumPlugin: Plugin = async (ctx): Promise<Hooks> => {
+  return {
+    tool: {
+      cesium_publish: createPublishTool(ctx),
+      cesium_ask: createAskTool(ctx),
+      cesium_wait: createWaitTool(ctx),
+      cesium_styleguide: createStyleguideTool(ctx),
+      cesium_critique: createCritiqueTool(ctx),
+      cesium_stop: createStopTool(ctx),
+    },
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(PROMPT_FRAGMENT);
+    },
+  };
+};
+
+export default CesiumPlugin;