voxflow 1.15.0 → 1.15.2

package/lib/commands/skills.js

@@ -0,0 +1,473 @@
+'use strict';
+
+/**
+ * VoxFlow CLI — `skills` subcommand surface.
+ *
+ * Single-command installer for VoxFlow Skills across AI agents.
+ * Detects which agents are available locally and runs the right install
+ * command for each. Falls back to the universal `npx skills add ...`
+ * Skills-protocol installer when no specific agent is detected.
+ *
+ * Subcommands:
+ *   install [--for <agent>] [--all] [--dry-run] [-y]   Install skills
+ *   list                                               Show supported agents
+ *   detect                                             Show what's detected
+ */
+
+const { execFile, execFileSync } = require('child_process');
+const { promisify } = require('util');
+const readline = require('readline');
+const { getFreshTokenInfo } = require('../core/auth');
+const { detectAIAgent } = require('../core/agent-env');
+
+const execFileAsync = promisify(execFile);
+
+const SKILLS_NPM_TARGET = 'VoxFlowStudio/skills';
+const SKILL_LIST = ['hub', 'podcast', 'transcribe', 'video', 'slice'];
+
+// Universal install command — same for every agent. The `skills` npm package
+// detects which AI agents are present on the user's machine and installs the
+// skill files (or symlinks them, for Claude Code etc.) into the right
+// per-agent locations automatically. We do NOT need a per-agent install:
+//   - `claude skills add voxflow` does NOT exist (was wrong in earlier docs)
+//   - `npx skills add VoxFlowStudio/skills --skill voxflow` was wrong too —
+//     `--skill voxflow` is interpreted as "find a skill literally named
+//     voxflow", but our repo has 5 skills (hub / podcast / transcribe /
+//     video / slice), no skill called voxflow.
+//
+// Flags:
+//   --all     install every skill in the target repo (we ship all 5).
+//   --yes     auto-confirm target-agent prompts (non-interactive).
+//   --global  install to `~/.agents/skills/` instead of `./.agents/skills/`.
+//             Without this, the `skills` package writes to the current
+//             directory, so the install evaporates when the user `cd`s
+//             elsewhere — see 1.10.3 verify (skills landed in /tmp/...
+//             and were inaccessible from the user's normal cwd).
+const UNIVERSAL_INSTALL = Object.freeze([
+  'npx', Object.freeze(['-y', 'skills', 'add', SKILLS_NPM_TARGET, '--all', '--yes', '--global']),
+]);
+
+// Agent registry. Each entry must define:
+//   name        Human-readable display name
+//   binary      CLI binary used for detection (null = no auto-detection)
+//   install     [cmd, args[]] to install skills for this agent
+//   docs        URL to agent-specific docs / install page
+const AGENTS = {
+  claude: {
+    name: 'Claude Code',
+    binary: 'claude',
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://docs.anthropic.com/claude/docs/claude-code',
+  },
+  cursor: {
+    name: 'Cursor',
+    binary: 'cursor',
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://docs.cursor.com/',
+  },
+  codex: {
+    name: 'Codex CLI',
+    binary: 'codex',
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://github.com/openai/codex',
+  },
+  gemini: {
+    name: 'Gemini CLI',
+    binary: 'gemini',
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://github.com/google-gemini/gemini-cli',
+  },
+  workbuddy: {
+    name: 'WorkBuddy',
+    binary: 'workbuddy',
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://voxflow.studio/docs/skills',
+  },
+  openclaw: {
+    name: 'OpenClaw',
+    binary: 'openclaw',
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://voxflow.studio/docs/skills',
+  },
+  generic: {
+    name: 'Generic Skills-protocol agent',
+    binary: null,
+    install: UNIVERSAL_INSTALL,
+    docs: 'https://voxflow.studio/docs/skills',
+  },
+};
+
+const AUTO_DETECTABLE = Object.keys(AGENTS).filter((k) => AGENTS[k].binary);
+
+// ─── Detection ────────────────────────────────────────────────────────────
+
+function binaryExists(binary, _exec = execFileSync) {
+  if (!binary) return false;
+  try {
+    const which = process.platform === 'win32' ? 'where' : 'which';
+    _exec(which, [binary], { stdio: 'ignore', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectAgents(_exec = execFileSync) {
+  return AUTO_DETECTABLE
+    .filter((key) => binaryExists(AGENTS[key].binary, _exec))
+    .map((key) => ({ key, ...AGENTS[key] }));
+}
+
+// ─── Selection logic ──────────────────────────────────────────────────────
+
+/**
+ * Collapse the list of install targets so that any two whose install command
+ * is byte-identical run only once. With the current registry every entry uses
+ * the same UNIVERSAL_INSTALL tuple, so this folds N targets into 1 — the
+ * underlying `npx skills add` walks the user's machine and writes to every
+ * agent's standard location in a single invocation.
+ */
+function dedupeByInstallCommand(targets) {
+  const seen = new Map();
+  for (const t of targets) {
+    const key = `${t.install[0]} ${t.install[1].join(' ')}`;
+    if (!seen.has(key)) seen.set(key, t);
+  }
+  return Array.from(seen.values());
+}
+
+function chooseTargets(opts, detected) {
+  if (opts.for) {
+    const t = AGENTS[opts.for];
+    if (!t) {
+      const known = Object.keys(AGENTS).join(', ');
+      throw new Error(`Unknown agent "${opts.for}". Supported: ${known}`);
+    }
+    return [{ key: opts.for, ...t }];
+  }
+  // Default: list every detected agent. Since the underlying universal
+  // install writes to every agent's standard location in one shot, showing
+  // only the "first" detected agent (older behavior) was misleading — the
+  // user got skills installed for ALL detected agents but the UI suggested
+  // otherwise. `--all` is now the implicit default; the flag is kept as a
+  // no-op alias so existing scripts don't break.
+  if (detected.length === 0) return [{ key: 'generic', ...AGENTS.generic }];
+  return detected;
+}
+
+// ─── Args ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const opts = { for: null, all: false, dryRun: false, yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--for') { opts.for = argv[++i]; if (opts.for) opts.for = opts.for.toLowerCase(); }
+    else if (a === '--all') opts.all = true;
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '-y' || a === '--yes') opts.yes = true;
+  }
+  return opts;
+}
+
+// ─── Install execution ────────────────────────────────────────────────────
+
+async function runInstall(target, { dryRun }, _exec = execFileAsync) {
+  const [cmd, args] = target.install;
+  const printable = `${cmd} ${args.join(' ')}`;
+  if (dryRun) return { ok: true, dryRun: true, command: printable };
+  try {
+    const { stdout, stderr } = await _exec(cmd, args, { timeout: 180_000 });
+    return { ok: true, stdout, stderr, command: printable };
+  } catch (err) {
+    return { ok: false, error: err, command: printable };
+  }
+}
+
+// ─── User prompt ──────────────────────────────────────────────────────────
+
+function ask(question, _input = process.stdin, _output = process.stderr) {
+  return new Promise((resolve) => {
+    if (!_input.isTTY) { resolve(''); return; }
+    const rl = readline.createInterface({ input: _input, output: _output });
+    rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+
+// ─── Output helpers ───────────────────────────────────────────────────────
+
+function out(line) { process.stderr.write(line); }
+
+function printDetection(detected, allKeys = AUTO_DETECTABLE) {
+  out('  Detecting AI agents on this machine...\n');
+  for (const key of allKeys) {
+    const found = detected.some((d) => d.key === key);
+    const mark = found ? '✓' : '·';
+    const suffix = found ? '' : '  (not detected)';
+    out(`    ${mark} ${AGENTS[key].name}${suffix}\n`);
+  }
+  out('\n');
+}
+
+function printList() {
+  out('\n  Supported AI agents and install methods:\n\n');
+  for (const [key, info] of Object.entries(AGENTS)) {
+    const cmd = `${info.install[0]} ${info.install[1].join(' ')}`;
+    const auto = info.binary ? '[auto-detect]' : '[fallback]';
+    out(`    ${key.padEnd(11)} ${info.name.padEnd(35)} ${auto}\n`);
+    out(`                → ${cmd}\n`);
+  }
+  out('\n  Run `voxflow skills install` for auto-detection,\n');
+  out('  or `voxflow skills install --for <agent>` to force one,\n');
+  out('  or `voxflow skills install --all` to install for every detected agent.\n\n');
+}
+
+function printNextSteps(targets, hasFailures) {
+  out('\n  What you can do now:\n');
+  out('    1. Make sure CLI is logged in (only needed once):\n');
+  out('         voxflow login\n');
+  out('    2. Open your AI agent and try saying:\n');
+  out('         "把这段话合成语音"\n');
+  out('         "生成一个 3 分钟 AI 播客"\n');
+  out('         "把这个视频翻译成日语"\n');
+  if (hasFailures) {
+    out('\n  ⚠ Some installs failed. You can retry manually with:\n');
+    for (const t of targets) {
+      out(`         ${t.install[0]} ${t.install[1].join(' ')}\n`);
+    }
+  }
+  out('\n  Docs: https://voxflow.studio/docs/skills\n\n');
+}
+
+// ─── Pre-flight auth advice ───────────────────────────────────────────────
+//
+// The skill install commands themselves don't authenticate against VoxFlow —
+// they only place skill files where the agent can read them. But the user's
+// real goal is "install + use it"; we surface auth status here so they (or
+// the AI agent driving the install) don't discover the missing login at the
+// next `voxflow say` call.
+//
+// We check via getFreshTokenInfo() which transparently uses a cached refresh
+// token if available — so an expired access token but valid refresh token
+// shows up as "logged in" silently.
+
+async function preflightAuthAdvice() {
+  let info;
+  try {
+    info = await getFreshTokenInfo();
+  } catch {
+    info = null;
+  }
+
+  if (info && info.valid) {
+    out(`  ✓ Logged in as ${info.email}\n\n`);
+    return { loggedIn: true, info };
+  }
+
+  const agentName = detectAIAgent();
+  out('  ⚠ Not logged in to VoxFlow.\n');
+  out('    Skills will install successfully, but the first `voxflow say` /\n');
+  out('    `voxflow narrate` call will prompt for login.\n');
+  out('\n');
+  if (agentName) {
+    out(`    👤 USER ACTION (you are running inside ${agentName}):\n`);
+    out('       After this command, run `voxflow login` and finish the browser flow.\n');
+    out('       Or skip browser entirely: `export VOXFLOW_TOKEN=<jwt>` then re-run.\n');
+  } else {
+    out('    Run `voxflow login` separately to set up auth ahead of time.\n');
+  }
+  out('\n');
+  return { loggedIn: false };
+}
+
+// ─── Subcommand handlers ──────────────────────────────────────────────────
+
+async function handleInstall(args) {
+  const opts = parseArgs(args);
+  const detected = detectAgents();
+
+  out('\n  VoxFlow Skill Installer\n\n');
+  printDetection(detected);
+
+  let targets;
+  try {
+    targets = chooseTargets(opts, detected);
+  } catch (err) {
+    out(`  Error: ${err.message}\n\n`);
+    printList();
+    process.exit(1);
+  }
+
+  // Dedupe targets that share the same install command. Since `npx skills add`
+  // detects all agents present on the machine and writes to each in one shot,
+  // running it once covers everything — no need to repeat per agent.
+  const uniqueByCommand = dedupeByInstallCommand(targets);
+
+  out('  Will install for:\n');
+  for (const t of targets) {
+    out(`    → ${t.name}\n`);
+  }
+  out(`\n  Command: ${uniqueByCommand[0].install[0]} ${uniqueByCommand[0].install[1].join(' ')}\n`);
+  if (uniqueByCommand.length === 1) {
+    out('  (One command covers all detected agents — `npx skills add` writes\n');
+    out('   to each agent\'s standard location automatically.)\n');
+  }
+  out('\n');
+
+  // Pre-flight auth check. The install commands themselves don't need a token,
+  // but the user's intent is "install + use it"; if they're not logged in,
+  // signal that early so the AI agent (or human) can address it before the
+  // first actual `voxflow say` fails. Skipped on --dry-run since dry-run is
+  // explicitly read-only.
+  if (!opts.dryRun) {
+    await preflightAuthAdvice();
+  }
+
+  if (!opts.yes && !opts.dryRun && process.stdin.isTTY) {
+    const answer = (await ask('  Proceed? [Y/n] ')).toLowerCase();
+    if (answer && answer !== 'y' && answer !== 'yes') {
+      out('  Cancelled.\n\n');
+      return { ok: false, reason: 'user-cancelled' };
+    }
+    out('\n');
+  }
+
+  const results = [];
+  for (const t of uniqueByCommand) {
+    out(`  Installing...\n`);
+    out(`    $ ${t.install[0]} ${t.install[1].join(' ')}\n`);
+    const r = await runInstall(t, opts);
+    results.push({ target: t, result: r });
+    if (r.dryRun) out(`    (dry-run, nothing executed)\n`);
+    else if (r.ok) {
+      out(`    ✓ Installed: ${SKILL_LIST.join(', ')}\n`);
+      out(`      → ~/.agents/skills/  (linked into every detected agent's skill dir)\n`);
+    }
+    else {
+      out(`    ✗ Failed: ${r.error.message.split('\n')[0]}\n`);
+      if (r.error.stderr) {
+        const trimmed = r.error.stderr.toString().trim().split('\n').slice(-3).join('\n      ');
+        if (trimmed) out(`      ${trimmed}\n`);
+      }
+    }
+  }
+
+  const hasFailures = results.some((r) => !r.result.ok && !r.result.dryRun);
+  printNextSteps(targets, hasFailures);
+  if (hasFailures) process.exit(1);
+  return { ok: !hasFailures, results };
+}
+
+function handleList() {
+  printList();
+  return { ok: true };
+}
+
+function handleDetect() {
+  const detected = detectAgents();
+  out('\n');
+  printDetection(detected);
+  const cmd = `${UNIVERSAL_INSTALL[0]} ${UNIVERSAL_INSTALL[1].join(' ')}`;
+  if (detected.length === 0) {
+    out('  No AI agents auto-detected. You can still install via the universal\n');
+    out('  Skills-protocol installer (it will write to whatever standard agent\n');
+    out('  locations exist on this machine):\n\n');
+    out(`    ${cmd}\n\n`);
+  } else {
+    out(`  Run \`voxflow skills install\` to install for the detected agents,\n`);
+    out(`  or run the underlying command directly:\n\n    ${cmd}\n\n`);
+  }
+  return { ok: true, detected: detected.map((d) => d.key) };
+}
+
+// ─── Top-level dispatch ───────────────────────────────────────────────────
+
+const SUBCOMMANDS = ['install', 'list', 'detect'];
+
+async function handle(args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  if (!sub || sub === '-h' || sub === '--help') {
+    printHelp();
+    process.exit(sub ? 0 : 1);
+    return;
+  }
+
+  if (!SUBCOMMANDS.includes(sub)) {
+    out(`Error: unknown subcommand "${sub}". Use one of: ${SUBCOMMANDS.join(' | ')}\n`);
+    printHelp();
+    process.exit(1);
+    return;
+  }
+
+  if (sub === 'install') return handleInstall(rest);
+  if (sub === 'list') return handleList();
+  if (sub === 'detect') return handleDetect();
+}
+
+function printHelp() {
+  out(`
+Usage: voxflow skills <subcommand> [options]
+
+Subcommands:
+  install     Install VoxFlow Skills into your AI agent
+  list        Show all supported agents and their install commands
+  detect      Show which agents are detected on this machine
+
+Options for \`install\`:
+  --for <agent>     Target a specific agent (claude | cursor | codex | gemini |
+                    workbuddy | openclaw | generic)
+  --all             Install for every detected agent
+  --dry-run         Print commands without executing
+  -y, --yes         Skip confirmation prompt
+
+Examples:
+  voxflow skills install                    # auto-detect best target
+  voxflow skills install --for claude       # force Claude Code
+  voxflow skills install --all              # install for every detected agent
+  voxflow skills install --dry-run          # preview without running
+  voxflow skills detect                     # what's on this machine
+  voxflow skills list                       # all supported agents
+
+`);
+}
+
+const meta = {
+  skills: {
+    usage: '<install | list | detect> [options]',
+    description: 'Install VoxFlow Skills into your AI agent (Claude Code, Cursor, Codex, Gemini, WorkBuddy, OpenClaw, etc.)',
+    options: [
+      'install [--for <agent>]   Install skills (auto-detect or force one)',
+      'install --all             Install for every detected agent',
+      'install --dry-run         Print commands without executing',
+      'install -y                Skip confirmation prompt',
+      'list                      Show every supported agent + command',
+      'detect                    Show what is auto-detected on this machine',
+    ],
+    examples: [
+      'voxflow skills install',
+      'voxflow skills install --for claude',
+      'voxflow skills install --all',
+      'voxflow skills detect',
+      'voxflow skills list',
+    ],
+  },
+};
+
+module.exports = {
+  // public surface
+  handle,
+  meta,
+  // helpers for tests
+  AGENTS,
+  AUTO_DETECTABLE,
+  SKILL_LIST,
+  UNIVERSAL_INSTALL,
+  binaryExists,
+  detectAgents,
+  chooseTargets,
+  dedupeByInstallCommand,
+  parseArgs,
+  runInstall,
+  preflightAuthAdvice,
+};