wicked-interactive 0.4.0

package/src/service/structural.js

@@ -0,0 +1,103 @@
+// structural.js — delegate structural-change edits to the supervising agent (ADR-0010).
+//
+// The service writes requests/_v{n}.request.json; the agent edits each fragment
+// (preserving data-wid) and writes requests/_v{n}.response.json; the service applies the
+// response through the INV-2 gate, producing a follow-on version (write-once, INV-4).
+
+import { readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import * as cheerio from "cheerio";
+import { regenerate } from "../core/regenerate.js";
+import { instrument } from "../core/instrument.js";
+import { themed } from "./theme-source.js";
+import { recordVersion, nextVersionNumber } from "../core/versions.js";
+import { atomicWrite, loadManifest, saveManifest, readVersionHtml } from "./fsstore.js";
+
+export const REQUESTS_DIR = "requests";
+
+/** Partition feedback items into the two engine paths. */
+export function splitItems(items) {
+  const deterministic = [];
+  const structural = [];
+  for (const it of items) (it.type === "structural-change" ? structural : deterministic).push(it);
+  return { deterministic, structural };
+}
+
+/** The serialized current outerHTML of the element a structural item targets. */
+export function extractFragment(html, selector) {
+  const $ = cheerio.load(html, null, false);
+  const el = $(`[data-wid="${selector}"]`);
+  return el.length ? $.html(el) : null;
+}
+
+const rootWid = (fragmentHtml) => {
+  const $ = cheerio.load(fragmentHtml, null, false);
+  return $("[data-wid]").first().attr("data-wid") || null;
+};
+
+/**
+ * Write the structural work request for version `version` (the partial). Each item gets
+ * its current fragment extracted from the partial HTML so the agent edits the real markup.
+ * @returns {{ requestFile: string, count: number }}
+ */
+export function writeStructuralRequest(dir, { version, baseHtmlFile, structural, documentId = dir }) {
+  mkdirSync(join(dir, REQUESTS_DIR), { recursive: true });
+  const html = readFileSync(join(dir, baseHtmlFile), "utf-8");
+  const items = structural.map((it) => ({
+    selector: it.selector,
+    instruction: it.instruction,
+    fragment: extractFragment(html, it.selector),
+  }));
+  const requestFile = `_v${version}.request.json`;
+  const body = { document_id: documentId, version, base_html: baseHtmlFile, items };
+  atomicWrite(join(dir, REQUESTS_DIR, requestFile), JSON.stringify(body, null, 2));
+  return { requestFile, count: items.length };
+}
+
+/**
+ * Apply an agent response: finalize the structural edits as a follow-on version.
+ * Response shape: { version, results: [{ selector, fragment }] }.
+ * The INV-2 gate (in regenerate) rejects any fragment that dropped a data-wid.
+ * @returns {Promise<{version:number, parent:number, applied:string[], rejected:object[]}>}
+ */
+export async function applyStructuralResponse(dir, responseFile, opts = {}) {
+  const resp = JSON.parse(readFileSync(join(dir, REQUESTS_DIR, responseFile), "utf-8"));
+  const parent = resp.version;
+  const bySelector = new Map(resp.results.map((r) => [r.selector, r.fragment]));
+
+  const baseHtml = readVersionHtml(dir, parent);
+  const feedback = {
+    items: resp.results.map((r) => (r.remove
+      ? { selector: r.selector, type: "remove" }
+      : { selector: r.selector, type: "structural-change", instruction: "(delegated)" })),
+  };
+  const llm = async (fragmentBefore) => {
+    const sel = rootWid(fragmentBefore);
+    const frag = bySelector.get(sel);
+    if (frag == null) throw new Error(`no agent result for ${sel}`);
+    return frag;
+  };
+
+  const { html: regenerated, applied, rejected } = await regenerate(baseHtml, feedback, { llm });
+  // Re-instrument so any new h2/p/li in the structural fragment pick up a data-wid.
+  // Without this, new content from the agent stays unclickable in the editor — INV-1
+  // still preserves existing wids, INV-2 already passed inside regenerate, so this is
+  // strictly additive.
+  // Re-apply the base theme (idempotent) so agent-produced versions stay themed (ADR-0016
+  // Slice C). Anchor-free, so the INV-2 gate that just passed is unaffected.
+  const html = themed(instrument(regenerated).html, opts);
+
+  let manifest = loadManifest(dir);
+  const version = nextVersionNumber(manifest);
+  atomicWrite(join(dir, `_v${version}.html`), html);
+  ({ 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, applied, rejected };
+}

package/src/service/theme-source.js

@@ -0,0 +1,63 @@
+// theme-source.js — resolve theme tokens from the wicked-prezzie plugin cache (ADR-0016).
+//
+// wicked-prezzie is a required sibling plugin but is NOT importable as a library (it's a
+// plugin/skill). We locate its `skills/theme/themes/<name>.json` under the same plugin search
+// paths the preflight uses and read the tokens. On any miss we fall back to the bundled
+// DEFAULT_THEME from core — resilience against prezzie's on-disk layout shifting, not
+// plugin-optional behavior (the preflight still requires prezzie to be installed).
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pluginSearchPaths } from "./preflight.js";
+import { DEFAULT_THEME, applyTheme } from "../core/theme.js";
+
+/** Locate prezzie's `skills/theme/themes` dir under any resolved plugin search path. */
+export function prezzieThemesDir() {
+  for (const base of pluginSearchPaths()) {
+    const root = join(base, "wicked-prezzie");
+    if (!existsSync(root)) continue;
+    // Direct (test-fixture layout) then the nested pkg/version cache layout.
+    const candidates = [join(root, "skills/theme/themes")];
+    let pkgs = [];
+    try { pkgs = readdirSync(root); } catch { pkgs = []; }
+    for (const pkg of pkgs) {
+      const pkgDir = join(root, pkg);
+      candidates.push(join(pkgDir, "skills/theme/themes"));
+      let vers = [];
+      try { vers = readdirSync(pkgDir); } catch { vers = []; }
+      for (const ver of vers) candidates.push(join(pkgDir, ver, "skills/theme/themes"));
+    }
+    for (const c of candidates) if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Resolve a theme token object by name. Reads prezzie's JSON if present; falls back to the
+ * bundled DEFAULT_THEME. Never throws — a missing/corrupt file degrades to the default so a
+ * version is always produced.
+ * @param {string} [name]
+ * @param {object} [opts] { themesDir?: string } — themesDir overrides discovery (tests)
+ */
+export function resolveThemeTokens(name = "corporate-light", opts = {}) {
+  const dir = opts.themesDir || prezzieThemesDir();
+  if (dir) {
+    const file = join(dir, `${name}.json`);
+    try {
+      if (existsSync(file)) return JSON.parse(readFileSync(file, "utf-8"));
+    } catch { /* fall through to default */ }
+  }
+  return DEFAULT_THEME;
+}
+
+/**
+ * Resolve the theme and apply it to an HTML string in one step — the seam used at every
+ * version-creation point. `opts.theme === false` skips theming; a string picks the theme by
+ * name; otherwise the default (`corporate-light`) is used.
+ */
+export function themed(html, opts = {}) {
+  if (opts.theme === false) return html;
+  const name = typeof opts.theme === "string" ? opts.theme : "corporate-light";
+  const tokens = resolveThemeTokens(name, opts);
+  return applyTheme(html, { tokens });
+}

package/src/service/workspace.js

@@ -0,0 +1,141 @@
+// workspace.js — a document workspace on disk and the feedback->regenerate pipeline.
+//
+// Layout (one directory per document):
+//   _v0.html, _v1.html, ...   version artifacts (write-once, INV-4)
+//   _v1.md, _v2.md, ...       feedback files (no _v0.md — v0 is the initial build)
+//   versions.json             parent-pointer manifest (ADR-0008)
+//   requests/                 structural-change delegation to the agent (ADR-0010)
+//
+// The service is the SINGLE writer of feedback files (ADR-0002): writes are atomic so the
+// watcher never reads a half-written file. Deterministic edits apply immediately;
+// structural edits are delegated to the supervising agent (ADR-0010).
+
+import { readFileSync, mkdirSync, readdirSync, copyFileSync } from "node:fs";
+import { join } from "node:path";
+import { instrument } from "../core/instrument.js";
+import { parseFeedback, serializeFeedback } from "../core/feedback-schema.js";
+import { regenerate } from "../core/regenerate.js";
+import { initManifest, recordVersion, getVersion, nextVersionNumber } from "../core/versions.js";
+import { atomicWrite, loadManifest, saveManifest, readVersionHtml } from "./fsstore.js";
+import { splitItems, writeStructuralRequest } from "./structural.js";
+import { themed } from "./theme-source.js";
+
+// Re-export the store reads so existing callers (server, tests) keep their import path.
+export { loadManifest, readVersionHtml } from "./fsstore.js";
+
+const versionFromHtmlFile = (f) => Number(/_v(\d+)\.html$/.exec(f)?.[1]);
+
+// Highest _v{n}.{md,html} on disk — so rapid writes reserve distinct numbers even before
+// the manifest is updated (two quick UPDATEs must not both grab _v1.md).
+function highestVersionOnDisk(dir) {
+  let max = -1;
+  for (const f of readdirSync(dir)) {
+    const m = /^_v(\d+)\.(md|html)$/.exec(f);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max;
+}
+
+/**
+ * Initialise a workspace from an HTML draft. Instruments it with data-wid (unless
+ * opts.instrument === false), writes _v0.html, and seeds the manifest.
+ */
+export function initWorkspace(dir, html, opts = {}) {
+  mkdirSync(dir, { recursive: true });
+  const anchored = opts.instrument === false ? html : instrument(html).html;
+  // Apply the prezzie-derived base theme so every version (including v0) shares a consistent
+  // look (ADR-0016 Slice C). Idempotent + anchor-free, so INV-1/INV-2 are unaffected.
+  const prepared = themed(anchored, opts);
+  atomicWrite(join(dir, "_v0.html"), prepared);
+  const manifest = initManifest("_v0.html", { kind: opts.kind });
+  saveManifest(dir, manifest);
+  return { manifest };
+}
+
+/**
+ * Write a feedback file as the single writer. Allocates the next version number,
+ * validates the feedback (round-trips through the schema), and writes _v{n}.md atomically.
+ * Does NOT touch the manifest — the version becomes real only once its HTML is produced.
+ */
+export function writeFeedback(dir, { items, author }) {
+  const manifest = loadManifest(dir);
+  const base = getVersion(manifest, manifest.head);
+  const version = Math.max(nextVersionNumber(manifest), highestVersionOnDisk(dir) + 1);
+  const feedback = {
+    frontmatter: {
+      version, base_html: base.html_file, timestamp: new Date().toISOString(),
+      ...(author ? { author } : {}),
+    },
+    items,
+  };
+  const md = serializeFeedback(feedback);
+  parseFeedback(md); // validate by round-trip; throws on invalid schema
+  const file = `_v${version}.md`;
+  atomicWrite(join(dir, file), md);
+  return { version, file };
+}
+
+/**
+ * Fork from an existing version (AC-21): non-destructive "start again from here". Copies
+ * _v{from}.html to a new write-once version whose parent is `from`; the new version becomes
+ * the head. Nothing is removed (AC-22).
+ * @returns {{ version: number, parent: number }}
+ */
+export function forkVersion(dir, from) {
+  let manifest = loadManifest(dir);
+  if (getVersion(manifest, from) == null) throw new Error(`fork: v${from} does not exist`);
+  const version = Math.max(nextVersionNumber(manifest), highestVersionOnDisk(dir) + 1);
+  copyFileSync(join(dir, `_v${from}.html`), join(dir, `_v${version}.html`));
+  ({ manifest } = recordVersion(manifest, { version, parent: from, feedbackFile: null }));
+  saveManifest(dir, manifest);
+  return { version, parent: from };
+}
+
+/**
+ * Process a feedback file: apply the DETERMINISTIC edits immediately (cheerio), write the
+ * partial _v{n}.html, record the version, and emit. STRUCTURAL items are delegated to the
+ * supervising agent via a request file (ADR-0010) and finalized later as a follow-on
+ * version. Idempotent on (version).
+ * @returns {Promise<{version,html_file,applied,rejected,stale,awaiting_structural}>}
+ */
+export async function processFeedbackFile(dir, mdFile, opts = {}) {
+  const md = readFileSync(join(dir, mdFile), "utf-8");
+  const feedback = parseFeedback(md);
+  const version = feedback.frontmatter.version;
+  const parent = versionFromHtmlFile(feedback.frontmatter.base_html);
+
+  let manifest = loadManifest(dir);
+  if (getVersion(manifest, version) != null) {
+    const existing = getVersion(manifest, version);
+    return { version, html_file: existing.html_file, applied: [], rejected: [], stale: [], awaiting_structural: 0, idempotent: true };
+  }
+
+  const { deterministic, structural } = splitItems(feedback.items);
+  const prevHtml = readVersionHtml(dir, parent);
+  const { html: regenerated, applied, rejected, stale } = await regenerate(prevHtml, { items: deterministic }, {});
+  // Re-instrument so any new h2/p/li introduced by the regen pick up a data-wid.
+  // instrument() preserves existing wids (INV-1), only ADDS for untagged blocks; safe to
+  // run after INV-2 has already passed. Without this, content added via structural-change
+  // stays unclickable in the editor.
+  // Re-apply the base theme (idempotent — replaces the inherited block) so the version stays
+  // themed after regeneration (ADR-0016 Slice C).
+  const html = themed(instrument(regenerated).html, opts);
+  atomicWrite(join(dir, `_v${version}.html`), html);
+  ({ manifest } = recordVersion(manifest, { version, parent, feedbackFile: mdFile }));
+  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(),
+    });
+  }
+
+  let awaiting_structural = 0;
+  if (structural.length) {
+    ({ count: awaiting_structural } = writeStructuralRequest(dir, {
+      version, baseHtmlFile: `_v${version}.html`, structural, documentId: opts.documentId ?? dir,
+    }));
+  }
+  return { version, html_file: `_v${version}.html`, applied, rejected, stale, awaiting_structural };
+}