voxflow 1.14.0 → 1.15.1

package/lib/commands/explain.js

@@ -0,0 +1,512 @@
+/**
+ * VoxFlow CLI — Explain command
+ *
+ * Generates an AI explainer video: LLM script → TTS narration → Remotion render → MP4
+ * Phase 1: demo mode with hardcoded script, audio-only fallback.
+ * Phase 2: full LLM + TTS pipeline.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { EXPLAIN_DEFAULTS } = require('../core/config');
+const { request, throwApiError, throwNetworkError } = require('../core/http');
+const { buildWav } = require('../core/audio');
+const { BYTES_PER_MS } = require('../core/timeline');
+const { mergeAudioVideo } = require('../core/ffmpeg');
+const { startSpinner } = require('../core/spinner');
+
+// ─── Demo Script ────────────────────────────────────────────────────────────
+
+const DEMO_SCRIPT = {
+  title: 'What is React?',
+  language: 'en',
+  style: 'modern',
+  scenes: [
+    {
+      type: 'title',
+      title: 'What is React?',
+      subtitle: 'A JavaScript library for building user interfaces',
+      narration: 'Welcome to this quick explainer on React, one of the most popular frontend libraries in the world.',
+    },
+    {
+      type: 'bullets',
+      heading: 'Core Concepts',
+      bullets: [
+        'Component-based architecture',
+        'Virtual DOM for efficient updates',
+        'Declarative UI with JSX',
+        'Unidirectional data flow',
+      ],
+      narration: 'React is built around several core concepts. First, everything is a component. Second, it uses a virtual DOM for efficient rendering. Third, you write declarative UI with JSX syntax. And fourth, data flows in one direction, from parent to child.',
+    },
+    {
+      type: 'bullets',
+      heading: 'Why Use React?',
+      bullets: [
+        'Massive ecosystem and community',
+        'Reusable component library',
+        'Excellent developer tools',
+      ],
+      narration: 'So why choose React? It has a massive ecosystem with thousands of libraries. You can build reusable component libraries. And the developer tools are some of the best in the industry.',
+    },
+    {
+      type: 'summary',
+      heading: 'Key Takeaways',
+      points: [
+        'React makes UI development predictable and efficient',
+        'Components are the building blocks of React apps',
+        'The virtual DOM optimizes rendering performance',
+      ],
+      narration: 'To summarize: React makes UI development predictable and efficient. Components are the fundamental building blocks. And the virtual DOM ensures your app stays fast, even as it grows. Thanks for watching!',
+    },
+  ],
+};
+
+// ─── TTS Synthesis ──────────────────────────────────────────────────────────
+
+async function synthesizeScene(apiBase, token, text, voiceId, speed, index, total) {
+  process.stdout.write(`    TTS scene [${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}`,
+      },
+    }, {
+      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 scene ${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 };
+}
+
+// ─── Audio Helpers ──────────────────────────────────────────────────────────
+
+function buildNarrationWav(pcmBuffers, silenceSec) {
+  const result = buildWav(pcmBuffers, silenceSec);
+  return result.wav;
+}
+
+// ─── LLM Script Generation ─────────────────────────────────────────────────
+
+/**
+ * Generate an ExplainScript by calling the LLM API.
+ * Falls back to a demo-based script on failure.
+ */
+async function generateScript(apiBase, token, topic, { language = 'en', sceneCount = 5, style = 'modern' } = {}) {
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/llm/generate-explain-script`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      timeoutMs: 180_000,
+    }, {
+      topic,
+      language,
+      sceneCount,
+      style,
+    }));
+  } catch (err) {
+    console.log(`    ⚠ LLM request failed: ${err.message}`);
+    console.log('    Falling back to demo script template.');
+    return buildFallbackScript(topic, style);
+  }
+
+  if (status !== 200 || data.code !== 'success' || !data.script) {
+    const msg = data?.message || `HTTP ${status}`;
+    console.log(`    ⚠ LLM generation failed: ${msg}`);
+    console.log('    Falling back to demo script template.');
+    return buildFallbackScript(topic, style);
+  }
+
+  console.log(`    ✓ Script generated: "${data.script.title}" (${data.script.scenes.length} scenes)`);
+  return data.script;
+}
+
+/**
+ * Build a fallback script based on DEMO_SCRIPT when LLM is unavailable.
+ */
+function buildFallbackScript(topic, style) {
+  const script = { ...DEMO_SCRIPT, title: topic, style };
+  script.scenes = [
+    { ...DEMO_SCRIPT.scenes[0], title: topic, narration: `Welcome to this explainer on ${topic}.` },
+    ...DEMO_SCRIPT.scenes.slice(1),
+  ];
+  return script;
+}
+
+// ─── Remotion Render ────────────────────────────────────────────────────────
+
+function findRemotionDir() {
+  // Walk up from CLI dir to find remotion/ at repo root
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = path.join(dir, 'remotion');
+    if (fs.existsSync(path.join(candidate, 'package.json'))) {
+      return candidate;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function isRemotionAvailable() {
+  const remotionDir = findRemotionDir();
+  if (!remotionDir) return false;
+  return fs.existsSync(path.join(remotionDir, 'node_modules', 'remotion'));
+}
+
+async function renderVideo(script, sceneTimings, outputPath, onProgress) {
+  const remotionDir = findRemotionDir();
+  if (!remotionDir) {
+    throw new Error('Remotion directory not found. Ensure remotion/ exists at the repo root with dependencies installed.');
+  }
+
+  // Write props to temp file
+  const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'voxflow-explain-'));
+  const propsPath = path.join(tmpDir, 'props.json');
+
+  const props = {
+    fps: 30,
+    script,
+    scenes: sceneTimings,
+  };
+  fs.writeFileSync(propsPath, JSON.stringify(props, null, 2));
+
+  // Spawn render.ts as a subprocess
+  const renderScript = path.join(remotionDir, 'render.ts');
+  const { execFile } = require('child_process');
+  const tsNode = path.join(remotionDir, 'node_modules', '.bin', 'ts-node');
+
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      tsNode,
+      [renderScript, '--props', propsPath, '--output', outputPath],
+      { cwd: remotionDir, maxBuffer: 50 * 1024 * 1024, timeout: 600_000 },
+      (err, stdout, stderr) => {
+        // Clean up temp
+        try { fs.unlinkSync(propsPath); fs.rmdirSync(tmpDir); } catch { /* ignore */ }
+
+        if (err) {
+          reject(new Error(`Remotion render failed: ${err.message}\n${stderr}`));
+          return;
+        }
+
+        // Parse stdout for result
+        try {
+          const lines = stdout.trim().split('\n');
+          const last = lines[lines.length - 1];
+          const result = JSON.parse(last);
+          resolve(result);
+        } catch {
+          resolve({ output: outputPath });
+        }
+      }
+    );
+
+    // Parse stderr for progress
+    if (child.stderr && onProgress) {
+      let buffer = '';
+      child.stderr.on('data', (chunk) => {
+        buffer += chunk.toString();
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) {
+          try {
+            const msg = JSON.parse(line);
+            if (msg.type === 'progress' && onProgress) {
+              onProgress(msg.percent);
+            }
+          } catch {
+            // Not JSON, just log output
+          }
+        }
+      });
+    }
+  });
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate an AI explainer video.
+ *
+ * @param {object} opts
+ * @param {string} opts.token       - JWT token
+ * @param {string} opts.api         - API base URL
+ * @param {string} [opts.topic]     - Video topic (or 'demo' for hardcoded demo)
+ * @param {string} [opts.voice]     - TTS voice ID
+ * @param {string} [opts.style]     - Visual style: modern, playful, corporate, chalkboard
+ * @param {string} [opts.language]  - Script language (en, zh, ja, etc.)
+ * @param {string} [opts.output]    - Output file path
+ * @param {number} [opts.speed]     - TTS speed
+ * @param {number} [opts.scenes]    - Number of scenes (for LLM generation)
+ * @param {boolean} [opts.audioOnly] - Skip video render, output WAV only
+ * @param {boolean} [opts.cloud]    - Render on cloud instead of local
+ * @returns {Promise<{outputPath: string, scriptPath: string, duration: number}>}
+ */
+async function explain(opts) {
+  const {
+    token,
+    api: apiBase,
+    topic = 'demo',
+    voice = EXPLAIN_DEFAULTS.voice,
+    style = EXPLAIN_DEFAULTS.style,
+    language = EXPLAIN_DEFAULTS.language,
+    speed = EXPLAIN_DEFAULTS.speed,
+    scenes: sceneCount = EXPLAIN_DEFAULTS.sceneCount,
+    audioOnly = false,
+    cloud = false,
+  } = opts;
+
+  // Reject .mp3 output — we write raw WAV bytes, not MP3-encoded data
+  if (opts.output && opts.output.endsWith('.mp3')) {
+    throw new Error('MP3 output is not supported for explain. Use .wav or .mp4');
+  }
+
+  // SIGINT handler for graceful cancellation
+  const sigintHandler = () => {
+    console.log('\n\nGeneration cancelled.');
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    // ── Step 1: Get or generate script ────────────────────────────────────
+    let script;
+    const isDemo = topic === 'demo' || topic === 'Demo';
+
+    if (isDemo) {
+      console.log('\n[1/4] Using demo script (hardcoded)...');
+      script = { ...DEMO_SCRIPT, style };
+    } else {
+      // Phase 2: LLM script generation
+      console.log('\n[1/4] Generating script via LLM...');
+      console.log(`    Topic: "${topic}" (${language}, ${sceneCount} scenes)`);
+      script = await generateScript(apiBase, token, topic, { language, sceneCount, style });
+    }
+
+    console.log(`    Script: ${script.scenes.length} scenes, style: ${script.style}`);
+
+    // ── Step 2: Synthesize TTS narration ──────────────────────────────────
+    console.log(`\n[2/4] Synthesizing narration (${script.scenes.length} scenes)...`);
+
+    const pcmBuffers = [];
+    const sceneTimings = [];
+    let firstQuota = null;
+    let lastQuota = null;
+
+    for (let i = 0; i < script.scenes.length; i++) {
+      const scene = script.scenes[i];
+      const result = await synthesizeScene(
+        apiBase, token, scene.narration, voice, speed, i, script.scenes.length
+      );
+      pcmBuffers.push(result.pcm);
+      if (!firstQuota && result.quota) firstQuota = result.quota;
+      lastQuota = result.quota;
+
+      // Build timing data for Remotion (audio merged via ffmpeg after render)
+      sceneTimings.push({
+        scene,
+        durationMs: result.durationMs,
+        audioSrc: '',
+      });
+    }
+
+    // Build narration WAV from all scene PCM buffers (used for audio-only or muxing)
+    const narrationWavBuffer = buildNarrationWav(pcmBuffers, EXPLAIN_DEFAULTS.silence);
+
+    // ── Step 3: Render video or audio ─────────────────────────────────────
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    let outputPath;
+
+    if (audioOnly || !isRemotionAvailable()) {
+      if (!audioOnly && !isRemotionAvailable()) {
+        console.log('\n[3/4] Remotion not available. Falling back to audio-only output.');
+        console.log('    To enable video rendering, install Remotion:');
+        console.log('      cd remotion && npm install');
+      } else {
+        console.log('\n[3/4] Building audio-only output...');
+      }
+
+      outputPath = opts.output || `explain-${timestamp}.wav`;
+      fs.writeFileSync(outputPath, narrationWavBuffer);
+    } else {
+      if (cloud) {
+        console.log('\n[3/4] Cloud rendering coming in Phase 2. Using local render.');
+      }
+      outputPath = opts.output || `explain-${timestamp}.mp4`;
+      const spinner = startSpinner(cloud ? '    Rendering video...' : '\n[3/4] Rendering video...');
+      try {
+        // Remotion renders video-only (no audio); we merge narration via ffmpeg
+        const silentVideoPath = outputPath + '.silent.mp4';
+        await renderVideo(script, sceneTimings, silentVideoPath, (percent) => {
+          spinner.update(`    Rendering video... ${percent}%`);
+        });
+        spinner.stop('OK');
+
+        // Merge narration audio into the rendered video
+        console.log('    Merging narration audio...');
+        const narrationWavPath = outputPath + '.narration.wav';
+        fs.writeFileSync(narrationWavPath, narrationWavBuffer);
+        await mergeAudioVideo(silentVideoPath, narrationWavPath, outputPath);
+
+        // Clean up temp files
+        try { fs.unlinkSync(silentVideoPath); } catch { /* ignore */ }
+        try { fs.unlinkSync(narrationWavPath); } catch { /* ignore */ }
+        console.log('    Audio merged OK');
+      } catch (err) {
+        spinner.stop('FAIL');
+        console.log(`    Video render failed: ${err.message}`);
+        console.log('    Falling back to audio-only...');
+        outputPath = outputPath.replace(/\.mp4$/, '.wav');
+        fs.writeFileSync(outputPath, narrationWavBuffer);
+      }
+    }
+
+    // ── Step 4: Save script & summary ─────────────────────────────────────
+    const scriptPath = outputPath.replace(/\.(mp4|wav)$/, '.json');
+    fs.writeFileSync(scriptPath, JSON.stringify(script, null, 2));
+
+    const totalDurationMs = sceneTimings.reduce((sum, s) => sum + s.durationMs, 0);
+    const fileStat = fs.statSync(outputPath);
+    const fileSizeMb = (fileStat.size / (1024 * 1024)).toFixed(1);
+    const durationStr = formatDuration(totalDurationMs);
+
+    console.log('\n[4/4] Done!');
+    console.log(`\n=== Output ===`);
+    console.log(`  File:     ${outputPath} (${fileSizeMb} MB, ${durationStr})`);
+    console.log(`  Script:   ${scriptPath}`);
+    console.log(`  Scenes:   ${script.scenes.length}`);
+    console.log(`  Style:    ${script.style}`);
+    if (lastQuota) {
+      const quotaUsed = firstQuota && lastQuota
+        ? (firstQuota.remaining - lastQuota.remaining)
+        : script.scenes.length * 100;
+      console.log(`  Quota:    ${quotaUsed} used, ${lastQuota.remaining ?? '?'} remaining`);
+    }
+
+    return { outputPath, scriptPath, duration: totalDurationMs };
+  } 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, parseIntFlag, 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');
+
+  // Validate flags BEFORE auth (to avoid browser login for invalid args)
+  const speed = parseFloatFlag(args, '--speed');
+  const output = parseFlag(args, '--output', '-o');
+  const scenes = parseIntFlag(args, '--scenes');
+
+  validateSpeed(args, speed);
+
+  if (output) {
+    const validExts = ['.wav', '.mp3', '.mp4'];
+    const hasValidExt = validExts.some(ext => output.toLowerCase().endsWith(ext));
+    if (!hasValidExt) {
+      console.error('Error: --output path must end with .wav, .mp3, or .mp4');
+      process.exit(1);
+    }
+  }
+
+  const style = parseFlag(args, '--style');
+  if (style && !['modern', 'playful', 'corporate', 'chalkboard'].includes(style)) {
+    console.error(`Error: --style must be one of: modern, playful, corporate, chalkboard (got: "${style}")`);
+    process.exit(1);
+  }
+
+  if (scenes !== undefined) {
+    if (isNaN(scenes) || scenes < 3 || scenes > 12) {
+      console.error(`Error: --scenes must be between 3 and 12 (got: "${parseFlag(args, '--scenes')}")`);
+      process.exit(1);
+    }
+  }
+
+  // Auth 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') || undefined,
+    voice: parseFlag(args, '--voice') || undefined,
+    style: style || undefined,
+    language: parseFlag(args, '--language') || undefined,
+    output, speed, scenes,
+    audioOnly: parseBoolFlag(args, '--audio-only'),
+    cloud: parseBoolFlag(args, '--cloud'),
+  };
+
+  await runWithRetry(explain, opts, api, explicitToken);
+}
+
+const meta = {
+  explain: {
+    usage: '[opts]',
+    description: 'Generate an AI explainer video from a topic',
+    options: [
+      `--topic <text>       Topic to explain (use "demo" for built-in demo)`,
+      `--style <style>      Visual style: modern (default), playful, corporate, chalkboard`,
+      `--language <code>    Script language: en (default), zh, ja, ko, etc.`,
+      `--voice <id>         TTS voice ID (default: ${EXPLAIN_DEFAULTS.voice})`,
+      `--speed <n>          TTS speed 0.5-2.0 (default: ${EXPLAIN_DEFAULTS.speed})`,
+      `--scenes <n>         Number of scenes, 3-12 (default: ${EXPLAIN_DEFAULTS.sceneCount})`,
+      `--audio-only         Skip video render, output WAV narration only`,
+      `--cloud              Render on cloud instead of local Remotion`,
+      `--output <path>      Output file path (default: ./explain-<timestamp>.mp4)`,
+    ],
+    examples: [
+      'voxflow explain --topic "What is React?"',
+      'voxflow explain --topic demo --output demo.mp4',
+      'voxflow explain --topic "区块链入门" --style chalkboard --voice v-male-Bk7vD3xP',
+      'voxflow explain --topic "Machine Learning" --audio-only',
+    ],
+  },
+};
+
+module.exports = { explain, handle, meta };

package/lib/commands/feedback.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const os = require('os');
+const { execFile } = require('child_process');
+const readline = require('readline');
+const pkg = require('../../package.json');
+
+const REPO = 'VoxFlowStudio/FlowStudio';
+const REPO_URL = `https://github.com/${REPO}`;
+
+const TYPE_MAP = {
+  bug:     { prefix: '[CLI Bug] ',     labels: 'type/bug,area/cli',  template: 'cli-bug.md' },
+  feature: { prefix: '[CLI Feature] ', labels: 'type/feat,area/cli', template: 'cli-feature.md' },
+  general: { prefix: '[CLI] ',         labels: 'area/cli',           template: null },
+};
+
+function systemInfo() {
+  return [
+    `**CLI version:** ${pkg.version}`,
+    `**OS:** ${process.platform} ${os.arch()} (${os.release()})`,
+    `**Node:** ${process.version}`,
+  ].join('\n');
+}
+
+function buildIssueUrl({ type, title, body }) {
+  const tmpl = TYPE_MAP[type] || TYPE_MAP.general;
+  const params = new URLSearchParams();
+  params.set('title', tmpl.prefix + title);
+  params.set('body', (body ? body + '\n\n' : '') + '---\n\n' + systemInfo());
+  params.set('labels', tmpl.labels);
+  if (tmpl.template) params.set('template', tmpl.template);
+  return `${REPO_URL}/issues/new?${params.toString()}`;
+}
+
+// Try `gh issue create`. Returns issue URL on success, null if gh unavailable/fails.
+function ghSubmit({ type, title, body }) {
+  return new Promise((resolve) => {
+    const tmpl = TYPE_MAP[type] || TYPE_MAP.general;
+    const fullTitle = tmpl.prefix + title;
+    const fullBody = (body ? body + '\n\n' : '') + '---\n\n' + systemInfo();
+    const ghArgs = [
+      'issue', 'create',
+      '--repo', REPO,
+      '--title', fullTitle,
+      '--body', fullBody,
+      '--label', tmpl.labels,
+    ];
+    execFile('gh', ghArgs, { timeout: 15000 }, (err, stdout) => {
+      if (err) { resolve(null); return; }
+      resolve((stdout || '').trim() || null);
+    });
+  });
+}
+
+async function collectInfo(presetType) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const ask = (q) => new Promise((res) => rl.question(q, (a) => res(a.trim())));
+  try {
+    process.stderr.write('\n  VoxFlow CLI Feedback\n\n');
+    let type = presetType;
+    if (!type) {
+      process.stderr.write('  Type:\n    1) Bug report\n    2) Feature request\n    3) General feedback\n\n');
+      const choice = await ask('  Choice [1/2/3]: ');
+      type = ({ '1': 'bug', '2': 'feature', '3': 'general' })[choice] || 'general';
+    }
+    const title = await ask('\n  Title: ');
+    if (!title) { process.stderr.write('  Title is required.\n\n'); return null; }
+    process.stderr.write('\n  Description (empty line to finish):\n');
+    const lines = [];
+    let line;
+    do {
+      line = await ask('  > ');
+      if (line) lines.push(line);
+    } while (line !== '');
+    return { type, title, body: lines.join('\n') };
+  } finally {
+    rl.close();
+  }
+}
+
+async function submitOrFallback({ type, title, body }, printUrl) {
+  // Try gh first (direct submit, no browser)
+  const issueUrl = await ghSubmit({ type, title, body });
+  if (issueUrl) {
+    process.stderr.write(`\n  ✓ Issue created: ${issueUrl}\n\n`);
+    process.stdout.write(issueUrl + '\n');
+    return;
+  }
+  // gh unavailable → URL fallback
+  const url = buildIssueUrl({ type, title, body });
+  if (printUrl) {
+    process.stdout.write(url + '\n');
+  } else {
+    process.stderr.write('\n  Opening browser...\n\n');
+    const open = (await import('open')).default;
+    await open(url);
+  }
+}
+
+async function handle(args) {
+  const { parseBoolFlag, parseFlag } = require('../core/args');
+
+  let presetType = null;
+  if (parseBoolFlag(args, '--bug')) presetType = 'bug';
+  else if (parseBoolFlag(args, '--feature')) presetType = 'feature';
+  else if (parseBoolFlag(args, '--general')) presetType = 'general';
+
+  const titleArg = parseFlag(args, '--title');
+  const bodyArg  = parseFlag(args, '--body');
+  const printUrl = parseBoolFlag(args, '--print-url');
+
+  // Non-interactive mode: --title provided (AI / scripted use)
+  if (titleArg) {
+    await submitOrFallback({ type: presetType || 'general', title: titleArg, body: bodyArg || '' }, printUrl);
+    return;
+  }
+
+  // Interactive mode: requires TTY
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      'voxflow feedback requires an interactive terminal.\n' +
+      'For non-interactive use: voxflow feedback --bug --title "..." --body "..."\n'
+    );
+    process.exit(1);
+  }
+
+  const info = await collectInfo(presetType);
+  if (!info) return;
+  await submitOrFallback(info, printUrl);
+}
+
+const meta = {
+  feedback: {
+    usage: '[--bug | --feature | --general] [--title "..."] [--body "..."] [--print-url]',
+    description: 'Submit a bug report or feature request to GitHub',
+    options: [
+      '--bug                     Pre-fill as bug report',
+      '--feature                 Pre-fill as feature request',
+      '--general                 Pre-fill as general feedback',
+      '--title <text>            Title (enables non-interactive / AI mode)',
+      '--body <text>             Description body',
+      '--print-url               Print URL instead of opening browser (fallback only)',
+    ],
+    examples: [
+      'voxflow feedback',
+      'voxflow feedback --bug',
+      'voxflow feedback --bug --title "asr crashes on wav files" --body "Steps: ..."',
+    ],
+  },
+};
+
+module.exports = { buildIssueUrl, systemInfo, ghSubmit, handle, meta };