@liustack/pptfast 0.8.0 → 0.11.0

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   resolveSpecThemeId,
   specJsonSchema,
   validateSpec
-} from "./chunk-HBRSZW67.js";
+} from "./chunk-WCBFCHOZ.js";
 import {
   installNodePlatform
 } from "./chunk-HFRNKYZ6.js";
@@ -35,7 +35,7 @@ import {
   sniffImageFormat,
   styleJsonSchema,
   validateIr
-} from "./chunk-4NKLJ7OK.js";
+} from "./chunk-ONO7V2SF.js";
 import {
   getPlatform
 } from "./chunk-L524YK63.js";
@@ -573,7 +573,10 @@ var JS = `
   // skills/pptfast/SKILL.md's phase-6 revision-request handling). Zero
   // network/storage \u2014 an in-memory Blob + a synthetic <a download> click,
   // the standard browser-only download pattern.
-  exportBtn.addEventListener('click', function () {
+  // pptfast serve (src/cli/serve.ts) depends on this function's
+  // callable-and-synchronous contract and return type \u2014 think before
+  // changing.
+  function buildExportBlob() {
     var requests = []
     Object.keys(annotations).forEach(function (key) {
       var i = parseInt(key, 10)
@@ -584,7 +587,16 @@ var JS = `
     })
     var deckTitle = document.getElementById('pf-title').textContent
     var payload = { version: '1', deck: deckTitle, requests: requests }
-    var blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
+    return new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' })
+  }
+  // The one sanctioned cross-module seam this file exposes (see this
+  // module's own doc comment) \u2014 a plain function reference, not data, so
+  // the caller always gets this build's live annotation state, never a
+  // stale snapshot.
+  window.__pptfastBuildExportBlob = buildExportBlob
+
+  exportBtn.addEventListener('click', function () {
+    var blob = buildExportBlob()
     var url = URL.createObjectURL(blob)
     var a = document.createElement('a')
     a.href = url
@@ -695,10 +707,11 @@ async function loadDeckTarget(arg, cwd, projectHit, userHit) {
   const target = await resolveDeckTarget(arg, resolveDecksDirSource(projectHit, userHit), cwd);
   if (await isDeckDirectory(target)) {
     const { ir, deckDir } = await readDeckDir(target);
-    return { raw: ir, baseDir: deckDir, isDir: true };
+    return { raw: ir, baseDir: deckDir, isDir: true, resolvedTarget: deckDir };
   }
   const raw = await loadIrFile(target);
-  return { raw, baseDir: dirname2(resolve5(target)), isDir: false };
+  const resolvedFile = resolve5(target);
+  return { raw, baseDir: dirname2(resolvedFile), isDir: false, resolvedTarget: resolvedFile };
 }
 async function runRender(irPath, opts) {
   const cwd = opts.cwd ?? process.cwd();
@@ -799,7 +812,10 @@ async function runSpecValidate(specPath) {
   }
   const spec2 = v.spec;
   const axes = resolveNarrative(spec2.narrative);
-  return `OK \u2014 ${spec2.pages.length} pages, narrative ${axes.strategy}/${axes.pacing}/${axes.audience}, theme "${resolveSpecThemeId(spec2)}"`;
+  const ok = `OK \u2014 ${spec2.pages.length} pages, narrative ${axes.strategy}/${axes.pacing}/${axes.audience}, theme "${resolveSpecThemeId(spec2)}"`;
+  const aliasNote = normalizedNote(v.normalized);
+  return aliasNote ? `${ok}
+${aliasNote}` : ok;
 }
 function runSchema(mode) {
   const schema = mode === "style" ? styleJsonSchema() : mode === "spec" ? specJsonSchema() : irJsonSchema();
@@ -850,50 +866,61 @@ async function runInit(cwd = process.cwd()) {
   }
   return `wrote ${target} \u2014 themes: \`pptfast themes\`, style schema: \`pptfast schema --style\``;
 }
-async function runPreview(irPath, outDir, opts = {}) {
+async function renderDeckSlides(target, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
-  const { raw, baseDir } = await loadDeckTarget(irPath, cwd, projectHit, userHit);
+  const { raw, baseDir, isDir, resolvedTarget } = await loadDeckTarget(target, cwd, projectHit, userHit);
   await applyDeckConfig(raw, { cwd, projectHit, userHit });
   const v = validateIr(raw);
   if (!v.ok) throw new PptfastError(`invalid IR:
 ${formatIssues(v.errors)}`);
   await resolveLocalAssets(v.ir, baseDir);
-  await mkdir2(outDir, { recursive: true });
   const ir = v.ir;
-  const svgs = [];
+  const svgs = ir.slides.map((_, i) => renderSlideSvg(ir, i));
+  return { ir, svgs, resolvedTarget, isDir, normalized: v.normalized };
+}
+function buildDeckAuditAndHtml(ir, svgs) {
+  const hasPlaceholder = ir.slides.some((slide) => slide.placeholder);
+  const auditReport = hasPlaceholder ? void 0 : auditDeck(ir);
+  const findings = auditReport?.findings ?? [];
+  const html = buildPreviewHtml({
+    title: ir.filename,
+    slides: ir.slides.map((slide, i) => ({
+      index: i,
+      id: slide.id,
+      type: slide.type,
+      svg: svgs[i],
+      placeholder: slide.placeholder
+    })),
+    findings: findings.map((f) => ({ page: f.page, slideId: f.slideId, code: f.code, message: f.message })),
+    auditNote: hasPlaceholder ? "audit overlay skipped \u2014 deck has unfilled placeholder pages; fill every page and re-run `pptfast preview --html` to see audit findings" : void 0,
+    checks: auditReport?.checks
+  });
+  return { html, findings, checks: auditReport?.checks };
+}
+async function buildDeckPreview(target, opts = {}) {
+  const rendered = await renderDeckSlides(target, opts);
+  const { html, findings, checks } = buildDeckAuditAndHtml(rendered.ir, rendered.svgs);
+  return { ...rendered, html, findings, checks };
+}
+async function runPreview(irPath, outDir, opts = {}) {
+  const { ir, svgs, normalized } = await renderDeckSlides(irPath, { cwd: opts.cwd });
+  await mkdir2(outDir, { recursive: true });
   for (let i = 0; i < ir.slides.length; i++) {
-    const svg = renderSlideSvg(ir, i);
-    svgs.push(svg);
     const name = `${String(i + 1).padStart(3, "0")}-${ir.slides[i].type}.svg`;
-    await writeFile2(join4(outDir, name), svg);
+    await writeFile2(join4(outDir, name), svgs[i]);
   }
   const ok = `wrote ${ir.slides.length} SVG files to ${outDir}`;
   const notes = [];
-  const aliasNote = normalizedNote(v.normalized);
+  const aliasNote = normalizedNote(normalized);
   if (aliasNote) notes.push(aliasNote);
   if (opts.htmlOut) {
+    const { html, findings } = buildDeckAuditAndHtml(ir, svgs);
     const htmlPath = join4(outDir, "preview.html");
-    const hasPlaceholder = ir.slides.some((slide) => slide.placeholder);
-    const auditReport = hasPlaceholder ? void 0 : auditDeck(ir);
-    const auditFindings = auditReport?.findings ?? [];
-    const html = buildPreviewHtml({
-      title: ir.filename,
-      slides: ir.slides.map((slide, i) => ({
-        index: i,
-        id: slide.id,
-        type: slide.type,
-        svg: svgs[i],
-        placeholder: slide.placeholder
-      })),
-      findings: auditFindings.map((f) => ({ page: f.page, slideId: f.slideId, code: f.code, message: f.message })),
-      auditNote: hasPlaceholder ? "audit overlay skipped \u2014 deck has unfilled placeholder pages; fill every page and re-run `pptfast preview --html` to see audit findings" : void 0,
-      checks: auditReport?.checks
-    });
     await writeFile2(htmlPath, html);
     notes.push(`note: wrote self-contained preview to ${htmlPath}`);
-    if (auditFindings.length > 0) {
-      notes.push(`note: audit found ${auditFindings.length} finding${auditFindings.length === 1 ? "" : "s"} \u2014 see preview.html`);
+    if (findings.length > 0) {
+      notes.push(`note: audit found ${findings.length} finding${findings.length === 1 ? "" : "s"} \u2014 see preview.html`);
     }
   }
   return notes.length > 0 ? `${ok}
@@ -1040,6 +1067,341 @@ ${detail}`);
   return `wrote ${outPath} (migrated IR v3 \u2192 v4)`;
 }
 
+// src/cli/serve.ts
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import { watch } from "fs";
+import { rename, unlink, writeFile as writeFile3 } from "fs/promises";
+import { createServer } from "http";
+import { platform as osPlatform } from "os";
+import { dirname as dirname3, join as join5 } from "path";
+var DEFAULT_PORT = 4400;
+var DEBOUNCE_MS = 200;
+var HEARTBEAT_MS = 3e4;
+var REVISION_REQUEST_FILENAME = "revision-request.json";
+var MAX_REVISION_REQUEST_BYTES = 1024 * 1024;
+function watchRoots(resolvedTarget, isDir) {
+  if (!isDir) return [resolvedTarget];
+  return [join5(resolvedTarget, SPEC_FILENAME), join5(resolvedTarget, PAGES_DIRNAME), join5(resolvedTarget, ASSETS_DIRNAME)];
+}
+var SERVE_CLIENT_SCRIPT_ID = "pptfast-serve-client";
+var SERVE_CLIENT_JS = `
+(function () {
+  // Each of the two jobs below is independently wrapped (own function, own
+  // try/catch at its call site at the bottom) so a failure in one \u2014 an
+  // EventSource construction that throws in some unusual embedding, a
+  // future buildPreviewHtml markup change that drops #pf-export-btn \u2014 can
+  // never take the other down with it; a single un-isolated top-level
+  // throw would otherwise abort the rest of this IIFE.
+
+  function setUpLiveReload() {
+    var es = new EventSource('/events')
+    es.addEventListener('reload', function () { location.reload() })
+
+    var banner = document.createElement('div')
+    banner.id = 'pptfast-serve-error-banner'
+    banner.setAttribute('role', 'alert')
+    banner.style.cssText =
+      'display:none;position:fixed;top:0;left:0;right:0;z-index:2147483647;' +
+      'background:#dc2626;color:#fff;font:13px/1.4 -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;' +
+      'padding:8px 16px;text-align:center'
+    document.body.appendChild(banner)
+
+    function showBanner(message) {
+      banner.textContent = 'pptfast serve: ' + message
+      banner.style.display = 'block'
+    }
+
+    es.addEventListener('error', function (e) {
+      if (!e || typeof e.data !== 'string') return // a real connection hiccup, not the server's own rebuild-failed frame
+      var message = 'rebuild failed'
+      try {
+        var parsed = JSON.parse(e.data)
+        if (parsed && typeof parsed.message === 'string') message = parsed.message
+      } catch (err) {}
+      showBanner(message)
+    })
+  }
+
+  function setUpRevisionRequestSubmit() {
+    var originalBtn = document.getElementById('pf-export-btn')
+    if (!originalBtn) return
+
+    var submitBtn = originalBtn.cloneNode(true)
+    submitBtn.textContent = 'Submit revision request'
+    originalBtn.replaceWith(submitBtn)
+
+    var status = document.createElement('span')
+    status.id = 'pptfast-serve-submit-status'
+    status.setAttribute('aria-live', 'polite')
+    status.style.cssText = 'margin-left:8px;font-size:12px'
+
+    var downloadLink = document.createElement('a')
+    downloadLink.id = 'pptfast-serve-download-fallback'
+    downloadLink.href = '#'
+    downloadLink.textContent = 'download a copy instead'
+    downloadLink.style.cssText = 'margin-left:8px;font-size:12px;color:#2563eb'
+
+    submitBtn.insertAdjacentElement('afterend', status)
+    status.insertAdjacentElement('afterend', downloadLink)
+
+    submitBtn.addEventListener('click', function () {
+      if (typeof window.__pptfastBuildExportBlob !== 'function') {
+        status.style.color = '#dc2626'
+        status.textContent = 'failed to submit revision request (export function unavailable \u2014 try reloading the page)'
+        return
+      }
+      status.style.color = ''
+      status.textContent = 'submitting\u2026'
+      // The extra Promise.resolve().then(...) wrapper (rather than calling
+      // window.__pptfastBuildExportBlob() directly and chaining off its
+      // result) means a synchronous throw from that call lands in the same
+      // .catch below as an async rejection or a network failure \u2014 every
+      // failure mode this chain can hit surfaces as the same inline
+      // status-line feedback, none of them silent.
+      Promise.resolve()
+        .then(function () {
+          return window.__pptfastBuildExportBlob()
+        })
+        .then(function (blob) {
+          return blob.text()
+        })
+        .then(function (text) {
+          return fetch('/revision-request', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: text,
+          })
+        })
+        .then(function (res) {
+          if (!res.ok) throw new Error('server responded ' + res.status)
+          status.style.color = '#16a34a'
+          status.textContent = 'Revision request saved to the deck directory'
+        })
+        .catch(function (err) {
+          status.style.color = '#dc2626'
+          status.textContent = 'failed to submit revision request' + (err && err.message ? ' (' + err.message + ')' : '')
+        })
+    })
+
+    downloadLink.addEventListener('click', function (e) {
+      e.preventDefault()
+      originalBtn.click()
+    })
+  }
+
+  try {
+    setUpLiveReload()
+  } catch (e) {
+    console.error('pptfast serve: failed to set up live reload', e)
+  }
+  try {
+    setUpRevisionRequestSubmit()
+  } catch (e) {
+    console.error('pptfast serve: failed to set up revision-request submit', e)
+  }
+})()
+`.trim();
+function buildServeClientScriptTag() {
+  return `<script id="${SERVE_CLIENT_SCRIPT_ID}">${SERVE_CLIENT_JS}</script>`;
+}
+function injectServeClient(html) {
+  if (html.includes(SERVE_CLIENT_SCRIPT_ID)) return html;
+  return html.replace("</body>", `${buildServeClientScriptTag()}
+</body>`);
+}
+async function atomicWriteFile(targetPath, data) {
+  const tmpPath = `${targetPath}.${randomUUID()}.tmp`;
+  await writeFile3(tmpPath, data, "utf8");
+  try {
+    await rename(tmpPath, targetPath);
+  } catch (e) {
+    await unlink(tmpPath).catch(() => {
+    });
+    throw e;
+  }
+}
+async function createServeServer(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const requestedPort = options.port ?? DEFAULT_PORT;
+  if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
+    throw new PptfastError(`invalid port ${requestedPort} \u2014 expected an integer between 0 and 65535`);
+  }
+  const initial = await buildDeckPreview(options.target, { cwd });
+  let cachedHtml = injectServeClient(initial.html);
+  const sseClients = /* @__PURE__ */ new Set();
+  const revisionRequestPath = initial.isDir ? join5(initial.resolvedTarget, REVISION_REQUEST_FILENAME) : join5(dirname3(initial.resolvedTarget), REVISION_REQUEST_FILENAME);
+  function writeToAll(chunk) {
+    for (const res of sseClients) {
+      try {
+        res.write(chunk);
+      } catch {
+      }
+    }
+  }
+  function broadcast(event, data) {
+    writeToAll(`event: ${event}
+data: ${JSON.stringify(data)}
+
+`);
+  }
+  async function rebuild() {
+    try {
+      const result = await buildDeckPreview(options.target, { cwd });
+      cachedHtml = injectServeClient(result.html);
+      broadcast("reload", {});
+    } catch (e) {
+      broadcast("error", { message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  async function handleRevisionRequestPost(req, res) {
+    const chunks = [];
+    let total = 0;
+    try {
+      for await (const chunk of req) {
+        total += chunk.length;
+        if (total > MAX_REVISION_REQUEST_BYTES) {
+          res.writeHead(413, { "Content-Type": "text/plain; charset=utf-8" });
+          res.end(`revision request body exceeds the ${MAX_REVISION_REQUEST_BYTES}-byte limit`);
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      }
+    } catch {
+      return;
+    }
+    const body = Buffer.concat(chunks).toString("utf8");
+    try {
+      JSON.parse(body);
+    } catch {
+      res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("invalid JSON body");
+      return;
+    }
+    try {
+      await atomicWriteFile(revisionRequestPath, body);
+    } catch (e) {
+      res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(`failed to write ${REVISION_REQUEST_FILENAME}: ${e instanceof Error ? e.message : String(e)}`);
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: true }));
+  }
+  const server = createServer((req, res) => {
+    const pathname = (req.url ?? "/").split("?")[0];
+    if (req.method === "GET" && pathname === "/") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(cachedHtml);
+      return;
+    }
+    if (req.method === "GET" && pathname === "/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive"
+      });
+      res.write("retry: 2000\n\n");
+      sseClients.add(res);
+      res.on("close", () => sseClients.delete(res));
+      res.on("error", () => sseClients.delete(res));
+      return;
+    }
+    if (pathname === "/revision-request") {
+      if (req.method !== "POST") {
+        res.writeHead(405, { "Content-Type": "text/plain; charset=utf-8", Allow: "POST" });
+        res.end("method not allowed \u2014 only POST is accepted on /revision-request");
+        return;
+      }
+      void handleRevisionRequestPost(req, res);
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("not found");
+  });
+  const heartbeat = setInterval(() => writeToAll(": heartbeat\n\n"), HEARTBEAT_MS);
+  let debounceTimer;
+  function scheduleRebuild() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = void 0;
+      void rebuild();
+    }, DEBOUNCE_MS);
+  }
+  const watchers = [];
+  for (const path of watchRoots(initial.resolvedTarget, initial.isDir)) {
+    try {
+      watchers.push(watch(path, () => scheduleRebuild()));
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+  function teardownWatchersAndTimers() {
+    clearInterval(heartbeat);
+    if (debounceTimer) clearTimeout(debounceTimer);
+    for (const w of watchers) w.close();
+  }
+  try {
+    await new Promise((resolveListen, rejectListen) => {
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        rejectListen(err);
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolveListen();
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(requestedPort, "127.0.0.1");
+    });
+  } catch (e) {
+    teardownWatchersAndTimers();
+    if (e.code === "EADDRINUSE") {
+      throw new PptfastError(`port ${requestedPort} is already in use \u2014 pick a different one with --port`);
+    }
+    throw e;
+  }
+  const address = server.address();
+  const actualPort = typeof address === "object" && address !== null ? address.port : requestedPort;
+  let closed = false;
+  async function close() {
+    if (closed) return;
+    closed = true;
+    teardownWatchersAndTimers();
+    for (const res of sseClients) res.end();
+    sseClients.clear();
+    if (typeof server.closeIdleConnections === "function") server.closeIdleConnections();
+    if (typeof server.closeAllConnections === "function") server.closeAllConnections();
+    await new Promise((resolveClose, rejectClose) => {
+      server.close((err) => err ? rejectClose(err) : resolveClose());
+    });
+  }
+  return { server, rebuild, close, url: `http://127.0.0.1:${actualPort}`, port: actualPort };
+}
+function openBrowser(url) {
+  const command = osPlatform() === "darwin" ? "open" : "xdg-open";
+  try {
+    const child = spawn(command, [url], { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+async function runServe(target, opts = {}) {
+  const handle = await createServeServer({ target, port: opts.port, cwd: opts.cwd });
+  console.log(`pptfast serve: ${handle.url} (Ctrl+C to stop)`);
+  if (opts.open !== false) openBrowser(handle.url);
+  process.on("SIGINT", () => {
+    void handle.close().then(
+      () => process.exit(0),
+      () => process.exit(1)
+    );
+  });
+}
+
 // src/cli/update.ts
 import { execFile } from "child_process";
 var PACKAGE_NAME = "@liustack/pptfast";
@@ -1211,6 +1573,20 @@ program.command("preview").description("Render each slide to an SVG file for vis
     fail(e);
   }
 });
+program.command("serve").description("Serve a live-reloading HTML preview of an IR JSON file, deck project directory, or bare deck name over HTTP").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptfast/decks").option("--port <number>", `port to listen on (default ${DEFAULT_PORT})`).option("--no-open", "do not open the URL in a browser after starting").action(async (target, opts) => {
+  try {
+    let port;
+    if (opts.port !== void 0) {
+      port = Number(opts.port);
+      if (!Number.isInteger(port)) {
+        fail(new Error(`invalid --port value "${opts.port}" \u2014 expected an integer`));
+      }
+    }
+    await runServe(target, { port, open: opts.open });
+  } catch (e) {
+    fail(e);
+  }
+});
 program.command("check-update").description("Check npm for a newer pptfast release").action(async () => {
   const info = await checkForUpdate({ currentVersion: VERSION });
   if (!info.checked) fail(new Error(`update check failed: ${info.error}`));