@cfbender/cesium 0.3.5

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@cfbender/cesium",
+  "version": "0.3.5",
+  "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
+  "license": "MIT",
+  "author": "Cody Bender",
+  "homepage": "https://github.com/cfbender/cesium#readme",
+  "bugs": "https://github.com/cfbender/cesium/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cfbender/cesium.git"
+  },
+  "keywords": [
+    "opencode",
+    "agent",
+    "html",
+    "artifact",
+    "plugin",
+    "cli",
+    "claret"
+  ],
+  "bin": {
+    "cesium": "./src/cli/index.ts"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "assets/styleguide.html",
+    "agents",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint",
+    "examples:bake": "bun run scripts/bake-examples.ts && oxfmt examples",
+    "cli": "bun run src/cli/index.ts",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest",
+    "nanoid": "^5.0.0",
+    "parse5": "^7.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.63.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/cli/commands/ls.ts

@@ -0,0 +1,186 @@
+// cesium ls — list artifacts for current project (or all).
+
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import { loadIndex, type IndexEntry } from "../../storage/index-cache.ts";
+import { deriveProjectIdentity } from "../../storage/paths.ts";
+
+export interface LsContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  cwd: string;
+  loadConfig?: () => CesiumConfig;
+}
+
+function defaultCtx(): LsContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    cwd: process.cwd(),
+  };
+}
+
+/** Truncate a string to maxLen, appending "…" if truncated. */
+function trunc(s: string, maxLen: number): string {
+  if (s.length <= maxLen) return s;
+  return s.slice(0, maxLen - 1) + "…";
+}
+
+/** Format an ISO date as "YYYY-MM-DDTHH:MM:SS" (no ms, no tz suffix). */
+function fmtDate(iso: string): string {
+  return iso.slice(0, 19);
+}
+
+/** Derive SUPER column value for an entry. */
+function superCol(entry: IndexEntry): string {
+  const parts: string[] = [];
+  if (entry.supersededBy !== null) {
+    parts.push(`→ ${entry.supersededBy.slice(0, 6)}`);
+  }
+  if (entry.supersedes !== null) {
+    parts.push(`← ${entry.supersedes.slice(0, 6)}`);
+  }
+  return parts.join(" ");
+}
+
+function getGitRemote(cwd: string): string | null {
+  try {
+    const result = execSync("git config --get remote.origin.url", {
+      cwd,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return result || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function lsCommand(argv: string[], ctx?: Partial<LsContext>): Promise<number> {
+  const resolved: LsContext = { ...defaultCtx(), ...ctx };
+
+  let values: {
+    all: boolean;
+    json: boolean;
+    limit: string | undefined;
+    help: boolean;
+  };
+
+  try {
+    const parsed = parseArgs({
+      args: argv,
+      options: {
+        all: { type: "boolean", short: "a", default: false },
+        json: { type: "boolean", default: false },
+        limit: { type: "string", short: "n" },
+        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 ls: ${e.message}\n`);
+    resolved.stderr.write(`Usage: cesium ls [--all] [--json] [--limit N]\n`);
+    return 1;
+  }
+
+  if (values.help) {
+    resolved.stdout.write(
+      [
+        "Usage: cesium ls [options]",
+        "",
+        "Options:",
+        "  --all, -a      Show artifacts for all projects (default: current project only)",
+        "  --json         Output as JSON array",
+        "  --limit, -n N  Show at most N most recent artifacts (default: 50)",
+        "  --help, -h     Show this help message",
+        "",
+      ].join("\n"),
+    );
+    return 0;
+  }
+
+  const limitRaw = values.limit !== undefined ? parseInt(values.limit, 10) : 50;
+  if (isNaN(limitRaw) || limitRaw < 1) {
+    resolved.stderr.write(`cesium ls: --limit must be a positive integer\n`);
+    return 1;
+  }
+  const limit = limitRaw;
+
+  // Load config
+  const cfg = (resolved.loadConfig ?? loadConfig)();
+
+  // Determine which index.json to read
+  let jsonPath: string;
+  if (values.all) {
+    jsonPath = join(cfg.stateDir, "index.json");
+  } else {
+    const gitRemote = getGitRemote(resolved.cwd);
+    const identity = deriveProjectIdentity({ cwd: resolved.cwd, gitRemote });
+    jsonPath = join(cfg.stateDir, "projects", identity.slug, "index.json");
+  }
+
+  let entries: IndexEntry[];
+  try {
+    entries = await loadIndex(jsonPath);
+  } catch (err) {
+    const e = err as Error;
+    resolved.stderr.write(`cesium ls: failed to read index: ${e.message}\n`);
+    return 1;
+  }
+
+  // Already sorted newest-first by loadIndex / appendEntry; apply limit
+  const limited = entries.slice(0, limit);
+
+  if (values.json) {
+    resolved.stdout.write(JSON.stringify(limited, null, 2) + "\n");
+    return 0;
+  }
+
+  // Table output
+  if (limited.length === 0) {
+    resolved.stdout.write("No artifacts found.\n");
+    return 0;
+  }
+
+  const COL_ID = 6;
+  const COL_KIND = 10;
+  const COL_TITLE = 37;
+  const COL_DATE = 19;
+
+  const header =
+    "ID".padEnd(COL_ID) +
+    "  " +
+    "KIND".padEnd(COL_KIND) +
+    "  " +
+    "TITLE".padEnd(COL_TITLE) +
+    "  " +
+    "CREATED".padEnd(COL_DATE) +
+    "  " +
+    "SUPER";
+
+  const sep = "─".repeat(header.length);
+
+  resolved.stdout.write(header + "\n");
+  resolved.stdout.write(sep + "\n");
+
+  for (const e of limited) {
+    const row =
+      e.id.slice(0, COL_ID).padEnd(COL_ID) +
+      "  " +
+      trunc(e.kind, COL_KIND).padEnd(COL_KIND) +
+      "  " +
+      trunc(e.title, COL_TITLE).padEnd(COL_TITLE) +
+      "  " +
+      fmtDate(e.createdAt).padEnd(COL_DATE) +
+      "  " +
+      superCol(e);
+    resolved.stdout.write(row + "\n");
+  }
+
+  return 0;
+}

package/src/cli/commands/open.ts

@@ -0,0 +1,208 @@
+// cesium open — find an artifact by id prefix and open it in the browser.
+
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { loadConfig, type CesiumConfig } from "../../config.ts";
+import { loadIndex } from "../../storage/index-cache.ts";
+import { pathsFor } from "../../storage/paths.ts";
+import {
+  ensureRunning,
+  readPidFile,
+  isAlive,
+  type LifecycleConfig,
+} from "../../server/lifecycle.ts";
+import { resolveDisplayHost } from "../../tools/publish.ts";
+
+export interface OpenContext {
+  stdout: { write: (s: string) => void };
+  stderr: { write: (s: string) => void };
+  loadConfig?: () => CesiumConfig;
+  opener?: (url: string) => Promise<void>;
+  ensureRunning?: (cfg: LifecycleConfig) => Promise<{ port: number; url: string } | null>;
+}
+
+function defaultCtx(): OpenContext {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+  };
+}
+
+/** Default OS-native URL opener. */
+async function defaultOpener(url: string): Promise<void> {
+  const os = platform();
+  let cmd: string;
+  let args: string[];
+
+  if (os === "darwin") {
+    cmd = "open";
+    args = [url];
+  } else if (os === "linux") {
+    cmd = "xdg-open";
+    args = [url];
+  } else {
+    // Windows and others: not supported in v1
+    throw new Error(
+      "cesium open: browser launch is not supported on this platform. Use --print to get the URL.",
+    );
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.unref();
+    child.on("error", reject);
+    child.on("spawn", resolve);
+  });
+}
+
+/** Try to resolve an http URL for the artifact. Returns null if server unavailable. */
+async function tryGetHttpUrl(
+  cfg: CesiumConfig,
+  serverPath: string,
+  runEnsureRunning: (cfg: LifecycleConfig) => Promise<{ port: number; url: string } | null>,
+): Promise<string | null> {
+  // First check existing PID file (fast path — no new server start needed for `open`)
+  const pidFilePath = join(cfg.stateDir, ".server.pid");
+  const pidContent = readPidFile(pidFilePath);
+  if (pidContent !== null && isAlive(pidContent.pid)) {
+    const displayHost = resolveDisplayHost(pidContent.hostname);
+    return `http://${displayHost}:${pidContent.port}${serverPath}`;
+  }
+
+  // Try to start server
+  try {
+    const info = await runEnsureRunning({
+      stateDir: cfg.stateDir,
+      port: cfg.port,
+      portMax: cfg.portMax,
+      idleTimeoutMs: cfg.idleTimeoutMs,
+      hostname: cfg.hostname,
+    });
+    if (info !== null) {
+      const displayHost = resolveDisplayHost(cfg.hostname);
+      return `http://${displayHost}:${info.port}${serverPath}`;
+    }
+  } catch {
+    // server failed to start — fall back to file://
+  }
+  return null;
+}
+
+export async function openCommand(argv: string[], ctx?: Partial<OpenContext>): Promise<number> {
+  const resolved: OpenContext = { ...defaultCtx(), ...ctx };
+
+  let values: { print: boolean; help: boolean };
+  let positionals: string[];
+
+  try {
+    const parsed = parseArgs({
+      args: argv,
+      options: {
+        print: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    values = parsed.values as typeof values;
+    positionals = parsed.positionals;
+  } catch (err) {
+    const e = err as Error;
+    resolved.stderr.write(`cesium open: ${e.message}\n`);
+    resolved.stderr.write(`Usage: cesium open <id-prefix> [--print]\n`);
+    return 1;
+  }
+
+  if (values.help) {
+    resolved.stdout.write(
+      [
+        "Usage: cesium open <id-prefix> [options]",
+        "",
+        "Options:",
+        "  --print     Print the URL instead of opening in the browser",
+        "  --help, -h  Show this help message",
+        "",
+        "Notes:",
+        "  Browser launch is supported on macOS (open) and Linux (xdg-open).",
+        "  On Windows, use --print to get the URL.",
+        "",
+      ].join("\n"),
+    );
+    return 0;
+  }
+
+  const idPrefix = positionals[0];
+  if (idPrefix === undefined || idPrefix.length === 0) {
+    resolved.stderr.write(`cesium open: missing required argument <id-prefix>\n`);
+    resolved.stderr.write(`Usage: cesium open <id-prefix> [--print]\n`);
+    return 1;
+  }
+
+  const prefixLower = idPrefix.toLowerCase();
+
+  const cfg = (resolved.loadConfig ?? loadConfig)();
+
+  // Search global index for matches
+  const globalJsonPath = join(cfg.stateDir, "index.json");
+  let allEntries;
+  try {
+    allEntries = await loadIndex(globalJsonPath);
+  } catch (err) {
+    const e = err as Error;
+    resolved.stderr.write(`cesium open: failed to read index: ${e.message}\n`);
+    return 1;
+  }
+
+  const matches = allEntries.filter((e) => e.id.toLowerCase().startsWith(prefixLower));
+
+  if (matches.length === 0) {
+    resolved.stderr.write(`cesium open: no artifact found with id prefix "${idPrefix}"\n`);
+    return 1;
+  }
+
+  if (matches.length > 1) {
+    resolved.stderr.write(
+      `cesium open: ambiguous prefix "${idPrefix}" — ${matches.length} matches:\n`,
+    );
+    for (const m of matches) {
+      resolved.stderr.write(`  ${m.id}  ${m.title}  (${m.kind})\n`);
+    }
+    return 2;
+  }
+
+  const entry = matches[0];
+  if (entry === undefined) {
+    // Unreachable: guarded by matches.length === 1, but satisfies the type checker
+    resolved.stderr.write(`cesium open: internal error — no match\n`);
+    return 1;
+  }
+  const paths = pathsFor({
+    stateDir: cfg.stateDir,
+    projectSlug: entry.projectSlug,
+    filename: entry.filename,
+  });
+
+  // Resolve URL
+  const runEnsureRunning = resolved.ensureRunning ?? ensureRunning;
+  const httpUrl = await tryGetHttpUrl(cfg, paths.serverPath, runEnsureRunning);
+  const url = httpUrl ?? paths.fileUrl;
+
+  if (values.print) {
+    resolved.stdout.write(url + "\n");
+    return 0;
+  }
+
+  const open = resolved.opener ?? defaultOpener;
+  try {
+    await open(url);
+  } catch (err) {
+    const e = err as Error;
+    resolved.stderr.write(`cesium open: ${e.message}\n`);
+    resolved.stdout.write(`URL: ${url}\n`);
+    return 1;
+  }
+
+  return 0;
+}