@cfbender/cesium 0.6.1 → 0.7.0

package/src/tools/annotate.ts

@@ -0,0 +1,336 @@
+// Tool handler for cesium_annotate — publishes an interactive review artifact.
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { loadConfig, type CesiumConfig } from "../config.ts";
+import { extractTextContent } from "../render/extract.ts";
+import { themeFromPreset, mergeTheme } from "../render/theme.ts";
+import { validateAnnotateInput, validateBlocksArray } 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 type { InteractiveData } from "../render/validate.ts";
+import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
+import { atomicWrite } from "../storage/write.ts";
+import { ensureThemeCss } from "../storage/assets.ts";
+import { writeFaviconSvg } from "../storage/favicon-write.ts";
+import { loadIndex, writeIndex, appendEntry, type IndexEntry } from "../storage/index-cache.ts";
+import { withLock } from "../storage/lock.ts";
+import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
+import { buildProjectSummaries } from "../storage/project-summaries.ts";
+import {
+  ensureServerRunning as defaultEnsureServerRunning,
+  type RunningInfo,
+  type LifecycleConfig,
+} from "../server/lifecycle.ts";
+import { buildTerminalSummary, resolveDisplayHost } from "./publish.ts";
+
+export interface AnnotateToolOverrides {
+  loadConfig?: () => CesiumConfig;
+  now?: () => Date;
+  nanoid?: () => string;
+  ensureRunning?: (cfg: LifecycleConfig) => Promise<RunningInfo | null>;
+}
+
+const TOOL_DESCRIPTION = `cesium_annotate — Publish an interactive review artifact where the user can leave
+per-line and per-block comments, plus a final verdict (Approve / Request changes / Comment).
+
+Use this when reviewing diffs, plans, PRDs, code proposals, RFCs, audits, or design docs —
+any content where chat-based feedback would be lossy. The artifact is a self-contained .html
+file with a comment rail and a sticky verdict footer.
+
+When NOT to use:
+- Short yes/no approvals → use cesium_ask with a react question instead.
+- One-way broadcasts with no feedback needed → use cesium_publish.
+
+Workflow:
+1. Call cesium_annotate → get back { id, filePath, fileUrl, httpUrl, terminalSummary }.
+2. Call cesium_wait with the returned id to block until the user finishes their review.
+3. If the user requests changes, revise and publish a new cesium_annotate (or cesium_publish)
+   with supersedes pointing at the prior id.
+
+Arguments:
+- title: descriptive title (3–8 words).
+- blocks: array of structured content blocks — all reviewable content lives here.
+  Call cesium_styleguide for the full block catalog.
+- verdictMode: "approve" | "approve-or-reject" | "full" (default: "full").
+  "full" exposes Approve / Request changes / Comment buttons.
+- perLineFor: block types that get per-line comment anchors (default: ["diff", "code"]).
+- requireVerdict: whether the user must submit a verdict before completing (default: true).
+- summary, tags, expiresAt: same semantics as cesium_publish.`;
+
+export function createAnnotateTool(
+  ctx: PluginInput,
+  overrides?: AnnotateToolOverrides,
+): ReturnType<typeof tool> {
+  const resolveConfig = overrides?.loadConfig ?? loadConfig;
+  const now = overrides?.now ?? (() => new Date());
+  const genId = overrides?.nanoid ?? defaultNanoid;
+  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureServerRunning;
+
+  return tool({
+    description: TOOL_DESCRIPTION,
+    args: {
+      title: tool.schema.string(),
+      blocks: tool.schema.array(tool.schema.any()),
+      verdictMode: tool.schema
+        .enum(["approve", "approve-or-reject", "full"] as [string, ...string[]])
+        .optional(),
+      perLineFor: tool.schema.array(tool.schema.string()).optional(),
+      requireVerdict: tool.schema.boolean().optional(),
+      summary: tool.schema.string().optional(),
+      tags: tool.schema.array(tool.schema.string()).optional(),
+      expiresAt: tool.schema.string().optional(),
+    },
+    async execute(args, _context) {
+      // 1. Validate top-level input shape
+      const validation = validateAnnotateInput(args);
+      if (!validation.ok) {
+        return `Error: ${validation.error}`;
+      }
+      const input = validation.value;
+
+      // 2. Deep-validate block contents
+      const blocksValidation = validateBlocksArray(input.blocks);
+      if (!blocksValidation.ok) {
+        const errorMessages = blocksValidation.errors
+          .map((e) => `${e.path}: ${e.message}`)
+          .join("; ");
+        return `Error: blocks validation failed — ${errorMessages}`;
+      }
+
+      // 3. Load config
+      const config = resolveConfig();
+
+      // 4. Probe git state
+      const shell = ctx.$.cwd(ctx.directory).nothrow();
+      let gitRemote: string | null = null;
+      let gitBranch: string | null = null;
+      let gitCommit: string | null = null;
+
+      try {
+        const remoteResult = await shell`git config --get remote.origin.url`.quiet();
+        if (remoteResult.exitCode === 0) {
+          gitRemote = remoteResult.text().trim() || null;
+        }
+      } catch {
+        // not a git repo or no remote
+      }
+
+      try {
+        const branchResult = await shell`git rev-parse --abbrev-ref HEAD`.quiet();
+        if (branchResult.exitCode === 0) {
+          gitBranch = branchResult.text().trim() || null;
+        }
+      } catch {
+        // not a git repo
+      }
+
+      try {
+        const commitResult = await shell`git rev-parse HEAD`.quiet();
+        if (commitResult.exitCode === 0) {
+          gitCommit = commitResult.text().trim() || null;
+        }
+      } catch {
+        // not a git repo
+      }
+
+      // 5. Derive project identity
+      const identity = deriveProjectIdentity({
+        cwd: ctx.directory,
+        gitRemote,
+        worktree: ctx.worktree ?? null,
+      });
+
+      // 6. Generate id + timestamps
+      const id = genId();
+      const createdAt = now();
+
+      // 7. Defaults
+      const expiresAt =
+        input.expiresAt ?? new Date(createdAt.getTime() + 24 * 60 * 60 * 1000).toISOString();
+      const requireVerdict = input.requireVerdict ?? true;
+      const verdictMode = input.verdictMode ?? "full";
+      const perLineFor = input.perLineFor ?? ["diff", "code"];
+
+      // 8. Render blocks → trusted HTML (do NOT scrub — templated output is trusted)
+      const highlightTheme = resolveHighlightTheme(config.themePreset);
+      const bodyHtml = await renderBlocks(input.blocks, { highlightTheme });
+
+      // 8a. Extract body text for full-text search
+      const bodyText = extractTextContent(bodyHtml);
+
+      // 9. Content SHA-256 over the rendered HTML
+      const contentSha256 = createHash("sha256").update(bodyHtml).digest("hex");
+
+      // 10. Compute filename + paths
+      const filename = artifactFilename({ title: input.title, id, createdAt });
+      const paths = pathsFor({
+        stateDir: config.stateDir,
+        projectSlug: identity.slug,
+        filename,
+      });
+
+      // 11. Build ArtifactMeta
+      const meta: ArtifactMeta = {
+        id,
+        title: input.title,
+        kind: "annotate",
+        summary: input.summary ?? null,
+        tags: input.tags ?? [],
+        createdAt: createdAt.toISOString(),
+        model: null,
+        sessionId: null,
+        projectSlug: identity.slug,
+        projectName: identity.name,
+        cwd: ctx.directory,
+        worktree: identity.worktree,
+        gitBranch,
+        gitCommit,
+        supersedes: null,
+        supersededBy: null,
+        contentSha256,
+      };
+
+      // 12. Build interactive data
+      const interactive: InteractiveData = {
+        kind: "annotate",
+        status: "open",
+        expiresAt,
+        verdictMode,
+        requireVerdict,
+        perLineFor,
+        comments: [],
+        verdict: null,
+      };
+
+      // 13. Build theme + ensure theme.css and favicon
+      const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
+      await ensureThemeCss(config.stateDir, theme);
+      await writeFaviconSvg(config.stateDir);
+
+      // 14. Wrap document
+      const fullHtml = wrapDocument({
+        body: bodyHtml,
+        meta,
+        theme,
+        warnings: [],
+        themeCssHref: "../../../theme.css",
+        interactive,
+      });
+
+      // 15. Atomic write
+      await atomicWrite(paths.artifactPath, fullHtml);
+
+      // 16. Build IndexEntry
+      const entry: IndexEntry = {
+        id: meta.id,
+        title: meta.title,
+        kind: meta.kind,
+        summary: meta.summary,
+        tags: meta.tags,
+        createdAt: meta.createdAt,
+        filename,
+        supersedes: null,
+        supersededBy: null,
+        gitBranch: meta.gitBranch,
+        gitCommit: meta.gitCommit,
+        contentSha256: meta.contentSha256,
+        projectSlug: identity.slug,
+        projectName: identity.name,
+        bodyText,
+      };
+
+      const lockPath = join(config.stateDir, ".index.lock");
+
+      await withLock({ lockPath }, async () => {
+        // 17. Update per-project index
+        const projectEntries = await loadIndex(paths.projectIndexJsonPath);
+        const updatedProjectEntries = appendEntry(projectEntries, entry);
+        await writeIndex(paths.projectIndexJsonPath, updatedProjectEntries);
+
+        // 18. Update global index
+        const globalEntries = await loadIndex(paths.globalIndexJsonPath);
+        const updatedGlobalEntries = appendEntry(globalEntries, entry);
+        await writeIndex(paths.globalIndexJsonPath, updatedGlobalEntries);
+
+        // 19. Render and write project index.html
+        const latestProjectEntries = await loadIndex(paths.projectIndexJsonPath);
+        const projectIndexHtml = renderProjectIndex({
+          projectSlug: identity.slug,
+          projectName: identity.name,
+          entries: latestProjectEntries,
+          theme,
+          themeCssHref: "../../theme.css",
+        });
+        await atomicWrite(paths.projectIndexPath, projectIndexHtml);
+
+        // 20. Render and write global index.html
+        const latestGlobalEntries = await loadIndex(paths.globalIndexJsonPath);
+        const projectSummaries = buildProjectSummaries(latestGlobalEntries);
+        const globalIndexHtml = renderGlobalIndex({
+          projects: projectSummaries,
+          theme,
+          themeCssHref: "theme.css",
+        });
+        await atomicWrite(paths.globalIndexPath, globalIndexHtml);
+      });
+
+      // 21. Start server (best-effort) and build URLs
+      let httpUrl: string | null = null;
+      let serverInfo: RunningInfo | null = null;
+
+      try {
+        const maybeInfo = await runEnsureRunning({
+          stateDir: config.stateDir,
+          port: config.port,
+          portMax: config.portMax,
+          idleTimeoutMs: config.idleTimeoutMs,
+          hostname: config.hostname,
+          theme,
+        });
+        if (maybeInfo !== null) {
+          serverInfo = maybeInfo;
+          const liveDisplay = resolveDisplayHost(config.hostname);
+          httpUrl = `http://${liveDisplay}:${serverInfo.port}${paths.serverPath}`;
+        }
+      } catch {
+        httpUrl = null;
+      }
+
+      const terminalSummary = buildTerminalSummary({
+        title: input.title,
+        kind: "annotate",
+        httpUrl: httpUrl ?? paths.fileUrl,
+        fileUrl: paths.fileUrl,
+        isSsh: Boolean(process.env["SSH_CONNECTION"]),
+        port: serverInfo?.port ?? config.port,
+      });
+
+      // 22. Return result
+      const result = {
+        id,
+        filePath: paths.artifactPath,
+        fileUrl: paths.fileUrl,
+        httpUrl,
+        terminalSummary,
+      };
+
+      return JSON.stringify(result, null, 2);
+    },
+  });
+}
+
+// Default nanoid implementation using built-in crypto for alphanumeric IDs
+function defaultNanoid(): string {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const bytes = new Uint8Array(6);
+  crypto.getRandomValues(bytes);
+  let result = "";
+  for (const byte of bytes) {
+    result += alphabet[byte % alphabet.length];
+  }
+  return result;
+}

package/src/tools/ask.ts

@@ -8,7 +8,7 @@ import { loadConfig, type CesiumConfig } from "../config.ts";
 import { scrub } from "../render/scrub.ts";
 import { extractTextContent } from "../render/extract.ts";
 import { themeFromPreset, mergeTheme } from "../render/theme.ts";
-import { validateAskInput, htmlBodyWarnings } from "../render/validate.ts";
+import { validateAskInput } from "../render/validate.ts";
 import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import type { InteractiveData } from "../render/validate.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
@@ -204,11 +204,11 @@ export function createAskTool(
         supersedes: null,
         supersededBy: null,
         contentSha256,
-        inputMode: "html",
       };
 
       // 12. Build interactive data
       const interactive: InteractiveData = {
+        kind: "ask",
         status: "open",
         requireAll,
         expiresAt,
@@ -221,10 +221,6 @@ export function createAskTool(
       if (scrubbed.removed.length > 0) {
         warnings.push(`Removed ${scrubbed.removed.length} external resource(s) during scrub.`);
       }
-      const bodyWarnings = htmlBodyWarnings(scrubbed.html);
-      for (const w of bodyWarnings) {
-        warnings.push(w);
-      }
 
       // 14. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);

package/src/tools/critique.ts

@@ -1,43 +1,34 @@
-// Tool handler for cesium_critique — mode-aware body analyzer.
-// Accepts either { html: string } (html mode) or { blocks: Block[] } (blocks mode). Exactly one required.
+// Tool handler for cesium_critique — analyzes a draft blocks array.
 
 import { tool } from "@opencode-ai/plugin";
 import type { PluginInput } from "@opencode-ai/plugin";
-import {
-  critiqueHtml,
-  critiqueBlocks,
-  type CritiqueResult,
-  type CritiqueSeverity,
-} from "../render/critique.ts";
+import { critique, type CritiqueResult, type CritiqueSeverity } from "../render/critique.ts";
 import type { Block } from "../render/blocks/types.ts";
 
-const TOOL_DESCRIPTION = `Analyze a draft HTML body for adherence to the cesium design
-system before publishing. Returns a 0-100 score and findings (warn/suggest/info).
+const TOOL_DESCRIPTION = `Analyze a draft cesium artifact (blocks array) for adherence to the
+cesium design system before publishing. Returns a 0-100 score and findings (warn/suggest/info).
 
-Call this on complex artifacts (>500 words, plans/comparisons/explainers) BEFORE
-calling cesium_publish. Address warn-level findings; suggest-level findings are
-optional but usually worth applying. info-level findings are FYI.
+Call this on substantive artifacts before \`cesium_publish\`. Address warn-level findings;
+suggest-level findings are optional but usually worth applying. info-level findings are FYI.
 
-The 'html' argument is the same body you'd pass to cesium_publish — body inner
-HTML only, no <!doctype>/<html>/<head>/<body> wrappers.`;
+The 'blocks' argument is the same array you'd pass to cesium_publish.`;
 
 /**
  * Format a CritiqueResult into a concise human-readable string the agent can parse.
  * Format:
  *   score: 87/100
- *   mode: html
  *
  *   warn:
- *   - [external-resource] External resource will be stripped...
+ *   - [raw-html-overuse] raw_html overuse: 3 raw_html blocks...
  *
  *   suggest:
- *   - [no-tldr] Long artifact with no .tldr summary...
+ *   - [missing-tldr] Document has 6 sections but no tldr block...
  *
  *   info:
- *   - [code-without-highlights] Code blocks render without...
+ *   - [code-without-meaningful-lang] Code block at ... uses lang "text"...
  */
 export function formatCritiqueForAgent(result: CritiqueResult): string {
-  const lines: string[] = [`score: ${result.score}/100`, `mode: ${result.mode}`];
+  const lines: string[] = [`score: ${result.score}/100`];
 
   const bySeverity: Record<CritiqueSeverity, typeof result.findings> = {
     warn: [],
@@ -67,34 +58,13 @@ export function createCritiqueTool(_ctx: PluginInput): ReturnType<typeof tool> {
   return tool({
     description: TOOL_DESCRIPTION,
     args: {
-      html: tool.schema.string().optional(),
-      blocks: tool.schema.any().optional(),
+      blocks: tool.schema.any(),
     },
     async execute(args) {
-      const hasHtml = args.html !== undefined && args.html !== null;
-      const hasBlocks = args.blocks !== undefined && args.blocks !== null;
-
-      if (hasHtml && hasBlocks) {
-        return "error: provide exactly one of html or blocks, not both";
-      }
-      if (!hasHtml && !hasBlocks) {
-        return "error: provide exactly one of html or blocks";
-      }
-
-      let result: CritiqueResult;
-
-      if (hasHtml) {
-        if (typeof args.html !== "string") {
-          return "error: html must be a string";
-        }
-        result = critiqueHtml(args.html);
-      } else {
-        if (!Array.isArray(args.blocks)) {
-          return "error: blocks must be an array";
-        }
-        result = critiqueBlocks(args.blocks as Block[]);
+      if (!Array.isArray(args.blocks)) {
+        return "error: blocks must be an array";
       }
-
+      const result = critique(args.blocks as Block[]);
       return formatCritiqueForAgent(result);
     },
   });

package/src/tools/publish.ts

@@ -6,10 +6,9 @@ import { join } from "node:path";
 import { tool } from "@opencode-ai/plugin";
 import type { PluginInput } from "@opencode-ai/plugin";
 import { loadConfig, type CesiumConfig } from "../config.ts";
-import { scrub } from "../render/scrub.ts";
 import { extractTextContent } from "../render/extract.ts";
 import { themeFromPreset, mergeTheme } from "../render/theme.ts";
-import { validatePublishInput, htmlBodyWarnings, PUBLISH_KINDS } from "../render/validate.ts";
+import { validatePublishInput, 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";
@@ -74,29 +73,14 @@ When to stay in the terminal: short factual answers, status updates ("done", "fi
 
 User overrides win: "/cesium" or "publish this" → publish; "in terminal" → don't.
 
-The \`html\` argument is the BODY ONLY — do NOT include <!doctype>, <html>, <head>, <body>.
-The plugin wraps your body with the design system.
-
-Available CSS classes (call cesium_styleguide for full reference + examples):
-- .eyebrow         uppercase mono micro-label above headings
-- .h-display       page-title heading
-- .h-section       section heading paired with .section-num
-- .section-num     numbered chip ("01", "02") next to .h-section
-- .card            bordered surface block (1.5px border, 12px radius)
-- .tldr            clay-bordered summary box (use ONE per doc, near top)
-- .callout         info box; modifiers: .callout.note .callout.warn .callout.risk
-- .code            block-level code panel; inline highlights via .kw .str .cm .fn
-- .timeline        milestone list with dots and connectors
-- .diagram         wraps inline SVG with a caption below
-- .compare-table   bordered comparison grid
-- .risk-table      bordered risk-grid (likelihood/impact/mitigation columns)
-- .kbd .pill .tag  inline chips
-- .byline          rendered automatically as the footer
-
-Inline \`style="..."\` and inline \`<svg>\` are encouraged for bespoke diagrams. NEVER reference
-external resources: no <script src=>, no <link rel=stylesheet href=http>, no remote fonts,
-no remote images. The plugin will silently strip external resources but the artifact will
-look broken in the resulting render.
+Content is described as a \`blocks\` array — a closed set of typed building blocks
+(hero, tldr, section, prose, list, callout, code, diff, timeline, compare_table,
+risk_table, kv, pill_row, divider, diagram, raw_html). Call \`cesium_styleguide\` for
+the full block catalog with schemas and rendered examples.
+
+The \`raw_html\` block is an escape hatch for content that doesn't fit the available
+blocks; \`diagram\` is for inline SVG/HTML visualizations. Both have their payloads
+scrubbed of external resources at publish time.
 
 Title aim: 3-8 words, descriptive. Kind: pick the closest match.`;
 
@@ -114,15 +98,10 @@ export function createPublishTool(
     args: {
       title: tool.schema.string(),
       kind: tool.schema.enum([...PUBLISH_KINDS] as [string, ...string[]]),
-      html: tool.schema
-        .string()
-        .optional()
-        .describe("Body HTML — escape valve / legacy mode. Provide exactly one of html or blocks."),
       blocks: tool.schema
         .array(tool.schema.any())
-        .optional()
         .describe(
-          "Structured block array — preferred for token efficiency. Provide exactly one of html or blocks.",
+          "Structured block array describing the artifact's content. Call cesium_styleguide for the block catalog.",
         ),
       summary: tool.schema.string().optional(),
       tags: tool.schema.array(tool.schema.string()).optional(),
@@ -185,21 +164,9 @@ export function createPublishTool(
       // 6. Timestamps
       const createdAt = now();
 
-      // 7. Render body (blocks path or html path)
-      let bodyHtml: string;
-      let scrubRemovedCount = 0;
-      const inputMode: "html" | "blocks" = input.blocks !== undefined ? "blocks" : "html";
-
-      if (input.blocks !== undefined) {
-        // Blocks path: render structured blocks → trusted HTML
-        const highlightTheme = resolveHighlightTheme(config.themePreset);
-        bodyHtml = await renderBlocks(input.blocks, { highlightTheme });
-      } else {
-        // HTML path: scrub agent-supplied HTML
-        const scrubbed = scrub(input.html);
-        bodyHtml = scrubbed.html;
-        scrubRemovedCount = scrubbed.removed.length;
-      }
+      // 7. Render body from structured blocks
+      const highlightTheme = resolveHighlightTheme(config.themePreset);
+      const bodyHtml = await renderBlocks(input.blocks, { highlightTheme });
 
       // 7a. Extract body text for full-text search
       const bodyText = extractTextContent(bodyHtml);
@@ -234,18 +201,11 @@ export function createPublishTool(
         supersedes: input.supersedes ?? null,
         supersededBy: null,
         contentSha256,
-        inputMode,
       };
 
-      // 11. Build warnings
+      // 11. Build warnings (reserved for future use — block-mode publishes
+      // produce trusted templated output so there is nothing to warn about today).
       const warnings: string[] = [];
-      if (scrubRemovedCount > 0) {
-        warnings.push(`Removed ${scrubRemovedCount} external resource(s) during scrub.`);
-      }
-      const bodyWarnings = input.html !== undefined ? htmlBodyWarnings(bodyHtml) : [];
-      for (const w of bodyWarnings) {
-        warnings.push(w);
-      }
 
       // 12. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
@@ -282,7 +242,7 @@ export function createPublishTool(
         projectSlug: identity.slug,
         projectName: identity.name,
         bodyText,
-        inputMode,
+        inputMode: "blocks",
       };
 
       const lockPath = join(config.stateDir, ".index.lock");

package/src/tools/styleguide.ts

@@ -8,7 +8,13 @@ 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]", highlightTheme: "claret-dark" };
+  return {
+    sectionCounter: counter,
+    depth: 0,
+    path: "blocks[0]",
+    highlightTheme: "claret-dark",
+    anchor: null,
+  };
 }
 
 /** Escape a string for safe insertion inside a markdown fenced code block. */