voxflow 1.15.0 → 1.15.2

package/lib/stage-core/snapshot-store.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * Append-only snapshot history for a watched deck JSON.
+ *
+ * Triggered on every parseable deck-change event from the watcher: AI edits
+ * (the user's external tool writes the file in place — see edit-prompt.js)
+ * AND hand edits both flow through here. Snapshots are content-addressed so
+ * a no-op save (atomic-write double event, JSON whitespace tweak that
+ * round-trips to the same shape) never adds a duplicate version.
+ *
+ * Layout:
+ *   <deckpath>.snapshots/
+ *     <unix-ms>-<hash6>.json    # raw deck JSON, pretty-printed
+ *
+ * Fallback path (when the deck dir is not writable, e.g. read-only checkouts
+ * or the bundled sample under node_modules):
+ *   ~/.config/voxflow/stage-snapshots/<sha-of-abs-path>/
+ *
+ * `restore` is a separate operation handled by the server (writes the
+ * snapshot bytes back to the deck file); the snapshot store itself is
+ * read/append-only — it never touches the live deck file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const DEFAULT_MAX_KEEP = 20;
+
+function shortHash(text) {
+  return crypto.createHash('sha1').update(text).digest('hex').slice(0, 12);
+}
+
+function pathSafeHash(absPath) {
+  return crypto.createHash('sha1').update(absPath).digest('hex').slice(0, 16);
+}
+
+function fallbackStoreFor(absDeckPath) {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'voxflow', 'stage-snapshots', pathSafeHash(absDeckPath));
+}
+
+function tryEnsureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    // Probe writability with a temp file we immediately delete. mkdirSync
+    // with recursive can succeed on read-only mounts in some edge cases.
+    const probe = path.join(dir, '.voxflow-probe-' + process.pid);
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} deckPath  Absolute path to deck JSON.
+ * @param {object} [opts]
+ * @param {number} [opts.maxKeep=20]
+ * @returns {{
+ *   snapshotIfChanged: (deck:object) => ({id:string, isNew:boolean, path:string}|null),
+ *   list: () => Array<{id:string, ts:number, hash:string, sizeBytes:number, cardCount:number}>,
+ *   load: (id:string) => object|null,
+ *   getStorePath: () => string,
+ * }}
+ */
+function createSnapshotStore(deckPath, opts = {}) {
+  const maxKeep = Number.isFinite(opts.maxKeep) && opts.maxKeep > 0 ? opts.maxKeep : DEFAULT_MAX_KEEP;
+  const absDeckPath = path.resolve(deckPath);
+
+  // Prefer adjacent-directory layout; fall back to home if the deck dir is
+  // read-only. Decided once at construction so the location is stable for
+  // the life of the stage server.
+  const adjacent = absDeckPath + '.snapshots';
+  let storePath = tryEnsureDir(adjacent) ? adjacent : null;
+  if (!storePath) {
+    const home = fallbackStoreFor(absDeckPath);
+    storePath = tryEnsureDir(home) ? home : null;
+  }
+  // If both fail, the store becomes a no-op — telemetry-style, never crash
+  // the stage server because we can't snapshot.
+
+  // ─── id format helpers ────────────────────────────────────────────────
+  const ID_RE = /^(\d+)-([0-9a-f]{12})$/;
+  function idFor(ts, hash) { return `${ts}-${hash}`; }
+  function parseId(id) {
+    const m = ID_RE.exec(String(id || ''));
+    if (!m) return null;
+    return { ts: Number(m[1]), hash: m[2] };
+  }
+
+  function listFiles() {
+    if (!storePath) return [];
+    let names;
+    try { names = fs.readdirSync(storePath); } catch { return []; }
+    return names
+      .filter((n) => n.endsWith('.json') && ID_RE.test(n.slice(0, -5)))
+      .map((n) => ({ name: n, id: n.slice(0, -5), parsed: parseId(n.slice(0, -5)) }))
+      .filter((f) => f.parsed)
+      .sort((a, b) => b.parsed.ts - a.parsed.ts); // newest first
+  }
+
+  function pruneOldest() {
+    const all = listFiles();
+    if (all.length <= maxKeep) return;
+    const stale = all.slice(maxKeep);
+    for (const f of stale) {
+      try { fs.unlinkSync(path.join(storePath, f.name)); } catch { /* best-effort */ }
+    }
+  }
+
+  function snapshotIfChanged(deck) {
+    if (!storePath) return null;
+    let serialized;
+    try {
+      serialized = JSON.stringify(deck, null, 2);
+    } catch { return null; }
+    const hash = shortHash(serialized);
+
+    const all = listFiles();
+    if (all.length > 0 && all[0].parsed.hash === hash) {
+      // Latest snapshot already matches — no-op (atomic-write double event,
+      // or a re-save that round-trips to the same content).
+      return { id: all[0].id, isNew: false, path: path.join(storePath, all[0].name) };
+    }
+
+    // If an OLDER snapshot has this exact hash (typical of Restore — user
+    // rolled back to a previous version), promote it to "current" by
+    // renaming the file to the new timestamp instead of writing a duplicate.
+    // This keeps the history clean: rewinding to v1 from v2 leaves you with
+    // [v1@now, v2@earlier] not [v1@now, v2@earlier, v1@old].
+    const ts = Date.now();
+    const newId = idFor(ts, hash);
+    const newPath = path.join(storePath, `${newId}.json`);
+    const olderMatch = all.find((f) => f.parsed.hash === hash);
+    if (olderMatch) {
+      const oldPath = path.join(storePath, olderMatch.name);
+      try {
+        fs.renameSync(oldPath, newPath);
+      } catch {
+        // Rename can fail across mount boundaries (rare for adjacent dir
+        // layout, possible in fallback). Fall through to the regular write
+        // path — user gets a duplicate entry but never a hard error.
+        try { fs.writeFileSync(newPath, serialized + '\n', 'utf8'); }
+        catch { return null; }
+      }
+      pruneOldest();
+      return { id: newId, isNew: true, path: newPath, promotedFrom: olderMatch.id };
+    }
+
+    try {
+      fs.writeFileSync(newPath, serialized + '\n', 'utf8');
+    } catch {
+      return null;
+    }
+    pruneOldest();
+    return { id: newId, isNew: true, path: newPath };
+  }
+
+  function load(id) {
+    if (!storePath) return null;
+    if (!ID_RE.test(String(id))) return null;
+    try {
+      const raw = fs.readFileSync(path.join(storePath, `${id}.json`), 'utf8');
+      return JSON.parse(raw);
+    } catch { return null; }
+  }
+
+  function list() {
+    return listFiles().map((f) => {
+      const filePath = path.join(storePath, f.name);
+      let sizeBytes = 0;
+      let cardCount = 0;
+      try {
+        const stat = fs.statSync(filePath);
+        sizeBytes = stat.size;
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        cardCount = Array.isArray(parsed && parsed.cards) ? parsed.cards.length : 0;
+      } catch { /* best-effort */ }
+      return {
+        id: f.id,
+        ts: f.parsed.ts,
+        hash: f.parsed.hash,
+        sizeBytes,
+        cardCount,
+      };
+    });
+  }
+
+  function getStorePath() { return storePath || ''; }
+
+  return { snapshotIfChanged, list, load, getStorePath };
+}
+
+module.exports = { createSnapshotStore, DEFAULT_MAX_KEEP };

package/lib/stage-core/watcher.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Watch a single JSON file. On change, debounce → re-read → publish event.
+ *
+ * Why not chokidar: we keep the CLI dep list to (open, pptxgenjs). fs.watch is
+ * built-in. Its known cross-platform quirks (one event vs many, atomic-write
+ * eviction on some editors) are mitigated by:
+ *   - Debouncing all events through a 50ms timer
+ *   - Re-opening the watch handle if ENOENT fires (some editors save by
+ *     rename — the original inode is unlinked, our watcher would go silent)
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath           Absolute path to deck.json
+ * @param {(deck: object|null, err?: Error) => void} opts.onChange
+ *        Called on every settled change. `deck` is parsed JSON, or null if
+ *        the file is missing / unparseable (err carries the reason).
+ * @param {number} [opts.debounceMs=80]    Coalesce burst events
+ * @returns {{ stop: () => void, currentPath: string }}
+ */
+function watchDeckFile({ filePath, onChange, debounceMs = 80 }) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('watchDeckFile: filePath is required');
+  }
+  const absPath = path.resolve(filePath);
+
+  let currentWatcher = null;
+  let debounceTimer = null;
+  let stopped = false;
+
+  function readAndPublish() {
+    if (stopped) return;
+    try {
+      const raw = fs.readFileSync(absPath, 'utf8');
+      let deck;
+      try {
+        deck = JSON.parse(raw);
+      } catch (parseErr) {
+        onChange(null, new Error(`JSON parse failed: ${parseErr.message}`));
+        return;
+      }
+      onChange(deck, undefined);
+    } catch (readErr) {
+      // ENOENT = file missing right now (atomic-save inode swap window).
+      // Other readers will retry on the next debounced event.
+      onChange(null, readErr);
+    }
+  }
+
+  function fireDebounced() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      readAndPublish();
+    }, debounceMs);
+  }
+
+  function startWatch() {
+    if (stopped) return;
+    try {
+      currentWatcher = fs.watch(absPath, { persistent: true }, (eventType) => {
+        // Some editors emit `rename` then `change`; we treat both the same.
+        // The debounce smooths bursty filesystem events.
+        void eventType;
+        fireDebounced();
+      });
+      currentWatcher.on('error', () => {
+        // Likely the underlying inode was evicted (atomic save). Re-arm.
+        try { currentWatcher.close(); } catch { /* already gone */ }
+        currentWatcher = null;
+        if (!stopped) {
+          // Re-poll once immediately, then retry the watch a tick later so
+          // the new inode exists.
+          fireDebounced();
+          setTimeout(() => { if (!stopped) startWatch(); }, 50);
+        }
+      });
+    } catch {
+      // File may not exist yet — caller can `voxflow slice stage` before
+      // running `voxflow slice` once. Schedule a retry.
+      if (!stopped) setTimeout(() => { if (!stopped) startWatch(); }, 200);
+    }
+  }
+
+  startWatch();
+
+  return {
+    currentPath: absPath,
+    stop() {
+      stopped = true;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (currentWatcher) {
+        try { currentWatcher.close(); } catch { /* already gone */ }
+        currentWatcher = null;
+      }
+    },
+  };
+}
+
+module.exports = { watchDeckFile };