voxflow 1.15.0 → 1.15.2

package/lib/cli.js

@@ -0,0 +1,270 @@
+/**
+ * VoxFlow CLI — Subcommand router
+ *
+ * Thin dispatcher: parses the top-level command, loads the matching module,
+ * and delegates to its `handle(args)` function. Help text is assembled
+ * lazily from each command's `meta` export.
+ */
+
+const pkg = require('../package.json');
+const { logger, parseVerbosityFromArgv } = require('./core/logger');
+
+// ─── Command Registry (auto-discovered, issue #2389) ────────────────────────
+//
+// Command modules live in ./commands/. Every module whose `meta` export is an
+// object mapping `commandName → { description, usage, options, examples }` is
+// picked up automatically. Aliases are meta entries with `{ alias: 'canonical' }`
+// — no need to maintain them separately.
+//
+// Two special-case shapes we still handle explicitly:
+//  - `auth-cmds.js` exports named handlers (handleLogin etc.) instead of a
+//    single `handle()` — dispatched via AUTH_HANDLERS.
+//  - Files without a `meta` export (e.g. `picstory-templates.js` shared helper)
+//    are skipped.
+
+// Auth-cmds handler name mapping (multi-handler module)
+const AUTH_HANDLERS = {
+  login:     'handleLogin',
+  logout:    'handleLogout',
+  status:    'handleStatus',
+  dashboard: 'handleDashboard',
+  clone:     'handleClone',
+};
+
+// Static registry — see commands/_registry.js for why this exists.
+// In dev cli.js is loaded from source and `lib/commands/` is on disk; in
+// the published bundle (ncc) there is no such directory, so we always
+// resolve through the registry instead of `fs.readdirSync`.
+const COMMAND_REGISTRY = require('./commands/_registry');
+
+/**
+ * Build the meta registry by walking COMMAND_REGISTRY. Each entry is a
+ * lazy thunk so loading a single command does not transitively pull in
+ * every other command's deps (ffmpeg/audio/llm).
+ * Returns { COMMAND_MAP, ALIASES, META }.
+ */
+function discoverCommands() {
+  // Maps command name (canonical or alias) → already-loaded module reference.
+  // Storing the module directly (vs. a path string) is what makes the slow
+  // path work in the ncc-bundled dist: in dist/index.js, dynamic
+  // `require('./commands/synthesize')` strings have no on-disk path to
+  // resolve and crash with "Cannot find module". The loader thunks were
+  // already bundled at build time, so once we've called loader() we have a
+  // valid object reference that survives the bundle.
+  const COMMAND_MAP = {};
+  const ALIASES = {};
+  const META = {};
+
+  for (const [fileBase, loader] of Object.entries(COMMAND_REGISTRY)) {
+    const mod = loader();
+    if (!mod || typeof mod.meta !== 'object') continue;
+
+    for (const [name, info] of Object.entries(mod.meta)) {
+      if (!info || typeof info !== 'object') continue;
+      COMMAND_MAP[name] = mod;
+      META[name] = info;
+      // fileBase is the canonical command for this module (matches the
+      // registry key); meta entries marked `alias` point to it via name.
+      void fileBase;
+      if (typeof info.alias === 'string') {
+        ALIASES[name] = info.alias;
+      }
+    }
+  }
+
+  return { COMMAND_MAP, ALIASES, META };
+}
+
+/**
+ * Lazy registry — scanned on first access, memoized thereafter. Hot path
+ * (canonical command dispatch) skips this entirely via fastResolveCommand.
+ */
+let _registry = null;
+function getRegistry() {
+  if (!_registry) _registry = discoverCommands();
+  return _registry;
+}
+
+/**
+ * Fast path: if `<command>` is a canonical entry in COMMAND_REGISTRY (not
+ * an alias), load and return its module without iterating the rest. Returns
+ * `null` for aliases, auth-cmds handlers, and unknown commands — those fall
+ * back to the full registry scan.
+ */
+function fastResolveCommand(command) {
+  if (!/^[a-z][a-z0-9-]*$/i.test(command)) return null; // guard against path traversal
+  const loader = COMMAND_REGISTRY[command];
+  if (!loader) return null;
+  const mod = loader();
+  if (!mod || typeof mod.meta !== 'object') return null;
+  const entry = mod.meta[command];
+  if (!entry || entry.alias) return null;
+  return mod;
+}
+
+// ─── Runner ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse argv and dispatch to the appropriate handler.
+ */
+async function run(argv) {
+  const rawArgs = argv || process.argv.slice(2);
+
+  // Strip global verbosity flags (-v / -vv / -vvv / --verbose[=level])
+  // BEFORE the subcommand sees them. Also honours DEBUG=voxflow:*.
+  // Subcommands get a clean argv so their own flag parsers don't choke.
+  // Note: `--version`/`-v` is a special case — if the first arg IS `-v`
+  // AND it's the only arg, treat it as version (legacy behaviour).
+  if (rawArgs.length === 1 && (rawArgs[0] === '--version' || rawArgs[0] === '-v')) {
+    console.log(pkg.version);
+    return;
+  }
+  const { level, rest: args } = parseVerbosityFromArgv(rawArgs);
+  logger.setLevel(level);
+  const command = args[0];
+
+  // Global flags
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === '--version') {
+    console.log(pkg.version);
+    return;
+  }
+
+  // Handle --help for any subcommand before dispatching (no login required)
+  if (args.includes('--help') || args.includes('-h')) {
+    printSubcommandHelp(command);
+    return;
+  }
+
+  // Auth commands share a single module with multiple handlers — resolve
+  // directly without touching the registry.
+  if (AUTH_HANDLERS[command]) {
+    const mod = require('./commands/auth-cmds');
+    return mod[AUTH_HANDLERS[command]](args.slice(1));
+  }
+
+  // Hot path: canonical command name maps 1:1 to a file. Skip the full
+  // scan of ./commands/ — this shaves ~30 ms off startup for common calls
+  // (voxflow synthesize, voxflow podcast, ...).
+  let handler = fastResolveCommand(command);
+  let canonical = null;
+
+  if (!handler) {
+    // Slow path: alias or unknown command — need the full registry to
+    // resolve. Pays the discovery cost once, cached for the rest of the
+    // process lifetime.
+    const { COMMAND_MAP, ALIASES } = getRegistry();
+    const mod = COMMAND_MAP[command];
+    if (!mod) {
+      console.error(`Unknown command: ${command}\nRun voxflow --help for usage.`);
+      process.exit(1);
+    }
+    canonical = ALIASES[command] || null;
+    handler = canonical ? COMMAND_MAP[canonical] : mod;
+  }
+
+  await handler.handle(args.slice(1));
+
+  // Post-command feedback prompt (non-blocking, skip silently on error)
+  try {
+    const { promptFeedback } = require('./core/feedback');
+    await promptFeedback(canonical || command);
+  } catch { /* feedback is optional — never block the CLI */ }
+}
+
+// ─── Help ───────────────────────────────────────────────────────────────────
+
+/**
+ * Return the auto-discovered meta registry (see discoverCommands above).
+ * Alias entries are injected by each command's own `meta` object now —
+ * no more hardcoded list in this file (issue #2389).
+ */
+function getAllMeta() {
+  return { ...getRegistry().META };
+}
+
+function printHelp() {
+  const COMMANDS = getAllMeta();
+
+  const lines = [
+    `\nvoxflow v${pkg.version} — AI audio content creation CLI`,
+    '',
+    'Usage:',
+    '  voxflow <command> [options]',
+    '',
+    'Commands:',
+  ];
+
+  for (const [name, cmd] of Object.entries(COMMANDS)) {
+    if (cmd.alias) continue; // skip aliases in command list
+    const padded = (name + (cmd.usage ? ' ' + cmd.usage : '')).padEnd(18);
+    lines.push(`  ${padded} ${cmd.description}`);
+  }
+
+  lines.push('');
+  for (const [name, cmd] of Object.entries(COMMANDS)) {
+    if (cmd.alias || !cmd.options) continue;
+    const label = cmd.aliasOf ? `${name} options (alias: ${cmd.aliasOf}):` : `${name} options:`;
+    // Capitalize first letter
+    lines.push(label.charAt(0).toUpperCase() + label.slice(1));
+    lines.push(...cmd.options.map(o => '  ' + o));
+    lines.push('');
+  }
+
+  lines.push(
+    'Common options:',
+    '  --help, -h           Show help (use with a command for command-specific help)',
+    '  --version, -v        Show version',
+    '',
+    'Advanced options:',
+    '  --api <url>          Override API endpoint (for self-hosted servers)',
+    '  --token <jwt>        Use explicit token (CI/CD, skip browser login)',
+    '',
+    'Examples:',
+  );
+
+  for (const [, cmd] of Object.entries(COMMANDS)) {
+    if (cmd.alias || !cmd.examples) continue;
+    lines.push(...cmd.examples.map(e => '  ' + e));
+  }
+
+  console.log(lines.join('\n'));
+}
+
+/**
+ * Per-subcommand help — shows usage, options, and examples for a single command.
+ * Falls back to global help for unknown commands.
+ */
+function printSubcommandHelp(command) {
+  const COMMANDS = getAllMeta();
+  const cmd = COMMANDS[command];
+  if (!cmd) { printHelp(); return; }
+  // Resolve alias first, then check for options
+  const resolved = cmd.alias ? COMMANDS[cmd.alias] : cmd;
+  if (!resolved || !resolved.options) { printHelp(); return; }
+  const name = cmd.alias || command;
+
+  const lines = [
+    `\nvoxflow ${name} — ${resolved.description}`,
+    '',
+    'Usage:',
+    `  voxflow ${name}${resolved.usage ? ' ' + resolved.usage : ''}`,
+    '',
+    'Options:',
+    ...resolved.options.map(o => '  ' + o),
+    '  --api <url>          Override API endpoint',
+    '  --token <jwt>        Use explicit token (skip browser login)',
+  ];
+
+  if (resolved.examples && resolved.examples.length > 0) {
+    lines.push('', 'Examples:', ...resolved.examples.map(e => '  ' + e));
+  }
+
+  console.log(lines.join('\n'));
+}
+
+module.exports = { run };

package/lib/commands/_registry.js

@@ -0,0 +1,48 @@
+/**
+ * Static registry of canonical command modules.
+ *
+ * Required because cli/dist/index.js (the published artifact) is produced
+ * by `ncc build` which bundles every `require()` it can statically detect.
+ * The previous auto-discovery (PR #2465) used `fs.readdirSync` against
+ * `lib/commands/` — fine in dev (where the directory exists) but invariant
+ * post-bundle: ncc has no directory to read, so every command lookup blew
+ * up with `ENOENT: no such file or directory, scandir 'dist/commands'`.
+ * That's how voxflow@1.8.2 shipped to npm and made every subcommand fail.
+ *
+ * Each entry is a thunk so we keep the lazy-load behaviour the auto-
+ * discovery refactor was designed for — the command module is only
+ * required when its name is dispatched.
+ *
+ * Adding a new command:
+ *   1. Create lib/commands/<name>.js with a `meta` export
+ *   2. Add `<name>: () => require('./<name>'),` here
+ *   3. The `cli registry parity` test will fail until both match
+ */
+'use strict';
+
+module.exports = {
+  add: () => require('./add'),
+  asr: () => require('./asr'),
+  'asr-jobs': () => require('./asr-jobs'),
+  'auth-cmds': () => require('./auth-cmds'),
+  dub: () => require('./dub'),
+  explain: () => require('./explain'),
+  feedback: () => require('./feedback'),
+  image: () => require('./image'),
+  'mcp-key': () => require('./mcp-key'),
+  narrate: () => require('./narrate'),
+  picstory: () => require('./picstory'),
+  podcast: () => require('./podcast'),
+  present: () => require('./present'),
+  publish: () => require('./publish'),
+  skills: () => require('./skills'),
+  slice: () => require('./slice'),
+  slides: () => require('./slides'),
+  story: () => require('./story'),
+  summarize: () => require('./summarize'),
+  synthesize: () => require('./synthesize'),
+  translate: () => require('./translate'),
+  upgrade: () => require('./upgrade'),
+  'video-translate': () => require('./video-translate'),
+  voices: () => require('./voices'),
+};

package/lib/commands/add.js

@@ -0,0 +1,242 @@
+/**
+ * VoxFlow CLI — `voxflow add <name>`
+ *
+ * Pulls a flow / voice-recipe / preset from the configured registry into
+ * the local project. Day-1 MVP: no dependsOn cascading, no ETag cache,
+ * no private-registry token — those are RFC §3.2/§4.2/§4.3 territory and
+ * land in Phase 2.
+ *
+ * Resolution rule (per RFC §7.3):
+ *   - input "foo"        → ${defaultAuthor}/foo
+ *   - input "owner/foo"  → owner/foo
+ *
+ * Type → local folder:
+ *   - voxflow:flow         → flows/<name>/...
+ *   - voxflow:voice-recipe → recipes/<name>/...
+ *   - voxflow:preset       → presets/<name>/...
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const DEFAULT_REGISTRY = 'https://raw.githubusercontent.com/VoxFlowStudio/skills/main';
+const DEFAULT_AUTHOR = 'voxflow';
+
+const TYPE_TO_DIR = {
+  'voxflow:flow': 'flows',
+  'voxflow:voice-recipe': 'recipes',
+  'voxflow:preset': 'presets',
+};
+
+// ─── HTTP fetch (raw text, distinct from core/http.js which JSON.parses) ────
+
+function fetchText(url) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const mod = u.protocol === 'https:' ? https : http;
+    mod.get(u, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        // Follow one redirect (raw.githubusercontent.com sometimes does this)
+        if (res.headers.location) {
+          fetchText(res.headers.location).then(resolve, reject);
+          return;
+        }
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+        res.resume();
+        return;
+      }
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    }).on('error', (err) => reject(err));
+  });
+}
+
+// ─── Pure helpers (exported for tests) ──────────────────────────────────────
+
+function resolveItemName(input, defaultAuthor) {
+  if (input.includes('/')) {
+    const [author, name] = input.split('/', 2);
+    return { author, name, key: `${author}/${name}` };
+  }
+  return { author: defaultAuthor, name: input, key: `${defaultAuthor}/${input}` };
+}
+
+function localTargetForFile(item, filePath) {
+  // Registry path: <author>/<name>/<rest>  → strip prefix
+  const prefix = `${item.author}/${item.name}/`;
+  const rest = filePath.startsWith(prefix) ? filePath.slice(prefix.length) : filePath;
+  const baseDir = TYPE_TO_DIR[item.type] || 'voxflow-items';
+  return path.join(baseDir, item.name, rest);
+}
+
+function findItem(registry, author, name) {
+  return registry.items.find(
+    (it) => (it.author || DEFAULT_AUTHOR) === author && it.name === name
+  );
+}
+
+function suggestNearby(registry, name) {
+  const all = registry.items.map((it) => `${it.author || DEFAULT_AUTHOR}/${it.name}`);
+  // Naive substring suggestion — enough for human readable error
+  return all.filter((slug) => slug.includes(name) || name.includes(slug.split('/')[1])).slice(0, 5);
+}
+
+// ─── Main entry ─────────────────────────────────────────────────────────────
+
+async function add(opts) {
+  const {
+    name: rawName,
+    registry: registryUrl = DEFAULT_REGISTRY,
+    defaultAuthor = DEFAULT_AUTHOR,
+    targetRoot = process.cwd(),
+    force = false,
+    log = console.log,
+  } = opts;
+
+  if (!rawName) {
+    throw new Error(`add_missing_name: voxflow add <name> — see voxflow add --help`);
+  }
+
+  const { author, name, key } = resolveItemName(rawName, defaultAuthor);
+
+  // 1. Fetch registry index
+  log(`◆ Fetching registry index: ${registryUrl}/registry.json`);
+  let indexRaw;
+  try {
+    indexRaw = await fetchText(`${registryUrl}/registry.json`);
+  } catch (err) {
+    throw new Error(`registry_unreachable: ${err.message}\n  fix: check network or pass --registry <url>`);
+  }
+  let registry;
+  try {
+    registry = JSON.parse(indexRaw);
+  } catch (err) {
+    throw new Error(`registry_invalid_json: ${registryUrl}/registry.json\n  fix: check the registry repo is healthy`);
+  }
+  if (!registry || !Array.isArray(registry.items)) {
+    throw new Error(`registry_invalid_shape: missing items[] in registry.json`);
+  }
+
+  // 2. Locate item
+  const item = findItem(registry, author, name);
+  if (!item) {
+    const nearby = suggestNearby(registry, name);
+    const suggestion = nearby.length
+      ? `\n  did you mean: ${nearby.join(', ')}`
+      : `\n  fix: voxflow add --list  to see available items`;
+    throw new Error(`item_not_found: ${key}${suggestion}`);
+  }
+  if (!Array.isArray(item.files) || item.files.length === 0) {
+    throw new Error(`item_empty_files: ${key} declares no files in registry`);
+  }
+
+  // 3. Download each file
+  log(`◆ Resolving ${key} (${item.type}) v${item.version || 'unversioned'}`);
+  const written = [];
+  const skipped = [];
+  for (const filePath of item.files) {
+    const target = path.join(targetRoot, localTargetForFile(item, filePath));
+    if (fs.existsSync(target) && !force) {
+      skipped.push(target);
+      continue;
+    }
+    const fileUrl = `${registryUrl}/${filePath}`;
+    let body;
+    try {
+      body = await fetchText(fileUrl);
+    } catch (err) {
+      throw new Error(`file_fetch_failed: ${fileUrl}\n  ${err.message}`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, body);
+    written.push(target);
+  }
+
+  // 4. Print summary
+  log(`✓ Added ${key} (${item.type})${item.version ? ' v' + item.version : ''}`);
+  for (const w of written) {
+    log(`  ${path.relative(targetRoot, w)}`);
+  }
+  if (skipped.length) {
+    log(`\n  Skipped (use --force to overwrite):`);
+    for (const s of skipped) {
+      log(`    ${path.relative(targetRoot, s)}`);
+    }
+  }
+  if (item.tryWith) {
+    log(`\nTry it:\n  ${item.tryWith}`);
+  }
+
+  return { item, written, skipped };
+}
+
+// ─── CLI handle ─────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  // Sub-flags
+  const opts = {};
+  // First positional that isn't a flag → name
+  const flagless = args.filter((a, i) => {
+    if (a.startsWith('--')) return false;
+    if (i > 0 && args[i - 1].startsWith('--') && !args[i - 1].includes('=')) return false;
+    return true;
+  });
+  opts.name = flagless[0];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--registry' && args[i + 1]) opts.registry = args[++i];
+    else if (args[i] === '--default-author' && args[i + 1]) opts.defaultAuthor = args[++i];
+    else if (args[i] === '--force') opts.force = true;
+    else if (args[i] === '--list') opts.list = true;
+  }
+
+  // --list short-circuits before name validation
+  if (opts.list) {
+    const url = (opts.registry || DEFAULT_REGISTRY) + '/registry.json';
+    const indexRaw = await fetchText(url);
+    const registry = JSON.parse(indexRaw);
+    console.log(`Registry: ${registry.name} v${registry.version || 'unversioned'}\n`);
+    for (const it of registry.items) {
+      const slug = `${it.author || DEFAULT_AUTHOR}/${it.name}`;
+      console.log(`  ${slug.padEnd(36)} ${it.type.padEnd(22)} ${it.description || ''}`);
+    }
+    return;
+  }
+
+  await add(opts);
+}
+
+const meta = {
+  add: {
+    usage: '<name> [opts]',
+    description: 'Pull a flow / voice-recipe / preset from the registry into the current project',
+    options: [
+      `--registry <url>         Override registry URL (default: ${DEFAULT_REGISTRY})`,
+      `--default-author <name>  Resolve unscoped names against this author (default: ${DEFAULT_AUTHOR})`,
+      `--force                  Overwrite existing local files`,
+      `--list                   List all items in the registry`,
+    ],
+    examples: [
+      'voxflow add dub-anime-jp-zh',
+      'voxflow add chico/my-custom-recipe',
+      'voxflow add --list',
+      'voxflow add foo --registry https://example.com/voxflow-registry/main',
+    ],
+  },
+};
+
+module.exports = {
+  add,
+  handle,
+  meta,
+  // Exported for tests
+  _internal: { resolveItemName, localTargetForFile, findItem, suggestNearby },
+};