wicked-interactive 0.4.0

package/src/service/export.js

@@ -0,0 +1,124 @@
+// export.js — export a version to a self-contained interactive HTML or a PDF (ADR-0009).
+//
+// HTML: inline local stylesheets, scripts, images (data-URI), and url() refs inside inlined
+//       CSS, so the file renders + stays interactive opened straight from disk (no server).
+// PDF:  render the self-contained HTML via headless Chrome (the primitive wicked-prezzie
+//       wraps; wicked-prezzie itself is a plugin/skill, not an importable library).
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import * as cheerio from "cheerio";
+import { readVersionHtml } from "./fsstore.js";
+
+const MIME = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
+  ".svg": "image/svg+xml", ".webp": "image/webp", ".woff": "font/woff", ".woff2": "font/woff2",
+  ".ttf": "font/ttf", ".otf": "font/otf", ".css": "text/css", ".js": "application/javascript",
+};
+const ext = (p) => { const i = p.lastIndexOf("."); return i < 0 ? "" : p.slice(i).toLowerCase(); };
+const isLocal = (url) => url && !/^(https?:)?\/\//.test(url) && !url.startsWith("data:") && !url.startsWith("#");
+
+function dataUri(absPath) {
+  const mime = MIME[ext(absPath)] || "application/octet-stream";
+  return `data:${mime};base64,${readFileSync(absPath).toString("base64")}`;
+}
+
+// Rewrite url(local) inside CSS to data-URIs, resolved relative to the CSS file's dir.
+function inlineCssUrls(css, cssDir) {
+  return css.replace(/url\(\s*['"]?([^'")]+)['"]?\s*\)/g, (m, url) => {
+    if (!isLocal(url)) return m;
+    const abs = resolve(cssDir, url);
+    return existsSync(abs) ? `url(${dataUri(abs)})` : m;
+  });
+}
+
+/**
+ * Produce a self-contained version of `html`. Local assets are resolved against `baseDir`.
+ * @returns {string}
+ */
+export function inlineHtml(html, { baseDir }) {
+  const $ = cheerio.load(html);
+
+  $('link[rel="stylesheet"]').each((_, el) => {
+    const href = $(el).attr("href");
+    if (!isLocal(href)) return;
+    const abs = resolve(baseDir, href);
+    if (!existsSync(abs)) return;
+    const css = inlineCssUrls(readFileSync(abs, "utf-8"), dirname(abs));
+    $(el).replaceWith(`<style>${css}</style>`);
+  });
+
+  $("script[src]").each((_, el) => {
+    const src = $(el).attr("src");
+    if (!isLocal(src)) return;
+    const abs = resolve(baseDir, src);
+    if (!existsSync(abs)) return;
+    $(el).removeAttr("src").text(readFileSync(abs, "utf-8"));
+  });
+
+  $("img[src]").each((_, el) => {
+    const src = $(el).attr("src");
+    if (!isLocal(src)) return;
+    const abs = resolve(baseDir, src);
+    if (existsSync(abs)) $(el).attr("src", dataUri(abs));
+  });
+
+  // Inline any remaining <style> blocks' url() refs (baseDir-relative).
+  $("style").each((_, el) => {
+    const css = $(el).html();
+    if (css && css.includes("url(")) $(el).text(inlineCssUrls(css, baseDir));
+  });
+
+  return $.html();
+}
+
+function exportsDir(dir) {
+  const out = join(dir, "exports");
+  mkdirSync(out, { recursive: true });
+  return out;
+}
+
+/** Export version → self-contained HTML. @returns {{ path: string, bytes: number }} */
+export function exportHtml(dir, version, outPath) {
+  const html = inlineHtml(readVersionHtml(dir, version), { baseDir: dir });
+  const path = outPath || join(exportsDir(dir), `export_v${version}.html`);
+  writeFileSync(path, html);
+  return { path, bytes: Buffer.byteLength(html) };
+}
+
+/** Locate a Chrome/Chromium binary (env override wins). */
+export function findChrome(override) {
+  const candidates = [
+    override, process.env.WI_CHROME,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser",
+  ].filter(Boolean);
+  return candidates.find((c) => existsSync(c)) || null;
+}
+
+/** Default PDF renderer: headless Chrome --print-to-pdf over the self-contained HTML. */
+export function chromeRenderer(htmlPath, pdfPath, { chromePath } = {}) {
+  const chrome = findChrome(chromePath);
+  if (!chrome) throw new Error("no Chrome/Chromium found for PDF render (set WI_CHROME)");
+  const r = spawnSync(chrome, [
+    "--headless=new", "--disable-gpu", "--no-sandbox",
+    "--no-pdf-header-footer", `--print-to-pdf=${pdfPath}`, `file://${htmlPath}`,
+  ], { timeout: 60000 });
+  if (r.status !== 0 || !existsSync(pdfPath)) {
+    throw new Error(`chrome PDF render failed (status ${r.status}): ${r.stderr?.toString().slice(0, 300)}`);
+  }
+}
+
+/**
+ * Export version → PDF. First builds the self-contained HTML, then renders it.
+ * `renderer(htmlPath, pdfPath, opts)` is injectable (tests pass a fake).
+ * @returns {{ path: string }}
+ */
+export function exportPdf(dir, version, outPath, { renderer = chromeRenderer, chromePath } = {}) {
+  const { path: htmlPath } = exportHtml(dir, version, join(exportsDir(dir), `export_v${version}.pdf.html`));
+  const path = outPath || join(exportsDir(dir), `export_v${version}.pdf`);
+  renderer(htmlPath, path, { chromePath });
+  return { path };
+}

package/src/service/fsstore.js

@@ -0,0 +1,26 @@
+// fsstore.js — shared on-disk primitives for a document workspace. Kept separate so both
+// workspace.js and structural.js can use them without importing each other (no cycle).
+
+import { readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+
+const MANIFEST = "versions.json";
+
+/** Atomic write: temp file + rename (so a watcher never reads a half-written file). */
+export function atomicWrite(path, content) {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+export function loadManifest(dir) {
+  return JSON.parse(readFileSync(join(dir, MANIFEST), "utf-8"));
+}
+
+export function saveManifest(dir, manifest) {
+  atomicWrite(join(dir, MANIFEST), JSON.stringify(manifest, null, 2));
+}
+
+export function readVersionHtml(dir, version) {
+  return readFileSync(join(dir, `_v${version}.html`), "utf-8");
+}

package/src/service/generation.js

@@ -0,0 +1,105 @@
+// generation.js — delegate "build a document from my content" to the supervising agent
+// (ADR-0010). The service is model-free: it cannot index files or generate HTML. So when a
+// doc is created with kind:"source", the service seeds a placeholder v0 and writes
+// requests/_gen.request.json; the agent reads the source materials, drives wicked-prezzie /
+// wicked-brain, and writes requests/_gen.response.json with the full first draft. The
+// service instruments + themes it and lands it as a follow-on version.
+//
+// Unlike a structural edit, the generated draft is a whole new document — there are no
+// pre-existing data-wid anchors to preserve (the placeholder v0's anchors are throwaway),
+// so instrument() simply assigns fresh ones.
+
+import { readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { instrument } from "../core/instrument.js";
+import { themed } from "./theme-source.js";
+import { recordVersion, nextVersionNumber, getVersion } from "../core/versions.js";
+import { atomicWrite, loadManifest, saveManifest } from "./fsstore.js";
+
+export const REQUESTS_DIR = "requests";
+export const GEN_REQUEST = "_gen.request.json";
+export const GEN_RESPONSE = "_gen.response.json";
+
+/** Placeholder shown at v0 while the agent builds the real draft from the user's content. */
+export function generationPlaceholder(name, sourcePaths, brief = "") {
+  const safe = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const paths = (Array.isArray(sourcePaths) ? sourcePaths : [sourcePaths]).filter(Boolean);
+  const title = safe((name || "your document").replace(/-/g, " "));
+  // Brief-only generation is first-class: with no source files the agent drafts from the
+  // brief alone, so the placeholder describes that instead of "0 locations".
+  const sources = paths.length === 0
+    ? "your brief"
+    : paths.length === 1
+      ? `<code>${safe(paths[0])}</code>`
+      : `${paths.length} locations`;
+  const list = paths.length > 1
+    ? `<ul>${paths.map((p) => `<li><code>${safe(p)}</code></li>`).join("")}</ul>`
+    : "";
+  const briefBlock = paths.length === 0 && brief
+    ? `<blockquote>${safe(brief)}</blockquote>`
+    : "";
+  return (
+    `<section>` +
+      `<h1>Building ${title}…</h1>` +
+      `<p class="lead">Reading ${sources} and drafting your document. ` +
+      `This view updates automatically the moment the first draft is ready.</p>` +
+      briefBlock +
+      list +
+    `</section>`
+  );
+}
+
+/**
+ * Write the generation work request for a freshly-created source doc. The agent watches for
+ * this file (or the `generation` SSE event) and fulfills it.
+ * @returns {{ requestFile: string }}
+ */
+export function writeGenerationRequest(dir, { sourcePaths, brief = "", documentId = dir, baseHtmlFile = "_v0.html" }) {
+  mkdirSync(join(dir, REQUESTS_DIR), { recursive: true });
+  const paths = (Array.isArray(sourcePaths) ? sourcePaths : [sourcePaths]).map((s) => String(s).trim()).filter(Boolean);
+  const body = {
+    document_id: documentId,
+    source_paths: paths,
+    brief,
+    base_html: baseHtmlFile,
+    ts: new Date().toISOString(),
+  };
+  atomicWrite(join(dir, REQUESTS_DIR, GEN_REQUEST), JSON.stringify(body, null, 2));
+  return { requestFile: GEN_REQUEST };
+}
+
+/**
+ * Apply the agent's generated draft as a follow-on version. Response shape: { html }.
+ * Instruments (fresh data-wids) and themes the draft, then records it write-once (INV-4)
+ * with the current head as parent.
+ * @returns {Promise<{version:number, parent:number}>}
+ */
+export async function applyGeneratedDraft(dir, responseFile, opts = {}) {
+  const resp = JSON.parse(readFileSync(join(dir, REQUESTS_DIR, responseFile), "utf-8"));
+  const html = String(resp.html ?? "");
+  if (!html.trim()) throw new Error("generation response missing html");
+
+  let manifest = loadManifest(dir);
+  const parent = manifest.head;
+  const version = nextVersionNumber(manifest);
+  const prepared = themed(instrument(html).html, opts);
+  atomicWrite(join(dir, `_v${version}.html`), prepared);
+  ({ manifest } = recordVersion(manifest, { version, parent, feedbackFile: responseFile }));
+  saveManifest(dir, manifest);
+
+  if (typeof opts.emit === "function") {
+    opts.emit("HTML_UPDATED", {
+      document_id: opts.documentId ?? dir,
+      version, html_file: `_v${version}.html`, prev_version: parent, ts: new Date().toISOString(),
+    });
+  }
+  return { version, parent };
+}
+
+/** Whether a doc still has a pending (unfulfilled) generation request. */
+export function hasPendingGeneration(dir) {
+  try {
+    return getVersion(loadManifest(dir), 1) == null
+      && readFileSync(join(dir, REQUESTS_DIR, GEN_REQUEST), "utf-8").length > 0;
+  } catch { return false; }
+}

package/src/service/preflight.js

@@ -0,0 +1,84 @@
+// preflight.js — detect required sibling plugins (ADR-0016).
+//
+// Each plugin has its own detection rule because they install differently:
+//   wicked-prezzie / wicked-garden  → Claude Code plugin caches (a directory per plugin)
+//   wicked-brain                    → npm package; the on-disk signal is the brain dir
+//                                      under ~/.wicked-brain (or its Windows equivalent).
+//
+// The plugin-cache list is overrideable via env (`WI_PLUGIN_PATHS`, colon-separated) so
+// non-default installations and tests can be picked up.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+// Exported so service-level plugin-cache lookups (e.g. theme-source) reuse the same paths.
+export function pluginSearchPaths() {
+  const env = (process.env.WI_PLUGIN_PATHS || "").split(":").filter(Boolean);
+  const home = homedir();
+  return [
+    ...env,
+    join(home, ".claude/plugins/cache"),
+    join(home, "alt-configs/.claude/plugins/cache"),
+    join(home, ".claude-code/plugins/cache"),
+  ];
+}
+
+function inPluginCache(name) {
+  for (const base of pluginSearchPaths()) {
+    if (existsSync(join(base, name))) return true;
+  }
+  return false;
+}
+
+function brainInstalled() {
+  // npm package: the durable signal is the brain directory (created by `wicked-brain:init`).
+  // The env override doubles as a test seam — WI_PLUGIN_PATHS sets HOME in tests, so the
+  // joined path lands inside the temp dir and detection is deterministic.
+  return existsSync(join(homedir(), ".wicked-brain")) || inPluginCache("wicked-brain");
+}
+
+const DETECTORS = {
+  "wicked-prezzie": () => inPluginCache("wicked-prezzie"),
+  "wicked-garden":  () => inPluginCache("wicked-garden"),
+  "wicked-brain":   brainInstalled,
+};
+
+// Each sibling installs differently, so a single command can't cover them. The hint shown
+// in the install gate maps each MISSING plugin to its real install step (prezzie/garden are
+// Claude Code plugins; brain is an npm package run via npx).
+const INSTALL_CMD = {
+  "wicked-prezzie": "/plugin marketplace add mikeparcewski/wicked-prezzie\n/plugin install wicked-prezzie",
+  "wicked-garden":  "/plugin marketplace add mikeparcewski/wicked-garden\n/plugin install wicked-garden",
+  "wicked-brain":   "npx wicked-brain",
+};
+
+// Playwright (ADR-0018) is the demo recorder. Unlike the sibling plugins it's an npm
+// dependency, so the durable signal is whether the package resolves from this project.
+// (Browser binaries are a second gate surfaced at record time — Playwright throws a clear
+// "Executable doesn't exist, run npx playwright install" we already wrap in recordDemo.)
+// Kept OUT of `required`/`missing` so it gates only demo creation, not ordinary documents.
+export const PLAYWRIGHT_INSTALL = "npx playwright install\nplaywright-cli install --skills";
+export function playwrightInstalled() {
+  try { require.resolve("playwright"); return true; } catch { return false; }
+}
+
+/** Snapshot the install state of every required plugin. */
+export function preflight() {
+  const required = {};
+  for (const [name, detect] of Object.entries(DETECTORS)) {
+    required[name] = { detected: detect() };
+  }
+  const missing = Object.keys(DETECTORS).filter((n) => !required[n].detected);
+  return {
+    ok: missing.length === 0,
+    required,
+    missing,
+    install_hint: missing.length ? missing.map((n) => INSTALL_CMD[n]).join("\n\n") : null,
+    // Demo-only dependency, reported alongside (not folded into `ok`/`missing`).
+    playwright: { detected: playwrightInstalled(), install_hint: PLAYWRIGHT_INSTALL },
+  };
+}