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/src/prompt/system-fragment.md ADDED Viewed

@@ -0,0 +1,97 @@
+# Cesium — beautiful HTML artifacts
+You have access to six tools:
+- `cesium_publish` — write a substantive response as a self-contained HTML document
+- `cesium_ask` — publish an interactive Q&A artifact; returns `{ id, httpUrl, ... }`
+- `cesium_wait` — block until the user completes a `cesium_ask` artifact (polls disk)
+- `cesium_styleguide` — fetch the full HTML design system reference (call this before writing anything complex)
+- `cesium_critique` — analyze a draft body for design-system adherence; returns a 0-100 score and findings
+- `cesium_stop` — stop the running cesium HTTP server
+## When to publish (vs. reply in terminal)
+Publish when:
+- Your response would be ≥ 400 words
+- It contains a comparison, decision matrix, or multi-section plan/PRD/RFC
+- It is a code review with more than 3 findings
+- It is a design proposal, audit, post-mortem, or explainer
+- The user is likely to re-read, share, or come back to it
+Stay in terminal for:
+- Short factual answers
+- Status updates ("done", "running tests", "fixed")
+- Mid-tool-call chatter
+- Single-paragraph replies
+- Acknowledgements
+User overrides:
+- "/cesium", "publish this", "make me an HTML report" → publish
+- "in terminal", "just tell me", "don't make a doc" → don't publish
+When uncertain: publish AND emit a 2-3 line terminal summary pointing at the doc. Cheap to over-publish, expensive to under-publish.
+## How to write the body
+The `html` argument is body-only (no `<!doctype>`, `<html>`, `<head>`, `<body>` wrappers — the plugin adds them).
+Use these classes (full reference via `cesium_styleguide`):
+- `.eyebrow` `.h-display` `.h-section` `.section-num`
+- `.card` `.tldr` `.callout` (`.note`/`.warn`/`.risk`)
+- `.code` (with `.kw` `.str` `.cm` `.fn` highlights)
+- `.timeline` `.diagram` `.compare-table` `.risk-table`
+- `.kbd` `.pill` `.tag`
+Inline `style="..."` and inline `<svg>` are encouraged for bespoke diagrams. NEVER reference external resources (no `<script src>`, no remote fonts, no CDN images).
+## Tone
+Warm, considered, not flashy. Match the aesthetic of a thoughtful design document, not marketing material.
+## Self-check before publishing
+For substantial artifacts (plans, reviews, comparisons, explainers > 500 words),
+call `cesium_critique` with your draft body BEFORE calling `cesium_publish`. Act
+on warn-level findings; consider suggest-level. info-level is FYI.
+If critique reports score < 70, revise the body before publishing.
+## After publishing
+The tool returns URLs (file://, http://). Print a short 2-line terminal summary like:
+```
+Cesium · <Title> (<kind>)
+  http://localhost:3030/projects/.../...
+  file:///.../...html
+```
+Do not paste the full document content into the terminal after publishing.
+## Stopping the server
+If the user asks to stop, restart, or recycle the cesium server (e.g. after a
+config change), call `cesium_stop`. The next `cesium_publish` will lazy-start
+a fresh server with the latest config.
+## Interactive Q&A: cesium_ask + cesium_wait
+When you need structured user input before producing a final artifact (design tradeoffs,
+plan branches, confirmation gates), publish an interactive artifact:
+1. `cesium_ask({ title, body, questions: [...] })` → returns `{ id, httpUrl, ... }`
+2. Print the terminalSummary so the user knows where to click.
+3. `cesium_wait({ id })` → blocks until user finishes (or 10-min timeout).
+4. Decide next step from `result.answers` — typically `cesium_publish` with the chosen path.
+Question types: pick_one, pick_many, confirm, ask_text, slider, react. The artifact
+is a permanent record of the conversation; once answered, controls freeze into a static
+markup that captures the user's decisions. Set `optional: true` on an `ask_text` question
+to add a Skip button (useful for "anything else?"-type follow-ups).
+Don't use cesium_ask for trivial yes/no questions you can ask in the terminal. Use it
+when the question deserves to live on disk as a decision record.

package/src/render/client-js.ts ADDED Viewed

@@ -0,0 +1,316 @@
+// Inline client JS bundle for interactive artifacts.
+// This script is embedded in artifacts with interactive.status === "open".
+// It POSTs answers to /api/sessions/:id/answers/:qid and handles UI state.
+//
+// Server response shape (Phase C will implement):
+// { ok: boolean, status: "open" | "complete" | "expired" | "cancelled", remaining: string[], replacementHtml: string }
+/** Returns the standalone JS string to embed in interactive artifacts. */
+export function getClientJs(): string {
+  return `(function cesiumClient() {
+  "use strict";
+  // ─── API base URL derived from window.location.pathname ────────────────────
+  // Artifacts are served at /projects/<projectSlug>/artifacts/<filename>.html
+  // If not served via cesium HTTP server (e.g. file://), apiBase will be null.
+  var m = window.location.pathname.match(/^\\/projects\\/([^\\/]+)\\/artifacts\\/([^\\/]+)$/);
+  var apiBase = m ? "/api/sessions/" + m[1] + "/" + m[2] : null;
+  // ─── File:// / offline banner ───────────────────────────────────────────────
+  if (!apiBase) {
+    document.addEventListener("DOMContentLoaded", function () {
+      if (document.querySelector(".cs-banner-offline")) return;
+      var banner = document.createElement("div");
+      banner.className = "cs-banner cs-banner-offline";
+      banner.textContent =
+        "Interactive controls require viewing this artifact via the cesium HTTP server. " +
+        "Run cesium open or visit localhost:3030";
+      document.body.insertBefore(banner, document.body.firstChild);
+    });
+  }
+  // ─── Session-ended banner ───────────────────────────────────────────────────
+  function showSessionEndedBanner() {
+    if (document.querySelector(".cs-banner-ended")) return;
+    var banner = document.createElement("div");
+    banner.className = "cs-banner cs-banner-ended";
+    banner.textContent = "Session ended — answers can no longer be submitted.";
+    document.body.insertBefore(banner, document.body.firstChild);
+    // Disable all interactive controls
+    var disabled = document.querySelectorAll(
+      ".cs-submit, .cs-skip, .cs-pick, .cs-confirm, .cs-react"
+    );
+    for (var i = 0; i < disabled.length; i++) {
+      var el = disabled[i];
+      if (el instanceof HTMLButtonElement || el instanceof HTMLInputElement) {
+        el.disabled = true;
+      }
+    }
+  }
+  // ─── POST answer ────────────────────────────────────────────────────────────
+  function postAnswer(qid, value) {
+    if (!apiBase) {
+      return Promise.reject(new Error("not served via cesium HTTP server"));
+    }
+    return fetch(apiBase + "/answers/" + qid, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ value: value }),
+    }).then(function (r) {
+      if (r.status === 410) {
+        showSessionEndedBanner();
+        throw new Error("session ended");
+      }
+      if (!r.ok) throw new Error("HTTP " + r.status);
+      return r.json();
+    });
+  }
+  // ─── Section replacement ────────────────────────────────────────────────────
+  function replaceSection(qid, replacementHtml) {
+    var section = document.querySelector(
+      "section[data-question-id=\\"" + qid + "\\"]"
+    );
+    if (!section) return;
+    var tmp = document.createElement("div");
+    tmp.innerHTML = replacementHtml;
+    var newSection = tmp.firstElementChild;
+    if (newSection && section.parentNode) {
+      section.parentNode.replaceChild(newSection, section);
+    }
+  }
+  // ─── Pending / error state ──────────────────────────────────────────────────
+  function setPending(section, pending) {
+    if (pending) {
+      section.dataset["pending"] = "true";
+      section.classList.add("cs-saving");
+      var btns = section.querySelectorAll("button, input");
+      for (var i = 0; i < btns.length; i++) {
+        var b = btns[i];
+        if (b instanceof HTMLButtonElement || b instanceof HTMLInputElement) {
+          b.disabled = true;
+        }
+      }
+    } else {
+      delete section.dataset["pending"];
+      section.classList.remove("cs-saving");
+      var btns2 = section.querySelectorAll("button, input");
+      for (var i2 = 0; i2 < btns2.length; i2++) {
+        var b2 = btns2[i2];
+        if (b2 instanceof HTMLButtonElement || b2 instanceof HTMLInputElement) {
+          b2.disabled = false;
+        }
+      }
+    }
+  }
+  function showError(section, message) {
+    var existing = section.querySelector(".cs-error");
+    if (existing) existing.remove();
+    var errEl = document.createElement("p");
+    errEl.className = "cs-error";
+    errEl.setAttribute("role", "alert");
+    errEl.textContent = "Failed to save: " + message;
+    section.appendChild(errEl);
+  }
+  function clearError(section) {
+    var existing = section.querySelector(".cs-error");
+    if (existing) existing.remove();
+  }
+  // ─── Submit helper ──────────────────────────────────────────────────────────
+  function submitAnswer(section, qid, value) {
+    clearError(section);
+    setPending(section, true);
+    postAnswer(qid, value)
+      .then(function (resp) {
+        if (resp && resp.replacementHtml) {
+          replaceSection(qid, resp.replacementHtml);
+        } else {
+          setPending(section, false);
+        }
+      })
+      .catch(function (err) {
+        setPending(section, false);
+        showError(section, err instanceof Error ? err.message : String(err));
+      });
+  }
+  // ─── pick_one wiring ─────────────────────────────────────────────────────────
+  function wirePickOne(section) {
+    var qid = section.dataset["questionId"] || "";
+    var btns = section.querySelectorAll("button.cs-pick");
+    for (var i = 0; i < btns.length; i++) {
+      (function (btn) {
+        btn.addEventListener("click", function () {
+          var dataValue = btn.dataset["value"] || "";
+          submitAnswer(section, qid, { type: "pick_one", selected: dataValue });
+        });
+      })(btns[i]);
+    }
+  }
+  // ─── pick_many wiring ────────────────────────────────────────────────────────
+  function wirePickMany(section) {
+    var qid = section.dataset["questionId"] || "";
+    var submitBtn = section.querySelector("button.cs-submit");
+    var minAttr = section.dataset["min"];
+    var maxAttr = section.dataset["max"];
+    var min = minAttr ? parseInt(minAttr, 10) : 1;
+    var max = maxAttr ? parseInt(maxAttr, 10) : Infinity;
+    function updateSubmitState() {
+      var checked = section.querySelectorAll("input[type=checkbox]:checked");
+      var count = checked.length;
+      if (submitBtn instanceof HTMLButtonElement) {
+        submitBtn.disabled = count < min || count > max;
+      }
+    }
+    var checkboxes = section.querySelectorAll("input[type=checkbox]");
+    for (var i = 0; i < checkboxes.length; i++) {
+      checkboxes[i].addEventListener("change", updateSubmitState);
+    }
+    if (submitBtn) {
+      submitBtn.addEventListener("click", function () {
+        var checked = section.querySelectorAll("input[type=checkbox]:checked");
+        var selected = [];
+        for (var i2 = 0; i2 < checked.length; i2++) {
+          var cb = checked[i2];
+          if (cb instanceof HTMLInputElement) {
+            selected.push(cb.dataset["value"] || "");
+          }
+        }
+        submitAnswer(section, qid, { type: "pick_many", selected: selected });
+      });
+    }
+  }
+  // ─── confirm wiring ──────────────────────────────────────────────────────────
+  function wireConfirm(section) {
+    var qid = section.dataset["questionId"] || "";
+    var btns = section.querySelectorAll("button.cs-confirm");
+    for (var i = 0; i < btns.length; i++) {
+      (function (btn) {
+        btn.addEventListener("click", function () {
+          var choice = btn.dataset["value"] || "";
+          submitAnswer(section, qid, { type: "confirm", choice: choice });
+        });
+      })(btns[i]);
+    }
+  }
+  // ─── ask_text wiring ─────────────────────────────────────────────────────────
+  function wireAskText(section) {
+    var qid = section.dataset["questionId"] || "";
+    var input = section.querySelector("input.cs-text, textarea.cs-text");
+    var submitBtn = section.querySelector("button.cs-submit");
+    var skipBtn = section.querySelector("button.cs-skip");
+    function updateSubmitState() {
+      if (submitBtn instanceof HTMLButtonElement && input) {
+        var val = input instanceof HTMLInputElement
+          ? input.value
+          : input instanceof HTMLTextAreaElement
+          ? input.value
+          : "";
+        submitBtn.disabled = val.trim() === "";
+      }
+    }
+    if (input) {
+      input.addEventListener("input", updateSubmitState);
+    }
+    if (submitBtn) {
+      submitBtn.addEventListener("click", function () {
+        var text = "";
+        if (input instanceof HTMLInputElement || input instanceof HTMLTextAreaElement) {
+          text = input.value;
+        }
+        submitAnswer(section, qid, { type: "ask_text", text: text });
+      });
+    }
+    if (skipBtn) {
+      skipBtn.addEventListener("click", function () {
+        submitAnswer(section, qid, { type: "ask_text", text: "" });
+      });
+    }
+  }
+  // ─── slider wiring ───────────────────────────────────────────────────────────
+  function wireSlider(section) {
+    var qid = section.dataset["questionId"] || "";
+    var sliderInput = section.querySelector("input.cs-slider");
+    var outputEl = section.querySelector("output.cs-slider-out");
+    var submitBtn = section.querySelector("button.cs-submit");
+    if (sliderInput) {
+      sliderInput.addEventListener("input", function () {
+        if (outputEl && sliderInput instanceof HTMLInputElement) {
+          outputEl.textContent = sliderInput.value;
+        }
+      });
+    }
+    if (submitBtn) {
+      submitBtn.addEventListener("click", function () {
+        var value = sliderInput instanceof HTMLInputElement
+          ? Number(sliderInput.value)
+          : 0;
+        submitAnswer(section, qid, { type: "slider", value: value });
+      });
+    }
+  }
+  // ─── react wiring ────────────────────────────────────────────────────────────
+  function wireReact(section) {
+    var qid = section.dataset["questionId"] || "";
+    var btns = section.querySelectorAll("button.cs-react");
+    var commentArea = section.querySelector("textarea.cs-react-comment");
+    for (var i = 0; i < btns.length; i++) {
+      (function (btn) {
+        btn.addEventListener("click", function () {
+          var decision = btn.dataset["value"] || "";
+          var comment = commentArea instanceof HTMLTextAreaElement && commentArea.value !== ""
+            ? commentArea.value
+            : undefined;
+          var value = comment !== undefined
+            ? { type: "react", decision: decision, comment: comment }
+            : { type: "react", decision: decision };
+          submitAnswer(section, qid, value);
+        });
+      })(btns[i]);
+    }
+  }
+  // ─── Wire all sections on DOMContentLoaded ───────────────────────────────────
+  document.addEventListener("DOMContentLoaded", function () {
+    var sections = document.querySelectorAll("section[data-question-id]");
+    for (var i = 0; i < sections.length; i++) {
+      var section = sections[i];
+      if (!(section instanceof HTMLElement)) continue;
+      var cls = section.className || "";
+      if (cls.indexOf("cs-control-pick_one") !== -1) {
+        wirePickOne(section);
+      } else if (cls.indexOf("cs-control-pick_many") !== -1) {
+        wirePickMany(section);
+      } else if (cls.indexOf("cs-control-confirm") !== -1) {
+        wireConfirm(section);
+      } else if (cls.indexOf("cs-control-ask_text") !== -1) {
+        wireAskText(section);
+      } else if (cls.indexOf("cs-control-slider") !== -1) {
+        wireSlider(section);
+      } else if (cls.indexOf("cs-control-react") !== -1) {
+        wireReact(section);
+      }
+    }
+  });
+})();`;
+}