voyageai-cli 1.23.1 → 1.26.0

package/src/lib/explanations.js

@@ -1434,6 +1434,50 @@ const concepts = {
       'vai chat --db myapp --collection knowledge',
     ],
   },
+
+  workflows: {
+    title: 'Agentic Workflows',
+    summary: 'Composable, multi-step RAG pipelines as JSON files',
+    content: [
+      `${pc.cyan('Workflows')} are composable, multi-step RAG pipelines defined as portable`,
+      `JSON files. Think Docker Compose or GitHub Actions, but for search and retrieval`,
+      `pipelines.`,
+      ``,
+      `${pc.bold('Why workflows?')} Instead of writing bash scripts to chain vai commands,`,
+      `a workflow file captures the intent declaratively. Workflows are reproducible,`,
+      `shareable (commit them to git), and inspectable.`,
+      ``,
+      `${pc.bold('How it works:')}`,
+      `Each workflow defines a DAG (directed acyclic graph) of steps. Each step maps`,
+      `to a vai operation (query, search, rerank, embed, etc.) or a control flow`,
+      `operation (merge, filter, transform, generate). Steps reference outputs from`,
+      `previous steps using ${pc.cyan('{{ template expressions }}')} for data flow.`,
+      ``,
+      `${pc.bold('Template expressions:')}`,
+      `  ${pc.cyan('{{ inputs.query }}')}              workflow input parameter`,
+      `  ${pc.cyan('{{ search.output.results }}')}      results from a previous step`,
+      `  ${pc.cyan('{{ merge.output.results[0] }}')}    array indexing`,
+      `  ${pc.cyan('{{ defaults.db }}')}                workflow default value`,
+      ``,
+      `${pc.bold('Parallel execution:')} The engine automatically detects independent steps`,
+      `and runs them in parallel. No configuration needed.`,
+      ``,
+      `${pc.bold('Step types:')}`,
+      `  ${pc.dim('VAI tools:')}     query, search, rerank, embed, similarity, ingest,`,
+      `                 collections, models, explain, estimate`,
+      `  ${pc.dim('Control flow:')} merge, filter, transform, generate`,
+      ``,
+      `${pc.bold('Built-in templates:')} Run ${pc.cyan('vai workflow list')} to see available`,
+      `templates like multi-collection-search, smart-ingest, research-and-summarize.`,
+    ].join('\n'),
+    links: ['https://github.com/mrlynn/voyageai-cli#workflows'],
+    tryIt: [
+      'vai workflow list',
+      'vai workflow init --name my-pipeline',
+      'vai workflow validate ./my-pipeline.vai-workflow.json',
+      'vai workflow run multi-collection-search --input query="test" --dry-run',
+    ],
+  },
 };
 
 /**
@@ -1598,6 +1642,15 @@ const aliases = {
   conversational: 'chat',
   'chat-history': 'chat',
   llm: 'chat',
+  // Workflow aliases
+  workflow: 'workflows',
+  workflows: 'workflows',
+  'rag-pipeline': 'workflows',
+  composable: 'workflows',
+  'workflow-engine': 'workflows',
+  'vai-workflow': 'workflows',
+  pipeline: 'workflows',
+  dag: 'workflows',
 };
 
 /**

package/src/lib/scaffold-structure.js

@@ -31,23 +31,22 @@ const PROJECT_STRUCTURE = {
       { template: 'env.example', output: '.env.example' },
       { template: 'README.md', output: 'README.md' },
       { template: 'layout.jsx', output: 'app/layout.jsx' },
+      { template: 'page-home.jsx', output: 'app/page.jsx' },
       { template: 'page-search.jsx', output: 'app/search/page.jsx' },
       { template: 'route-search.js', output: 'app/api/search/route.js' },
       { template: 'route-ingest.js', output: 'app/api/ingest/route.js' },
       { template: 'lib-voyage.js', output: 'lib/voyage.js' },
       { template: 'lib-mongo.js', output: 'lib/mongodb.js' },
       { template: 'theme.js', output: 'lib/theme.js' },
+      { template: 'theme-registry.jsx', output: 'components/ThemeRegistry.jsx' },
+      { template: 'navbar.jsx', output: 'components/Navbar.jsx' },
+      { template: 'footer.jsx', output: 'components/Footer.jsx' },
+      { template: 'favicon.svg', output: 'public/favicon.svg' },
+    ],
+    binaryFiles: [
+      { source: 'vai-logo-256.png', output: 'public/vai-logo.png' },
     ],
     extraFiles: [
-      {
-        output: 'app/page.jsx',
-        content: `'use client';
-import { redirect } from 'next/navigation';
-export default function Home() {
-  redirect('/search');
-}
-`,
-      },
       {
         output: 'next.config.js',
         content: `/** @type {import('next').NextConfig} */

package/src/lib/telemetry.js

@@ -9,7 +9,7 @@
  * - command name, version, platform, locale
  */
 
-const TELEMETRY_URL = 'https://vai.mlynn.org/api/telemetry';
+const TELEMETRY_URL = 'https://vaicli.com/api/telemetry';
 const TIMEOUT_MS = 3000;
 
 /**

package/src/lib/template-engine.js

@@ -0,0 +1,240 @@
+'use strict';
+
+/**
+ * Template expression engine for vai workflows.
+ *
+ * Resolves {{ expression }} strings against a context object.
+ * Supports dot-path access and array indexing only.
+ * No eval(), no function calls, no arithmetic.
+ *
+ * Grammar:
+ *   expression = segment ("." segment)*
+ *   segment    = identifier ("[" index "]")?
+ *   identifier = [a-zA-Z_][a-zA-Z0-9_]*
+ *   index      = [0-9]+
+ */
+
+// Matches {{ path.to.value }} including {{ path[0].field }}
+const TEMPLATE_RE = /\{\{\s*(.+?)\s*\}\}/g;
+
+// A string that is exactly one template expression with no surrounding text
+// Use [^}] to prevent matching across multiple {{ }} pairs
+const SOLE_TEMPLATE_RE = /^\{\{\s*([^}]+?)\s*\}\}$/;
+
+/**
+ * Check if a string contains template expressions.
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isTemplateString(str) {
+  if (typeof str !== 'string') return false;
+  // Use a fresh regex to avoid global lastIndex state issues
+  return /\{\{\s*(.+?)\s*\}\}/.test(str);
+}
+
+/**
+ * Parse a dot-path expression into segments.
+ *
+ * @param {string} expr - e.g. "search_api.output.results[0].content"
+ * @returns {Array<{key: string, index?: number}>}
+ * @throws {Error} on invalid syntax
+ */
+function parseExpression(expr) {
+  const trimmed = expr.trim();
+  if (!trimmed) throw new Error('Empty expression');
+
+  const segments = [];
+  const parts = trimmed.split('.');
+
+  for (const part of parts) {
+    // Check for array indexing: identifier[index]
+    const bracketMatch = part.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\[(\d+)\]$/);
+    if (bracketMatch) {
+      segments.push({ key: bracketMatch[1], index: parseInt(bracketMatch[2], 10) });
+      continue;
+    }
+
+    // Plain identifier
+    if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(part)) {
+      segments.push({ key: part });
+      continue;
+    }
+
+    throw new Error(`Invalid expression segment: "${part}" in "${expr}"`);
+  }
+
+  return segments;
+}
+
+/**
+ * Resolve a parsed path against a context object.
+ * Returns undefined (no throw) if any segment is missing.
+ *
+ * @param {Array<{key: string, index?: number}>} segments
+ * @param {object} context
+ * @returns {*}
+ */
+function resolvePath(segments, context) {
+  let current = context;
+
+  for (const seg of segments) {
+    if (current == null || typeof current !== 'object') return undefined;
+
+    current = current[seg.key];
+    if (current == null) return current; // null or undefined
+
+    if (seg.index !== undefined) {
+      if (!Array.isArray(current)) return undefined;
+      current = current[seg.index];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Resolve template expressions within a single string.
+ *
+ * If the entire string is a single template expression, return the resolved
+ * value directly (preserving type: array, number, object, etc.).
+ * If the string contains templates mixed with text, return a string with
+ * substitutions.
+ *
+ * @param {string} str
+ * @param {object} context
+ * @returns {*}
+ */
+function resolveString(str, context) {
+  // Fast path: no templates
+  if (!str.includes('{{')) return str;
+
+  // Check if the entire string is a single template expression
+  const soleMatch = str.match(SOLE_TEMPLATE_RE);
+  if (soleMatch) {
+    try {
+      const segments = parseExpression(soleMatch[1]);
+      return resolvePath(segments, context);
+    } catch {
+      return undefined;
+    }
+  }
+
+  // Mixed text + templates: substitute all, coerce to string
+  return str.replace(TEMPLATE_RE, (_match, expr) => {
+    try {
+      const segments = parseExpression(expr);
+      const value = resolvePath(segments, context);
+      if (value === undefined) return '';
+      if (value === null) return 'null';
+      if (typeof value === 'object') return JSON.stringify(value);
+      return String(value);
+    } catch {
+      return '';
+    }
+  });
+}
+
+/**
+ * Recursively resolve all template expressions in a value.
+ * Handles strings, arrays, and plain objects.
+ *
+ * @param {*} value
+ * @param {object} context
+ * @returns {*}
+ */
+function resolveTemplate(value, context) {
+  if (typeof value === 'string') {
+    return resolveString(value, context);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => resolveTemplate(item, context));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const resolved = {};
+    for (const [k, v] of Object.entries(value)) {
+      resolved[k] = resolveTemplate(v, context);
+    }
+    return resolved;
+  }
+
+  // numbers, booleans, null, undefined pass through
+  return value;
+}
+
+/**
+ * Deep-resolve all template expressions in an object tree.
+ * Alias for resolveTemplate when called on an object.
+ *
+ * @param {object} obj
+ * @param {object} context
+ * @returns {object}
+ */
+function resolveAllTemplates(obj, context) {
+  return resolveTemplate(obj, context);
+}
+
+/**
+ * Extract step IDs referenced by template expressions in an object tree.
+ * Ignores "inputs" and "defaults" prefixes (those are workflow-level, not step refs).
+ *
+ * @param {*} obj - Step inputs, condition, forEach value
+ * @returns {Set<string>} Set of step IDs referenced
+ */
+function extractDependencies(obj) {
+  const deps = new Set();
+
+  function scan(value) {
+    if (typeof value === 'string') {
+      // Reset regex state
+      const re = /\{\{\s*(.+?)\s*\}\}/g;
+      let match;
+      while ((match = re.exec(value)) !== null) {
+        const expr = match[1].trim();
+        // Extract the first segment (root identifier)
+        const dotIdx = expr.indexOf('.');
+        const bracketIdx = expr.indexOf('[');
+        let root;
+        if (dotIdx === -1 && bracketIdx === -1) {
+          root = expr;
+        } else if (dotIdx === -1) {
+          root = expr.slice(0, bracketIdx);
+        } else if (bracketIdx === -1) {
+          root = expr.slice(0, dotIdx);
+        } else {
+          root = expr.slice(0, Math.min(dotIdx, bracketIdx));
+        }
+
+        // Skip workflow-level references
+        if (root !== 'inputs' && root !== 'defaults') {
+          deps.add(root);
+        }
+      }
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      value.forEach(scan);
+      return;
+    }
+
+    if (value !== null && typeof value === 'object') {
+      Object.values(value).forEach(scan);
+    }
+  }
+
+  scan(obj);
+  return deps;
+}
+
+module.exports = {
+  isTemplateString,
+  parseExpression,
+  resolvePath,
+  resolveString,
+  resolveTemplate,
+  resolveAllTemplates,
+  extractDependencies,
+  TEMPLATE_RE,
+};

package/src/lib/templates/nextjs/README.md.tpl

@@ -1,13 +1,39 @@
-# {{projectName}}
+# 🔍 {{projectName}}
 
-A semantic search application powered by Voyage AI embeddings, MongoDB Atlas Vector Search, and Next.js with Material UI.
+> Semantic search application powered by **Voyage AI** embeddings, **MongoDB Atlas Vector Search**, and **Next.js** with Material UI.
 
-## Configuration
+[![Generated by vai](https://img.shields.io/badge/scaffolded%20with-vai-00ED64?style=flat-square)](https://github.com/mrlynn/voyageai-cli)
+[![Next.js](https://img.shields.io/badge/Next.js-14-black?style=flat-square&logo=next.js)](https://nextjs.org)
+[![MUI](https://img.shields.io/badge/MUI-5-007FFF?style=flat-square&logo=mui)](https://mui.com)
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# 1. Install
+npm install
+
+# 2. Configure
+cp .env.example .env.local
+# → Edit .env.local with your Voyage AI key + MongoDB URI
+
+# 3. Create vector index (see below)
+
+# 4. Run
+npm run dev
+```
+
+Open **[http://localhost:3000](http://localhost:3000)** — you'll see a branded landing page with a link to the search UI.
+
+---
+
+## 🔧 Configuration
 
 | Setting | Value |
 |---------|-------|
 | Embedding Model | `{{model}}` |
-| Dimensions | {{dimensions}} |
+| Dimensions | `{{dimensions}}` |
 | Database | `{{db}}` |
 | Collection | `{{collection}}` |
 | Vector Index | `{{index}}` |
@@ -15,77 +41,74 @@ A semantic search application powered by Voyage AI embeddings, MongoDB Atlas Vec
 | Rerank Model | `{{rerankModel}}` |
 {{/if}}
 
-## Setup
-
-### 1. Install dependencies
-
-```bash
-npm install
-```
-
-### 2. Configure environment
-
-Copy `.env.example` to `.env.local` and fill in your credentials:
+### Environment Variables
 
-```bash
-cp .env.example .env.local
+```env
+VOYAGE_API_KEY=       # From dash.voyageai.com
+MONGODB_URI=          # Atlas connection string
 ```
 
-Required variables:
-- `VOYAGE_API_KEY` - Your Voyage AI API key from [dash.voyageai.com](https://dash.voyageai.com)
-- `MONGODB_URI` - Your MongoDB Atlas connection string
+### Vector Search Index
 
-### 3. Create vector index
-
-In MongoDB Atlas, create a vector search index on your collection:
+Create this index on your `{{collection}}` collection in Atlas:
 
 ```json
 {
-  "fields": [
-    {
-      "type": "vector",
-      "path": "{{field}}",
-      "numDimensions": {{dimensions}},
-      "similarity": "cosine"
-    }
-  ]
+  "fields": [{
+    "type": "vector",
+    "path": "{{field}}",
+    "numDimensions": {{dimensions}},
+    "similarity": "cosine"
+  }]
 }
 ```
 
-Name the index `{{index}}`.
-
-### 4. Start the development server
-
-```bash
-npm run dev
-```
+Name it **`{{index}}`**.
 
-Open [http://localhost:3000](http://localhost:3000) to see the search interface.
+---
 
-## Project Structure
+## 📁 Project Structure
 
 ```
 {{projectName}}/
 ├── app/
-│   ├── layout.jsx          # Root layout with MUI theme
-│   ├── page.jsx            # Home page
-│   ├── search/
-│   │   └── page.jsx        # Search page (MUI)
+│   ├── layout.jsx              # Root layout (Inter font, theme)
+│   ├── page.jsx                # Landing page (hero + features)
+│   ├── search/page.jsx         # Search UI (score bars, copy, fade-in)
 │   └── api/
-│       ├── search/route.js # Search endpoint
-│       └── ingest/route.js # Ingest endpoint
+│       ├── search/route.js     # POST /api/search
+│       └── ingest/route.js     # POST /api/ingest
+├── components/
+│   ├── ThemeRegistry.jsx       # Light/dark mode with persistence
+│   ├── Navbar.jsx              # Branded AppBar + dark toggle
+│   └── Footer.jsx              # Powered-by footer
 ├── lib/
-│   ├── voyage.js           # Voyage AI client
-│   ├── mongodb.js          # MongoDB connection
-│   └── theme.js            # MUI theme
+│   ├── voyage.js               # Voyage AI client
+│   ├── mongodb.js              # MongoDB connection + vector search
+│   └── theme.js                # MUI theme (light + dark palettes)
+├── public/favicon.svg
 ├── .env.example
-├── package.json
-└── README.md
+└── package.json
 ```
 
-## API Endpoints
+---
+
+## 🌗 Features
+
+- **Dark mode** — auto-detects system preference, persists choice
+- **Score visualization** — color-coded progress bars for relevance scores
+- **Copy to clipboard** — one-click copy on each result
+- **Responsive** — works on mobile and desktop
+- **Branded** — vai + Voyage AI + MongoDB branding throughout
+{{#if rerank}}
+- **Reranking** — results refined with {{rerankModel}} for better relevance
+{{/if}}
+
+---
+
+## 🔌 API Endpoints
 
-### POST /api/search
+### `POST /api/search`
 
 ```bash
 curl -X POST http://localhost:3000/api/search \
@@ -93,7 +116,7 @@ curl -X POST http://localhost:3000/api/search \
   -d '{"query": "How does vector search work?", "limit": 5}'
 ```
 
-### POST /api/ingest
+### `POST /api/ingest`
 
 ```bash
 curl -X POST http://localhost:3000/api/ingest \
@@ -103,4 +126,4 @@ curl -X POST http://localhost:3000/api/ingest \
 
 ---
 
-Generated by [vai](https://github.com/mrlynn/voyageai-cli) v{{vaiVersion}}
+<sub>Generated by [vai](https://github.com/mrlynn/voyageai-cli) v{{vaiVersion}} on {{generatedAt}}</sub>

package/src/lib/templates/nextjs/favicon.svg.tpl

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <defs>
+    <linearGradient id="vg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#00ED64"/>
+      <stop offset="100%" stop-color="#00D4AA"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="8" fill="#001E2B"/>
+  <path d="M8 8 L16 26 L24 8" fill="none" stroke="url(#vg)" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="18" y="20" font-family="sans-serif" font-size="7" font-weight="bold" fill="url(#vg)">ai</text>
+</svg>

package/src/lib/templates/nextjs/footer.jsx.tpl

@@ -0,0 +1,49 @@
+/**
+ * Branded footer
+ * Generated by vai v{{vaiVersion}} on {{generatedAt}}
+ */
+
+'use client';
+
+import { Box, Typography, Link, Stack, Divider } from '@mui/material';
+
+export default function Footer() {
+  return (
+    <Box component="footer" sx={{ mt: 'auto', pt: 6, pb: 4 }}>
+      <Divider sx={{ mb: 3 }} />
+      <Stack
+        direction={{ xs: 'column', sm: 'row' }}
+        justifyContent="space-between"
+        alignItems="center"
+        spacing={1}
+        sx={{ px: 3 }}
+      >
+        <Typography variant="caption" color="text.secondary">
+          Built with{' '}
+          <Link
+            href="https://github.com/mrlynn/voyageai-cli"
+            target="_blank"
+            rel="noopener"
+            underline="hover"
+            color="primary"
+            fontWeight={600}
+          >
+            vai
+          </Link>
+          {' '}· Powered by{' '}
+          <Link href="https://www.voyageai.com" target="_blank" rel="noopener" underline="hover" color="inherit">
+            Voyage AI
+          </Link>
+          {' '}+{' '}
+          <Link href="https://www.mongodb.com/atlas/search" target="_blank" rel="noopener" underline="hover" color="inherit">
+            MongoDB Atlas Vector Search
+          </Link>
+        </Typography>
+
+        <Typography variant="caption" color="text.secondary" sx={{ fontFamily: 'monospace', fontSize: '0.65rem' }}>
+          v{{vaiVersion}}
+        </Typography>
+      </Stack>
+    </Box>
+  );
+}

package/src/lib/templates/nextjs/layout.jsx.tpl

@@ -1,27 +1,33 @@
 /**
- * Root Layout with MUI Theme
+ * Root Layout with vai branding
  * Generated by vai v{{vaiVersion}} on {{generatedAt}}
  */
 
 import { AppRouterCacheProvider } from '@mui/material-nextjs/v14-appRouter';
-import { ThemeProvider } from '@mui/material/styles';
-import CssBaseline from '@mui/material/CssBaseline';
-import { theme } from '@/lib/theme';
+import { ThemeRegistry } from '@/components/ThemeRegistry';
 
 export const metadata = {
-  title: '{{projectName}}',
-  description: 'Semantic search powered by Voyage AI',
+  title: '{{projectName}} — Semantic Search',
+  description: 'Semantic search powered by Voyage AI embeddings and MongoDB Atlas Vector Search.',
+  icons: { icon: '/favicon.svg' },
 };
 
 export default function RootLayout({ children }) {
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
+          rel="stylesheet"
+        />
+      </head>
       <body>
         <AppRouterCacheProvider>
-          <ThemeProvider theme={theme}>
-            <CssBaseline />
+          <ThemeRegistry>
             {children}
-          </ThemeProvider>
+          </ThemeRegistry>
         </AppRouterCacheProvider>
       </body>
     </html>

package/src/lib/templates/nextjs/lib-mongo.js.tpl

@@ -7,10 +7,10 @@
 
 import { MongoClient } from 'mongodb';
 
-const MONGODB_URI = process.env.MONGODB_URI;
-
-if (!MONGODB_URI) {
-  throw new Error('MONGODB_URI environment variable is required');
+function getUri() {
+  const uri = process.env.MONGODB_URI;
+  if (!uri) throw new Error('MONGODB_URI environment variable is required');
+  return uri;
 }
 
 // Cache the client promise for connection reuse in serverless
@@ -30,7 +30,7 @@ export async function getMongoClient() {
   }
 
   if (!cached.promise) {
-    cached.promise = MongoClient.connect(MONGODB_URI);
+    cached.promise = MongoClient.connect(getUri());
   }
 
   cached.conn = await cached.promise;