voxflow 1.15.0 → 1.15.2

package/lib/stage-core/edit-prompt.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Build a copy-pasteable AI prompt that asks the user's preferred AI tool
+ * (Claude Code / Cursor / ChatGPT / etc.) to edit one card of a stage deck.
+ *
+ * Two modes:
+ *   - Card mode (default): rewrite the whole card.
+ *   - Selection mode: rewrite a specific selected substring inside the card.
+ *
+ * The function is provider-agnostic on purpose. We do not generate
+ * Cursor-flavored diff prompts vs Claude-flavored natural-language prompts;
+ * one universal template is enough for v1. If usage data shows a real need
+ * for per-provider templates, ship a `~/.config/voxflow/edit-prompt-template.md`
+ * override later (see issue #3330).
+ *
+ * The output is intentionally readable to a human (so the user can sanity-
+ * check what they're about to send to their AI), and tells the AI it only
+ * needs to edit the file in place — the stage SSE will hot-reload.
+ *
+ * @param {object} opts
+ * @param {string} opts.deckPath       Absolute path to the deck JSON file.
+ * @param {number} opts.cardIdx        Zero-based index of the card.
+ * @param {object} opts.card           The card object (any shape — we just stringify it).
+ * @param {string} [opts.selectedText] Optional selected substring to focus on.
+ * @returns {string} The prompt, ready for clipboard.
+ */
+function buildEditPrompt(opts) {
+  const deckPath = String(opts && opts.deckPath || '').trim();
+  const cardIdx = Number.isFinite(opts && opts.cardIdx) ? opts.cardIdx : 0;
+  const card = (opts && opts.card && typeof opts.card === 'object') ? opts.card : {};
+  const selectedText = (opts && typeof opts.selectedText === 'string')
+    ? opts.selectedText.trim() : '';
+
+  if (!deckPath) {
+    throw new Error('buildEditPrompt: deckPath is required');
+  }
+
+  const kind = (typeof card.kind === 'string' && card.kind) || 'unknown';
+  let cardJson;
+  try {
+    cardJson = JSON.stringify(card, null, 2);
+  } catch {
+    // Circular refs or non-serializable garbage — fall back to a minimal stub
+    // so the prompt still makes sense.
+    cardJson = JSON.stringify({ kind: card.kind || null, _note: 'card not stringifiable' }, null, 2);
+  }
+
+  const header = [
+    "I'm iterating on a Slice deck (vertical 1080x1920 card video — narrated, theme-styled).",
+    '',
+    'File to edit:',
+    '  ' + deckPath,
+    '',
+    'Card to change: cards[' + cardIdx + ']  (kind: ' + kind + ')',
+  ].join('\n');
+
+  const cardBlock = [
+    'Current card value:',
+    '```json',
+    cardJson,
+    '```',
+  ].join('\n');
+
+  const footer = [
+    'When you finish, save the file in place — preserve every other field and the JSON structure.',
+    'The local stage server is watching this file and will hot-reload the browser preview within ~150ms.',
+  ].join('\n');
+
+  if (selectedText) {
+    const selectionBlock = [
+      'Specifically, this exact substring needs to change:',
+      '  ' + JSON.stringify(selectedText),
+      '',
+      'Replace only that substring; keep everything else in the card identical unless the change requires touching adjacent text.',
+    ].join('\n');
+
+    return [
+      header,
+      '',
+      selectionBlock,
+      '',
+      cardBlock,
+      '',
+      'Change request:',
+      '  <REPLACE THIS WITH YOUR INSTRUCTION — e.g. "make it punchier", "shorten to 12 chars">',
+      '',
+      footer,
+    ].join('\n');
+  }
+
+  return [
+    header,
+    '',
+    cardBlock,
+    '',
+    'Change request:',
+    '  <REPLACE THIS WITH YOUR INSTRUCTION — e.g. "rewrite caption + narration in a more visceral tone">',
+    '',
+    footer,
+  ].join('\n');
+}
+
+module.exports = { buildEditPrompt };

package/lib/stage-core/event-bus.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Tiny pub/sub bus shared between the file watcher and SSE response streams.
+ *
+ * Subscribers register a callback; publish(event) fans out synchronously.
+ * Used to decouple the watcher (writes) from the HTTP server (reads).
+ */
+
+function createEventBus() {
+  const listeners = new Set();
+
+  return {
+    subscribe(fn) {
+      listeners.add(fn);
+      return function unsubscribe() {
+        listeners.delete(fn);
+      };
+    },
+    publish(event) {
+      for (const fn of listeners) {
+        try { fn(event); } catch { /* one bad subscriber must not break others */ }
+      }
+    },
+    size() {
+      return listeners.size;
+    },
+  };
+}
+
+module.exports = { createEventBus };

package/lib/stage-core/port.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const net = require('net');
+
+/**
+ * Probe a single port on 127.0.0.1. Resolves true if listen() succeeds.
+ */
+function probePort(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.once('error', () => resolve(false));
+    srv.once('listening', () => {
+      srv.close(() => resolve(true));
+    });
+    try {
+      srv.listen({ port, host: '127.0.0.1', exclusive: true });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Find a free port starting at `preferred`, scanning up to `maxTries` ports.
+ *
+ * Stage default is 5180 — already inside the studio CORS allowlist (5173-5186)
+ * but distinct from Vite (5173) so a parallel `studio dev` does not clash.
+ *
+ * @param {number} preferred  Starting port
+ * @param {number} maxTries   Max sequential ports to try (default 10 → 5180-5189)
+ * @returns {Promise<number>} Available port
+ * @throws  if every candidate is occupied
+ */
+async function findAvailablePort(preferred = 5180, maxTries = 10) {
+  for (let i = 0; i < maxTries; i++) {
+    const candidate = preferred + i;
+    if (await probePort(candidate)) return candidate;
+  }
+  throw new Error(
+    `No free port in [${preferred}, ${preferred + maxTries - 1}]. ` +
+    `Pass --port <n> or free a port and retry.`
+  );
+}
+
+module.exports = { findAvailablePort, probePort };

package/lib/stage-core/server.js

@@ -0,0 +1,352 @@
+'use strict';
+
+const http = require('http');
+const { findAvailablePort } = require('./port');
+
+/**
+ * Start the Stage HTTP server.
+ *
+ * Routes (MVP):
+ *   GET  /                → serves the per-module Stage UI (passed in)
+ *   GET  /healthz         → liveness probe (200 "ok")
+ *   GET  /api/deck        → returns the current deck JSON (or 404 + reason)
+ *   GET  /events          → Server-Sent Events stream (push deck updates)
+ *
+ * SSE was chosen over WebSocket to avoid a `ws` runtime dep (the CLI keeps
+ * its dep list at exactly two — `open`, `pptxgenjs`). Stage only needs
+ * server→client push; client→server actions go through plain HTTP POST when
+ * we add Phase 1.3+ (renderStill, publish).
+ *
+ * @param {object} opts
+ * @param {string} opts.uiHtml      Static HTML served at /
+ * @param {() => {deck:object|null, error?:string, sourcePath:string}} opts.getDeckSnapshot
+ * @param {(handler: (event:object) => void) => () => void} opts.subscribe
+ *        Subscribe to deck-change events (returns unsubscribe fn)
+ * @param {object} [opts.snapshots]   Optional snapshot store handle.
+ *   If provided, exposes /api/snapshots, /api/snapshots/:id, and
+ *   POST /api/snapshots/restore. Pass `null` (or omit) to disable history.
+ *   Shape: { list(), load(id), restore(id) }. `restore` writes the snapshot
+ *   bytes back to the deck file and returns the restored deck object.
+ * @param {object} [opts.cloudRender] Optional cloud-render client handle.
+ *   If provided, exposes POST /api/render-mp4, GET /api/render-status/:id,
+ *   and GET /api/quota-balance — all proxies to the upstream API. Shape:
+ *   { submit(deck), status(jobId), quota() }. Lets users go from "deck I
+ *   like" → mp4 without leaving stage; the proxy keeps the JWT off the page.
+ * @param {number} [opts.preferredPort=5180]
+ * @param {number} [opts.maxPortTries=10]
+ * @returns {Promise<{server:http.Server, port:number, url:string, close:() => Promise<void>}>}
+ */
+async function startStageServer(opts) {
+  const {
+    uiHtml,
+    getDeckSnapshot,
+    subscribe,
+    snapshots = null,
+    cloudRender = null,
+    preferredPort = 5180,
+    maxPortTries = 10,
+  } = opts;
+
+  if (typeof uiHtml !== 'string' || !uiHtml) {
+    throw new Error('startStageServer: uiHtml (string) is required');
+  }
+  if (typeof getDeckSnapshot !== 'function') {
+    throw new Error('startStageServer: getDeckSnapshot (fn) is required');
+  }
+  if (typeof subscribe !== 'function') {
+    throw new Error('startStageServer: subscribe (fn) is required');
+  }
+
+  const port = await findAvailablePort(preferredPort, maxPortTries);
+
+  const sseClients = new Set();
+
+  // Defense against drive-by requests from other browser tabs. Any tab on
+  // http://evil.com can `fetch('http://127.0.0.1:<port>/api/deck')` —
+  // binding to 127.0.0.1 stops external networks but not the local browser.
+  // Cross-origin fetch/XHR/EventSource always sends Origin; top-level
+  // navigation and curl do not. So: missing Origin = allow (address bar /
+  // curl), present + matches loopback host:port = allow, anything else = 403.
+  function isAllowedOrigin(originHeader) {
+    if (!originHeader) return true;
+    let url;
+    try { url = new URL(originHeader); } catch { return false; }
+    if (url.protocol !== 'http:') return false;
+    const hostOk = url.hostname === '127.0.0.1'
+      || url.hostname === 'localhost'
+      || url.hostname === '::1';
+    return hostOk && url.port === String(port);
+  }
+
+  const server = http.createServer((req, res) => {
+    if (!isAllowedOrigin(req.headers.origin)) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        code: 'forbidden_origin',
+        message: `Origin ${req.headers.origin} is not allowed; stage server only accepts loopback origins on port ${port}.`,
+      }));
+      return;
+    }
+
+    if (req.method === 'GET' && req.url === '/') {
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      res.end(uiHtml);
+      return;
+    }
+
+    if (req.method === 'GET' && req.url === '/healthz') {
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('ok');
+      return;
+    }
+
+    if (req.method === 'GET' && req.url === '/api/deck') {
+      const snap = getDeckSnapshot();
+      if (!snap.deck) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          code: 'deck_unavailable',
+          message: snap.error || 'No deck loaded yet.',
+          sourcePath: snap.sourcePath,
+        }));
+        return;
+      }
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      res.end(JSON.stringify({
+        code: 'success',
+        sourcePath: snap.sourcePath,
+        deck: snap.deck,
+      }));
+      return;
+    }
+
+    // ─── Snapshot history (optional; only mounted when `snapshots` passed) ──
+    if (snapshots && req.method === 'GET' && req.url === '/api/snapshots') {
+      const versions = snapshots.list();
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      res.end(JSON.stringify({
+        code: 'success',
+        storePath: snapshots.getStorePath ? snapshots.getStorePath() : '',
+        versions,
+      }));
+      return;
+    }
+
+    if (snapshots && req.method === 'GET' && req.url.startsWith('/api/snapshots/')) {
+      const id = req.url.slice('/api/snapshots/'.length);
+      const deck = snapshots.load(id);
+      if (!deck) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code: 'snapshot_not_found', message: `No snapshot: ${id}` }));
+        return;
+      }
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      res.end(JSON.stringify({ code: 'success', id, deck }));
+      return;
+    }
+
+    if (snapshots && req.method === 'POST' && req.url === '/api/snapshots/restore') {
+      const chunks = [];
+      let totalBytes = 0;
+      req.on('data', (chunk) => {
+        totalBytes += chunk.length;
+        // Hard cap; restore body is just `{ "id": "..." }` (~80 bytes)
+        if (totalBytes > 1024) {
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on('end', () => {
+        let body;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); }
+        catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ code: 'bad_json', message: 'restore body must be JSON' }));
+          return;
+        }
+        const id = body && typeof body.id === 'string' ? body.id : null;
+        if (!id || !snapshots.restore) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ code: 'invalid_id', message: 'missing or invalid id' }));
+          return;
+        }
+        let result;
+        try { result = snapshots.restore(id); }
+        catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ code: 'restore_failed', message: err.message || 'restore error' }));
+          return;
+        }
+        if (!result || !result.deck) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ code: 'snapshot_not_found', message: `No snapshot: ${id}` }));
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ code: 'success', id, deck: result.deck }));
+      });
+      return;
+    }
+
+    // ─── Cloud render proxy (optional) ───────────────────────────────────────
+    // POST /api/render-mp4  body { deck }  → submit a cloud render job
+    // GET  /api/render-status/:id          → poll job status / video url
+    // GET  /api/quota-balance              → read remaining quota for confirm
+    //
+    // The proxy talks to the backend with the local CLI token; the page
+    // never sees the JWT. All three are off-by-default — only mounted when
+    // a cloudRender client was passed at construction.
+    function sendJson(status, payload) {
+      res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      res.end(JSON.stringify(payload));
+    }
+    function statusForCode(code) {
+      if (code === 'not_logged_in') return 401;
+      if (code === 'quota_exceeded') return 402;
+      if (code === 'invalid_deck' || code === 'invalid_id') return 400;
+      if (code === 'job_not_found') return 404;
+      if (code === 'success') return 200;
+      return 502; // upstream error
+    }
+
+    if (cloudRender && req.method === 'POST' && req.url === '/api/render-mp4') {
+      const chunks = [];
+      let total = 0;
+      // Decks are small (5-8 cards, ~5 KB). 64 KB cap defends against pasted
+      // monsters without affecting the realistic upper bound.
+      const MAX = 64 * 1024;
+      req.on('data', (c) => {
+        total += c.length;
+        if (total > MAX) { req.destroy(); return; }
+        chunks.push(c);
+      });
+      req.on('end', async () => {
+        let body;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); }
+        catch { return sendJson(400, { code: 'bad_json', message: 'render body must be JSON' }); }
+        const deck = body && body.deck;
+        if (!deck || !Array.isArray(deck.cards)) {
+          return sendJson(400, { code: 'invalid_deck', message: 'deck.cards required' });
+        }
+        let result;
+        try { result = await cloudRender.submit(deck); }
+        catch (err) { return sendJson(502, { code: 'upstream_error', message: err.message }); }
+        return sendJson(statusForCode(result.code), result);
+      });
+      return;
+    }
+
+    if (cloudRender && req.method === 'GET' && req.url.startsWith('/api/render-status/')) {
+      const id = decodeURIComponent(req.url.slice('/api/render-status/'.length));
+      (async () => {
+        let result;
+        try { result = await cloudRender.status(id); }
+        catch (err) { return sendJson(502, { code: 'upstream_error', message: err.message }); }
+        return sendJson(statusForCode(result.code), result);
+      })();
+      return;
+    }
+
+    if (cloudRender && req.method === 'GET' && req.url === '/api/quota-balance') {
+      (async () => {
+        let result;
+        try { result = await cloudRender.quota(); }
+        catch (err) { return sendJson(502, { code: 'upstream_error', message: err.message }); }
+        return sendJson(statusForCode(result.code), result);
+      })();
+      return;
+    }
+
+    if (req.method === 'GET' && req.url === '/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      });
+      // Initial frame so EventSource resolves "open" promptly.
+      res.write(`: stage stream open\n\n`);
+
+      // Push the current snapshot immediately so the UI does not have to
+      // race the first watcher event.
+      const snap = getDeckSnapshot();
+      const initial = {
+        type: snap.deck ? 'deck' : 'error',
+        sourcePath: snap.sourcePath,
+        deck: snap.deck || null,
+        error: snap.error || null,
+        ts: Date.now(),
+      };
+      res.write(`event: ${initial.type}\n`);
+      res.write(`data: ${JSON.stringify(initial)}\n\n`);
+
+      const unsubscribe = subscribe((event) => {
+        try {
+          res.write(`event: ${event.type}\n`);
+          res.write(`data: ${JSON.stringify(event)}\n\n`);
+        } catch {
+          // Connection closed under us; teardown handler will clean up.
+        }
+      });
+
+      const heartbeat = setInterval(() => {
+        try { res.write(`: heartbeat\n\n`); } catch { /* dead */ }
+      }, 15_000);
+      heartbeat.unref?.();
+
+      const teardown = () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+        sseClients.delete(res);
+        try { res.end(); } catch { /* already ended */ }
+      };
+      req.on('close', teardown);
+      req.on('aborted', teardown);
+      sseClients.add(res);
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ code: 'not_found', message: `No route: ${req.method} ${req.url}` }));
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.removeListener('error', reject);
+      resolve();
+    });
+  });
+
+  return {
+    server,
+    port,
+    url: `http://127.0.0.1:${port}`,
+    async close() {
+      // End all live SSE streams so server.close() does not hang.
+      for (const res of sseClients) {
+        try { res.end(); } catch { /* already gone */ }
+      }
+      sseClients.clear();
+      await new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+module.exports = { startStageServer };