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

voyageai-cli 1.30.0 → 1.30.2

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 (82) hide show

package/README.md +4 -4
package/package.json +1 -1
package/src/cli.js +8 -0
package/src/commands/about.js +3 -3
package/src/commands/chat.js +32 -11
package/src/commands/code-search.js +751 -0
package/src/commands/doctor.js +1 -1
package/src/commands/export.js +124 -0
package/src/commands/import.js +195 -0
package/src/commands/index-workspace.js +243 -0
package/src/commands/mcp-server.js +113 -3
package/src/commands/playground.js +120 -4
package/src/commands/quickstart.js +4 -4
package/src/commands/workflow.js +132 -65
package/src/lib/catalog.js +4 -2
package/src/lib/code-search.js +315 -0
package/src/lib/codegen.js +1 -1
package/src/lib/explanations.js +3 -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/github.js +226 -0
package/src/lib/template-engine.js +154 -20
package/src/lib/workflow-builder.js +753 -0
package/src/lib/workflow-formatters.js +454 -0
package/src/lib/workflow-input-cache.js +111 -0
package/src/lib/workflow-scaffold.js +1 -1
package/src/lib/workflow.js +297 -28
package/src/mcp/install.js +280 -7
package/src/mcp/schemas/index.js +170 -0
package/src/mcp/server.js +19 -4
package/src/mcp/tools/authoring.js +662 -0
package/src/mcp/tools/code-search.js +620 -0
package/src/mcp/tools/ingest.js +2 -5
package/src/mcp/tools/retrieval.js +2 -15
package/src/mcp/tools/workspace.js +452 -0
package/src/mcp/utils.js +20 -0
package/src/playground/announcements.md +52 -5
package/src/playground/help/workflow-nodes.js +127 -2
package/src/playground/index.html +17109 -12438
package/src/playground/vendor/mermaid.min.js +2811 -0
package/src/workflows/code-review.json +110 -0
package/src/workflows/cost-analysis.json +5 -0
package/src/workflows/rag-chat.json +165 -0
package/src/workflows/tests/code-review.fresh-index.test.json +83 -0
package/src/workflows/tests/code-review.happy-path.test.json +121 -0
package/src/workflows/tests/code-review.no-question.test.json +70 -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/png-export.js ADDED Viewed

@@ -0,0 +1,96 @@
+'use strict';
+/**
+ * Render PNG from Mermaid diagram via Playwright.
+ *
+ * @param {object} normalized
+ * @param {object} options
+ * @param {string} [options.resolution='2x'] - '1x' | '2x' | '3x'
+ * @param {string} [options.background='transparent'] - 'transparent' | 'dark' | 'light'
+ * @param {boolean} [options.includeWatermark=true]
+ * @param {boolean} [options.fitToContent=true]
+ * @returns {Promise<{ content: Buffer, mimeType: string }>}
+ */
+async function renderPng(normalized, options = {}) {
+  // If raw PNG buffer provided (from Electron canvas capture)
+  if (normalized._pngBuffer) {
+    return { content: normalized._pngBuffer, mimeType: 'image/png' };
+  }
+  const { workflowToMermaid } = require('./mermaid-export');
+  if (normalized._context !== 'workflow' && normalized._context !== 'benchmark') {
+    throw new Error(`PNG 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 PNG rendering');
+  }
+  const png = await renderMermaidToPng(mermaidSrc, options);
+  return { content: png, mimeType: 'image/png' };
+}
+/**
+ * Render Mermaid syntax to PNG using Playwright.
+ */
+async function renderMermaidToPng(mermaidSrc, options = {}) {
+  const { chromium } = require('playwright');
+  const resolution = options.resolution || '2x';
+  const scale = parseInt(resolution) || 2;
+  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({
+      deviceScaleFactor: scale,
+    });
+    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;padding:16px;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 fitToContent = options.fitToContent !== false;
+    let screenshotOpts = { type: 'png' };
+    if (background === 'transparent') {
+      screenshotOpts.omitBackground = true;
+    }
+    if (fitToContent) {
+      const svgEl = await page.$('svg');
+      const box = await svgEl.boundingBox();
+      if (box) {
+        screenshotOpts.clip = {
+          x: Math.max(0, box.x - 8),
+          y: Math.max(0, box.y - 8),
+          width: box.width + 16,
+          height: box.height + 16,
+        };
+      }
+    }
+    const buffer = await page.screenshot(screenshotOpts);
+    return buffer;
+  } finally {
+    await browser.close();
+  }
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+module.exports = { renderPng, renderMermaidToPng };

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/github.js ADDED Viewed

@@ -0,0 +1,226 @@
+'use strict';
+/**
+ * GitHub API fetcher for remote repository indexing.
+ * Uses native fetch (Node 18+) — no axios.
+ */
+/**
+ * Get GitHub auth token from env or vai config.
+ * @returns {string|null}
+ */
+function getAuthToken() {
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+  try {
+    const { getConfigValue } = require('./config');
+    return getConfigValue('github.token') || null;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Check if a source string is a GitHub URL or shorthand.
+ * @param {string} source
+ * @returns {boolean}
+ */
+function isGitHubUrl(source) {
+  if (!source || typeof source !== 'string') return false;
+  if (source.includes('github.com')) return true;
+  // owner/repo shorthand (must have exactly one slash, no spaces, no path separators at start)
+  if (/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(source)) return true;
+  return false;
+}
+/**
+ * Parse a GitHub URL into owner and repo.
+ * Supports: https://github.com/owner/repo, github.com/owner/repo, owner/repo
+ * @param {string} source
+ * @returns {{ owner: string, repo: string }}
+ */
+function parseGitHubUrl(source) {
+  if (!source) throw new Error('Empty GitHub source');
+  // Strip trailing .git
+  source = source.replace(/\.git$/, '');
+  // Full URL
+  const urlMatch = source.match(/github\.com[/:]([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)/);
+  if (urlMatch) {
+    return { owner: urlMatch[1], repo: urlMatch[2] };
+  }
+  // owner/repo shorthand
+  const shortMatch = source.match(/^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)$/);
+  if (shortMatch) {
+    return { owner: shortMatch[1], repo: shortMatch[2] };
+  }
+  throw new Error(`Cannot parse GitHub URL: ${source}`);
+}
+/**
+ * Make a GitHub API request with optional auth and backoff.
+ * @param {string} url
+ * @param {string|null} token
+ * @param {number} [retries=3]
+ * @returns {Promise<object>}
+ */
+async function githubFetch(url, token, retries = 3) {
+  const headers = { 'Accept': 'application/vnd.github.v3+json' };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const res = await fetch(url, { headers });
+    if (res.status === 403) {
+      const remaining = res.headers.get('x-ratelimit-remaining');
+      const resetAt = res.headers.get('x-ratelimit-reset');
+      if (remaining === '0' && resetAt) {
+        const waitMs = Math.max(0, (parseInt(resetAt) * 1000) - Date.now()) + 1000;
+        if (attempt < retries && waitMs < 120000) {
+          await new Promise(r => setTimeout(r, waitMs));
+          continue;
+        }
+        throw new Error(`GitHub rate limit exceeded. Resets at ${new Date(parseInt(resetAt) * 1000).toISOString()}`);
+      }
+    }
+    if (res.status === 404) {
+      throw new Error(`GitHub resource not found: ${url}. Is the repo public or do you have a valid GITHUB_TOKEN?`);
+    }
+    if (!res.ok) {
+      if (attempt < retries) {
+        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
+        continue;
+      }
+      throw new Error(`GitHub API error ${res.status}: ${await res.text()}`);
+    }
+    return res.json();
+  }
+}
+/**
+ * Fetch the recursive file tree for a repo.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} branch
+ * @param {string|null} token
+ * @returns {Promise<Array<{path: string, size: number, sha: string}>>}
+ */
+async function fetchRepoTree(owner, repo, branch, token) {
+  const data = await githubFetch(
+    `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`,
+    token
+  );
+  if (!data.tree) throw new Error('No tree data returned from GitHub');
+  return data.tree
+    .filter(entry => entry.type === 'blob')
+    .map(entry => ({ path: entry.path, size: entry.size || 0, sha: entry.sha }));
+}
+/**
+ * Fetch file contents from a GitHub repo.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} filePath
+ * @param {string} branch
+ * @param {string|null} token
+ * @returns {Promise<string>}
+ */
+async function fetchFileContents(owner, repo, filePath, branch, token) {
+  const data = await githubFetch(
+    `https://api.github.com/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}`,
+    token
+  );
+  if (data.encoding === 'base64' && data.content) {
+    return Buffer.from(data.content, 'base64').toString('utf-8');
+  }
+  throw new Error(`Unexpected encoding for ${filePath}: ${data.encoding}`);
+}
+/**
+ * Fetch changed files between two commits.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} baseSha
+ * @param {string} headSha
+ * @param {string|null} token
+ * @returns {Promise<Array<{filename: string, status: string}>>}
+ */
+async function fetchChangedFiles(owner, repo, baseSha, headSha, token) {
+  const data = await githubFetch(
+    `https://api.github.com/repos/${owner}/${repo}/compare/${baseSha}...${headSha}`,
+    token
+  );
+  return (data.files || []).map(f => ({ filename: f.filename, status: f.status }));
+}
+/**
+ * Fetch multiple files concurrently with a pool limit.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string[]} filePaths
+ * @param {string} branch
+ * @param {string|null} token
+ * @param {number} [concurrency=5]
+ * @returns {Promise<Array<{path: string, content: string}|{path: string, error: string}>>}
+ */
+async function fetchFilesBatch(owner, repo, filePaths, branch, token, concurrency = 5) {
+  const results = [];
+  let i = 0;
+  async function worker() {
+    while (i < filePaths.length) {
+      const idx = i++;
+      const fp = filePaths[idx];
+      try {
+        const content = await fetchFileContents(owner, repo, fp, branch, token);
+        results[idx] = { path: fp, content };
+      } catch (err) {
+        results[idx] = { path: fp, error: err.message };
+      }
+    }
+  }
+  const workers = [];
+  for (let w = 0; w < Math.min(concurrency, filePaths.length); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+/**
+ * Resolve a branch name to its HEAD commit SHA.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} branch
+ * @param {string|null} token
+ * @returns {Promise<string>} commit SHA
+ */
+async function resolveCommitSha(owner, repo, branch, token) {
+  const data = await githubFetch(
+    `https://api.github.com/repos/${owner}/${repo}/commits/${branch}`,
+    token
+  );
+  return data.sha;
+}
+module.exports = {
+  getAuthToken,
+  isGitHubUrl,
+  parseGitHubUrl,
+  fetchRepoTree,
+  fetchFileContents,
+  fetchChangedFiles,
+  fetchFilesBatch,
+  resolveCommitSha,
+};