voyageai-cli 1.26.0 → 1.27.0

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/playground.js

@@ -277,6 +277,7 @@ function createPlaygroundServer() {
           db: proj.db || null,
           collection: proj.collection || null,
           chat: proj.chat || {},
+          mode: proj.chat?.mode || 'pipeline',
         }));
         return;
       }
@@ -308,6 +309,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');
@@ -337,6 +352,40 @@ 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: 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') {
@@ -364,6 +413,7 @@ function createPlaygroundServer() {
         if (parsed.maxDocs !== undefined) proj.chat.maxContextDocs = parsed.maxDocs;
         if (parsed.rerank !== undefined) proj.chat.rerank = parsed.rerank;
         if (parsed.systemPrompt !== undefined) proj.chat.systemPrompt = parsed.systemPrompt;
+        if (parsed.mode !== undefined) proj.chat.mode = parsed.mode;
 
         try {
           saveProject(proj, filePath || undefined);
@@ -401,20 +451,23 @@ function createPlaygroundServer() {
 
         // API: Chat message (streaming SSE)
         if (req.url === '/api/chat/message') {
-          const { query, db, collection, provider, model, maxDocs, rerank, systemPrompt } = parsed;
+          const { query, db, collection, provider, model, maxDocs, rerank, systemPrompt, mode } = parsed;
+          const isAgent = mode === 'agent';
+
           if (!query) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'query is required' }));
             return;
           }
-          if (!db || !collection) {
+          // Pipeline mode requires db + collection; agent mode they're optional
+          if (!isAgent && (!db || !collection)) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'db and collection are required' }));
+            res.end(JSON.stringify({ error: 'db and collection are required for pipeline mode' }));
             return;
           }
 
           const { createLLMProvider } = require('../lib/llm');
-          const { chatTurn } = require('../lib/chat');
+          const { chatTurn, agentChatTurn } = require('../lib/chat');
           const { ChatHistory } = require('../lib/history');
 
           let llm;
@@ -447,21 +500,68 @@ function createPlaygroundServer() {
           });
 
           try {
-            for await (const event of chatTurn({
-              query, db, collection, llm, history,
-              opts: {
-                maxDocs: maxDocs || 5,
-                rerank: rerank !== false,
-                stream: true,
-                systemPrompt,
-              },
-            })) {
-              if (event.type === 'retrieval') {
-                res.write(`event: retrieval\ndata: ${JSON.stringify(event.data)}\n\n`);
-              } else if (event.type === 'chunk') {
-                res.write(`event: chunk\ndata: ${JSON.stringify({ text: event.data })}\n\n`);
-              } else if (event.type === 'done') {
-                res.write(`event: done\ndata: ${JSON.stringify(event.data)}\n\n`);
+            if (isAgent) {
+              // Agent mode: LLM decides which tools to call
+              for await (const event of agentChatTurn({
+                query, llm, history,
+                opts: { systemPrompt, db: db || undefined, collection: collection || undefined },
+              })) {
+                if (event.type === 'tool_call') {
+                  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') {
+                  res.write(`event: done\ndata: ${JSON.stringify(event.data)}\n\n`);
+                }
+              }
+            } else {
+              // Pipeline mode: fixed RAG retrieval
+              for await (const event of chatTurn({
+                query, db, collection, llm, history,
+                opts: {
+                  maxDocs: maxDocs || 5,
+                  rerank: rerank !== false,
+                  stream: true,
+                  systemPrompt,
+                },
+              })) {
+                if (event.type === 'retrieval') {
+                  res.write(`event: retrieval\ndata: ${JSON.stringify(event.data)}\n\n`);
+                } else if (event.type === 'chunk') {
+                  res.write(`event: chunk\ndata: ${JSON.stringify({ text: event.data })}\n\n`);
+                } else if (event.type === 'done') {
+                  res.write(`event: done\ndata: ${JSON.stringify(event.data)}\n\n`);
+                }
               }
             }
           } catch (err) {
@@ -622,6 +722,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