voxflow 1.14.0 → 1.15.1

package/lib/commands/slides/index.js

@@ -0,0 +1,345 @@
+/**
+ * VoxFlow CLI — Slides command
+ *
+ * Thin orchestrator: delegates to submodules for constants, LLM generation,
+ * TTS narration, and HTML rendering/export.
+ *
+ * Submodules:
+ *   ./constants.js      — themes, templates, system prompt
+ *   ./html-renderer.js  — layout renderers, CSS, HTML export builder
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { SLIDES_DEFAULTS } = require('../../core/config');
+const { request, throwApiError, throwNetworkError } = require('../../core/http');
+const { chatCompletion } = require('../../core/llm-client');
+const { buildWav } = require('../../core/audio');
+const { BYTES_PER_MS } = require('../../core/timeline');
+const { startSpinner } = require('../../core/spinner');
+const {
+  VALID_THEMES, VALID_TEMPLATES, VALID_MODELS,
+  TEMPLATE_HINTS, TEMPLATE_STRUCTURES,
+  SLIDES_SYSTEM_PROMPT, VALID_MODEL_ALIASES,
+} = require('./constants');
+const { buildExportHTML } = require('./html-renderer');
+
+// ─── LLM Slide Generation ───────────────────────────────────────────────────
+
+async function generateSlides(apiBase, token, text, template, model) {
+  const templateHint = TEMPLATE_HINTS[template] || '';
+  const structure = TEMPLATE_STRUCTURES[template] || [];
+
+  let userContent = text;
+  if (templateHint) {
+    userContent += `\n\nTemplate hint: ${templateHint}`;
+  }
+  if (structure.length > 0) {
+    const structureDesc = structure.map((s, i) => `  Slide ${i + 1}: layout="${s.layout}" — ${s.hint}`).join('\n');
+    userContent += `\n\nSuggested structure:\n${structureDesc}`;
+  }
+
+  const messages = [
+    { role: 'system', content: SLIDES_SYSTEM_PROMPT },
+    { role: 'user', content: userContent },
+  ];
+
+  const modelPreset = VALID_MODEL_ALIASES.includes(model) ? model : 'swift';
+
+  const result = await chatCompletion({
+    apiBase,
+    token,
+    messages,
+    temperature: 0.7,
+    maxTokens: 4000,
+    modelPreset,
+  });
+
+  let jsonStr = result.content.trim();
+  const fenceMatch = jsonStr.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenceMatch) jsonStr = fenceMatch[1].trim();
+
+  const data = JSON.parse(jsonStr);
+
+  if (!data.slides || !Array.isArray(data.slides) || data.slides.length < 2) {
+    throw new Error('LLM returned invalid slide structure (need at least 2 slides)');
+  }
+
+  return { data, quota: result.quota };
+}
+
+// ─── TTS Synthesis ──────────────────────────────────────────────────────────
+
+async function synthesizeNarration(apiBase, token, text, voiceId, speed, index, total) {
+  process.stdout.write(`    TTS slide [${index + 1}/${total}]...`);
+
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/tts/synthesize`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      timeoutMs: 180_000,
+    }, {
+      text,
+      voiceId,
+      speed,
+      volume: 1.0,
+    }));
+  } catch (err) {
+    console.log(' FAIL');
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    console.log(' FAIL');
+    throwApiError(status, data, `TTS slide ${index + 1}`);
+  }
+
+  const pcmBuffer = Buffer.from(data.audio, 'base64');
+  const durationMs = Math.round(pcmBuffer.length / BYTES_PER_MS);
+  console.log(` OK (${(pcmBuffer.length / 1024).toFixed(0)} KB, ${(durationMs / 1000).toFixed(1)}s)`);
+  return { pcm: pcmBuffer, durationMs, quota: data.quota };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+async function slides(opts) {
+  const {
+    token,
+    api: apiBase,
+    text: inputText,
+    voice = SLIDES_DEFAULTS.voice,
+    speed = SLIDES_DEFAULTS.speed,
+    theme = SLIDES_DEFAULTS.theme,
+    template = SLIDES_DEFAULTS.template,
+    model = SLIDES_DEFAULTS.model,
+    noAudio = false,
+  } = opts;
+
+  const sigintHandler = () => {
+    console.log('\n\nGeneration cancelled.');
+    process.exit(0);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    const totalSteps = noAudio ? 2 : 3;
+    let stepNum = 1;
+
+    // Step 1: Generate slide data via LLM
+    console.log(`\n[${stepNum}/${totalSteps}] Generating slides from text...`);
+    console.log(`    Theme: ${theme}, Template: ${template}, Model: ${model}`);
+
+    const spinner = startSpinner('    Calling LLM...');
+    let slidesData;
+    let llmQuota = null;
+    try {
+      const result = await generateSlides(apiBase, token, inputText, template, model);
+      slidesData = result.data;
+      llmQuota = result.quota;
+      spinner.stop(`OK (${slidesData.slides.length} slides)`);
+    } catch (err) {
+      spinner.stop('FAIL');
+      throw new Error(`Slide generation failed: ${err.message}`);
+    }
+
+    const slideCount = slidesData.slides.length;
+    const layoutList = slidesData.slides.map(s => s.layout).join(', ');
+    console.log(`    Slides: ${slideCount} (${layoutList})`);
+
+    stepNum++;
+
+    // Step 2: TTS narration (optional)
+    let firstQuota = llmQuota;
+    let lastQuota = llmQuota;
+
+    if (!noAudio) {
+      const narrations = slidesData.slides.filter(s => s.narration);
+      console.log(`\n[${stepNum}/${totalSteps}] Synthesizing narration (${narrations.length} slides with narration)...`);
+
+      for (let i = 0; i < slidesData.slides.length; i++) {
+        const slide = slidesData.slides[i];
+        if (!slide.narration) {
+          slide.audio = { durationMs: 5000 };
+          continue;
+        }
+
+        const result = await synthesizeNarration(
+          apiBase, token, slide.narration, voice, speed, i, slideCount
+        );
+        if (!firstQuota && result.quota) firstQuota = result.quota;
+        lastQuota = result.quota;
+
+        const { wav } = buildWav([result.pcm], 0);
+        const dataUri = `data:audio/wav;base64,${wav.toString('base64')}`;
+
+        slide.audio = {
+          durationMs: result.durationMs,
+          dataUri,
+        };
+      }
+
+      stepNum++;
+    } else {
+      for (const slide of slidesData.slides) {
+        slide.audio = { durationMs: 5000 };
+      }
+    }
+
+    // Final: Generate HTML and save
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const outputPath = opts.output || `slides-${timestamp}.html`;
+
+    console.log(`\n[${stepNum}/${totalSteps}] Writing HTML...`);
+
+    const html = buildExportHTML(slidesData, theme);
+    fs.writeFileSync(outputPath, html, 'utf8');
+
+    const fileStat = fs.statSync(outputPath);
+    const fileSizeKb = (fileStat.size / 1024).toFixed(0);
+
+    console.log('\n=== Output ===');
+    console.log(`  File:     ${outputPath} (${fileSizeKb} KB)`);
+    console.log(`  Slides:   ${slideCount} (${layoutList})`);
+    console.log(`  Theme:    ${theme}`);
+    console.log(`  Template: ${template}`);
+    if (!noAudio) {
+      const totalDuration = slidesData.slides.reduce((sum, s) => sum + (s.audio?.durationMs || 5000), 0);
+      console.log(`  Duration: ${formatDuration(totalDuration)}`);
+    }
+    if (lastQuota) {
+      const quotaUsed = firstQuota && lastQuota
+        ? (firstQuota.remaining - lastQuota.remaining)
+        : slideCount * 100;
+      console.log(`  Quota:    ${quotaUsed} used, ${lastQuota.remaining ?? '?'} remaining`);
+    }
+    console.log('\n  Open in browser to view and present.');
+
+    return { outputPath, slideCount };
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+function formatDuration(ms) {
+  const totalSec = Math.round(ms / 1000);
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min === 0) return `${sec}s`;
+  return `${min}m${sec.toString().padStart(2, '0')}s`;
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseFloatFlag, parseBoolFlag, validateSpeed, 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 speed = parseFloatFlag(args, '--speed');
+  const output = parseFlag(args, '--output', '-o');
+
+  validateSpeed(args, speed);
+
+  if (output) {
+    if (!output.toLowerCase().endsWith('.html')) {
+      console.error('Error: --output path must end with .html');
+      process.exit(1);
+    }
+  }
+
+  const theme = parseFlag(args, '--theme');
+  if (theme && !VALID_THEMES.includes(theme)) {
+    console.error(`Error: --theme must be one of: ${VALID_THEMES.join(', ')} (got: "${theme}")`);
+    process.exit(1);
+  }
+
+  const template = parseFlag(args, '--template');
+  if (template && !VALID_TEMPLATES.includes(template)) {
+    console.error(`Error: --template must be one of: ${VALID_TEMPLATES.join(', ')} (got: "${template}")`);
+    process.exit(1);
+  }
+
+  const model = parseFlag(args, '--model');
+  if (model && !VALID_MODELS.includes(model)) {
+    console.error(`Error: --model must be one of: ${VALID_MODELS.join(', ')} (got: "${model}")`);
+    process.exit(1);
+  }
+
+  let text = parseFlag(args, '--text');
+  if (!text) {
+    const valuedFlags = new Set([
+      '--text', '--voice', '--speed', '--theme', '--template',
+      '--model', '--output', '-o', '--token', '--api',
+    ]);
+    for (let i = 0; i < args.length; i++) {
+      if (args[i].startsWith('-')) {
+        if (valuedFlags.has(args[i])) i++;
+        continue;
+      }
+      text = args[i];
+      break;
+    }
+  }
+
+  if (!text) {
+    console.error('Error: No text provided. Usage: voxflow slides "your topic" [options]');
+    process.exit(1);
+  }
+
+  let token;
+  if (explicitToken) {
+    token = explicitToken;
+  } else {
+    token = await getToken({ api });
+    const info = getTokenInfo();
+    if (info) {
+      console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+    }
+  }
+
+  const slidesOpts = {
+    token, api, text,
+    theme: theme || undefined,
+    template: template || undefined,
+    model: model || undefined,
+    voice: parseFlag(args, '--voice') || undefined,
+    speed, output,
+    noAudio: parseBoolFlag(args, '--no-audio'),
+  };
+
+  await runWithRetry(slides, slidesOpts, api, explicitToken);
+}
+
+const meta = {
+  slides: {
+    usage: '"topic" [opts]',
+    description: 'Generate AI presentation slides as HTML',
+    options: [
+      `<text>               Topic or text (positional arg or --text)`,
+      `--text <text>        Topic to generate slides about`,
+      `--voice <id>         TTS voice ID (default: ${SLIDES_DEFAULTS.voice})`,
+      `--speed <n>          TTS speed 0.5-2.0 (default: ${SLIDES_DEFAULTS.speed})`,
+      `--theme <name>       Theme: midnight, paper, ember, forest, ocean (default: ${SLIDES_DEFAULTS.theme})`,
+      `--template <name>    Template: product, report, tutorial, pitch, free (default: ${SLIDES_DEFAULTS.template})`,
+      `--model <id>         Model: swift, balanced, pro, creative (default: ${SLIDES_DEFAULTS.model})`,
+      `--no-audio           Skip TTS synthesis, generate slides only`,
+      `--output <path>      Output HTML file (default: ./slides-<timestamp>.html)`,
+    ],
+    examples: [
+      'voxflow slides "AI in Healthcare"',
+      'voxflow slides "Q4 Revenue Report" --template report --theme paper',
+      'voxflow slides "React Tutorial" --template tutorial --model balanced',
+      'voxflow slides "Startup Pitch" --template pitch --theme ocean --no-audio',
+    ],
+  },
+};
+
+module.exports = { slides, handle, meta, VALID_THEMES, VALID_TEMPLATES, VALID_MODELS };

package/lib/commands/slides.js

@@ -0,0 +1,11 @@
+/**
+ * VoxFlow CLI — Slides command
+ *
+ * Thin dispatcher — delegates to submodules in ./slides/.
+ * See slides/index.js for the orchestrator, slides/constants.js,
+ * slides/html-renderer.js for layout rendering and CSS.
+ */
+
+'use strict';
+
+module.exports = require('./slides/index');

package/lib/commands/story.js

@@ -0,0 +1,302 @@
+/**
+ * VoxFlow CLI — Story command
+ *
+ * Generates a story with TTS narration.
+ * Pipeline: LLM → parse paragraphs → TTS per paragraph → WAV
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { STORY_DEFAULTS } = require('../core/config');
+const { request, throwApiError, throwNetworkError, ApiError } = require('../core/http');
+const { parseParagraphs, buildWav, createSilence } = require('../core/audio');
+const { startSpinner } = require('../core/spinner');
+const { synthesizeTTS } = require('../core/tts-synthesizer');
+
+// ─── Step 1: Generate Story ─────────────────────────────────────────────────
+
+async function generateStory(apiBase, token, topic) {
+  const spinner = startSpinner('\n[1/3] Generating story text...');
+
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/llm/chat`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      timeoutMs: 180_000,
+    }, {
+      messages: [{ role: 'user', content: topic }],
+      stream: false,
+      temperature: 0.8,
+    }));
+  } catch (err) {
+    spinner.stop('FAIL');
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    spinner.stop('FAIL');
+    throwApiError(status, data, 'LLM');
+  }
+
+  const story = data.content;
+  const quota = data.quota;
+  spinner.stop('OK');
+  console.log(`    ${story.length} chars. Quota remaining: ${quota?.remaining ?? '?'}`);
+  return { story, quota };
+}
+
+// ─── Step 2: TTS Synthesis ──────────────────────────────────────────────────
+
+async function synthesizeParagraph(apiBase, token, text, voiceId, speed, index, total) {
+  const result = await synthesizeTTS({
+    apiBase, token, text, voiceId, speed,
+    index, total,
+  });
+
+  console.log(` OK (${(result.audio.length / 1024).toFixed(0)} KB)`);
+  return { pcm: result.audio, quota: result.quota };
+}
+
+async function synthesizeAll(apiBase, token, paragraphs, voiceId, speed) {
+  console.log(`\n[2/3] Synthesizing TTS audio (${paragraphs.length} segments)...`);
+
+  const pcmBuffers = [];
+  let lastQuota = null;
+  for (let i = 0; i < paragraphs.length; i++) {
+    const result = await synthesizeParagraph(apiBase, token, paragraphs[i], voiceId, speed, i, paragraphs.length);
+    pcmBuffers.push(result.pcm);
+    lastQuota = result.quota;
+  }
+
+  return { pcmBuffers, quota: lastQuota };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a story with TTS narration.
+ *
+ * @param {object} opts
+ * @param {string} opts.token       - JWT token
+ * @param {string} opts.api         - API base URL
+ * @param {string} [opts.voice]     - TTS voice ID
+ * @param {string} [opts.topic]     - Story prompt
+ * @param {string} [opts.output]    - Output WAV path
+ * @param {number} [opts.paragraphs]- Number of paragraphs
+ * @param {number} [opts.speed]     - TTS speed
+ * @param {number} [opts.silence]   - Silence gap between paragraphs (seconds)
+ * @returns {Promise<{outputPath: string, textPath: string, duration: number, quotaUsed: number}>}
+ */
+async function story(opts) {
+  // SIGINT handler for graceful cancellation
+  const sigintHandler = () => {
+    console.log('\n\nGeneration cancelled.');
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    return await _story(opts);
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+function buildStoryPrompt(userTopic, paragraphCount) {
+  if (userTopic) {
+    return `${userTopic}\n\n要求：\n1. 严格输出 ${paragraphCount} 段（不多不少）\n2. 段落之间用且仅用一个空行分隔\n3. 不要添加段落编号、标题或前言，直接输出正文`;
+  }
+  return `请写一个适合5岁儿童的短故事，要求：
+1. 严格输出 ${paragraphCount} 段（不多不少），每段 2-3 句话
+2. 每段描述一个清晰的画面场景
+3. 语言简单易懂，充满童趣
+4. 段落之间用且仅用一个空行分隔
+5. 不要添加段落编号、标题或前言，直接输出故事内容`;
+}
+
+/**
+ * Clamp parsed paragraphs to exactly `target` count.
+ *
+ * The LLM doesn't always strictly honor the prompt constraint — if it
+ * returns more paragraphs than requested, we merge consecutive ones into
+ * roughly equal-sized buckets. If it returns fewer, we keep what we got.
+ *
+ * Issue #2916: `voxflow story --topic ... --paragraphs 1` was returning
+ * 5+ paragraphs even after the prompt fix. Hard-clamp guarantees the user
+ * gets exactly N TTS segments and quota cost is what they expected.
+ */
+function clampParagraphs(paragraphs, target) {
+  if (!Array.isArray(paragraphs)) return [];
+  if (paragraphs.length <= target || target < 1) return paragraphs;
+  const buckets = Array.from({ length: target }, () => []);
+  for (let i = 0; i < paragraphs.length; i++) {
+    const slot = Math.min(target - 1, Math.floor((i * target) / paragraphs.length));
+    buckets[slot].push(paragraphs[i]);
+  }
+  return buckets.map(b => b.join(' ')).filter(s => s.trim().length > 0);
+}
+
+async function _story(opts) {
+  const voice = opts.voice || STORY_DEFAULTS.voice;
+  const paragraphCount = opts.paragraphs || STORY_DEFAULTS.paragraphs;
+  const speed = opts.speed ?? STORY_DEFAULTS.speed;
+  const silence = opts.silence ?? STORY_DEFAULTS.silence;
+  const api = opts.api;
+  const token = opts.token;
+
+  // When the user passes --topic, the default paragraph-structure prompt
+  // was dropped, so --paragraphs was silently ignored (issue #2916).
+  // buildStoryPrompt always injects the paragraph constraint.
+  const topic = buildStoryPrompt(opts.topic, paragraphCount);
+
+  // Default output path
+  let outputPath = opts.output;
+  if (!outputPath) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    outputPath = path.resolve(`story-${ts}.wav`);
+  }
+
+  console.log('\n=== VoxFlow Story Generator ===');
+  console.log(`Voice:      ${voice}`);
+  console.log(`API:        ${api}`);
+  console.log(`Paragraphs: ${paragraphCount}`);
+  console.log(`Speed:      ${speed}`);
+  console.log(`Output:     ${outputPath}`);
+
+  // Step 1: LLM
+  const { story: storyText } = await generateStory(api, token, topic);
+
+  // Step 2: Parse + clamp to requested paragraph count
+  const rawParagraphs = parseParagraphs(storyText);
+  if (rawParagraphs.length === 0) {
+    throw new Error('No paragraphs found in generated story');
+  }
+  const paragraphs = clampParagraphs(rawParagraphs, paragraphCount);
+  if (rawParagraphs.length !== paragraphs.length) {
+    console.log(`    ${rawParagraphs.length} paragraphs from LLM → merged to ${paragraphs.length} (--paragraphs ${paragraphCount})`);
+  } else {
+    console.log(`    ${paragraphs.length} paragraphs`);
+  }
+
+  // Step 3: TTS
+  const { pcmBuffers, quota: lastQuota } = await synthesizeAll(api, token, paragraphs, voice, speed);
+
+  // Step 4: WAV
+  console.log('\n[3/3] Merging audio...');
+  const { wav, duration } = buildWav(pcmBuffers, silence);
+
+  // Write files
+  const outDir = path.dirname(outputPath);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const outputExt = path.extname(outputPath).toLowerCase();
+  const needsConvert = outputExt !== '.wav';
+
+  if (needsConvert) {
+    // Write WAV to a temp file, then convert to the target format
+    const tempWavPath = outputPath.replace(/\.[^.]+$/, '.tmp.wav');
+    fs.writeFileSync(tempWavPath, wav);
+
+    const { checkFfmpeg, convertAudioFormat } = require('../core/ffmpeg');
+    const ffmpegInfo = await checkFfmpeg();
+    if (!ffmpegInfo.available) {
+      // Fallback: keep the WAV temp file as the output
+      fs.renameSync(tempWavPath, outputPath);
+      console.log(`\n    Warning: ffmpeg not found, saved as WAV in ${outputPath}`);
+    } else {
+      await convertAudioFormat(tempWavPath, outputPath);
+      try { fs.unlinkSync(tempWavPath); } catch { /* ignore */ }
+    }
+  } else {
+    fs.writeFileSync(outputPath, wav);
+  }
+
+  // Derive text path using path.extname for robustness (works for any extension)
+  const textPath = outputPath.slice(0, -path.extname(outputPath).length) + '.txt';
+  const textContent = paragraphs.map((p, i) => `[${i + 1}] ${p}`).join('\n\n');
+  fs.writeFileSync(textPath, textContent, 'utf8');
+
+  const quotaUsed = 1 + paragraphs.length;
+  console.log(`\n=== Done ===`);
+  console.log(`Output: ${outputPath} (${(fs.statSync(outputPath).size / 1024).toFixed(1)} KB, ${duration.toFixed(1)}s)`);
+  console.log(`Story:  ${textPath}`);
+  console.log(`Quota:  ${quotaUsed} used, ${lastQuota?.remaining ?? '?'} remaining`);
+
+  return { outputPath, textPath, duration, quotaUsed };
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseIntFlag, parseFloatFlag, validateSpeed, validateSilence, validateOutput, 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');
+
+  // Parse and validate options before auth
+  const paragraphs = parseIntFlag(args, '--paragraphs');
+  const speed = parseFloatFlag(args, '--speed');
+  const silence = parseFloatFlag(args, '--silence');
+  const output = parseFlag(args, '--output', '-o');
+
+  if (paragraphs !== undefined) {
+    if (isNaN(paragraphs) || paragraphs < 1 || paragraphs > 20) {
+      console.error(`Error: --paragraphs must be an integer between 1 and 20 (got: "${parseFlag(args, '--paragraphs')}")`);
+      process.exit(1);
+    }
+  }
+
+  validateSpeed(args, speed);
+  validateSilence(args, silence);
+  validateOutput(output);
+
+  // Authenticate after validation
+  let token;
+  if (explicitToken) {
+    token = explicitToken;
+  } else {
+    token = await getToken({ api });
+    const info = getTokenInfo();
+    if (info) {
+      console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+    }
+  }
+
+  const opts = {
+    token, api,
+    topic: parseFlag(args, '--topic'),
+    voice: parseFlag(args, '--voice'),
+    output, paragraphs, speed, silence,
+  };
+
+  await runWithRetry(story, opts, api, explicitToken);
+}
+
+const meta = {
+  story: {
+    usage: '[opts]',
+    description: 'Generate a story with TTS narration',
+    options: [
+      `--topic <text>       Story topic (default: children's story)`,
+      `--voice <id>         TTS voice ID (default: ${STORY_DEFAULTS.voice})`,
+      `--output <path>      Output WAV path (default: ./story-<timestamp>.wav)`,
+      `--paragraphs <n>     Paragraph count, 1-20 (default: ${STORY_DEFAULTS.paragraphs})`,
+      `--speed <n>          TTS speed 0.5-2.0 (default: ${STORY_DEFAULTS.speed})`,
+      `--silence <sec>      Silence between paragraphs, 0-5.0 (default: ${STORY_DEFAULTS.silence})`,
+    ],
+    examples: [
+      'voxflow story --topic "三只小猪"',
+      'voxflow story --topic "space adventure" --voice v-male-Bk7vD3xP --paragraphs 10',
+    ],
+  },
+  // Alias picked up by the CLI router (issue #2389)
+  generate: { alias: 'story', description: 'Alias for story' },
+};
+
+module.exports = { story, handle, meta, ApiError, _test: { parseParagraphs, buildWav, createSilence, buildStoryPrompt, clampParagraphs } };