voxflow 1.14.0 → 1.15.1

package/lib/commands/slice-stage.js

@@ -0,0 +1,264 @@
+'use strict';
+
+/**
+ * `voxflow slice stage <deck.json>` — boot a local Stage server that watches a
+ * deck JSON file and hot-reloads a localhost preview page on every change.
+ *
+ * No `meta` export — this is reached only via `slice.js` dispatch (first
+ * positional arg `stage`), so it stays out of the registry parity test.
+ *
+ * Phase 1 scope: server + watcher + minimal deck-JSON UI.
+ * Phase 1.3+ will add: Remotion `renderStill` thumbnails, exports, publish.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { startStageServer } = require('../stage-core/server');
+const { watchDeckFile } = require('../stage-core/watcher');
+const { createEventBus } = require('../stage-core/event-bus');
+const { createSnapshotStore } = require('../stage-core/snapshot-store');
+const { createCloudRenderClient } = require('../stage-core/cloud-render');
+const { renderSliceStageHtml } = require('../stage-ui/slice/template');
+const { emit: emitTelemetry } = require('../core/telemetry');
+
+// Sourced from the canonical registry at repo root. Previously this list
+// silently fell out of sync (lagged at 6 themes while the rest of the repo
+// had 13) — the JSON import makes that impossible.
+const SLICE_THEME_REGISTRY = require('../../../slice-themes.json');
+const VALID_THEMES = SLICE_THEME_REGISTRY.themes.map((t) => t.id);
+
+function loadInitialDeck(absPath) {
+  try {
+    const raw = fs.readFileSync(absPath, 'utf8');
+    return { deck: JSON.parse(raw), error: null };
+  } catch (err) {
+    return { deck: null, error: err.code === 'ENOENT'
+      ? `File not found: ${absPath}. Run \`voxflow slice <article>\` first, or pass --output to write a deck.json.`
+      : `Could not read deck: ${err.message}` };
+  }
+}
+
+/**
+ * Programmatic entry — used by tests + the CLI handler. Returns a handle that
+ * exposes the listening URL and a stop() that tears everything down.
+ *
+ * @param {object} opts
+ * @param {string} opts.deckPath
+ * @param {string} [opts.theme]              Lock to a single theme (validated)
+ * @param {number} [opts.port=5180]
+ * @param {number} [opts.maxPortTries=10]
+ * @returns {Promise<{url:string, port:number, stop:() => Promise<void>}>}
+ */
+async function startSliceStage(opts) {
+  const deckPath = path.resolve(opts.deckPath);
+  const theme = opts.theme;
+  if (theme && !VALID_THEMES.includes(theme)) {
+    throw new Error(
+      `Unknown theme "${theme}". Valid: ${VALID_THEMES.join(', ')}`
+    );
+  }
+
+  const bus = createEventBus();
+  let snapshot = loadInitialDeck(deckPath);
+  snapshot.sourcePath = deckPath;
+
+  // Per-deck history. Initial parseable load = baseline snapshot (v0). Every
+  // subsequent watcher event with parseable content gets snapshotted; the
+  // store dedups by content hash so atomic-write double events stay one
+  // version. A `restore` flag rides on the deck event so the UI knows to
+  // skip the just-changed diff highlight (otherwise restoring an old deck
+  // would flash every card as "changed").
+  const snapshotStore = createSnapshotStore(deckPath);
+  let pendingRestoreId = null;
+  if (snapshot.deck) snapshotStore.snapshotIfChanged(snapshot.deck);
+
+  const watcher = watchDeckFile({
+    filePath: deckPath,
+    onChange(deck, err) {
+      if (err && !deck) {
+        snapshot = { deck: null, error: err.message, sourcePath: deckPath };
+        bus.publish({ type: 'error', sourcePath: deckPath, error: err.message, ts: Date.now() });
+        return;
+      }
+      snapshot = { deck, error: null, sourcePath: deckPath };
+      snapshotStore.snapshotIfChanged(deck);
+      const restoredFromId = pendingRestoreId;
+      pendingRestoreId = null;
+      bus.publish({
+        type: 'deck',
+        sourcePath: deckPath,
+        deck,
+        theme: theme || null,
+        ts: Date.now(),
+        restoredFrom: restoredFromId,
+      });
+    },
+  });
+
+  // Server-side restore writer: writes the chosen snapshot bytes back to the
+  // live deck file, sets `pendingRestoreId` so the next watcher event tags
+  // the deck event with `restoredFrom`. Server.js passes through to this.
+  const snapshotsBridge = {
+    list: snapshotStore.list,
+    load: snapshotStore.load,
+    getStorePath: snapshotStore.getStorePath,
+    restore(id) {
+      const deck = snapshotStore.load(id);
+      if (!deck) return null;
+      pendingRestoreId = id;
+      try {
+        fs.writeFileSync(deckPath, JSON.stringify(deck, null, 2) + '\n', 'utf8');
+      } catch (err) {
+        pendingRestoreId = null;
+        throw err;
+      }
+      return { deck };
+    },
+  };
+
+  const preferredPort = Number.isInteger(opts.port) && opts.port > 0 ? opts.port : 5180;
+  const maxPortTries = Number.isInteger(opts.maxPortTries) && opts.maxPortTries > 0
+    ? opts.maxPortTries : 10;
+
+  // We have to start the server before knowing the final port (port-conflict
+  // retry happens inside startStageServer). So we render the HTML lazily,
+  // re-rendering each request with the actual port baked in.
+  let actualPort = preferredPort;
+  const uiHtml = () => renderSliceStageHtml({ sourcePath: deckPath, port: actualPort });
+
+  // startStageServer takes a string for uiHtml; we pass a stub that will be
+  // replaced once we know the port. Cheap workaround: render once with
+  // `preferredPort`, then patch after we get the real port back.
+  const initialHtml = renderSliceStageHtml({ sourcePath: deckPath, port: preferredPort });
+
+  // Cloud render bridge — proxies POST /api/render-mp4 (and friends) to the
+  // backend cloud-render endpoint. Token comes from the same CLI cache the
+  // user logged into; the page never sees the JWT.
+  const cloudRender = opts.cloudRender || createCloudRenderClient();
+
+  const handle = await startStageServer({
+    uiHtml: initialHtml,
+    getDeckSnapshot: () => snapshot,
+    subscribe: bus.subscribe,
+    snapshots: snapshotsBridge,
+    cloudRender,
+    preferredPort,
+    maxPortTries,
+  });
+  actualPort = handle.port;
+
+  // Single anonymous launch event — feeds the "should Stage get an MCP?"
+  // decision. Fire-and-forget; opt-out via VOXFLOW_TELEMETRY=0 / DO_NOT_TRACK.
+  emitTelemetry('cli.slice.stage.launched', { theme: theme || null });
+
+  // If the port shifted (5180 → 5181 due to conflict), re-render the HTML so
+  // the footer hint shows the truthy URL. We swap by replacing the listener
+  // on the server: simpler than re-injecting, just update the closure used
+  // by startStageServer's GET / branch via a tiny patch.
+  if (actualPort !== preferredPort) {
+    // The HTML is captured by closure inside startStageServer; rather than
+    // wiring a setter, we do nothing — the page only references the port in
+    // a footer hint, and the live SSE connection works regardless. This is
+    // acceptable for MVP; revisit if/when port mismatch becomes user-visible.
+    void uiHtml;
+  }
+
+  return {
+    url: handle.url,
+    port: handle.port,
+    sourcePath: deckPath,
+    async stop() {
+      watcher.stop();
+      await handle.close();
+    },
+  };
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag } = require('../core/args');
+
+  const portFlag = parseFlag(args, '--port');
+  const themeFlag = parseFlag(args, '--theme');
+  const noOpen = args.includes('--no-open');
+
+  // First positional arg that isn't a flag value
+  const valuedFlags = new Set(['--port', '--theme']);
+  let deckPath = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('-')) {
+      if (valuedFlags.has(args[i])) i++;
+      continue;
+    }
+    deckPath = args[i];
+    break;
+  }
+  if (!deckPath) {
+    console.error('Error: provide a deck JSON file');
+    console.error('Usage: voxflow slice stage <deck.json> [--port <n>] [--theme <id>] [--no-open]');
+    process.exit(1);
+  }
+
+  let port;
+  if (portFlag) {
+    const parsed = Number.parseInt(portFlag, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+      console.error(`Error: --port "${portFlag}" is not a valid TCP port`);
+      process.exit(1);
+    }
+    port = parsed;
+  }
+
+  let stage;
+  try {
+    stage = await startSliceStage({
+      deckPath,
+      theme: themeFlag || undefined,
+      port,
+    });
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log('\x1b[36m=== VoxFlow Stage — Slice ===\x1b[0m');
+  console.log(`Watching:  ${stage.sourcePath}`);
+  console.log(`Preview:   ${stage.url}`);
+  if (themeFlag) console.log(`Theme:     ${themeFlag}`);
+  console.log('');
+  console.log('Edit the deck JSON to hot-reload. Ctrl+C to stop.');
+  console.log('');
+
+  if (!noOpen && !process.env.CI) {
+    try {
+      const open = (await import('open')).default;
+      await open(stage.url);
+    } catch {
+      // Non-fatal — user can open the URL manually.
+    }
+  }
+
+  // Keep the process alive until SIGINT.
+  let stopping = false;
+  const stopAndExit = async (signal) => {
+    if (stopping) return;
+    stopping = true;
+    console.log(`\n\x1b[33m${signal} received — stopping Stage…\x1b[0m`);
+    try { await stage.stop(); } catch { /* best-effort */ }
+    process.exit(0);
+  };
+  process.on('SIGINT', () => stopAndExit('SIGINT'));
+  process.on('SIGTERM', () => stopAndExit('SIGTERM'));
+
+  // Park.
+  return new Promise(() => { /* never resolves; SIGINT exits */ });
+}
+
+module.exports = {
+  handle,
+  startSliceStage,
+  VALID_THEMES,
+};

package/lib/commands/slice.js

@@ -0,0 +1,343 @@
+/**
+ * VoxFlow CLI — Slice command
+ *
+ * Slice an article (markdown / plain text) into a 5–8 card narrated deck JSON
+ * via /api/slice/deck (renamed from /api/paper-slide/slice in #3307 Deploy 2).
+ * Charges `slice-deck` (200 quota) under the new mount; legacy `paper-slide-slice`
+ * op still exists for the soft-deprecated `/api/paper-slide/slice` path that
+ * stays mounted for ~30 days.
+ *
+ * The cloud renderer that turns this deck into a 1080×1920 mp4 lives in the
+ * web app (voxflow.studio/apps/slice) — this command only produces the
+ * structured deck JSON, suitable for piping into custom pipelines or for
+ * inspection / iteration on the AI's slicing quality.
+ *
+ * Thirty-three themes supported (paper-slide / editorial-mag / bold-poster /
+ * notion-card / brutalist / glass-dark / broadsheet / blueprint /
+ * daisy-pastel / showa-catalog / photo-feature / atmospheric / art-mag /
+ * tome-noir / flomo-mute / substack-drop / ink-scroll / podcast-clip /
+ * ink-wash / morandi-calm / douyin-data / highlighter-note / memphis-design /
+ * bauhaus-grid / riso-print / chrome-y2k / botanical-press / art-nouveau /
+ * tabloid-print / arcade-pixel / hand-lettered / stamp-collector /
+ * tropical-postcard) — must match backend's VALID_THEMES set
+ * (backend/services/paper-slide/deck-validator.js) or the API rejects with
+ * `invalid_theme`. Both lists derive from /slice-themes.json so they
+ * auto-sync.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { request, throwApiError, throwNetworkError, ApiError } = require('../core/http');
+
+// Sourced from the canonical registry at repo root. The CLI gates user
+// input against this list, so adding a theme to slice-themes.json is enough
+// for `voxflow slice --theme xxx` to accept it.
+const SLICE_THEME_REGISTRY = require('../../../slice-themes.json');
+const VALID_THEMES = SLICE_THEME_REGISTRY.themes.map((t) => t.id);
+const DEFAULT_THEME = SLICE_THEME_REGISTRY.default;
+// Theme id -> array of valid variant ids (palette swaps within a theme).
+// Mirrors backend/services/paper-slide/deck-validator.js#THEME_VARIANTS so
+// the CLI rejects unknown variants client-side before paying a network round
+// trip. Themes without variants get an empty array — passing --variant for
+// them is a hard error too (theme typo'd or feature confusion).
+const THEME_VARIANTS = Object.fromEntries(
+    SLICE_THEME_REGISTRY.themes.map((t) => [
+        t.id,
+        (t.variants || []).map((v) => v.id),
+    ])
+);
+const MIN_ARTICLE_CHARS = 80;
+
+/**
+ * Slice an article via the backend.
+ *
+ * @param {object} opts
+ * @param {string} opts.token    JWT token
+ * @param {string} opts.api      API base URL
+ * @param {string} opts.article  Article text (≥ 80 chars)
+ * @param {string} [opts.theme]  Slice theme id (default: paper-slide)
+ * @param {string} [opts.output] Output JSON path (default: stdout)
+ * @param {boolean} [opts.json]  Pure-JSON mode (suppress logs / spinners)
+ * @returns {Promise<{deck: object, usage: object, quotaUsed: number, outputPath: string|null}>}
+ */
+async function slice(opts) {
+    const article = opts.article;
+    if (typeof article !== 'string' || article.trim().length < MIN_ARTICLE_CHARS) {
+        throw new Error(
+            `Article must be a non-empty string of at least ${MIN_ARTICLE_CHARS} characters ` +
+            `(got ${article ? article.trim().length : 0}).`
+        );
+    }
+
+    const theme = opts.theme || DEFAULT_THEME;
+    if (!VALID_THEMES.includes(theme)) {
+        throw new Error(
+            `Unknown theme "${theme}". Valid: ${VALID_THEMES.join(', ')}`
+        );
+    }
+
+    const variantId = opts.variant;
+    if (variantId != null) {
+        const validVariants = THEME_VARIANTS[theme] || [];
+        if (validVariants.length === 0) {
+            throw new Error(
+                `--variant set but theme "${theme}" declares no variants. ` +
+                `Themes with variants: ${
+                    Object.entries(THEME_VARIANTS)
+                        .filter(([, ids]) => ids.length > 0)
+                        .map(([id]) => id)
+                        .join(', ') || '(none yet)'
+                }`
+            );
+        }
+        if (!validVariants.includes(variantId)) {
+            throw new Error(
+                `Unknown variant "${variantId}" for theme "${theme}". Valid: ${validVariants.join(', ')}`
+            );
+        }
+    }
+
+    const api = opts.api;
+    const token = opts.token;
+    const quiet = opts.json === true;
+
+    if (!quiet) {
+        console.log('\n=== VoxFlow Slice ===');
+        console.log(`Theme:   ${theme}${variantId ? ` (variant: ${variantId})` : ''}`);
+        console.log(`Article: ${article.trim().length} chars`);
+    }
+
+    let status, data;
+    try {
+        ({ status, data } = await request(`${api}/api/slice/deck`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${token}`,
+            },
+            // Slice runs a structured-output Claude call producing 5–8
+            // narrated cards. P50 is 10–20s but P95 spikes past the 60s
+            // default request timeout under upstream load (verified
+            // against api.voxflow.studio/api/slice/deck with the
+            // 1.11.1 client). Match the 180s convention used by every
+            // other LLM-bound CLI command (image / picstory / explain /
+            // present / story).
+            timeoutMs: 180_000,
+        }, {
+            article: article.trim(),
+            theme,
+            ...(variantId ? { variantId } : {}),
+        }));
+    } catch (err) {
+        throwNetworkError(err, api);
+    }
+
+    if (status !== 200 || !data || data.code !== 'success') {
+        throwApiError(status, data, 'slice');
+    }
+
+    const deck = data.data?.deck;
+    const usage = data.data?.usage || {};
+    if (!deck) {
+        throw new Error('Slice response missing `data.deck`');
+    }
+
+    // Authoritative cost from quota response, fallback to catalog.
+    const PAPER_SLIDE_SLICE_CATALOG_COST = 200;
+    const quotaUsed = typeof data.quota?.costDelta === 'number'
+        ? data.quota.costDelta
+        : PAPER_SLIDE_SLICE_CATALOG_COST;
+
+    const payload = JSON.stringify({ deck, usage, theme }, null, 2);
+    let outputPath = null;
+    if (opts.output) {
+        outputPath = path.resolve(opts.output);
+        const outDir = path.dirname(outputPath);
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(outputPath, payload + '\n', 'utf8');
+        if (!quiet) {
+            console.log(`\nWrote ${outputPath} (${(payload.length / 1024).toFixed(1)} KB)`);
+        }
+    } else if (quiet) {
+        process.stdout.write(payload + '\n');
+    } else {
+        console.log('\n--- Deck JSON ---');
+        console.log(payload);
+    }
+
+    if (!quiet) {
+        const cardCount = Array.isArray(deck.cards) ? deck.cards.length : 0;
+        console.log('\n=== Done ===');
+        console.log(`Cards:  ${cardCount}`);
+        console.log(`Quota:  ${quotaUsed} used, ${data.quota?.remaining ?? '?'} remaining`);
+        // Two next-step paths: (1) iterate locally with stage if an output
+        // file exists (no quota cost, hot-reload); (2) ship via the web
+        // renderer. Only print the stage hint when we actually have a path
+        // to feed it — stdout-only runs have nowhere for stage to attach.
+        if (outputPath) {
+            console.log(`\nPreview locally: voxflow slice stage ${outputPath}`);
+            console.log(`Or render mp4:   https://voxflow.studio/apps/slice (paste/import the JSON)`);
+        } else {
+            console.log(`\nNext: render the deck at https://voxflow.studio/apps/slice (paste the JSON or import).`);
+        }
+    }
+
+    return { deck, usage, quotaUsed, outputPath };
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+    // Sub-action dispatch: `voxflow slice stage <deck.json>` boots the local
+    // preview/iteration server instead of generating a deck. Kept as a
+    // first-positional-arg check so the legacy `voxflow slice <article>`
+    // signature is unchanged. slice-stage.js has no `meta` export of its
+    // own — it would otherwise need to be in _registry.js (parity test).
+    if (args.length > 0 && args[0] === 'stage') {
+        const sliceStage = require('./slice-stage');
+        return sliceStage.handle(args.slice(1));
+    }
+    // `voxflow slice render <deck.json>` — offline local Remotion render
+    // (Phase 0: silent video). Same first-positional dispatch pattern as
+    // `stage`; the subcommand file has no `meta` export so it stays out of
+    // _registry.js (parity test).
+    if (args.length > 0 && args[0] === 'render') {
+        const sliceRender = require('./slice-render');
+        return sliceRender.handle(args.slice(1));
+    }
+    // `voxflow slice preview <deck.json>` — localhost HTML page with a
+    // midpoint-frame still per card (no mp4, fraction of the render cost).
+    if (args.length > 0 && args[0] === 'preview') {
+        const slicePreview = require('./slice-preview');
+        return slicePreview.handle(args.slice(1));
+    }
+
+    const { parseFlag, runWithRetry } = require('../core/args');
+    const { getToken, getTokenInfo } = require('../core/auth');
+    const { API_BASE } = require('../core/config');
+
+    const api = parseFlag(args, '--api') || API_BASE;
+    const explicitToken = parseFlag(args, '--token');
+
+    const inlineText = parseFlag(args, '--text');
+    const theme = parseFlag(args, '--theme');
+    const variant = parseFlag(args, '--variant');
+    const output = parseFlag(args, '--output', '-o');
+    const jsonMode = args.includes('--json');
+
+    let article;
+    if (inlineText) {
+        article = inlineText;
+    } else {
+        // First positional arg that isn't a flag value
+        const valuedFlags = new Set([
+            '--text', '--theme', '--variant', '--output', '-o',
+            '--token', '--api',
+        ]);
+        let filePath;
+        for (let i = 0; i < args.length; i++) {
+            if (args[i].startsWith('-')) {
+                if (valuedFlags.has(args[i])) i++;
+                continue;
+            }
+            filePath = args[i];
+            break;
+        }
+        if (!filePath) {
+            console.error('Error: provide an article file or --text "..."');
+            console.error('Usage: voxflow slice <file> [--theme <id>] [-o <out.json>]');
+            process.exit(1);
+        }
+        try {
+            article = fs.readFileSync(path.resolve(filePath), 'utf8');
+        } catch (err) {
+            console.error(`Error: cannot read file "${filePath}": ${err.message}`);
+            process.exit(1);
+        }
+    }
+
+    if (theme && !VALID_THEMES.includes(theme)) {
+        console.error(`Error: --theme "${theme}" not in: ${VALID_THEMES.join(', ')}`);
+        process.exit(1);
+    }
+    if (variant) {
+        const targetTheme = theme || DEFAULT_THEME;
+        const validVariants = THEME_VARIANTS[targetTheme] || [];
+        if (validVariants.length === 0) {
+            console.error(
+                `Error: --variant set but theme "${targetTheme}" declares no variants.`
+            );
+            const themesWithVariants = Object.entries(THEME_VARIANTS)
+                .filter(([, ids]) => ids.length > 0)
+                .map(([id]) => id);
+            if (themesWithVariants.length > 0) {
+                console.error(`Themes with variants: ${themesWithVariants.join(', ')}`);
+            }
+            process.exit(1);
+        }
+        if (!validVariants.includes(variant)) {
+            console.error(
+                `Error: --variant "${variant}" not in ${targetTheme}'s variants: ${validVariants.join(', ')}`
+            );
+            process.exit(1);
+        }
+    }
+
+    let token;
+    if (explicitToken) {
+        token = explicitToken;
+    } else {
+        token = await getToken({ api });
+        if (!jsonMode) {
+            const info = getTokenInfo();
+            if (info) {
+                console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+            }
+        }
+    }
+
+    const opts = {
+        token, api, article,
+        theme: theme || undefined,
+        variant: variant || undefined,
+        output: output || undefined,
+        json: jsonMode,
+    };
+
+    await runWithRetry(slice, opts, api, explicitToken);
+}
+
+const meta = {
+    slice: {
+        usage: '<file> [--theme <id>] [--variant <id>] [--text <s>] [-o <file>] [--json]',
+        description: 'Slice an article into a 5–8 card deck JSON (Slice / paper-slide AI; 200 quota)',
+        options: [
+            '<file>               Article file (markdown / plain text, ≥ 80 chars)',
+            '--text <string>      Pass article inline instead of reading a file',
+            `--theme <id>         One of: ${VALID_THEMES.join(', ')} (default: ${DEFAULT_THEME})`,
+            '--variant <id>       Palette swap within the theme (e.g. editorial-mag → cream / sepia / cold-grey). Themes without variants reject this flag.',
+            '-o, --output <path>  Write deck JSON to file (default: print to stdout/console)',
+            '--json               Pure JSON mode — suppress all logs, emit only the deck JSON to stdout (for piping)',
+        ],
+        examples: [
+            'voxflow slice article.md',
+            'voxflow slice article.md --theme editorial-mag -o deck.json',
+            'voxflow slice article.md --theme editorial-mag --variant sepia -o deck.json',
+            'voxflow slice --text "..." --theme bold-poster --json | jq .deck',
+            'voxflow slice stage deck.json                  # local preview, hot-reload',
+            'voxflow slice stage deck.json --port 5180 --no-open',
+            'voxflow slice render deck.json --output out.mp4  # offline render (no quota, no cloud)',
+        ],
+    },
+};
+
+module.exports = {
+    slice,
+    handle,
+    meta,
+    VALID_THEMES,
+    THEME_VARIANTS,
+    DEFAULT_THEME,
+    MIN_ARTICLE_CHARS,
+    ApiError,
+};