voxflow 1.14.0 → 1.15.1

package/lib/commands/voices.js

@@ -0,0 +1,292 @@
+/**
+ * VoxFlow CLI — Voices command
+ *
+ * Browse and filter available TTS voices. By default queries the public catalog
+ * (no auth). `--mine` switches to the authenticated `/api/voice/list` endpoint
+ * to show the signed-in user's cloned voices.
+ */
+
+const { request, throwNetworkError, throwApiError, ApiError } = require('../core/http');
+
+/**
+ * Fetch and display available TTS voices.
+ *
+ * @param {object} opts
+ * @param {string} opts.api          - API base URL
+ * @param {string} [opts.search]     - Search query (matches name, tone, style, scenarios)
+ * @param {string} [opts.gender]     - Filter by gender: male/m/female/f
+ * @param {string} [opts.language]   - Filter by language code: zh, en, etc.
+ * @param {boolean} [opts.json]      - Output raw JSON
+ * @param {boolean} [opts.extended]  - Include extended voice library
+ * @param {boolean} [opts.mine]      - List the signed-in user's cloned voices
+ * @param {string}  [opts.token]     - Bearer token (required when mine=true)
+ */
+async function voices(opts) {
+  const api = opts.api;
+
+  if (opts.mine) {
+    return listMyClonedVoices(opts);
+  }
+
+  const includeExtended = opts.extended ? 'true' : 'false';
+
+  // Fetch voices (public endpoint, no auth)
+  let status, data;
+  try {
+    ({ status, data } = await request(
+      `${api}/api/tts/voices?includeExtended=${includeExtended}`,
+      { method: 'GET' }
+    ));
+  } catch (err) {
+    throwNetworkError(err, api);
+  }
+
+  if (status !== 200) {
+    throw new Error(`Failed to fetch voices (${status}): ${data?.message || 'unknown error'}`);
+  }
+
+  // Public endpoint returns { voices: [...] } directly (no code wrapper)
+  let voiceList = data.voices || data.data?.voices || [];
+
+  // Apply filters
+  if (opts.gender) {
+    const normalized = normalizeGender(opts.gender);
+    if (!normalized) {
+      throw new Error(`--gender must be one of: male, m, female, f (got: "${opts.gender}")`);
+    }
+    voiceList = voiceList.filter((v) => {
+      const vGender = (v.gender || '').toLowerCase();
+      return vGender === normalized;
+    });
+  }
+
+  if (opts.language) {
+    const lang = opts.language.toLowerCase();
+    voiceList = voiceList.filter((v) => (v.language || '').toLowerCase() === lang);
+  }
+
+  if (opts.search) {
+    const query = opts.search.toLowerCase();
+    voiceList = voiceList.filter((v) => {
+      const searchable = [
+        v.name, v.nameEn, v.tone, v.style,
+        v.description, v.scenarios,
+      ].filter(Boolean).join(' ').toLowerCase();
+      return searchable.includes(query);
+    });
+  }
+
+  if (opts.useCase) {
+    const tag = opts.useCase.toLowerCase();
+    voiceList = voiceList.filter((v) => Array.isArray(v.recommendedFor) && v.recommendedFor.map(String).map(s => s.toLowerCase()).includes(tag));
+  }
+
+  // Output
+  if (voiceList.length === 0) {
+    console.log('No voices match your criteria.');
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(voiceList, null, 2));
+  } else {
+    printTable(voiceList);
+  }
+
+  console.log(`\nFound ${voiceList.length} voice${voiceList.length === 1 ? '' : 's'}.`);
+}
+
+/**
+ * Fetch and print the user's cloned voices via the authenticated endpoint.
+ */
+async function listMyClonedVoices(opts) {
+  const { api, token } = opts;
+  if (!token) {
+    throw new ApiError('Not authenticated — run `voxflow login` first.', 'token_missing', 401);
+  }
+
+  let status, data;
+  try {
+    ({ status, data } = await request(
+      `${api}/api/voice/list`,
+      { method: 'GET', headers: { Authorization: `Bearer ${token}` } }
+    ));
+  } catch (err) {
+    throwNetworkError(err, api);
+  }
+
+  if (status === 401) {
+    throwApiError(401, data, 'voices --mine');
+  }
+
+  if (status !== 200 || data?.code !== 'success') {
+    throw new Error(`Failed to fetch cloned voices (${status}): ${data?.message || 'unknown error'}`);
+  }
+
+  const list = (data.voices || []).map((v) => ({
+    id: v.voice_id,
+    name: v.voice_name || '(unnamed)',
+    language: v.language || '',
+    gender: v.gender || '',
+    durationSec: v.audio_duration ? Number(v.audio_duration).toFixed(1) : '',
+    createdAt: v.created_at ? v.created_at.replace('T', ' ').slice(0, 19) : '',
+    usageCount: v.usage_count || 0,
+    model: v.model || '',
+  }));
+
+  if (list.length === 0) {
+    console.log('No cloned voices yet. Create one with:');
+    console.log('  voxflow clone --input recording.wav --name "My Voice"');
+    console.log(`Used 0/${data.limit ?? '?'} clone slots.`);
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(list, null, 2));
+  } else {
+    printMineTable(list);
+    console.log(`\nUsed ${data.used ?? list.length}/${data.limit ?? '?'} clone slots.`);
+    console.log('Use a voice: voxflow say "..." --voice <id>');
+  }
+}
+
+/**
+ * Normalize gender input to lowercase standard form.
+ * @returns {'male'|'female'|null}
+ */
+function normalizeGender(input) {
+  const g = (input || '').toLowerCase().trim();
+  if (g === 'male' || g === 'm') return 'male';
+  if (g === 'female' || g === 'f') return 'female';
+  return null;
+}
+
+/**
+ * Print voices as a formatted table.
+ */
+function printTable(voiceList) {
+  // Column widths
+  const colPick = 2;
+  const colId = 24;
+  const colName = 14;
+  const colGender = 8;
+  const colTone = 22;
+  const colStyle = 20;
+
+  // Header — ★ marks editorial-curated podcast picks (recommendedFor:['podcast'])
+  const header = [
+    '★'.padEnd(colPick),
+    'ID'.padEnd(colId),
+    'Name'.padEnd(colName),
+    'Gender'.padEnd(colGender),
+    'Tone'.padEnd(colTone),
+    'Style'.padEnd(colStyle),
+  ].join('  ');
+
+  console.log(`\n${header}`);
+  console.log('-'.repeat(header.length));
+
+  // Rows
+  for (const v of voiceList) {
+    const isPodcast = Array.isArray(v.recommendedFor) && v.recommendedFor.includes('podcast');
+    const row = [
+      (isPodcast ? '★' : ' ').padEnd(colPick),
+      truncate(v.id || '', colId).padEnd(colId),
+      truncate(v.name || '', colName).padEnd(colName),
+      truncate(v.gender || '', colGender).padEnd(colGender),
+      truncate(v.tone || '', colTone).padEnd(colTone),
+      truncate(v.style || '', colStyle).padEnd(colStyle),
+    ].join('  ');
+    console.log(row);
+  }
+}
+
+function printMineTable(voiceList) {
+  const colId = 40;
+  const colName = 18;
+  const colDur = 7;
+  const colCreated = 19;
+
+  const header = [
+    'ID'.padEnd(colId),
+    'Name'.padEnd(colName),
+    'Sec'.padEnd(colDur),
+    'Created'.padEnd(colCreated),
+  ].join('  ');
+
+  console.log(`\n${header}`);
+  console.log('-'.repeat(header.length));
+
+  for (const v of voiceList) {
+    const row = [
+      truncate(v.id, colId).padEnd(colId),
+      truncate(v.name, colName).padEnd(colName),
+      String(v.durationSec).padEnd(colDur),
+      truncate(v.createdAt, colCreated).padEnd(colCreated),
+    ].join('  ');
+    console.log(row);
+  }
+}
+
+/**
+ * Truncate a string to max length, adding ellipsis if needed.
+ */
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + '…';
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseBoolFlag, runWithRetry } = require('../core/args');
+  const { API_BASE } = require('../core/config');
+  const { getToken } = require('../core/auth');
+
+  const api = parseFlag(args, '--api') || API_BASE;
+  const explicitToken = parseFlag(args, '--token');
+
+  const opts = {
+    api,
+    search: parseFlag(args, '--search'),
+    gender: parseFlag(args, '--gender'),
+    language: parseFlag(args, '--language'),
+    useCase: parseFlag(args, '--use-case'),
+    json: parseBoolFlag(args, '--json'),
+    extended: parseBoolFlag(args, '--extended'),
+    mine: parseBoolFlag(args, '--mine'),
+  };
+
+  if (opts.mine) {
+    opts.token = explicitToken || await getToken({ api });
+    await runWithRetry(voices, opts, api, explicitToken);
+    return;
+  }
+
+  // Public catalog — no auth, no retry
+  await voices(opts);
+}
+
+const meta = {
+  voices: {
+    usage: '[opts]',
+    description: 'Browse and search available TTS voices (use --mine for your cloned voices)',
+    options: [
+      `--mine               List your cloned voices (requires login)`,
+      `--search <query>     Search by name, tone, style, description`,
+      `--gender <m|f>       Filter by gender: male/m or female/f`,
+      `--language <code>    Filter by language: zh, en, etc.`,
+      `--use-case <tag>     Filter by editorial-curated use case (e.g. podcast)`,
+      `--extended           Include extended voice library (380+ voices)`,
+      `--json               Output raw JSON instead of table`,
+    ],
+    examples: [
+      'voxflow voices --mine                # list my cloned voices',
+      'voxflow voices --search "温柔" --gender female',
+      'voxflow voices --use-case podcast    # editorial podcast picks',
+      'voxflow voices --extended --json',
+    ],
+  },
+};
+
+module.exports = { voices, handle, meta };

package/lib/core/agent-env.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * AI agent environment detection.
+ *
+ * The CLI may be invoked directly by a human in a terminal, OR delegated by
+ * an AI agent (Claude Code / Cursor / Codex / Gemini CLI / WorkBuddy / OpenClaw).
+ * Auth, prompts, and timeouts behave differently in each case:
+ *   - Human:  open browser, 3-minute timeout, single-line "🔐 Login required" notice
+ *   - Agent:  print a structured USER-ACTION panel that the agent can clearly
+ *             relay to the user, longer 10-minute timeout, do not assume the
+ *             browser auto-open will land on the user's machine.
+ *
+ * Detection is environment-variable driven. Each agent sets at least one of
+ * these markers when it spawns subprocesses; they're stable enough to rely on.
+ */
+
+const env = process.env;
+
+/**
+ * Detect whether we're running inside a known AI agent. Returns the agent's
+ * display name, or null when running directly in a terminal.
+ *
+ * Order matters: more specific markers are checked first so a single-purpose
+ * env var wins over a more generic terminal hint.
+ */
+function detectAIAgent(_env = env) {
+  if (_env.CLAUDECODE) return 'Claude Code';
+  if (_env.CURSOR_AGENT || _env.CURSOR_TRACE_ID) return 'Cursor';
+  if (_env.CODEX_SANDBOX || _env.CODEX_AGENT || _env.OPENAI_CODEX) return 'Codex';
+  if (_env.GEMINI_CLI || _env.GEMINI_AGENT) return 'Gemini CLI';
+  if (_env.WORKBUDDY || _env.WORKBUDDY_AGENT) return 'WorkBuddy';
+  if (_env.OPENCLAW || _env.OPENCLAW_AGENT) return 'OpenClaw';
+
+  // Generic AI-agent hint — when an agent doesn't set its own marker but
+  // does export a generic AI flag.
+  if (_env.AI_AGENT) return _env.AI_AGENT;
+
+  return null;
+}
+
+/**
+ * True when running in any AI-agent context. Convenience wrapper.
+ */
+function isAIAgent(_env = env) {
+  return detectAIAgent(_env) !== null;
+}
+
+/**
+ * Build a structured "USER ACTION REQUIRED" panel for the given login URL.
+ * The panel is designed to stand out in agent transcripts — agents can quote
+ * it verbatim and the user immediately sees what they need to do.
+ *
+ * @param {object} opts
+ * @param {string} opts.loginUrl   The URL the user should open
+ * @param {string} [opts.agentName] Display name from detectAIAgent()
+ * @param {number} [opts.timeoutSec] Timeout in seconds (default 600)
+ * @param {string} [opts.userCode]  Optional pairing code displayed prominently
+ * @returns {string}
+ */
+function buildUserActionPanel({ loginUrl, agentName, timeoutSec = 600, userCode }) {
+  const min = Math.round(timeoutSec / 60);
+  const heading = agentName
+    ? `USER ACTION REQUIRED  (you are running inside ${agentName})`
+    : `USER ACTION REQUIRED`;
+
+  const lines = [
+    '',
+    '╔══════════════════════════════════════════════════════════════════╗',
+    `║  👤 ${heading.padEnd(60)} ║`,
+    '╠══════════════════════════════════════════════════════════════════╣',
+    '║  1. Open this URL in your browser to authorize voxflow CLI:                ║',
+    '║                                                                                          ║',
+    `║     ${loginUrl}`,
+    '║                                                                                          ║',
+  ];
+
+  if (userCode) {
+    lines.push(
+      `║     Pairing code (verify it matches the page): ${userCode}`,
+      '║                                                                                          ║',
+    );
+  }
+
+  lines.push(
+    `║  2. After login, this command will continue automatically (waiting ${String(min).padStart(2)} min). ║`,
+    '║                                                                                          ║',
+    '║  Skip this entirely:                                                                     ║',
+    '║     export VOXFLOW_TOKEN=<your-jwt>   # then re-run                                      ║',
+    '║                                                                                          ║',
+    '║  Already logged in but stuck?                                                            ║',
+    '║     rm ~/.config/voxflow/token.json   # then re-run `voxflow login`                      ║',
+    '╚══════════════════════════════════════════════════════════════════╝',
+    '',
+  );
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  detectAIAgent,
+  isAIAgent,
+  buildUserActionPanel,
+};

package/lib/core/args.js

@@ -0,0 +1,107 @@
+/**
+ * VoxFlow CLI — Argument parsing & validation utilities
+ *
+ * Shared helpers extracted from cli.js for use by all command handlers.
+ */
+
+const { getToken } = require('./auth');
+const { ApiError } = require('./http');
+
+// ─── Arg Parsing ────────────────────────────────────────────────────────────
+
+function parseFlag(args, ...flags) {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  }
+  return null;
+}
+
+function parseIntFlag(args, ...flags) {
+  const val = parseFlag(args, ...flags);
+  return val != null ? parseInt(val, 10) : undefined;
+}
+
+function parseFloatFlag(args, ...flags) {
+  const val = parseFlag(args, ...flags);
+  return val != null ? parseFloat(val) : undefined;
+}
+
+function parseBoolFlag(args, ...flags) {
+  return flags.some((f) => args.includes(f));
+}
+
+// ─── Validation Helpers ─────────────────────────────────────────────────────
+
+function validateSpeed(args, speed) {
+  if (speed !== undefined) {
+    if (isNaN(speed) || speed < 0.5 || speed > 2.0) {
+      console.error(`Error: --speed must be between 0.5 and 2.0 (got: "${parseFlag(args, '--speed')}")`);
+      process.exit(1);
+    }
+  }
+}
+
+function validateSilence(args, silence) {
+  if (silence !== undefined) {
+    if (isNaN(silence) || silence < 0 || silence > 5.0) {
+      console.error(`Error: --silence must be between 0 and 5.0 (got: "${parseFlag(args, '--silence')}")`);
+      process.exit(1);
+    }
+  }
+}
+
+function validateOutput(output, _format) {
+  if (output) {
+    const validExts = ['.wav', '.mp3'];
+    const hasValidExt = validExts.some(ext => output.toLowerCase().endsWith(ext));
+    if (!hasValidExt) {
+      console.error('Error: --output path must end with .wav or .mp3');
+      process.exit(1);
+    }
+  }
+}
+
+function validateFormat(format) {
+  if (format && !['pcm', 'wav', 'mp3'].includes(format)) {
+    console.error(`Error: --format must be one of: pcm, wav, mp3 (got: "${format}")`);
+    process.exit(1);
+  }
+}
+
+function assertFileExists(filePath, label) {
+  const resolved = require('path').resolve(filePath);
+  if (!require('fs').existsSync(resolved)) {
+    console.error(`Error: ${label} file not found: ${resolved}`);
+    process.exit(1);
+  }
+}
+
+// ─── Retry with token refresh ───────────────────────────────────────────────
+
+async function runWithRetry(fn, opts, api, explicitToken) {
+  try {
+    return await fn(opts);
+  } catch (err) {
+    if (err instanceof ApiError && err.code === 'token_expired' && !explicitToken) {
+      console.log('\nToken expired, refreshing...');
+      opts.token = await getToken({ api, refresh: true });
+      return await fn(opts);
+    } else {
+      throw err;
+    }
+  }
+}
+
+module.exports = {
+  parseFlag,
+  parseIntFlag,
+  parseFloatFlag,
+  parseBoolFlag,
+  validateSpeed,
+  validateSilence,
+  validateOutput,
+  validateFormat,
+  assertFileExists,
+  runWithRetry,
+};