npm - voyageai-cli - Versions diffs - 1.30.0 → 1.30.1 - Mend

voyageai-cli 1.30.0 → 1.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/package.json +1 -1
package/src/cli.js +6 -0
package/src/commands/chat.js +32 -11
package/src/commands/export.js +124 -0
package/src/commands/import.js +195 -0
package/src/commands/index-workspace.js +239 -0
package/src/commands/mcp-server.js +113 -3
package/src/commands/playground.js +111 -3
package/src/lib/export/contexts/benchmark-export.js +27 -0
package/src/lib/export/contexts/chat-export.js +41 -0
package/src/lib/export/contexts/explore-export.js +22 -0
package/src/lib/export/contexts/search-export.js +54 -0
package/src/lib/export/contexts/workflow-export.js +80 -0
package/src/lib/export/formats/clipboard-export.js +29 -0
package/src/lib/export/formats/csv-export.js +45 -0
package/src/lib/export/formats/json-export.js +50 -0
package/src/lib/export/formats/markdown-export.js +189 -0
package/src/lib/export/formats/mermaid-export.js +274 -0
package/src/lib/export/formats/pdf-export.js +117 -0
package/src/lib/export/formats/png-export.js +96 -0
package/src/lib/export/formats/svg-export.js +116 -0
package/src/lib/export/index.js +175 -0
package/src/lib/workflow.js +206 -27
package/src/mcp/install.js +280 -7
package/src/mcp/schemas/index.js +40 -0
package/src/mcp/server.js +2 -0
package/src/mcp/tools/workspace.js +463 -0
package/src/playground/announcements.md +52 -5
package/src/playground/index.html +11125 -7796
package/src/playground/vendor/mermaid.min.js +2811 -0
package/src/workflows/rag-chat.json +165 -0
package/src/workflows/tests/consistency-check.happy-path.test.json +28 -0
package/src/workflows/tests/consistency-check.missing-source.test.json +26 -0
package/src/workflows/tests/cost-analysis.happy-path.test.json +28 -0
package/src/workflows/tests/enrich-and-ingest.happy-path.test.json +38 -0
package/src/workflows/tests/enrich-and-ingest.notify-fails.test.json +38 -0
package/src/workflows/tests/intelligent-ingest.all-filtered.test.json +26 -0
package/src/workflows/tests/intelligent-ingest.happy-path.test.json +28 -0
package/src/workflows/tests/kb-health-report.custom-queries.test.json +24 -0
package/src/workflows/tests/kb-health-report.happy-path.test.json +26 -0
package/src/workflows/tests/multi-collection-search.happy-path.test.json +40 -0
package/src/workflows/tests/multi-collection-search.one-empty.test.json +28 -0
package/src/workflows/tests/rag-chat.happy-path.test.json +26 -0
package/src/workflows/tests/rag-chat.no-relevant-results.test.json +25 -0
package/src/workflows/tests/research-and-summarize.happy-path.test.json +33 -0
package/src/workflows/tests/research-and-summarize.no-results.test.json +29 -0
package/src/workflows/tests/search-with-fallback.empty-both.test.json +24 -0
package/src/workflows/tests/search-with-fallback.fallback-branch.test.json +24 -0
package/src/workflows/tests/search-with-fallback.happy-path.test.json +27 -0
package/src/workflows/tests/smart-ingest.duplicate-detected.test.json +34 -0
package/src/workflows/tests/smart-ingest.happy-path.test.json +31 -0
package/src/playground/assets/announcements/appstore.jpg +0 -0
package/src/playground/assets/announcements/circuits.jpg +0 -0
package/src/playground/assets/announcements/csvingest.jpg +0 -0
package/src/playground/assets/announcements/green-wave.jpg +0 -0

package/src/lib/export/formats/svg-export.js ADDED Viewed

@@ -0,0 +1,116 @@
+'use strict';
+/**
+ * Render an SVG string for export.
+ * In CLI context, this generates SVG from Mermaid via Playwright.
+ * In Electron/browser context, this serializes and cleans the DOM SVG.
+ *
+ * @param {object} normalized - Normalized data (must have _context = 'workflow' or provide _svgContent)
+ * @param {object} options
+ * @param {string} [options.background='transparent'] - 'transparent' | 'dark' | 'light'
+ * @param {boolean} [options.includeWatermark=true]
+ * @param {boolean} [options.fitToContent=true]
+ * @returns {{ content: string, mimeType: string }}
+ */
+function renderSvg(normalized, options = {}) {
+  // If raw SVG content is provided (from browser/Electron capture), clean and return it
+  if (normalized._svgContent) {
+    const cleaned = cleanSvg(normalized._svgContent, options);
+    return { content: cleaned, mimeType: 'image/svg+xml' };
+  }
+  // For CLI: generate SVG from Mermaid (async path handled by renderSvgAsync)
+  throw new Error('SVG export requires either _svgContent (browser) or use renderSvgAsync (CLI)');
+}
+/**
+ * Async SVG render — generates SVG from Mermaid using Playwright.
+ * @param {object} normalized
+ * @param {object} options
+ * @returns {Promise<{ content: string, mimeType: string }>}
+ */
+async function renderSvgAsync(normalized, options = {}) {
+  if (normalized._svgContent) {
+    return renderSvg(normalized, options);
+  }
+  // Generate Mermaid source, then render via Playwright
+  const { workflowToMermaid } = require('./mermaid-export');
+  if (normalized._context !== 'workflow' && normalized._context !== 'benchmark') {
+    throw new Error(`SVG export not supported for context: ${normalized._context}`);
+  }
+  const mermaidSrc = normalized._context === 'workflow'
+    ? workflowToMermaid(normalized, options)
+    : null;
+  if (!mermaidSrc) {
+    throw new Error('No Mermaid source available for SVG rendering');
+  }
+  const svg = await renderMermaidToSvg(mermaidSrc, options);
+  return { content: svg, mimeType: 'image/svg+xml' };
+}
+/**
+ * Render Mermaid syntax to SVG using Playwright.
+ */
+async function renderMermaidToSvg(mermaidSrc, options = {}) {
+  const { chromium } = require('playwright');
+  const background = options.background || 'transparent';
+  const bgColor = background === 'dark' ? '#1e1e1e' : background === 'light' ? '#ffffff' : 'transparent';
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage();
+    const html = `<!DOCTYPE html>
+<html><head>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+</head><body style="margin:0;background:${bgColor};">
+<pre class="mermaid">${escapeHtml(mermaidSrc)}</pre>
+<script>mermaid.initialize({ startOnLoad: true, theme: '${options.theme || 'dark'}' });</script>
+</body></html>`;
+    await page.setContent(html, { waitUntil: 'networkidle' });
+    await page.waitForSelector('svg', { timeout: 10000 });
+    const svg = await page.evaluate(() => {
+      const el = document.querySelector('svg');
+      // Remove interactive attributes
+      el.removeAttribute('style');
+      const scripts = el.querySelectorAll('script');
+      scripts.forEach(s => s.remove());
+      return el.outerHTML;
+    });
+    const cleaned = cleanSvg(svg, options);
+    return cleaned;
+  } finally {
+    await browser.close();
+  }
+}
+/**
+ * Clean an SVG string: remove scripts, event handlers, optionally add watermark.
+ */
+function cleanSvg(svgStr, options = {}) {
+  // Strip event handlers
+  let svg = svgStr.replace(/\s+on\w+="[^"]*"/g, '');
+  // Strip <script> tags
+  svg = svg.replace(/<script[\s\S]*?<\/script>/gi, '');
+  if (options.includeWatermark !== false) {
+    // Insert watermark before closing </svg>
+    const watermark = '<text x="99%" y="99%" text-anchor="end" font-size="10" fill="#666" opacity="0.5">Generated by vai</text>';
+    svg = svg.replace('</svg>', `${watermark}</svg>`);
+  }
+  return svg;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+module.exports = { renderSvg, renderSvgAsync, renderMermaidToSvg, cleanSvg };

package/src/lib/export/index.js ADDED Viewed

@@ -0,0 +1,175 @@
+'use strict';
+const { renderJson, renderJsonl } = require('./formats/json-export');
+const { renderCsv } = require('./formats/csv-export');
+const { renderMarkdown } = require('./formats/markdown-export');
+const { renderMermaid } = require('./formats/mermaid-export');
+const { copyToClipboard } = require('./formats/clipboard-export');
+const { renderSvgAsync } = require('./formats/svg-export');
+const { renderPng } = require('./formats/png-export');
+const { renderPdf } = require('./formats/pdf-export');
+const { normalizeWorkflow, WORKFLOW_FORMATS } = require('./contexts/workflow-export');
+const { normalizeSearch, SEARCH_FORMATS } = require('./contexts/search-export');
+const { normalizeChat, CHAT_FORMATS } = require('./contexts/chat-export');
+const { normalizeBenchmark, BENCHMARK_FORMATS } = require('./contexts/benchmark-export');
+const { normalizeExplore, EXPLORE_FORMATS } = require('./contexts/explore-export');
+// ════════════════════════════════════════════════════════════════════
+// Context → Formats mapping
+// ════════════════════════════════════════════════════════════════════
+const FORMAT_MAP = {
+  workflow: WORKFLOW_FORMATS,
+  search: SEARCH_FORMATS,
+  chat: CHAT_FORMATS,
+  benchmark: BENCHMARK_FORMATS,
+  explore: EXPLORE_FORMATS,
+};
+const TRANSFORMERS = {
+  workflow: normalizeWorkflow,
+  search: normalizeSearch,
+  chat: normalizeChat,
+  benchmark: normalizeBenchmark,
+  explore: normalizeExplore,
+};
+const RENDERERS = {
+  json: renderJson,
+  jsonl: renderJsonl,
+  csv: renderCsv,
+  markdown: renderMarkdown,
+  mermaid: renderMermaid,
+  svg: renderSvgAsync,
+  png: renderPng,
+  pdf: renderPdf,
+};
+// Formats that produce binary (Buffer) output
+const BINARY_FORMATS = new Set(['png', 'pdf']);
+const EXT_MAP = {
+  json: '.json',
+  jsonl: '.jsonl',
+  csv: '.csv',
+  markdown: '.md',
+  mermaid: '.mmd',
+  svg: '.svg',
+  png: '.png',
+  pdf: '.pdf',
+};
+// ════════════════════════════════════════════════════════════════════
+// Public API
+// ════════════════════════════════════════════════════════════════════
+/**
+ * Get supported formats for a given context.
+ * @param {string} context
+ * @returns {string[]}
+ */
+function getFormatsForContext(context) {
+  return FORMAT_MAP[context] || [];
+}
+/**
+ * Build a deterministic filename for the export.
+ * Pattern: {context}-{name}-{timestamp}.{ext}
+ * @param {string} context
+ * @param {object} data
+ * @param {string} format
+ * @returns {string}
+ */
+function buildFilename(context, data, format) {
+  const name = (data.name || data.sessionId || data.query || context)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40);
+  const ts = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+  const ext = EXT_MAP[format] || '.txt';
+  return `${context}-${name}-${ts}${ext}`;
+}
+/**
+ * Main export entry point.
+ *
+ * @param {object} params
+ * @param {string} params.context - 'workflow' | 'search' | 'chat' | 'benchmark' | 'explore'
+ * @param {string} params.format - 'json' | 'jsonl' | 'csv' | 'markdown' | 'mermaid' | 'clipboard'
+ * @param {object} params.data - Raw source data
+ * @param {object} [params.options] - Format & context specific options
+ * @returns {{ content: string, mimeType: string, suggestedFilename: string, format: string }}
+ */
+async function exportArtifact({ context, format, data, options = {} }) {
+  // Handle clipboard as a meta-format: pick the best underlying format and copy
+  const isClipboard = format === 'clipboard';
+  const effectiveFormat = isClipboard ? pickClipboardFormat(context) : format;
+  // Validate
+  const supported = getFormatsForContext(context);
+  if (!supported.includes(format)) {
+    throw new ExportError(
+      `Format "${format}" not supported for ${context}. Supported: ${supported.join(', ')}`
+    );
+  }
+  // Transform
+  const transformer = TRANSFORMERS[context];
+  if (!transformer) {
+    throw new ExportError(`Unknown export context: "${context}"`);
+  }
+  const normalized = transformer(data, options);
+  // Render
+  const renderer = RENDERERS[effectiveFormat];
+  if (!renderer) {
+    throw new ExportError(`No renderer for format: "${effectiveFormat}"`);
+  }
+  const output = await renderer(normalized, options);
+  const isBinary = BINARY_FORMATS.has(effectiveFormat);
+  // Clipboard side-effect (text only — binary clipboard handled by Electron)
+  if (isClipboard) {
+    const ok = copyToClipboard(typeof output.content === 'string' ? output.content : output.content.toString());
+    if (!ok) {
+      throw new ExportError('Failed to copy to clipboard — unsupported platform or missing clipboard tool');
+    }
+  }
+  return {
+    content: output.content,
+    mimeType: output.mimeType,
+    suggestedFilename: buildFilename(context, data, effectiveFormat),
+    format: effectiveFormat,
+  };
+}
+/**
+ * Pick the best text format for clipboard based on context.
+ */
+function pickClipboardFormat(context) {
+  switch (context) {
+    case 'workflow': return 'mermaid';
+    case 'search': return 'json';
+    case 'chat': return 'markdown';
+    case 'benchmark': return 'json';
+    case 'explore': return 'json';
+    default: return 'json';
+  }
+}
+class ExportError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ExportError';
+  }
+}
+module.exports = {
+  exportArtifact,
+  getFormatsForContext,
+  buildFilename,
+  ExportError,
+};

package/src/lib/workflow.js CHANGED Viewed

@@ -45,32 +45,55 @@ const SCHEMA_LIMITS = {
 /**
  * Validate a workflow definition object.
- * Returns an array of error strings (empty = valid).
+ * Two modes: strict (default) returns error strings for backward compatibility,
+ * draft mode returns structured issue objects with severity levels.
  *
  * @param {object} definition - Parsed workflow JSON
- * @returns {string[]} errors
+ * @param {object} [options]
+ * @param {'strict'|'draft'} [options.mode='strict'] - Validation mode
+ * @returns {string[]|object} In strict: string[] errors. In draft: { valid, mode, issues, stats }
  */
-function validateWorkflow(definition) {
-  const errors = [];
+function validateWorkflow(definition, { mode = 'strict' } = {}) {
+  const issues = [];
+  // Helper to add issue
+  function addIssue(severity, stepId, code, message, field = null, referencedStep = null) {
+    issues.push({
+      severity,
+      stepId,
+      code,
+      message,
+      ...(field && { field }),
+      ...(referencedStep && { referencedStep })
+    });
+  }
   // Top-level required fields
   if (!definition || typeof definition !== 'object') {
-    return ['Workflow definition must be a JSON object'];
+    addIssue('error', null, 'INVALID_DEFINITION', 'Workflow definition must be a JSON object');
+    return mode === 'strict' ? ['Workflow definition must be a JSON object'] : { valid: false, mode, issues, stats: { totalSteps: 0, errors: 1, warnings: 0, info: 0 } };
   }
   if (!definition.name || typeof definition.name !== 'string') {
-    errors.push('Workflow must have a "name" string');
+    const severity = mode === 'draft' ? 'info' : 'error';
+    addIssue(severity, null, 'MISSING_WORKFLOW_NAME', 'Workflow must have a "name" string');
   }
   if (!Array.isArray(definition.steps) || definition.steps.length === 0) {
-    errors.push('Workflow must have a non-empty "steps" array');
+    addIssue('error', null, 'MISSING_STEPS', 'Workflow must have a non-empty "steps" array');
   }
-  if (errors.length > 0) return errors; // Can't validate steps without them
+  const structuralErrors = issues.filter(i => i.severity === 'error');
+  if (structuralErrors.length > 0 && !Array.isArray(definition.steps)) {
+    // Can't validate steps without them
+    return formatResponse(mode, issues, 0);
+  }
   // Validate inputs schema
   if (definition.inputs) {
     for (const [key, schema] of Object.entries(definition.inputs)) {
       if (schema.type && !['string', 'number', 'boolean', 'array'].includes(schema.type)) {
-        errors.push(`Input "${key}" has invalid type "${schema.type}" (must be string, number, boolean, or array)`);
+        addIssue('error', null, 'INVALID_INPUT_TYPE', `Input "${key}" has invalid type "${schema.type}" (must be string, number, boolean, or array)`);
       }
     }
   }
@@ -84,7 +107,7 @@ function validateWorkflow(definition) {
     const prefix = `Step ${i}`;
     if (!step.id || typeof step.id !== 'string') {
-      errors.push(`${prefix}: must have a string "id"`);
+      addIssue('error', step.id || `step${i}`, 'MISSING_STEP_ID', `${prefix}: must have a string "id"`);
       continue;
     }
@@ -98,14 +121,20 @@ function validateWorkflow(definition) {
     // Tool validation
     if (!step.tool || typeof step.tool !== 'string') {
-      errors.push(`${stepPrefix}: must have a string "tool"`);
+      addIssue('error', step.id, 'MISSING_TOOL', `${stepPrefix}: must have a string "tool"`);
     } else if (!ALL_TOOLS.has(step.tool)) {
-      errors.push(`${stepPrefix}: unknown tool "${step.tool}" (available: ${[...ALL_TOOLS].join(', ')})`);
+      addIssue('error', step.id, 'INVALID_TOOL', `${stepPrefix}: unknown tool "${step.tool}" (available: ${[...ALL_TOOLS].join(', ')})`);
     }
     // Inputs validation
     if (step.tool !== 'generate' && (!step.inputs || typeof step.inputs !== 'object')) {
-      errors.push(`${stepPrefix}: must have an "inputs" object`);
+      const severity = mode === 'draft' ? 'info' : 'error';
+      addIssue(severity, step.id, 'MISSING_INPUTS', `${stepPrefix}: must have an "inputs" object`);
+    }
+    // Step name validation (only in draft mode for better UX)
+    if (!step.name && mode === 'draft') {
+      addIssue('info', step.id, 'MISSING_STEP_NAME', `${stepPrefix}: missing "name" field`);
     }
     // Check template references point to known step IDs or reserved prefixes
@@ -127,25 +156,32 @@ function validateWorkflow(definition) {
       const deps = extractDependencies(inputsToCheck);
       for (const dep of deps) {
         if (!forEachVars.has(dep) && !loopVars.has(dep) && !stepIds.has(dep) && !definition.steps.some(s => s.id === dep)) {
-          errors.push(`${stepPrefix}: references unknown step "${dep}"`);
+          const severity = mode === 'draft' ? 'warning' : 'error';
+          addIssue(severity, step.id, 'UNKNOWN_STEP_REF', `${stepPrefix}: references unknown step "${dep}"`, null, dep);
         }
       }
     }
     // Condition validation (if present, should be a string)
     if (step.condition !== undefined && typeof step.condition !== 'string') {
-      errors.push(`${stepPrefix}: "condition" must be a string`);
+      addIssue('error', step.id, 'INVALID_CONDITION', `${stepPrefix}: "condition" must be a string`);
+    }
+    // Empty condition validation
+    if (step.condition !== undefined && typeof step.condition === 'string' && step.condition.trim() === '') {
+      const severity = mode === 'draft' ? 'info' : 'error';
+      addIssue(severity, step.id, 'EMPTY_CONDITION', `${stepPrefix}: "condition" is empty`);
     }
     // forEach validation (if present, should be a template string)
     if (step.forEach !== undefined && typeof step.forEach !== 'string') {
-      errors.push(`${stepPrefix}: "forEach" must be a string`);
+      addIssue('error', step.id, 'INVALID_FOREACH', `${stepPrefix}: "forEach" must be a string`);
     }
   }
   // Report duplicates
   for (const id of duplicateIds) {
-    errors.push(`Duplicate step id: "${id}"`);
+    addIssue('error', id, 'DUPLICATE_ID', `Duplicate step id: "${id}"`);
   }
   // Validate conditional branch references
@@ -157,40 +193,183 @@ function validateWorkflow(definition) {
         if (refs && Array.isArray(refs)) {
           for (const ref of refs) {
             if (!stepIds.has(ref)) {
-              errors.push(`Step "${step.id}": conditional ${branch} references unknown step "${ref}"`);
+              const severity = mode === 'draft' ? 'warning' : 'error';
+              addIssue(severity, step.id, 'UNKNOWN_STEP_REF', `Step "${step.id}": conditional ${branch} references unknown step "${ref}"`, null, ref);
             }
           }
         }
       }
       if (!step.inputs.condition) {
-        errors.push(`Step "${step.id}": conditional must have a "condition" input`);
+        const severity = mode === 'draft' ? 'info' : 'error';
+        addIssue(severity, step.id, 'MISSING_REQUIRED_INPUT', `Step "${step.id}": conditional must have a "condition" input`, 'inputs.condition');
       }
       if (!step.inputs.then || !Array.isArray(step.inputs.then)) {
-        errors.push(`Step "${step.id}": conditional must have a "then" array`);
+        const severity = mode === 'draft' ? 'info' : 'error';
+        addIssue(severity, step.id, 'MISSING_REQUIRED_INPUT', `Step "${step.id}": conditional must have a "then" array`, 'inputs.then');
       }
     }
     // Validate loop inline step
     if (step.tool === 'loop' && step.inputs) {
       if (!step.inputs.items) {
-        errors.push(`Step "${step.id}": loop must have an "items" input`);
+        const severity = mode === 'draft' ? 'info' : 'error';
+        addIssue(severity, step.id, 'MISSING_REQUIRED_INPUT', `Step "${step.id}": loop must have an "items" input`, 'inputs.items');
       }
       if (!step.inputs.as || typeof step.inputs.as !== 'string') {
-        errors.push(`Step "${step.id}": loop must have a string "as" input`);
+        const severity = mode === 'draft' ? 'info' : 'error';
+        addIssue(severity, step.id, 'MISSING_REQUIRED_INPUT', `Step "${step.id}": loop must have a string "as" input`, 'inputs.as');
       }
       if (!step.inputs.step || typeof step.inputs.step !== 'object') {
-        errors.push(`Step "${step.id}": loop must have a "step" object`);
+        const severity = mode === 'draft' ? 'info' : 'error';
+        addIssue(severity, step.id, 'MISSING_REQUIRED_INPUT', `Step "${step.id}": loop must have a "step" object`, 'inputs.step');
       } else if (step.inputs.step.tool && !ALL_TOOLS.has(step.inputs.step.tool)) {
-        errors.push(`Step "${step.id}": loop sub-step has unknown tool "${step.inputs.step.tool}"`);
+        addIssue('error', step.id, 'INVALID_TOOL', `Step "${step.id}": loop sub-step has unknown tool "${step.inputs.step.tool}"`);
       }
     }
   }
   // Check for circular dependencies
-  const cycleErrors = detectCycles(definition.steps);
-  errors.push(...cycleErrors);
+  const cycleResult = detectCyclesAsIssues(definition.steps);
+  for (const issue of cycleResult) {
+    addIssue('error', issue.stepId, 'CIRCULAR_DEPENDENCY', issue.message);
+  }
+  // Draft-only checks: orphan nodes
+  if (mode === 'draft') {
+    for (const step of definition.steps || []) {
+      const isReferenced = (definition.steps || []).some(
+        other => other.id !== step.id &&
+          extractStepReferences(other).some(ref => ref.stepId === step.id)
+      );
+      const hasReferences = extractStepReferences(step).length > 0;
+      if (!isReferenced && !hasReferences && (definition.steps || []).length > 1) {
+        addIssue('info', step.id, 'ORPHAN_NODE', `Step "${step.id}" is not connected to any other step`);
+      }
+    }
+  }
-  return errors;
+  return formatResponse(mode, issues, (definition.steps || []).length);
+}
+/**
+ * Extract step references from a step for orphan detection.
+ * @param {object} step
+ * @returns {Array<{stepId: string, field?: string}>}
+ */
+function extractStepReferences(step) {
+  const refs = [];
+  if (!step.inputs) return refs;
+  const deps = extractDependencies(step.inputs);
+  for (const dep of deps) {
+    if (dep !== 'inputs' && dep !== 'defaults' && dep !== 'item' && dep !== 'index') {
+      refs.push({ stepId: dep });
+    }
+  }
+  return refs;
+}
+/**
+ * Format the response based on validation mode.
+ * @param {string} mode
+ * @param {Array} issues
+ * @param {number} totalSteps
+ * @returns {string[]|object}
+ */
+function formatResponse(mode, issues, totalSteps) {
+  const errors = issues.filter(i => i.severity === 'error');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  const info = issues.filter(i => i.severity === 'info');
+  if (mode === 'draft') {
+    return {
+      valid: errors.length === 0,
+      mode: 'draft',
+      issues,
+      stats: {
+        totalSteps,
+        errors: errors.length,
+        warnings: warnings.length,
+        info: info.length
+      }
+    };
+  }
+  // Strict mode: backward-compatible format
+  if (errors.length > 0) {
+    return errors.map(e => e.message);
+  }
+  // In strict mode, warnings and info are also treated as errors
+  const allIssues = issues.filter(i => i.severity !== 'info' || mode === 'strict');
+  if (allIssues.length > 0) {
+    return allIssues.map(e => e.message);
+  }
+  return [];
+}
+/**
+ * Detect circular dependencies and return as issue objects.
+ * @param {Array} steps
+ * @returns {Array<{stepId: string, message: string}>}
+ */
+function detectCyclesAsIssues(steps) {
+  const issues = [];
+  const stepMap = new Map(steps.map(s => [s.id, s]));
+  const adjList = new Map();
+  // Build adjacency list from template dependencies
+  for (const step of steps) {
+    const deps = extractDependencies(step.inputs || {});
+    if (step.condition) {
+      const condDeps = extractDependencies(step.condition);
+      for (const d of condDeps) deps.add(d);
+    }
+    if (step.forEach) {
+      const forDeps = extractDependencies(step.forEach);
+      for (const d of forDeps) deps.add(d);
+    }
+    adjList.set(step.id, deps);
+  }
+  // DFS cycle detection
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map(steps.map(s => [s.id, WHITE]));
+  function dfs(nodeId, path) {
+    color.set(nodeId, GRAY);
+    path.push(nodeId);
+    const neighbors = adjList.get(nodeId) || new Set();
+    for (const dep of neighbors) {
+      if (!stepMap.has(dep)) continue; // Unknown deps caught by other checks
+      if (color.get(dep) === GRAY) {
+        const cycleStart = path.indexOf(dep);
+        const cycle = path.slice(cycleStart).concat(dep);
+        issues.push({
+          stepId: cycle[0],
+          message: `Circular dependency: ${cycle.join(' -> ')}`
+        });
+        return;
+      }
+      if (color.get(dep) === WHITE) {
+        dfs(dep, path);
+      }
+    }
+    path.pop();
+    color.set(nodeId, BLACK);
+  }
+  for (const step of steps) {
+    if (color.get(step.id) === WHITE) {
+      dfs(step.id, []);
+    }
+  }
+  return issues;
 }
 /**