voyageai-cli 1.24.0 → 1.26.0

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;

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

@@ -6,16 +6,22 @@
  * Dimensions: {{dimensions}}
  */
 
-const VOYAGE_API_URL = process.env.VOYAGE_API_URL || 'https://api.voyageai.com/v1';
-const VOYAGE_API_KEY = process.env.VOYAGE_API_KEY;
+function getApiUrl() {
+  return process.env.VOYAGE_API_URL || 'https://api.voyageai.com/v1';
+}
+
+function getApiKey() {
+  const key = process.env.VOYAGE_API_KEY;
+  if (!key) throw new Error('VOYAGE_API_KEY environment variable is required');
+  return key;
+}
 
 /**
  * Generate embeddings for text(s) using Voyage AI.
  */
 export async function embed(input, options = {}) {
-  if (!VOYAGE_API_KEY) {
-    throw new Error('VOYAGE_API_KEY environment variable is required');
-  }
+  const VOYAGE_API_URL = getApiUrl();
+  const VOYAGE_API_KEY = getApiKey();
 
   const texts = Array.isArray(input) ? input : [input];
   
@@ -66,9 +72,8 @@ export async function embedDocuments(documents, options = {}) {
  * Rerank documents by relevance to a query.
  */
 export async function rerank(query, documents, options = {}) {
-  if (!VOYAGE_API_KEY) {
-    throw new Error('VOYAGE_API_KEY environment variable is required');
-  }
+  const VOYAGE_API_URL = getApiUrl();
+  const VOYAGE_API_KEY = getApiKey();
 
   const response = await fetch(`${VOYAGE_API_URL}/rerank`, {
     method: 'POST',

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

@@ -0,0 +1,98 @@
+/**
+ * Branded AppBar with dark mode toggle
+ * Generated by vai v{{vaiVersion}} on {{generatedAt}}
+ */
+
+'use client';
+
+import {
+  AppBar,
+  Toolbar,
+  Typography,
+  IconButton,
+  Box,
+  Chip,
+  Tooltip,
+  useTheme,
+} from '@mui/material';
+import DarkModeIcon from '@mui/icons-material/DarkMode';
+import LightModeIcon from '@mui/icons-material/LightMode';
+import GitHubIcon from '@mui/icons-material/GitHub';
+import { useColorMode } from './ThemeRegistry';
+
+export default function Navbar() {
+  const theme = useTheme();
+  const { mode, toggle } = useColorMode();
+
+  return (
+    <AppBar position="sticky" elevation={0} color="transparent">
+      <Toolbar sx={{ gap: 1.5 }}>
+        {/* Logo / wordmark */}
+        <Box
+          component="img"
+          src="/vai-logo.png"
+          alt="vai logo"
+          sx={{ height: 28, width: 28 }}
+        />
+        <Typography
+          variant="h6"
+          sx={{
+            fontWeight: 800,
+            letterSpacing: '-0.02em',
+            background: `linear-gradient(135deg, ${theme.palette.primary.main} 0%, ${theme.palette.primary.dark} 100%)`,
+            WebkitBackgroundClip: 'text',
+            WebkitTextFillColor: 'transparent',
+          }}
+        >
+          {{projectName}}
+        </Typography>
+
+        <Chip
+          label="vai"
+          size="small"
+          sx={{
+            fontWeight: 700,
+            fontSize: '0.65rem',
+            height: 20,
+            bgcolor: 'primary.main',
+            color: 'primary.contrastText',
+          }}
+        />
+
+        <Box sx={{ flex: 1 }} />
+
+        {/* Model badge */}
+        <Chip
+          label="{{model}}"
+          size="small"
+          variant="outlined"
+          sx={{
+            display: { xs: 'none', sm: 'flex' },
+            fontFamily: 'monospace',
+            fontSize: '0.7rem',
+          }}
+        />
+
+        {/* GitHub link */}
+        <Tooltip title="View on GitHub">
+          <IconButton
+            size="small"
+            href="https://github.com/mrlynn/voyageai-cli"
+            target="_blank"
+            rel="noopener"
+            sx={{ color: 'text.secondary' }}
+          >
+            <GitHubIcon fontSize="small" />
+          </IconButton>
+        </Tooltip>
+
+        {/* Dark mode toggle */}
+        <Tooltip title={mode === 'dark' ? 'Light mode' : 'Dark mode'}>
+          <IconButton size="small" onClick={toggle} sx={{ color: 'text.secondary' }}>
+            {mode === 'dark' ? <LightModeIcon fontSize="small" /> : <DarkModeIcon fontSize="small" />}
+          </IconButton>
+        </Tooltip>
+      </Toolbar>
+    </AppBar>
+  );
+}