voxflow 1.15.0 → 1.15.2

package/lib/commands/slice.js

@@ -0,0 +1,346 @@
+/**
+ * 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>` — alias for `slice stage`. The
+    // earlier static-thumbnail Phase 0 preview was strictly less capable
+    // than stage's hot-reload edit workflow (no file watcher, no live
+    // updates, no version history), so we route both to the same handler
+    // and keep "preview" as a discoverable name for new users.
+    if (args.length > 0 && (args[0] === 'preview')) {
+        const sliceStage = require('./slice-stage');
+        return sliceStage.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,
+};

package/lib/commands/slides/constants.js

@@ -0,0 +1,108 @@
+/**
+ * Slides command — Constants, templates, and LLM prompts.
+ */
+
+'use strict';
+
+const VALID_THEMES = ['midnight', 'paper', 'ember', 'forest', 'ocean'];
+const VALID_TEMPLATES = ['product', 'report', 'tutorial', 'pitch', 'free'];
+const VALID_MODELS = ['swift', 'balanced', 'pro', 'creative'];
+
+const SLIDE_LAYOUTS = [
+  'hero', 'title-bullets', 'two-column', 'three-cards',
+  'image-left', 'image-right', 'quote', 'timeline', 'stats', 'section',
+];
+
+const TEMPLATE_HINTS = {
+  product: 'This is a product launch presentation. Focus on value proposition, clear feature benefits, and persuasive metrics. End with a strong call to action.',
+  report: 'This is an annual/quarterly report. Use real-looking data, professional tone, clear metrics with year-over-year comparisons. Be factual and concise.',
+  tutorial: 'This is a step-by-step tutorial. Number each step clearly, use practical examples, and include actionable tips. Keep instructions concise and easy to follow.',
+  pitch: 'This is a startup investor pitch deck. Be compelling with real-looking metrics, clear market sizing (TAM/SAM/SOM), and a persuasive narrative arc. Show traction with specific numbers.',
+  free: '',
+};
+
+const TEMPLATE_STRUCTURES = {
+  product: [
+    { layout: 'hero', hint: 'Product name and tagline' },
+    { layout: 'title-bullets', hint: 'Pain points the product solves' },
+    { layout: 'two-column', hint: 'Problem vs Solution comparison' },
+    { layout: 'three-cards', hint: 'Key feature 1, 2, 3' },
+    { layout: 'three-cards', hint: 'More features or benefits' },
+    { layout: 'stats', hint: 'Performance metrics or user stats' },
+    { layout: 'quote', hint: 'Customer testimonial or endorsement' },
+    { layout: 'hero', hint: 'Call to action and next steps' },
+  ],
+  report: [
+    { layout: 'hero', hint: 'Report title, year, organization' },
+    { layout: 'title-bullets', hint: 'Executive summary highlights' },
+    { layout: 'stats', hint: 'Quarterly or annual key metrics' },
+    { layout: 'two-column', hint: 'Achievements and highlights' },
+    { layout: 'title-bullets', hint: 'Challenges and lessons learned' },
+    { layout: 'timeline', hint: 'Key milestones or roadmap' },
+    { layout: 'hero', hint: 'Outlook and closing statement' },
+  ],
+  tutorial: [
+    { layout: 'hero', hint: 'Tutorial title and what you will learn' },
+    { layout: 'title-bullets', hint: 'Overview and prerequisites' },
+    { layout: 'two-column', hint: 'Step 1 with details' },
+    { layout: 'two-column', hint: 'Step 2 with details' },
+    { layout: 'two-column', hint: 'Step 3 with details' },
+    { layout: 'two-column', hint: 'Step 4 with details' },
+    { layout: 'three-cards', hint: 'Pro tips and best practices' },
+    { layout: 'hero', hint: 'Summary and next steps' },
+  ],
+  pitch: [
+    { layout: 'hero', hint: 'Company name, one-line pitch' },
+    { layout: 'title-bullets', hint: 'The problem being solved' },
+    { layout: 'stats', hint: 'Market size and opportunity' },
+    { layout: 'two-column', hint: 'Solution and how it works' },
+    { layout: 'three-cards', hint: 'Business model and revenue streams' },
+    { layout: 'stats', hint: 'Traction and key metrics' },
+    { layout: 'three-cards', hint: 'Team members and expertise' },
+    { layout: 'hero', hint: 'The ask — funding, partnerships, next steps' },
+  ],
+  free: [],
+};
+
+const SLIDES_SYSTEM_PROMPT = `You are a professional presentation designer creating business-quality slide decks. Generate structured JSON.
+
+STRICT RULES:
+1. Output ONLY valid JSON, no markdown fences, no extra text
+2. Each slide must have: id (number), layout (string), content (object), narration (string)
+3. narration: speaker script, 2-3 sentences, natural professional tone
+4. Layout choices: ${SLIDE_LAYOUTS.join(', ')}
+5. NEVER use emoji characters anywhere — not in titles, bullets, headings, or card icons. Use short text labels instead (e.g. "01", "A", "i", or leave icon field empty string "")
+6. Write concise, data-driven text. No vague filler. Every bullet should contain a specific fact, number, or insight.
+7. First slide: "hero". Last slide: "hero" or "section" for closing. Use varied layouts in between — avoid repeating the same layout consecutively.
+8. 8-10 slides total. Prefer stats, timeline, two-column, quote layouts for variety.
+9. For three-cards: set icon to "" (empty string). For stats: use real-looking numbers with units.
+
+CONTENT STRUCTURE per layout:
+- hero: { title, subtitle }
+- title-bullets: { title, bullets: string[] } (max 5 bullets)
+- two-column: { title, left: { heading, text }, right: { heading, text } }
+- three-cards: { title, cards: [{ icon: "", heading, text }] } (exactly 3 cards)
+- image-left / image-right: { title, imagePrompt, text }
+- quote: { quote, author, context }
+- timeline: { title, events: [{ year, text }] } (3-5 events)
+- stats: { title, stats: [{ value, label }] } (2-4 stats with realistic numbers)
+- section: { title, subtitle }
+
+OUTPUT FORMAT:
+{
+  "meta": { "title": "..." },
+  "slides": [ ... ]
+}`;
+
+const VALID_MODEL_ALIASES = ['swift', 'balanced', 'pro', 'creative'];
+
+module.exports = {
+  VALID_THEMES,
+  VALID_TEMPLATES,
+  VALID_MODELS,
+  SLIDE_LAYOUTS,
+  TEMPLATE_HINTS,
+  TEMPLATE_STRUCTURES,
+  SLIDES_SYSTEM_PROMPT,
+  VALID_MODEL_ALIASES,
+};