voyageai-cli 1.26.1 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.26.1",
+  "version": "1.28.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

package/src/commands/config.js

@@ -67,6 +67,39 @@ function registerConfig(program) {
       const storedValue = key === 'default-dimensions' ? parseInt(value, 10) : value;
       setConfigValue(internalKey, storedValue);
       console.log(ui.success(`Set ${ui.cyan(key)} = ${SECRET_KEYS.has(internalKey) ? ui.dim(maskSecret(String(storedValue))) : storedValue}`));
+
+      // When setting an API key, auto-configure the matching base URL
+      if (internalKey === 'apiKey') {
+        const { identifyKey, ATLAS_API_BASE, VOYAGE_API_BASE } = require('../lib/api');
+        const keyInfo = identifyKey(storedValue);
+        const currentBase = getConfigValue('baseUrl');
+
+        if (keyInfo.type === 'atlas') {
+          if (currentBase !== ATLAS_API_BASE) {
+            setConfigValue('baseUrl', ATLAS_API_BASE);
+            console.log('');
+            console.log(ui.success(`Auto-configured base URL → ${ui.cyan(ATLAS_API_BASE)}`));
+          }
+          console.log('');
+          console.log(`  🔑 ${ui.bold('MongoDB Atlas key detected')} (al-*)`);
+          console.log(`     Endpoint: ${ui.cyan(ATLAS_API_BASE)}`);
+          console.log(`     Atlas provides Voyage AI models with Atlas-native billing.`);
+          console.log(`     All vai features work identically on both endpoints.`);
+        } else if (keyInfo.type === 'voyage') {
+          if (currentBase !== VOYAGE_API_BASE) {
+            setConfigValue('baseUrl', VOYAGE_API_BASE);
+            console.log('');
+            console.log(ui.success(`Auto-configured base URL → ${ui.cyan(VOYAGE_API_BASE)}`));
+          }
+          console.log('');
+          console.log(`  🔑 ${ui.bold('Voyage AI key detected')} (pa-*)`);
+          console.log(`     Endpoint: ${ui.cyan(VOYAGE_API_BASE)}`);
+        } else {
+          console.log('');
+          console.log(`  ⚠️  Unrecognized key prefix. Expected ${ui.cyan('al-*')} (Atlas) or ${ui.cyan('pa-*')} (Voyage AI).`);
+          console.log(`     Make sure your base URL matches: ${ui.cyan('vai config set base-url <url>')}`);
+        }
+      }
     });
 
   // ── config get [key] ──

package/src/commands/doctor.js

@@ -4,7 +4,7 @@ const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const pc = require('picocolors');
-const { getConfigValue } = require('../lib/config');
+const { getConfigValue, setConfigValue, CONFIG_DIR, CONFIG_PATH } = require('../lib/config');
 const { getApiBase } = require('../lib/api');
 
 /**
@@ -240,15 +240,83 @@ async function checkConfig() {
   };
 }
 
+// ── Fix functions (for --fix mode) ──
+
+async function fixApiKey() {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  return new Promise((resolve) => {
+    console.log(pc.cyan('\n  Fixing: Voyage AI API Key'));
+    console.log(pc.dim('  Get a key at: https://dash.voyageai.com/api-keys\n'));
+
+    rl.question('  Enter your Voyage AI API key: ', (key) => {
+      rl.close();
+      const trimmed = (key || '').trim();
+      if (!trimmed) {
+        console.log(pc.yellow('  Skipped (no key entered)'));
+        resolve(false);
+        return;
+      }
+      try {
+        setConfigValue('apiKey', trimmed);
+        // Also set in env for the current session so the connection check passes
+        process.env.VOYAGE_API_KEY = trimmed;
+        console.log(pc.green('  ✓ API key saved to ~/.vai/config.json'));
+        resolve(true);
+      } catch (err) {
+        console.log(pc.red(`  ✗ Failed to save: ${err.message}`));
+        resolve(false);
+      }
+    });
+  });
+}
+
+function fixConfigPermissions() {
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+    console.log(pc.green('  ✓ Fixed ~/.vai/config.json permissions to 600'));
+    return true;
+  } catch (err) {
+    console.log(pc.red(`  ✗ Failed to fix permissions: ${err.message}`));
+    return false;
+  }
+}
+
+function fixConfigDir() {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    console.log(pc.green('  ✓ Created ~/.vai/ directory'));
+    return true;
+  } catch (err) {
+    console.log(pc.red(`  ✗ Failed to create directory: ${err.message}`));
+    return false;
+  }
+}
+
+async function fixPdfParse() {
+  const { execSync } = require('child_process');
+  console.log(pc.cyan('\n  Installing pdf-parse...'));
+  try {
+    execSync('npm install pdf-parse', { stdio: 'pipe' });
+    console.log(pc.green('  ✓ pdf-parse installed'));
+    return true;
+  } catch (err) {
+    console.log(pc.red(`  ✗ Failed to install: ${err.message}`));
+    return false;
+  }
+}
+
 async function runDoctor(options = {}) {
-  const { json, verbose } = options;
-  
+  const { json, verbose, fix } = options;
+
   console.log(pc.bold('\n🩺 Voyage AI CLI Health Check\n'));
-  
+
   const results = {};
   let hasError = false;
   let hasWarning = false;
-  
+  const fixable = [];
+
   // Run all checks
   const checks = [
     { key: 'node', fn: checkNodeVersion },
@@ -258,12 +326,12 @@ async function runDoctor(options = {}) {
     { key: 'pdfParse', fn: checkPdfParse },
     { key: 'config', fn: checkConfig },
   ];
-  
+
   for (const { key, fn } of checks) {
     const check = CHECKS[key];
     const result = await fn();
     results[key] = result;
-    
+
     // Determine status icon
     let icon;
     if (result.ok === true) {
@@ -276,15 +344,23 @@ async function runDoctor(options = {}) {
       icon = warnMark();
       hasWarning = true;
     }
-    
+
     // Print result
     console.log(`  ${icon} ${pc.bold(check.name)}: ${result.message}`);
-    
+
     if (result.hint && (verbose || result.ok === false)) {
       console.log(`      ${pc.dim(result.hint)}`);
     }
+
+    // Track fixable issues
+    if (result.ok !== true) {
+      if (key === 'apiKey' && result.ok === false) fixable.push('apiKey');
+      if (key === 'pdfParse' && result.ok === null) fixable.push('pdfParse');
+      if (key === 'config' && result.message && result.message.includes('permissions')) fixable.push('configPerms');
+      if (key === 'config' && result.ok === null) fixable.push('configDir');
+    }
   }
-  
+
   // Summary
   console.log('');
   if (hasError) {
@@ -294,7 +370,43 @@ async function runDoctor(options = {}) {
   } else {
     console.log(pc.green('  ✓ All checks passed. vai is ready to use!\n'));
   }
-  
+
+  // --fix mode: attempt automatic repairs
+  if (fix && fixable.length > 0) {
+    console.log(pc.bold('  🔧 Attempting fixes...\n'));
+    let fixed = 0;
+
+    for (const item of fixable) {
+      if (item === 'configDir') {
+        if (fixConfigDir()) fixed++;
+      }
+      if (item === 'apiKey') {
+        if (await fixApiKey()) fixed++;
+      }
+      if (item === 'configPerms') {
+        if (fixConfigPermissions()) fixed++;
+      }
+      if (item === 'pdfParse') {
+        if (await fixPdfParse()) fixed++;
+      }
+    }
+
+    console.log('');
+    if (fixed > 0) {
+      console.log(pc.green(`  ✓ Fixed ${fixed} issue${fixed === 1 ? '' : 's'}. Run ${pc.bold('vai doctor')} again to verify.\n`));
+    } else {
+      console.log(pc.yellow('  No issues were fixed. See hints above for manual steps.\n'));
+    }
+    return 0;
+  } else if (fix && fixable.length === 0 && (hasError || hasWarning)) {
+    console.log(pc.dim('  No auto-fixable issues found. See hints above for manual steps.\n'));
+  }
+
+  // Suggest --fix if there are fixable issues and not in fix mode
+  if (!fix && fixable.length > 0) {
+    console.log(pc.dim(`  Tip: run ${pc.bold('vai doctor --fix')} to attempt automatic repairs\n`));
+  }
+
   // Suggest next steps
   if (!hasError) {
     console.log(pc.dim('  Next steps:'));
@@ -302,11 +414,11 @@ async function runDoctor(options = {}) {
     console.log(pc.dim('    vai quickstart  — Zero-to-search tutorial'));
     console.log(pc.dim('    vai explain     — Learn key concepts\n'));
   }
-  
+
   if (json) {
     console.log(JSON.stringify(results, null, 2));
   }
-  
+
   return hasError ? 1 : 0;
 }
 
@@ -316,10 +428,41 @@ function register(program) {
     .description('Run health checks on your vai setup')
     .option('--json', 'Output results as JSON')
     .option('-v, --verbose', 'Show hints for all checks')
+    .option('-f, --fix', 'Attempt to fix issues automatically')
     .action(async (options) => {
       const exitCode = await runDoctor(options);
       if (exitCode !== 0) process.exit(exitCode);
     });
 }
 
-module.exports = { register, runDoctor };
+/**
+ * Run all checks programmatically and return structured results.
+ * Used by the playground /api/doctor endpoint.
+ */
+async function runChecks() {
+  const checks = [
+    { key: 'node', fn: checkNodeVersion },
+    { key: 'apiKey', fn: checkApiKey },
+    { key: 'apiConnection', fn: checkApiConnection },
+    { key: 'mongodb', fn: checkMongoDB },
+    { key: 'pdfParse', fn: checkPdfParse },
+    { key: 'config', fn: checkConfig },
+  ];
+
+  const results = {};
+  for (const { key, fn } of checks) {
+    const result = await fn();
+    // Strip picocolors ANSI codes from messages for JSON output
+    const clean = (s) => typeof s === 'string' ? s.replace(/\x1b\[[0-9;]*m/g, '') : s;
+    results[key] = {
+      name: CHECKS[key].name,
+      required: CHECKS[key].required,
+      ok: result.ok,
+      message: clean(result.message),
+      hint: result.hint ? clean(result.hint) : null,
+    };
+  }
+  return results;
+}
+
+module.exports = { register, runDoctor, runChecks };

package/src/commands/mcp-server.js

@@ -14,6 +14,7 @@ function registerMcpServer(program) {
     .option('--host <address>', 'Bind address (http transport only)', '127.0.0.1')
     .option('--db <name>', 'Default MongoDB database for tools')
     .option('--collection <name>', 'Default collection for tools')
+    .option('--no-sse', 'Disable SSE transport (SSE is enabled by default for HTTP)')
     .option('--verbose', 'Enable debug logging to stderr')
     .action(async (opts) => {
       if (opts.verbose) {
@@ -27,7 +28,9 @@ function registerMcpServer(program) {
       const { runStdioServer, runHttpServer } = require('../mcp/server');
 
       if (opts.transport === 'http') {
-        await runHttpServer({ port: opts.port, host: opts.host });
+        // SSE is enabled by default for HTTP transport (required for n8n, etc.)
+        // Use --no-sse to disable if needed
+        await runHttpServer({ port: opts.port, host: opts.host, sse: opts.sse !== false });
       } else if (opts.transport === 'stdio') {
         await runStdioServer();
       } else {

package/src/commands/playground.js

@@ -14,13 +14,16 @@ function registerPlayground(program) {
     .command('playground')
     .description('Launch interactive web playground for Voyage AI')
     .option('-p, --port <port>', 'Port to serve on', '3333')
+    .option('--host <address>', 'Bind address', '127.0.0.1')
     .option('--no-open', 'Skip auto-opening browser')
     .action(async (opts) => {
       const port = parseInt(opts.port, 10) || 3333;
+      const host = opts.host || '127.0.0.1';
       const server = createPlaygroundServer();
 
-      server.listen(port, () => {
-        const url = `http://localhost:${port}`;
+      server.listen(port, host, () => {
+        const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+        const url = `http://${displayHost}:${port}`;
         console.log(`🧭 Playground running at ${url} — Press Ctrl+C to stop`);
 
         if (opts.open !== false) {
@@ -309,6 +312,20 @@ function createPlaygroundServer() {
         return;
       }
 
+      // API: Doctor health checks
+      if (req.method === 'GET' && req.url === '/api/doctor') {
+        try {
+          const { runChecks } = require('./doctor');
+          const results = await runChecks();
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(results));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return;
+      }
+
       // API: Settings origins — where each config value comes from
       if (req.method === 'GET' && req.url === '/api/settings/origins') {
         const { resolveLLMConfig } = require('../lib/llm');
@@ -338,6 +355,54 @@ function createPlaygroundServer() {
         return;
       }
 
+      // API: List built-in workflows
+      if (req.method === 'GET' && req.url === '/api/workflows') {
+        try {
+          const { listBuiltinWorkflows } = require('../lib/workflow');
+          const workflows = listBuiltinWorkflows();
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ workflows }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return;
+      }
+
+      // API: List example workflows (must be before the :name route)
+      if (req.method === 'GET' && req.url === '/api/workflows/examples') {
+        try {
+          const { listExampleWorkflows } = require('../lib/workflow');
+          const examples = listExampleWorkflows();
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ examples }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return;
+      }
+
+      // API: Get a specific workflow by name
+      if (req.method === 'GET' && req.url?.startsWith('/api/workflows/')) {
+        const name = decodeURIComponent(req.url.replace('/api/workflows/', ''));
+        if (!name) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Workflow name is required' }));
+          return;
+        }
+        try {
+          const { loadWorkflow } = require('../lib/workflow');
+          const definition = loadWorkflow(name);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ definition }));
+        } catch (err) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return;
+      }
+
       // API: Save chat config (POST) — persists to .vai.json
       // Placed before generic POST handler so it doesn't require Voyage API key
       if (req.method === 'POST' && req.url === '/api/chat/config') {
@@ -459,8 +524,37 @@ function createPlaygroundServer() {
                 opts: { systemPrompt, db: db || undefined, collection: collection || undefined },
               })) {
                 if (event.type === 'tool_call') {
-                  const { name, args, timeMs, error } = event.data;
-                  res.write(`event: tool_call\ndata: ${JSON.stringify({ name, args, timeMs, error })}\n\n`);
+                  const { name, args, timeMs, error, result } = event.data;
+                  // Build a short human-readable summary of the tool result
+                  let resultSummary = '';
+                  if (!error && result) {
+                    if (name === 'vai_query' || name === 'vai_search') {
+                      const docs = result.results || result.documents || [];
+                      resultSummary = `Found ${docs.length} result${docs.length !== 1 ? 's' : ''}`;
+                    } else if (name === 'vai_collections') {
+                      const colls = result.collections || [];
+                      resultSummary = colls.length > 0
+                        ? colls.map(c => `<code>${c.name || c}</code>`).slice(0, 5).join(', ')
+                        : 'No collections found';
+                    } else if (name === 'vai_models') {
+                      const models = result.models || [];
+                      resultSummary = `${models.length} model${models.length !== 1 ? 's' : ''} available`;
+                    } else if (name === 'vai_embed') {
+                      const dims = result.dimensions || result.embedding?.length || '?';
+                      resultSummary = `${dims}-dim vector`;
+                    } else if (name === 'vai_similarity') {
+                      const score = result.similarity ?? result.score;
+                      resultSummary = score !== undefined ? `Score: ${Number(score).toFixed(4)}` : '';
+                    } else if (name === 'vai_rerank') {
+                      const items = result.results || [];
+                      resultSummary = `Reranked ${items.length} result${items.length !== 1 ? 's' : ''}`;
+                    } else if (name === 'vai_estimate') {
+                      resultSummary = result.recommendation || '';
+                    } else if (name === 'vai_explain' || name === 'vai_topics') {
+                      resultSummary = result.title || result.topic || '';
+                    }
+                  }
+                  res.write(`event: tool_call\ndata: ${JSON.stringify({ name, args, timeMs, error, resultSummary })}\n\n`);
                 } else if (event.type === 'chunk') {
                   res.write(`event: chunk\ndata: ${JSON.stringify({ text: event.data })}\n\n`);
                 } else if (event.type === 'done') {
@@ -645,6 +739,120 @@ function createPlaygroundServer() {
           }));
           return;
         }
+
+        // API: Validate a workflow definition
+        if (req.url === '/api/workflows/validate') {
+          const { validateWorkflow } = require('../lib/workflow');
+          const { definition } = parsed;
+          if (!definition) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'definition is required' }));
+            return;
+          }
+          const errors = validateWorkflow(definition);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ valid: errors.length === 0, errors }));
+          return;
+        }
+
+        // API: Get execution plan (layers + dependency graph)
+        if (req.url === '/api/workflows/plan') {
+          const { buildExecutionPlan, buildDependencyGraph, validateWorkflow } = require('../lib/workflow');
+          const { definition } = parsed;
+          if (!definition || !definition.steps) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'definition with steps is required' }));
+            return;
+          }
+          const errors = validateWorkflow(definition);
+          if (errors.length > 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid workflow', errors }));
+            return;
+          }
+          const layers = buildExecutionPlan(definition.steps);
+          const graphMap = buildDependencyGraph(definition.steps);
+          // Convert Map<string, Set<string>> to plain object for JSON serialization
+          const graph = {};
+          for (const [stepId, deps] of graphMap) {
+            graph[stepId] = Array.from(deps);
+          }
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ layers, graph }));
+          return;
+        }
+
+        // API: Execute a workflow (streaming SSE)
+        if (req.url === '/api/workflows/execute') {
+          const { executeWorkflow, validateWorkflow: validateWf } = require('../lib/workflow');
+          const { definition, inputs } = parsed;
+          if (!definition) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'definition is required' }));
+            return;
+          }
+          const errors = validateWf(definition);
+          if (errors.length > 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid workflow', errors }));
+            return;
+          }
+
+          // Stream execution events as SSE
+          res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+          });
+
+          try {
+            const result = await executeWorkflow(definition, {
+              inputs: inputs || {},
+              onStepStart: (stepId, stepDef) => {
+                res.write(`event: step_start\ndata: ${JSON.stringify({
+                  stepId,
+                  name: stepDef.name || stepId,
+                  tool: stepDef.tool,
+                })}\n\n`);
+              },
+              onStepComplete: (stepId, output, timeMs) => {
+                // Summarize output to avoid huge payloads
+                let summary = '';
+                if (output && typeof output === 'object') {
+                  if (output.results) summary = `${output.results.length} results`;
+                  else if (output.similarity !== undefined) summary = `similarity: ${Number(output.similarity).toFixed(4)}`;
+                  else if (output.text) summary = output.text.slice(0, 100) + (output.text.length > 100 ? '...' : '');
+                  else summary = JSON.stringify(output).slice(0, 200);
+                }
+                res.write(`event: step_complete\ndata: ${JSON.stringify({
+                  stepId, timeMs, summary,
+                  output: JSON.stringify(output).length < 5000 ? output : { _truncated: true, summary },
+                })}\n\n`);
+              },
+              onStepSkip: (stepId, reason) => {
+                res.write(`event: step_skip\ndata: ${JSON.stringify({ stepId, reason })}\n\n`);
+              },
+              onStepError: (stepId, error) => {
+                res.write(`event: step_error\ndata: ${JSON.stringify({
+                  stepId,
+                  error: error.message || String(error),
+                })}\n\n`);
+              },
+            });
+
+            res.write(`event: done\ndata: ${JSON.stringify({
+              output: result.output,
+              totalTimeMs: result.totalTimeMs,
+              layers: result.layers,
+              steps: result.steps,
+            })}\n\n`);
+          } catch (err) {
+            res.write(`event: error\ndata: ${JSON.stringify({ error: err.message })}\n\n`);
+          }
+
+          res.end();
+          return;
+        }
       }
 
       // 404

package/src/commands/workflow.js

@@ -22,6 +22,45 @@ function collectInputs(pair, prev) {
   return prev;
 }
 
+/**
+ * Interactively prompt the user for missing workflow inputs using @clack/prompts.
+ * Only prompts for inputs not already provided via --input flags.
+ *
+ * @param {object} definition - Workflow definition
+ * @param {object} existingInputs - Inputs already provided via --input
+ * @returns {Promise<object>} Merged inputs (existing + prompted)
+ */
+async function promptForInputs(definition, existingInputs) {
+  const { buildInputSteps } = require('../lib/workflow');
+  const { createCLIRenderer } = require('../lib/wizard-cli');
+  const { runWizard } = require('../lib/wizard');
+
+  const allSteps = buildInputSteps(definition);
+  // Only prompt for inputs not already provided
+  const steps = allSteps.filter(s => !(s.id in existingInputs));
+  if (steps.length === 0) return existingInputs;
+
+  const renderer = createCLIRenderer({
+    title: `${definition.name || 'Workflow'} inputs`,
+    doneMessage: 'Inputs ready.',
+    showBackHint: true,
+  });
+
+  const { answers, cancelled } = await runWizard({
+    steps,
+    config: {},
+    renderer,
+    initial: {},
+  });
+
+  if (cancelled) {
+    console.log(pc.dim('Cancelled.'));
+    process.exit(0);
+  }
+
+  return { ...existingInputs, ...answers };
+}
+
 /**
  * Register the workflow command on a Commander program.
  * @param {import('commander').Command} program
@@ -43,6 +82,7 @@ function registerWorkflow(program) {
     .option('--quiet', 'Suppress progress output', false)
     .option('--dry-run', 'Show execution plan without running', false)
     .option('--verbose', 'Show step details', false)
+    .option('--no-interactive', 'Disable interactive input prompting')
     .action(async (file, opts) => {
       const { loadWorkflow, executeWorkflow, buildExecutionPlan, validateWorkflow } = require('../lib/workflow');
 
@@ -64,6 +104,11 @@ function registerWorkflow(program) {
 
       const workflowName = definition.name || file;
 
+      // Interactive prompting for missing inputs
+      if (opts.interactive !== false && process.stdin.isTTY) {
+        opts.input = await promptForInputs(definition, opts.input);
+      }
+
       if (opts.dryRun) {
         // Dry run: show plan
         const layers = buildExecutionPlan(definition.steps);