@cfbender/cesium 0.5.0 → 0.5.2

package/src/server/lifecycle.ts

@@ -2,7 +2,10 @@
 
 import { join } from "node:path";
 import { readFileSync, unlinkSync } from "node:fs";
-import { unlink, writeFile } from "node:fs/promises";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
 import { startServer, type ServerHandle } from "./http.ts";
 import { acquireLock } from "../storage/lock.ts";
 import { createApiHandler } from "./api.ts";
@@ -202,8 +205,19 @@ export async function stopRunning(stateDir: string): Promise<void> {
   }
 }
 
-export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo> {
-  const { stateDir, port, portMax, idleTimeoutMs, hostname = "127.0.0.1", theme = defaultTheme() } = cfg;
+// ─── In-process (foreground) server start ────────────────────────────────────
+// Used by `cesium serve` CLI. Runs Bun.serve() in-process; killing the process
+// IS stopping the server, which is the user's intent for a foreground invocation.
+
+export async function runServerForeground(cfg: LifecycleConfig): Promise<RunningInfo> {
+  const {
+    stateDir,
+    port,
+    portMax,
+    idleTimeoutMs,
+    hostname = "127.0.0.1",
+    theme = defaultTheme(),
+  } = cfg;
   const pidFilePath = join(stateDir, ".server.pid");
   const lockPath = join(stateDir, ".server-start.lock");
 
@@ -310,6 +324,177 @@ export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo>
   }
 }
 
+// ─── Detached (lazy) server start ────────────────────────────────────────────
+// Used by plugin callers (publish, ask). Spawns `cesium serve` as a detached
+// subprocess so the subprocess PID is what ends up in the PID file. Sending a
+// signal to that PID kills only the server child, never the plugin host.
+
+// Locate CLI entry relative to this file: src/server/lifecycle.ts → src/cli/index.ts
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_ENTRY = join(HERE, "..", "cli", "index.ts");
+
+// Readiness poll backoff schedule (ms between attempts)
+const POLL_SCHEDULE = [50, 100, 200, 500, 1000, 1000, 1000, 1000, 1000, 1000];
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function httpProbe(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
+    // Any HTTP response (even 404) means the server is up
+    return res.status < 600;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureServerRunning(cfg: LifecycleConfig): Promise<RunningInfo> {
+  const { stateDir, port, idleTimeoutMs } = cfg;
+  const pidFilePath = join(stateDir, ".server.pid");
+  // Use a separate lock from runServerForeground's ".server-start.lock" to avoid
+  // deadlock: the child process runs runServerForeground which acquires that lock,
+  // so the parent must not hold it while waiting for the child.
+  const spawnLockPath = join(stateDir, ".server-spawn.lock");
+
+  // Fast path: read existing PID file and probe liveness
+  const existing = readPidFile(pidFilePath);
+  if (existing !== null && isAlive(existing.pid)) {
+    const probeUrl = `http://${existing.hostname}:${existing.port}/`;
+    const alive = await httpProbe(probeUrl);
+    if (alive) {
+      return {
+        port: existing.port,
+        url: `http://${existing.hostname}:${existing.port}`,
+        pid: existing.pid,
+        startedAt: existing.startedAt,
+      };
+    }
+    // Process alive but not responding — fall through to spawn fresh
+  }
+
+  // Ensure state dir exists before trying to acquire lock or write files
+  await mkdir(stateDir, { recursive: true });
+
+  // Use a spawn-only lock to prevent concurrent spawns. Release it immediately
+  // after spawning so the child can acquire its own (.server-start.lock) lock.
+  const spawnLock = await acquireLock({
+    lockPath: spawnLockPath,
+    timeoutMs: 15_000,
+    staleMs: 30_000,
+  });
+  try {
+    // Re-check after acquiring lock
+    const existingAfterLock = readPidFile(pidFilePath);
+    if (existingAfterLock !== null && isAlive(existingAfterLock.pid)) {
+      const probeUrl = `http://${existingAfterLock.hostname}:${existingAfterLock.port}/`;
+      const alive = await httpProbe(probeUrl);
+      if (alive) {
+        return {
+          port: existingAfterLock.port,
+          url: `http://${existingAfterLock.hostname}:${existingAfterLock.port}`,
+          pid: existingAfterLock.pid,
+          startedAt: existingAfterLock.startedAt,
+        };
+      }
+    }
+
+    // Clean up stale PID file if present
+    try {
+      await unlink(pidFilePath);
+    } catch {
+      // ENOENT is fine
+    }
+
+    // Build spawn args — rely on env vars for config; CLI flags as defense in depth.
+    // portMax is not a serve flag; the child will scan ports starting from `port`.
+    // Port 0 means "auto-assign" — the CLI flag rejects 0, so rely on CESIUM_PORT=0 env var.
+    const spawnArgs: string[] = ["run", CLI_ENTRY, "serve", "--state-dir", stateDir];
+    if (port > 0) {
+      spawnArgs.push("--port", String(port));
+    }
+    // Pass idle timeout so the detached child self-terminates on inactivity.
+    // Serve command defaults to 0 (never) for foreground use; we override for daemon mode.
+    if (idleTimeoutMs > 0) {
+      spawnArgs.push("--idle-timeout", String(idleTimeoutMs));
+    }
+
+    const child = spawn("bun", spawnArgs, {
+      detached: true,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        CESIUM_STATE_DIR: stateDir,
+        CESIUM_PORT: String(port),
+      },
+    });
+
+    // Unref so the parent can exit without waiting for the child
+    child.unref();
+
+    if (child.pid === undefined) {
+      throw new Error("cesium: failed to spawn server subprocess (no PID assigned)");
+    }
+  } finally {
+    // Release spawn lock immediately — the child needs to acquire its own lock
+    // (.server-start.lock via runServerForeground). Holding the spawn lock any
+    // longer would deadlock the child.
+    await spawnLock.release();
+  }
+
+  // Wait for the child to write its PID file and respond to HTTP.
+  // This polling happens OUTSIDE the spawn lock so the child can run freely.
+  const deadline = Date.now() + 10_000;
+  let lastError = "timeout";
+  let scheduleIdx = 0;
+
+  while (Date.now() < deadline) {
+    const waitMs = POLL_SCHEDULE[scheduleIdx] ?? 1000;
+    scheduleIdx = Math.min(scheduleIdx + 1, POLL_SCHEDULE.length - 1);
+    await sleep(waitMs);
+
+    const pidContent = readPidFile(pidFilePath);
+    if (pidContent !== null && isAlive(pidContent.pid)) {
+      const probeUrl = `http://${pidContent.hostname}:${pidContent.port}/`;
+      const alive = await httpProbe(probeUrl);
+      if (alive) {
+        return {
+          port: pidContent.port,
+          url: `http://${pidContent.hostname}:${pidContent.port}`,
+          pid: pidContent.pid,
+          startedAt: pidContent.startedAt,
+        };
+      }
+      lastError = `pid ${pidContent.pid} alive but not yet responding on port ${pidContent.port}`;
+    } else if (pidContent !== null) {
+      lastError = `pid ${pidContent.pid} in PID file is not alive`;
+    } else {
+      lastError = "PID file not yet written";
+    }
+  }
+
+  // Timeout — try to clean up the spawned process
+  const staleContent = readPidFile(pidFilePath);
+  if (staleContent !== null && isAlive(staleContent.pid)) {
+    try {
+      process.kill(staleContent.pid, "SIGTERM");
+    } catch {
+      // best-effort
+    }
+  }
+
+  throw new Error(
+    `cesium: timed out waiting for server to start in ${stateDir} (last: ${lastError})`,
+  );
+}
+
+// ─── Backward-compat alias ────────────────────────────────────────────────────
+// Internal callers have been updated to use runServerForeground or ensureServerRunning.
+// Keep ensureRunning exported for any external consumers that haven't migrated.
+
+export { runServerForeground as ensureRunning };
+
 // ─── Test reset hook ──────────────────────────────────────────────────────────
 // This function is intended for test use only. It clears module-level singleton
 // state, stops any running server, and removes signal/exit listeners.

package/src/storage/index-gen.ts

@@ -236,9 +236,8 @@ function indexJs(): string {
 function renderEntryCard(entry: IndexEntry): string {
   const isSuperseded = entry.supersededBy !== null ? "1" : "0";
   const kindPill = `<span class="pill">${esc(entry.kind)}</span>`;
-  const inputModeBadge = entry.inputMode !== undefined
-    ? ` <span class="tag">${esc(entry.inputMode)}</span>`
-    : "";
+  const inputModeBadge =
+    entry.inputMode !== undefined ? ` <span class="tag">${esc(entry.inputMode)}</span>` : "";
   const dateStr = `<span class="card-date">${esc(formatDate(entry.createdAt))}</span>`;
   const supersededBadge =
     entry.supersedes !== null

package/src/tools/ask.ts

@@ -20,7 +20,7 @@ import { withLock } from "../storage/lock.ts";
 import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
 import { buildProjectSummaries } from "../storage/project-summaries.ts";
 import {
-  ensureRunning as defaultEnsureRunning,
+  ensureServerRunning as defaultEnsureServerRunning,
   type RunningInfo,
   type LifecycleConfig,
 } from "../server/lifecycle.ts";
@@ -58,7 +58,7 @@ export function createAskTool(
   const resolveConfig = overrides?.loadConfig ?? loadConfig;
   const now = overrides?.now ?? (() => new Date());
   const genId = overrides?.nanoid ?? defaultNanoid;
-  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureRunning;
+  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureServerRunning;
 
   return tool({
     description: TOOL_DESCRIPTION,

package/src/tools/publish.ts

@@ -11,6 +11,7 @@ import { extractTextContent } from "../render/extract.ts";
 import { themeFromPreset, mergeTheme } from "../render/theme.ts";
 import { validatePublishInput, htmlBodyWarnings, PUBLISH_KINDS } from "../render/validate.ts";
 import { renderBlocks } from "../render/blocks/render.ts";
+import { resolveHighlightTheme } from "../render/blocks/highlight.ts";
 import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite, patchEmbeddedMetadata } from "../storage/write.ts";
@@ -27,7 +28,7 @@ import { withLock } from "../storage/lock.ts";
 import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
 import { buildProjectSummaries } from "../storage/project-summaries.ts";
 import {
-  ensureRunning as defaultEnsureRunning,
+  ensureServerRunning as defaultEnsureServerRunning,
   type RunningInfo,
   type LifecycleConfig,
 } from "../server/lifecycle.ts";
@@ -106,7 +107,7 @@ export function createPublishTool(
   const resolveConfig = overrides?.loadConfig ?? loadConfig;
   const now = overrides?.now ?? (() => new Date());
   const genId = overrides?.nanoid ?? defaultNanoid;
-  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureRunning;
+  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureServerRunning;
 
   return tool({
     description: TOOL_DESCRIPTION,
@@ -116,9 +117,7 @@ export function createPublishTool(
       html: tool.schema
         .string()
         .optional()
-        .describe(
-          "Body HTML — escape valve / legacy mode. Provide exactly one of html or blocks.",
-        ),
+        .describe("Body HTML — escape valve / legacy mode. Provide exactly one of html or blocks."),
       blocks: tool.schema
         .array(tool.schema.any())
         .optional()
@@ -193,7 +192,8 @@ export function createPublishTool(
 
       if (input.blocks !== undefined) {
         // Blocks path: render structured blocks → trusted HTML
-        bodyHtml = renderBlocks(input.blocks);
+        const highlightTheme = resolveHighlightTheme(config.themePreset);
+        bodyHtml = await renderBlocks(input.blocks, { highlightTheme });
       } else {
         // HTML path: scrub agent-supplied HTML
         const scrubbed = scrub(input.html);

package/src/tools/styleguide.ts

@@ -8,7 +8,7 @@ import type { RenderCtx, SectionCounter } from "../render/blocks/render.ts";
 
 function makeCtx(): RenderCtx {
   const counter: SectionCounter = { value: 1 };
-  return { sectionCounter: counter, depth: 0, path: "blocks[0]" };
+  return { sectionCounter: counter, depth: 0, path: "blocks[0]", highlightTheme: "claret-dark" };
 }
 
 /** Escape a string for safe insertion inside a markdown fenced code block. */
@@ -18,7 +18,7 @@ function escapeForCodeFence(s: string): string {
 }
 
 /** Generate the full markdown reference from the catalog. Deterministic — same catalog → same output. */
-export function generateStyleguideMarkdown(): string {
+export async function generateStyleguideMarkdown(): Promise<string> {
   const lines: string[] = [];
 
   lines.push("# Cesium publishing reference");
@@ -40,8 +40,26 @@ export function generateStyleguideMarkdown(): string {
   lines.push("## Block reference");
   lines.push("");
 
-  for (const blockType of blockTypes) {
+  // Pre-render all examples in parallel (order preserved via index)
+  const renderedExamples = await Promise.all(
+    blockTypes.map(async (blockType) => {
+      const entry = blockCatalog[blockType];
+      if (entry.renderedExample !== undefined) {
+        return entry.renderedExample;
+      }
+      try {
+        return await renderBlock(entry.example, makeCtx());
+      } catch {
+        return "";
+      }
+    }),
+  );
+
+  for (let i = 0; i < blockTypes.length; i++) {
+    const blockType = blockTypes[i];
+    if (blockType === undefined) continue;
     const entry = blockCatalog[blockType];
+    const rendered = renderedExamples[i] ?? "";
 
     lines.push(`### \`${entry.type}\``);
     lines.push("");
@@ -62,15 +80,6 @@ export function generateStyleguideMarkdown(): string {
     lines.push("```");
     lines.push("");
 
-    // Rendered HTML
-    const rendered = entry.renderedExample ?? (() => {
-      try {
-        return renderBlock(entry.example, makeCtx());
-      } catch {
-        return "";
-      }
-    })();
-
     if (rendered !== "") {
       lines.push("Renders to:");
       lines.push("");
@@ -92,21 +101,17 @@ export function generateStyleguideMarkdown(): string {
     "- Inline: `**bold**`, `*italic*`, `` `code` ``, `[text](href)` (relative or anchor only).",
   );
   lines.push(
-    "- HTML safelist: `<kbd>`, `<span class=\"pill\">`, `<span class=\"tag\">`. Anything else is escaped.",
+    '- HTML safelist: `<kbd>`, `<span class="pill">`, `<span class="tag">`. Anything else is escaped.',
   );
   lines.push("");
   lines.push("## When to reach for raw_html / diagram");
   lines.push("");
-  lines.push(
-    "- `diagram` — inline SVG visualizations or bespoke composed HTML diagrams.",
-  );
+  lines.push("- `diagram` — inline SVG visualizations or bespoke composed HTML diagrams.");
   lines.push(
     "- `raw_html` — anything genuinely creative that doesn't fit a known block type." +
       " Include a `purpose` string describing what you're building.",
   );
-  lines.push(
-    "- Critique flags raw_html overuse (>2 blocks or >30% of body characters).",
-  );
+  lines.push("- Critique flags raw_html overuse (>2 blocks or >30% of body characters).");
 
   return lines.join("\n");
 }
@@ -117,7 +122,7 @@ export function createStyleguideTool(_ctx: PluginInput): ReturnType<typeof tool>
       "Returns the cesium HTML design system reference page (CSS classes with example usage). Call this once at the start of writing a complex artifact to internalize the available components.",
     args: {},
     async execute(_args, _context) {
-      return generateStyleguideMarkdown();
+      return await generateStyleguideMarkdown();
     },
   });
 }