npm - @cfbender/cesium - Versions diffs - 0.3.5 - Mend

@cfbender/cesium 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/ARCHITECTURE.md +304 -0
package/CHANGELOG.md +335 -0
package/LICENSE +21 -0
package/README.md +479 -0
package/agents/cesium.md +39 -0
package/assets/styleguide.html +857 -0
package/package.json +61 -0
package/src/cli/commands/ls.ts +186 -0
package/src/cli/commands/open.ts +208 -0
package/src/cli/commands/prune.ts +348 -0
package/src/cli/commands/restart.ts +38 -0
package/src/cli/commands/serve.ts +214 -0
package/src/cli/commands/stop.ts +130 -0
package/src/cli/commands/theme.ts +333 -0
package/src/cli/index.ts +78 -0
package/src/config.ts +94 -0
package/src/index.ts +35 -0
package/src/prompt/system-fragment.md +97 -0
package/src/render/client-js.ts +316 -0
package/src/render/controls.ts +302 -0
package/src/render/critique.ts +360 -0
package/src/render/extract.ts +83 -0
package/src/render/scrub.ts +141 -0
package/src/render/theme.ts +712 -0
package/src/render/validate.ts +524 -0
package/src/render/wrap.ts +165 -0
package/src/server/api.ts +166 -0
package/src/server/http.ts +195 -0
package/src/server/lifecycle.ts +331 -0
package/src/server/stop.ts +124 -0
package/src/storage/index-cache.ts +71 -0
package/src/storage/index-gen.ts +447 -0
package/src/storage/lock.ts +108 -0
package/src/storage/mutate.ts +396 -0
package/src/storage/paths.ts +159 -0
package/src/storage/project-summaries.ts +19 -0
package/src/storage/theme-write.ts +19 -0
package/src/storage/write.ts +75 -0
package/src/tools/ask.ts +353 -0
package/src/tools/critique.ts +66 -0
package/src/tools/publish.ts +404 -0
package/src/tools/stop.ts +53 -0
package/src/tools/styleguide.ts +23 -0
package/src/tools/wait.ts +192 -0

package/ARCHITECTURE.md ADDED Viewed

@@ -0,0 +1,304 @@
+# Architecture
+Cesium is an opencode plugin that converts substantive agent responses into self-contained
+HTML artifacts stored on disk and served locally. This document describes the architectural
+decisions made for v1.
+**Status: v0.3.0 shipped.** See [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+---
+## Vision
+When the agent produces something worth keeping — a plan, comparison, code review, audit,
+explainer, or RFC — it generates a beautiful `.html` file instead of printing markdown to
+the terminal. The artifact lives in `~/.local/state/cesium/` and can be opened in a browser,
+shared over SSH, or archived as-is. The terminal remains the control surface. Each artifact
+is 100% self-contained: no external stylesheets, no CDN scripts, no network required to view.
+---
+## Trigger model
+Cesium is **agent-decided via tool call**, not automatic on every response. The plugin
+injects a ~40-line system-prompt fragment (~600 tokens) into every agent session that
+describes when to publish vs. stay in the terminal.
+**Publish heuristics (baked into the injected prompt):**
+- Response would be >= ~400 words, OR
+- Contains a comparison, decision matrix, or multi-section plan/PRD/RFC, OR
+- A code review with more than 3 findings, OR
+- Anything the user is likely to revisit or share.
+**Stay in terminal:**
+- Direct factual question, short status update, mid-tool-loop chatter.
+**User override always wins:** `/cesium`, "publish this", "make me an HTML report" force
+publish; "just tell me", "in terminal" suppress it.
+**Tie-breaker:** when uncertain, publish and emit a 2-3 line terminal summary.
+---
+## Tool surface
+Two tools are registered by the plugin:
+### `cesium_publish` (primary)
+Accepts the body HTML and metadata for one artifact. The plugin owns the full HTML shell:
+`<!doctype html>`, `<head>`, the inlined CSS framework, embedded metadata, and the footer
+with revision links. The agent writes only the `<body>` inner HTML.
+Input fields:
+- `title` (string, required)
+- `kind` — `"plan" | "review" | "comparison" | "report" | "explainer" | "design" | "audit" | "rfc" | "other"`
+- `html` — body inner HTML
+- `summary` — optional 1-2 line terminal blurb
+- `tags` — optional string array
+- `supersedes` — optional id of artifact this revises
+Returns: `{ id, filePath, fileUrl, httpUrl, indexUrl }`
+### `cesium_styleguide` (on-demand reference)
+Returns the full CSS reference page as a string. Called by the agent before starting a
+complex artifact. Kept separate to avoid bloating every tool call.
+---
+## HTML generation strategy
+**Approach:** shared inline CSS framework + agent-written semantic HTML.
+The plugin injects a known-good `<style>` block (~3kb) into every artifact. The agent
+composes content using a named class vocabulary (documented in the tool description and
+retrievable via `cesium_styleguide`). The agent may also use inline `style="..."` and
+inline `<svg>` for bespoke diagrams.
+**Strict portability rule:** no external resources. The scrub pass strips or rewrites:
+- `<link rel="stylesheet" href="...">` — removed, comment left
+- `<script src="...">` — removed, comment left
+- `url(https://...)` in style — removed
+- `<img src="http...">` — removed, comment left
+Broken or unparseable HTML is tolerated: the file is written anyway with a warning banner
+prepended. Validation errors (missing title, empty html, invalid kind) are caught before
+write and returned as tool errors.
+**Color tokens (default theme):**
+| Token         | Value     | Role                  |
+| ------------- | --------- | --------------------- |
+| `--bg`        | `#FAF9F5` | ivory page background |
+| `--surface`   | `#FFFFFF` | card/panel surface    |
+| `--surface-2` | `#F0EEE6` | secondary surface     |
+| `--oat`       | `#E3DACC` | muted border fill     |
+| `--rule`      | `#D1CFC5` | rule / divider        |
+| `--ink`       | `#141413` | primary text          |
+| `--ink-soft`  | `#3D3D3A` | secondary text        |
+| `--muted`     | `#87867F` | placeholder / caption |
+| `--accent`    | `#D97757` | clay — callout/link   |
+| `--olive`     | `#788C5D` | sage — success        |
+| `--code-bg`   | `#141413` | code panel bg         |
+| `--code-fg`   | `#E8E6DE` | code panel fg         |
+User theme overrides: `~/.config/opencode/cesium.json` → `theme` field (per-token overrides
+stack on top of the active preset). Four named presets are shipped (`warm`, `cool`, `mono`,
+`paper`) selectable via `themePreset` — see README for the full preset reference.
+**Type stack:** system fonts only (`ui-serif`, `system-ui`, `ui-monospace`) — strict
+portability requires no remote font loads.
+**Named component classes the agent uses:**
+`.eyebrow`, `.h-display`, `.h-section`, `.section-num`, `.card`, `.tldr`, `.callout`,
+`.code`, `.timeline`, `.diagram`, `.compare-table`, `.risk-table`, `.kbd`, `.pill`,
+`.tag`, `.byline`
+---
+## Storage layout
+```
+~/.local/state/cesium/
+├── index.html                              # global cross-project index
+├── index.json                              # global cache (rebuilt on every publish)
+└── projects/
+    └── <project-slug>/
+        ├── index.html                      # per-project index
+        ├── index.json                      # per-project cache
+        └── artifacts/
+            ├── 2026-05-11T14-22-09Z__plan-auth-rewrite__a7K9pQ.html
+            └── ...
+```
+**Project slug derivation (priority order):**
+1. Git remote `origin`, normalized: `github-com-cfb-cesium`
+2. `<cwd-basename>-<6char-hash-of-absolute-path>` — prevents collisions when multiple repos
+   share the same basename
+**Worktrees** of one repo merge into one project directory. Branch is captured in artifact
+metadata, not in the path.
+**Filename:** `<iso-utc-timestamp>__<title-slug>__<6char-nanoid>.html`
+Sortable, greppable, human-readable, collision-resistant.
+**Metadata: dual-source.**
+Each artifact embeds a `<script type="application/json" id="cesium-meta">` block — the
+source of truth. The artifact is 100% self-contained; metadata travels with the file.
+`index.json` is a derived cache rebuilt on every publish (not the authoritative store).
+**Metadata fields:** `id`, `title`, `kind`, `summary`, `tags`, `createdAt`, `model`,
+`sessionId`, `projectSlug`, `projectName`, `cwd`, `worktree`, `gitBranch`, `gitCommit`,
+`supersedes?`, `supersededBy?`, `contentSha256`
+---
+## Index & serving
+**Index:** per-project and global `index.html` regenerated atomically on every publish.
+Lists artifacts grouped by week, with kind filter chips, inline title search (tiny inline
+JS), and revision-chain collapsing (latest version visible by default). Pre-rendered — works
+without the server (archivable, rsync-friendly).
+**Server:** lazy auto-start, single global process, port 3030 (increments to 3031..3050 if
+busy).
+- Bun HTTP server bound to `127.0.0.1:3030`, rooted at `~/.local/state/cesium/`.
+- Starts on first publish in an opencode session.
+- Idle-shuts after 30 minutes of no requests (configurable via `cesium.json`).
+- PID file at `~/.local/state/cesium/.server.pid`. Stale PID detected and cleared on startup.
+- SIGTERM handler for clean shutdown.
+- SSH detection: if `$SSH_CONNECTION` is set, publish output reminds the user to forward
+  the port. Server does NOT bind to `0.0.0.0` by default.
+**Terminal output after publish:**
+```
+Cesium · Auth design (plan)
+  http://localhost:3030/projects/github-com-cfb-cesium/artifacts/...
+  file:///Users/cfb/.local/state/cesium/...
+```
+---
+## Revision chains
+When `cesium_publish` receives a `supersedes` id:
+1. New artifact is written with `supersedes` populated.
+2. Previous artifact's embedded metadata is patched in-place: `supersededBy` field added.
+   Visual content is untouched.
+3. Index renders the chain: "v3 of auth design (revises v2, v1)".
+---
+## Interactive artifacts (v0.3.0)
+### The artifact-as-UI insight
+In v0.3.0, `ask`-kind artifacts collapse the "publish" and "interactive UI" pipelines
+into one. The artifact file IS the form. Inline JS POSTs individual answers to the
+cesium HTTP server; the server mutates the file on disk atomically; once all required
+questions are answered the status transitions to `"complete"` and the controls freeze
+into a static answered record. The same `.html` file is the form, the live conversation,
+and the permanent record — no separate UI, no database, no websocket.
+### Storage
+`ask`-kind artifacts carry an `interactive` field in the embedded
+`<script type="application/json" id="cesium-meta">` block. Shape:
+```ts
+type InteractiveData = {
+  status: "open" | "complete" | "expired" | "cancelled";
+  requireAll: boolean;
+  expiresAt: string; // ISO-8601
+  questions: Question[];
+  answers: Record<string, { value: AnswerValue; answeredAt: string }>;
+  completedAt?: string;
+};
+```
+The same atomic-write + `index.json` cache pattern as publish artifacts applies.
+`src/storage/mutate.ts` owns the read-mutate-write cycle for interactive artifacts.
+### Transport
+Answer submission:
+```
+POST /api/sessions/<projectSlug>/<filename>/answers/<questionId>
+Body: { "value": <AnswerValue> }
+```
+State query:
+```
+GET /api/sessions/<projectSlug>/<filename>/state
+Response: { status, remaining, answers }
+```
+The server uses `withLock` on `<artifactPath>.lock` for all read-mutate-write
+operations — the same lock primitive used by the index.
+### Tools
+- **`cesium_ask`** — validates input, builds the interactive artifact, writes it to
+  disk, starts the server, and returns `{ id, filePath, fileUrl, httpUrl }`.
+- **`cesium_wait`** — polls disk every 500 ms, reading the artifact's embedded
+  `interactive.status`. Returns the full `answers` map once status is non-`"open"`.
+  No subagents, no WebSockets — pure polling, pure HTTP.
+### Question types (v0.3.0)
+Six types ship in v0.3.0: `pick_one`, `pick_many`, `confirm`, `ask_text`, `slider`,
+`react`. Branching logic, ranking, and file/image inputs are deferred.
+Each type has a corresponding control renderer in `src/render/controls.ts` that
+produces the interactive HTML, and an answered renderer (`renderAnswered`) that
+produces the frozen read-only record once an answer is recorded.
+### Lifecycle
+Status transitions: `open` → `complete` (all required answers received) or
+`open` → `expired` (server-side check on `expiresAt`) or `open` → `cancelled`
+(explicit cancellation via API).
+Once status is non-`"open"`, `wrapDocument` omits the inline
+`<script data-cesium-client>` tag entirely, so the file loads without any interactive
+overhead. Controls render as `.cs-answered` read-only markup.
+### CSS additions
+`src/render/theme.ts` → `frameworkRulesCss()` gained ~210 lines of `.cs-*` rules:
+- `.cs-questions` — container
+- `.cs-question` — individual question block
+- `.cs-control` — wraps each input widget
+- `.cs-answered` — frozen answer display
+- `.cs-banner` / `.cs-banner-offline` / `.cs-banner-ended` — status banners
+- Per-type modifiers: `.cs-pick`, `.cs-confirm`, `.cs-slider`, `.cs-text`, `.cs-react`
+---
+## v1 build phases
+| Phase | Scope                                                                              | Status  |
+| ----- | ---------------------------------------------------------------------------------- | ------- |
+| 0     | Scaffolding, configs, docs, empty stubs                                            | shipped |
+| 1     | Storage + render core (paths, write, theme, wrap, scrub, validate)                 | shipped |
+| 2     | `cesium_publish` + `cesium_styleguide` tools, plugin entry, system prompt fragment | shipped |
+| 3     | Per-project + global `index.html` generation, file lock, revision chains           | shipped |
+| 4     | Lazy auto-server, port-scan, idle shutdown, SSH detection                          | shipped |
+| 5     | Reference examples, dedicated agent definition, release polish                     | shipped |
+| A     | Interactive artifact types + `cesium_ask` tool                                     | shipped |
+| B     | Answer submission API (`/api/sessions/…/answers/:qid`) + per-artifact file lock    | shipped |
+| C     | `cesium_wait` polling tool + client JS answer submission                           | shipped |
+| D     | Interactive lifecycle (status transitions, expiry, freeze)                         | shipped |
+| E     | `buildProjectSummaries` refactor, `examples/ask.html`, docs, v0.3.0 release        | shipped |

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,335 @@
+# Changelog
+## v0.3.5 — 2026-05-11
+Fixes the `Publish to npm` GitHub Action.
+- **fix:** Workflow now uses Node 24 (which ships with npm 11+, required for
+  the OIDC trusted-publisher flow). The previous attempt used Node 22 plus an
+  explicit `npm install -g npm@latest` step, which hit a `MODULE_NOT_FOUND`
+  on `promise-retry` in the runner's pre-cached npm. Bundled npm 11 from
+  Node 24 sidesteps the upgrade step entirely.
+## v0.3.4 — 2026-05-11
+Smoke test for the npm publish GitHub Action (OIDC trusted-publisher flow).
+First release published from CI.
+- **fix:** Removed `publishConfig.provenance: true` from `package.json`. The
+  field forces `--provenance` even on local publishes, where it fails with
+  `Automatic provenance generation not supported for provider: null`. The
+  GitHub Action passes `--provenance` explicitly, so CI publishes still
+  ship with an npm provenance attestation.
+- **docs:** Bootstrap step in README "Releasing" no longer passes
+  `--provenance` (it can't work locally).
+## v0.3.3 — 2026-05-11
+First release published to npm as **`@cfbender/cesium`**. No runtime behavior
+changes; only packaging and release infrastructure.
+- **packaging:** Renamed package from `cesium` to `@cfbender/cesium` (scoped,
+  public). Install with `bun install -g @cfbender/cesium`. Old git-URL installs
+  still work but will fall behind.
+- **packaging:** Added explicit `files` allowlist to package.json — the
+  published tarball ships `src/`, `assets/styleguide.html`, `agents/`, and
+  `ARCHITECTURE.md` only. Tests, examples, scripts, design specs, and the
+  README demo video are excluded.
+- **packaging:** `engines.bun >= 1.0.0` declared (cesium runs TS directly via
+  Bun; the CLI's `#!/usr/bin/env bun` shebang requires Bun on `PATH`).
+- **packaging:** `prepublishOnly` runs `typecheck` + `test` before publish.
+- **packaging:** `publishConfig.access = "public"` and
+  `publishConfig.provenance = true` so scoped publishes work and ship with
+  npm provenance attestations.
+- **ci:** New `.github/workflows/publish.yml`. Triggers on `v*` tag push,
+  runs typecheck + tests, verifies tag-vs-package-version match, then
+  `npm publish --access public --provenance` via npm's **Trusted Publisher
+  OIDC flow** — no `NPM_TOKEN` secret required. The first release is
+  published manually so the package exists on the registry; subsequent
+  releases are tag-triggered. See README "Releasing" for the bootstrap.
+- **docs:** README install section rewritten around the npm package; mise /
+  `bun update -g` upgrade flows documented; trusted-publisher bootstrap +
+  release-via-tag flow documented.
+## v0.3.2 — 2026-05-11
+Quality-of-life patch focused on `cesium serve` reliability and README polish.
+- **fix:** `cesium serve` no longer auto-shuts-down on idle. The configured
+  `idleTimeoutMs` exists for the plugin's lazy-started server and was being
+  unintentionally applied to foreground `cesium serve`, killing the process
+  unexpectedly. Foreground serve now runs until SIGINT/SIGTERM by default.
+- **new:** `cesium serve --idle-timeout DUR` opts back into auto-shutdown.
+  Accepts plain milliseconds or a suffixed duration (`90s`, `30m`, `2h`).
+  Use `0`, `never`, or `off` to disable explicitly.
+- **internal:** `lifecycle.startIdleTimer` now treats `idleTimeoutMs <= 0` as
+  "never time out" and skips creating the interval.
+- **docs:** README demo asset (`assets/cesium.mp4`, ~600 KB, 720px wide)
+  embedded near the top via a `<video>` tag.
+- **docs:** New "Common workflows" section in the README covering forced
+  publish, finding/opening artifacts, sharing, pruning, theme changes,
+  server restart, and Q&A loops.
+- **docs:** Acknowledgements section added.
+- **tests:** 889 → 906 (+9 serve-arg parser tests, +2 lifecycle tests for
+  the `idleTimeoutMs <= 0` path; the previously-skipped flaky idle-timer
+  test was preserved).
+## v0.3.1 — 2026-05-11
+Small quality-of-life patch. The only user-visible change is the Skip button on
+optional `ask_text` questions; all other v0.3.0 behavior is unchanged.
+- **new:** `optional?: boolean` field on `ask_text` questions (default `false`).
+  When `true`, the server accepts an empty-string answer (skipped), and the
+  answered section renders a muted "(skipped)" placeholder instead of a blockquote.
+- **new:** Skip button rendered alongside Submit for optional ask_text controls
+  (`class="cs-skip"`), wrapped in a `class="cs-button-row"` flex container.
+- **new:** Client JS `cs-skip` click handler — POSTs `{ type: "ask_text", text: "" }`
+  via the same `submitAnswer` path as Submit.
+- **examples:** `ask.html` "constraints" question is now `optional: true` — showcases
+  the Skip button.
+- **tests:** 870 → 889 (+19 new tests across validate, mutate, controls, client-js,
+  theme, system-fragment).
+## v0.3.0 — 2026-05-11
+### Added
+- **`cesium_ask`** — publish an interactive Q&A artifact and return its URL. The
+  agent calls this when it needs structured input before producing a final artifact:
+  design tradeoffs, plan choices, confirmation gates. Returns `{ id, filePath, fileUrl, httpUrl }`.
+- **`cesium_wait`** — block until the user finishes answering all required questions.
+  Polls disk every 500 ms reading the artifact's embedded `interactive.status`. Returns
+  the full `answers` map once complete, expired, or cancelled.
+- **New artifact kind: `"ask"`** — interactive Q&A artifacts. A single self-contained
+  `.html` file that embeds the question form, client JS, and answers. Server-mutated
+  atomically on each answer; crystallizes into a permanent static record once complete.
+  The same file is the form, the live session, and the archive.
+- **Six question types:** `pick_one` (radio group + recommended), `pick_many`
+  (checkbox group + min/max), `confirm` (yes/no with custom labels), `ask_text`
+  (free-text, optional multiline), `slider` (numeric range), `react` (thumbs reaction
+  with optional comment).
+- **Server: new `/api/*` routes** — `POST /api/sessions/<slug>/<file>/answers/<qid>`
+  submits an individual answer; `GET /api/sessions/<slug>/<file>/state` returns current
+  status and remaining question ids. Per-artifact file lock (`<artifactPath>.lock`).
+- **`examples/ask.html`** — baked demo artifact demonstrating all six question types
+  in `status: "open"` state. Open in browser to see the controls.
+### Changed
+- **Storage:** new `src/storage/mutate.ts` — atomic read-mutate-write for interactive
+  artifacts. New `src/storage/project-summaries.ts` — `buildProjectSummaries` extracted
+  from `publish.ts` and `ask.ts` into a shared module (no behavior change).
+- **Render:** new `src/render/controls.ts` (question control + answered renderers) and
+  `src/render/client-js.ts` (~309-line inline JS bundle for answer POSTing and UI state).
+  ~210 new `.cs-*` CSS rules in `frameworkRulesCss()`.
+- **Tests:** 863 → 870 (commit 1 refactor: +7 project-summaries tests). Full suite: 870
+  pass (+281 new tests since v0.2.4).
+## v0.2.4 — 2026-05-11
+### Added
+- `cesium --version` / `cesium -v` / `cesium version` — print the installed
+  version. Useful for confirming what's actually running after an upgrade.
+### Changed
+- `claret-dark` code panels now render at `surface2` (`#2B1F22`) instead of
+  recessed `#0F0509`. The recessed value gave only ~9 luminance points of
+  contrast against the page bg; the elevated value reads cleanly.
+## v0.2.3 — 2026-05-11
+### Added
+- `cesium_stop` tool. The agent can now stop the running cesium HTTP server
+  from inside an opencode session via a tool call. Useful for cycling the
+  server after a config change, or cleaning up at session end. Idempotent.
+- `claret-dark` theme preset — dark wine background with bright rose and sage
+  accents, sourced from `claret.nvim`'s dark palette.
+- `claret-light` theme preset — the previous `claret` palette, renamed.
+### Changed
+- **Default theme is now `claret-dark`.** If you have `themePreset: "claret"`
+  in `~/.config/opencode/cesium.json`, you'll now see the dark variant. Set
+  `themePreset: "claret-light"` to keep the old look. The bare `"claret"` name
+  is preserved as an alias for `"claret-dark"`.
+- Refactored cross-process server-stop logic into `src/server/stop.ts` so the
+  CLI's `cesium stop` and the new `cesium_stop` tool share the same code path.
+## v0.2.2 — 2026-05-11
+### Added
+- `cesium stop` — kills the running cesium server cross-process via its PID
+  file. Sends SIGTERM with a configurable grace period (`--timeout`, default
+  3000 ms), then SIGKILL. `--force` skips the grace. Idempotent: safe when no
+  server is running.
+- `cesium restart` — stops then re-starts the server. Replaces the calling
+  terminal with the new server (foreground, like `cesium serve`). Inherits
+  serve's `--port` / `--hostname` flags.
+## v0.2.1 — 2026-05-11
+### Changed
+- **Default theme is now `claret`** — a deep-rose-on-warm-cream palette derived
+  from the claret.nvim color scheme. The previous default (`warm`) is still
+  available as a preset; set `themePreset: "warm"` in `cesium.json` to keep the
+  old look.
+### Added
+- Dynamic theme via `<stateDir>/theme.css`. Each artifact (and index page) now
+  references this file via a relative `<link rel="stylesheet">`. Changing the
+  configured theme and running `cesium theme apply` re-skins all linked
+  artifacts on disk — file://-served artifacts fall back to their original
+  inline tokens, preserving offline portability.
+- `claret` theme preset.
+- `cesium theme show` — print resolved theme tokens, indicate when on-disk
+  theme.css is out of date.
+- `cesium theme apply` — write theme.css from current config.
+- `cesium theme apply --rewrite-artifacts` — retrofit existing artifacts and
+  index pages on disk to reference theme.css. Adds the `<link>` tag idempotently
+  to files that don't already have one.
+### Architectural notes
+- Inline `<style>` blocks now contain framework rules + a _fallback_ token set
+  baked at publish time. The external `theme.css` overrides the fallback when
+  present (CSS cascade). Standalone `.html` files still render correctly when
+  opened via `file://` without the surrounding state dir.
+## v0.2.0 — 2026-05-11
+This is the v0.2.0 polish release. Three smaller features shipped as 0.1.3–0.1.5
+(theme presets, cesium_critique, full-text search) and the standalone CLI lands
+here. Use `cesium <subcommand>` from any shell.
+### Added
+- Standalone `cesium` CLI with subcommands:
+  - `cesium ls [--all] [--json] [--limit N]` — list artifacts
+  - `cesium open <id-prefix> [--print]` — open an artifact in the browser
+  - `cesium serve [--port N] [--hostname H]` — run the local server in foreground
+  - `cesium prune --older-than <duration> [--yes]` — delete old artifacts
+- `package.json` `bin` field exposes the CLI when the plugin is installed via
+  bun/opencode (linked into `node_modules/.bin/cesium`).
+## v0.1.5 — 2026-05-11
+### Added
+- Index search now matches body text in addition to titles. Each artifact's
+  rendered card carries a `data-body-text` attribute (capped at 5000 chars,
+  lowercased) and the inline filter checks both fields.
+- Body text is extracted at publish time via parse5 and stored on the
+  `IndexEntry` shape.
+### Changed
+- `IndexEntry` gained a `bodyText: string` field. Existing `index.json` files
+  without this field are loaded with an empty string; republishing populates it.
+- Search input placeholder updated from "Filter by title…" to
+  "Filter by title or content…".
+## v0.1.4 — 2026-05-11
+### Added
+- `cesium_critique` tool. Agent can call this before publishing to get a 0-100
+  score and structured findings (warn/suggest/info) about how well the body
+  adheres to the design system. The system-prompt fragment now instructs
+  agents to self-check on complex artifacts.
+## v0.1.3 — 2026-05-11
+### Added
+- Four theme presets (`warm`, `cool`, `mono`, `paper`) selectable via `themePreset`
+  in `~/.config/opencode/cesium.json`. `CESIUM_THEME_PRESET` env honored.
+- Per-token `theme: {...}` overrides now stack on top of the chosen preset.
+## v0.1.2 — 2026-05-11
+### Added
+- Each artifact now renders a small back-nav at the top of the body linking to
+  its project's `index.html` and to the global `index.html`. Uses relative
+  paths so it works the same over `http://` and `file://`.
+## v0.1.1 — 2026-05-11
+### Added
+- `hostname` config field (default `127.0.0.1`) lets the local HTTP server bind
+  to any address, including `0.0.0.0` for LAN access. `CESIUM_HOSTNAME` env var
+  is honored as an override.
+- Display URLs in `terminalSummary` now resolve sensibly: `127.0.0.1` becomes
+  `localhost`, `0.0.0.0` becomes the first non-loopback IPv4 interface address,
+  named hosts pass through verbatim. Generated http URLs are always reachable.
+### Changed
+- `terminalSummary` URLs now show `http://localhost:3030/...` by default
+  (previously `http://127.0.0.1:3030/...`). Functionally equivalent on a single
+  machine; consistent with how URLs are rendered when binding to other hosts.
+## v0.1.0 — 2026-05-11
+Initial release.
+### Tools
+- `cesium_publish` — agent-decided HTML artifact publishing with strict portability
+  (no external resources), input validation, embedded JSON metadata, atomic writes,
+  and revision chains via `supersedes`.
+- `cesium_styleguide` — on-demand design system reference for the agent.
+### Storage
+- Artifacts written to `~/.local/state/cesium/projects/<project-slug>/artifacts/`.
+- Project slug derived from git remote when available, else `<basename>-<6char hash>`.
+- Embedded `<script type="application/json" id="cesium-meta">` is the source of truth;
+  `index.json` per-project + global is a regenerated cache.
+- Revision chains: `supersedes` field links a new artifact to its predecessor; the
+  predecessor's metadata is patched in-place with `supersededBy`.
+### Index pages
+- Per-project and global `index.html` regenerated atomically on every publish.
+- Inline JS for kind-filter chips, title search, and revision-chain collapsing.
+- File lock at `<stateDir>/.index.lock` serializes concurrent publishes.
+### Server
+- Lazy-start Bun HTTP server on port 3030 (configurable). Scans 3030–3050 on conflict.
+- Static file serving with proper MIME types and path-traversal defense in depth.
+- Idle shutdown after 30 minutes of no requests.
+- SSH detection (`$SSH_CONNECTION`) emits a `ssh -L` port-forward hint in the publish
+  output.
+- PID file at `<stateDir>/.server.pid` with stale-process detection.
+### Design system
+- Warm ivory / clay / oat palette inspired by the html-effectiveness reference.
+- 16 named component classes covering typography, cards, callouts, code panels,
+  timelines, diagrams, comparison and risk tables, and inline chips.
+- System fonts only — no remote resources. Files are fully self-contained.
+### Agent steering
+- `experimental.chat.system.transform` hook injects a ~600-token system fragment
+  describing the trigger heuristic (≥ 400 word threshold) and the component-class
+  cheatsheet.
+- Optional dedicated `@cesium` agent definition shipped at `agents/cesium.md` —
+  copy into `~/.config/opencode/agents/` to invoke explicit-publish sessions.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 cfb
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.