@scrymore/scry-deployer 0.2.1 → 0.3.0

package/bin/cli.js

@@ -18,6 +18,8 @@ const { runCoverageAnalysis, loadCoverageReport, extractCoverageSummary } = requ
 const { postPRComment } = require('../lib/pr-comment.js');
 const { runInit } = require('../lib/init.js');
 const { runUpdateWorkflows } = require('../lib/update-workflows.js');
+const { runQueueImageUpload } = require('../lib/imageUpload.js');
+const { runLocalImageProcessing } = require('../lib/localImageProcessing.js');
 
 async function runAnalysis(argv) {
     const logger = createLogger(argv);
@@ -123,9 +125,30 @@ async function runDeployment(argv) {
 
         await postPRComment(buildDeployResult(argv, coverageSummary, uploadResult), coverageSummary);
 
-        logger.success('\n🎉 Deployment successful! 🎉');
+        // Report only what actually completed. Uploading is synchronous;
+        // indexing is not. A build can fail in the queue seconds after this
+        // point — during one run the pipeline died 7s later on a revoked
+        // credential — and this command previously printed
+        // "Deployment successful" over it, sending people looking for the
+        // cause three steps downstream (ISSUES.md #4).
+        logger.success('\n✅ Upload complete.');
         logUploadLinks(argv, coverageSummary, uploadResult, logger);
 
+        if (uploadResult?.metadataUpload?.queued) {
+            logger.info(
+                '\n⏳ Indexing has been queued, not finished.\n' +
+                '   This command cannot confirm it succeeded. Components will not be\n' +
+                '   searchable until processing completes, and a failed build reports\n' +
+                '   nothing here. Before relying on search, confirm the build shows\n' +
+                "   processingStatus 'completed' rather than 'failed'."
+            );
+        } else if (uploadResult?.metadataUpload) {
+            logger.warn(
+                '\n⚠️  Metadata was uploaded but not queued for processing.\n' +
+                '   The Storybook is hosted, but its components are NOT being indexed.'
+            );
+        }
+
     } finally {
         // 4. Clean up the local archive
         if (fs.existsSync(outPath)) {
@@ -182,7 +205,6 @@ async function main() {
         environment: process.env.NODE_ENV || 'production',
     });
 
-    let config;
     try {
         const args = await yargs(hideBin(process.argv))
             .command('$0', 'Deploy Storybook static build', (yargs) => {
@@ -255,7 +277,7 @@ async function main() {
                     });
             }, async (argv) => {
                 // Load and merge configuration
-                config = loadConfig(argv);
+                const config = loadConfig(argv);
 
                 // Validate required fields
                 if (!config.dir) {
@@ -311,7 +333,7 @@ async function main() {
                     });
             }, async (argv) => {
                 // Load and merge configuration
-                config = loadConfig(argv);
+                const config = loadConfig(argv);
 
                 await runAnalysis(config);
             })
@@ -422,6 +444,97 @@ async function main() {
 
                 await runInit(initConfig);
             })
+            .command('upload-images', 'Upload a folder of images for search indexing', (yargs) => {
+                return yargs
+                    .option('dir', {
+                        describe: 'Path to the image directory',
+                        type: 'string',
+                        demandOption: true,
+                    })
+                    .option('project', {
+                        describe: 'Project name/identifier',
+                        type: 'string',
+                        demandOption: true,
+                    })
+                    .option('local', {
+                        describe: 'Process images locally instead of uploading to the queue',
+                        type: 'boolean',
+                        default: false,
+                    })
+                    .option('openai-api-key', {
+                        describe: 'OpenAI API key (for --local mode)',
+                        type: 'string',
+                    })
+                    .option('jina-api-key', {
+                        describe: 'Jina API key (for --local mode)',
+                        type: 'string',
+                    })
+                    .option('milvus-address', {
+                        describe: 'Milvus/Zilliz endpoint (for --local mode)',
+                        type: 'string',
+                    })
+                    .option('milvus-token', {
+                        describe: 'Milvus/Zilliz auth token (for --local mode)',
+                        type: 'string',
+                    })
+                    .option('milvus-collection', {
+                        describe: 'Milvus collection name (for --local mode)',
+                        type: 'string',
+                    })
+                    .option('api-key', {
+                        describe: 'API key for the deployment service (queue mode)',
+                        type: 'string',
+                    })
+                    .option('api-url', {
+                        describe: 'Base URL for the deployment service API (queue mode)',
+                        type: 'string',
+                    })
+                    .option('verbose', {
+                        describe: 'Enable verbose logging',
+                        type: 'boolean',
+                    });
+            }, async (argv) => {
+                const config = loadConfig(argv);
+
+                if (!config.dir) {
+                    throw new Error('--dir is required. Provide a path to the image directory.');
+                }
+
+                if (!fs.existsSync(config.dir)) {
+                    throw new Error(`Directory not found: ${config.dir}`);
+                }
+                if (!fs.lstatSync(config.dir).isDirectory()) {
+                    throw new Error(`Path is not a directory: ${config.dir}`);
+                }
+
+                if (config.local) {
+                    // Local mode: process images directly via LLM + embeddings + Milvus
+                    const requiredLocalKeys = {
+                        openaiApiKey: { flag: '--openai-api-key', env: 'OPENAI_API_KEY' },
+                        jinaApiKey: { flag: '--jina-api-key', env: 'JINA_API_KEY' },
+                        milvusAddress: { flag: '--milvus-address', env: 'MILVUS_ADDRESS' },
+                        milvusToken: { flag: '--milvus-token', env: 'MILVUS_TOKEN' },
+                        milvusCollection: { flag: '--milvus-collection', env: 'MILVUS_COLLECTION' },
+                    };
+
+                    const resolved = {};
+                    for (const [key, { flag, env }] of Object.entries(requiredLocalKeys)) {
+                        resolved[key] = config[key] || process.env[env];
+                        if (!resolved[key]) {
+                            throw new Error(`${flag} or ${env} env var is required for local mode`);
+                        }
+                    }
+
+                    await runLocalImageProcessing({
+                        dir: config.dir,
+                        project: config.project,
+                        ...resolved,
+                        verbose: config.verbose,
+                    });
+                } else {
+                    await runQueueImageUpload(config);
+                }
+            })
             .command('debug-sentry', 'Test Sentry integration by throwing an error', () => {}, () => {
                 throw new Error('Sentry debug error from scry-node CLI');
             })
@@ -432,7 +545,7 @@ async function main() {
             .parse();
 
     } catch (error) {
-        await handleError(error, config);
+        await handleError(error, error.config || {});
     }
 }
 

package/lib/apiClient.js

@@ -153,14 +153,15 @@ function validatePresignedUrl(presignedUrl) {
  * Upload a buffer to a presigned URL.
  *
  * @param {string} presignedUrl
- * @param {Buffer} buffer
+ * @param {Buffer|import('stream').Readable} data
  * @param {string} contentType
  * @returns {Promise<{status:number}>}
  */
-async function putToPresignedUrl(presignedUrl, buffer, contentType) {
-  logger.debug(`Starting PUT upload to presigned URL. Size: ${buffer.length} bytes, Content-Type: ${contentType}`);
+async function putToPresignedUrl(presignedUrl, data, contentType) {
+  const size = Buffer.isBuffer(data) ? `${data.length} bytes` : 'stream';
+  logger.debug(`Starting PUT upload to presigned URL. Size: ${size}, Content-Type: ${contentType}`);
   
-  const uploadResponse = await axios.put(presignedUrl, buffer, {
+  const uploadResponse = await axios.put(presignedUrl, data, {
     headers: {
       'Content-Type': contentType,
     },
@@ -321,7 +322,7 @@ async function uploadMetadataZip(apiClient, target, metadataZipPath, customLogge
     };
   } catch (error) {
     const message = error.response?.data?.error || error.message || 'Unknown error';
-    customLogger.warn(`Metadata ZIP upload failed: ${message}`);
+    customLogger.error(`Metadata ZIP upload failed: ${message}`);
     return { success: false, error: message };
   }
 }

package/lib/imageUpload.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { zipDirectory } = require('./archive.js');
+const { getApiClient, requestPresignedUrl, putToPresignedUrl } = require('./apiClient.js');
+const { createLogger } = require('./logger.js');
+
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg']);
+
+/**
+ * Recursively find image files in a directory.
+ * Excludes __MACOSX and hidden files.
+ *
+ * @param {string} dir
+ * @returns {string[]} Array of absolute file paths
+ */
+function findImageFiles(dir) {
+  const results = [];
+
+  function walk(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip hidden files/dirs and __MACOSX
+      if (entry.name.startsWith('.') || entry.name === '__MACOSX') continue;
+
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (IMAGE_EXTENSIONS.has(ext)) {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+/**
+ * Run queue-mode image upload.
+ * ZIPs the directory, uploads via presigned URL, signals completion.
+ *
+ * @param {object} config
+ * @param {string} config.dir - Path to image directory
+ * @param {string} config.project - Project identifier
+ * @param {string} config.apiKey - API key
+ * @param {string} config.apiUrl - API base URL
+ * @param {boolean} [config.verbose]
+ */
+async function runQueueImageUpload(config) {
+  const logger = createLogger(config);
+
+  // 1. Validate directory and count images
+  logger.info('Scanning for images...');
+  const imageFiles = findImageFiles(config.dir);
+  if (imageFiles.length === 0) {
+    throw new Error(`No image files (.png, .jpg, .jpeg) found in: ${config.dir}`);
+  }
+  logger.success(`Found ${imageFiles.length} images`);
+
+  const zipPath = path.join(os.tmpdir(), `scry-image-upload-${Date.now()}.zip`);
+
+  try {
+    // 2. ZIP the directory
+    logger.info('Creating ZIP archive...');
+    await zipDirectory(config.dir, zipPath);
+    const zipSize = fs.statSync(zipPath).size;
+    logger.success(`ZIP created: ${(zipSize / 1024 / 1024).toFixed(1)} MB`);
+    logger.debug(`ZIP path: ${zipPath}`);
+
+    // 3. Initialize upload — get presigned URL and uploadId
+    logger.info('Initializing upload...');
+    const apiClient = getApiClient(config.apiUrl, config.apiKey);
+
+    const initResponse = await apiClient.post(
+      `/upload-images/${config.project}`,
+      { imageCount: imageFiles.length },
+      { headers: { 'Content-Type': 'application/json' } }
+    );
+
+    const { uploadId, uploadNumber, presignedUrl, zipKey } = initResponse.data;
+    logger.info(`Upload #${uploadNumber} initialized (id: ${uploadId})`);
+    logger.debug(`Presigned URL received, zipKey: ${zipKey}`);
+
+    // 4. PUT ZIP to presigned URL (stream to avoid loading entire file into memory)
+    logger.info('Uploading ZIP to storage...');
+    const fileStream = fs.createReadStream(zipPath);
+    await putToPresignedUrl(presignedUrl, fileStream, 'application/zip');
+    logger.success('ZIP uploaded to storage');
+
+    // 5. Signal completion
+    logger.info('Signaling upload complete...');
+    await apiClient.post(
+      `/upload-images/${config.project}/complete`,
+      { uploadId, zipKey },
+      { headers: { 'Content-Type': 'application/json' } }
+    );
+
+    logger.success(`\nUpload #${uploadNumber} queued for processing (${imageFiles.length} images)`);
+    logger.info(`Upload ID: ${uploadId}`);
+
+    return { uploadId, uploadNumber, imageCount: imageFiles.length };
+  } finally {
+    // 6. Cleanup
+    if (fs.existsSync(zipPath)) {
+      fs.unlinkSync(zipPath);
+      logger.debug(`Cleaned up temporary ZIP: ${zipPath}`);
+    }
+  }
+}
+
+module.exports = {
+  findImageFiles,
+  runQueueImageUpload,
+};

package/lib/localImageProcessing.js

@@ -0,0 +1,663 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { XMLParser } = require('fast-xml-parser');
+const { createLogger } = require('./logger.js');
+const { findImageFiles } = require('./imageUpload.js');
+
+// ───────────────────────── XML Parsing ─────────────────────────
+
+const xmlParser = new XMLParser({
+  ignoreAttributes: true,
+  trimValues: true,
+});
+
+function parseXmlToJson(xmlContent) {
+  const wrapped = `<root>${xmlContent}</root>`;
+  const parsed = xmlParser.parse(wrapped);
+  const root = parsed.root || {};
+
+  // Navigate into any wrapper element (e.g. component-documentation)
+  const doc = root['component-documentation'] || root;
+
+  const result = {};
+
+  if (doc['screen-name']) result.screenName = String(doc['screen-name']).trim();
+  if (doc.description) result.description = String(doc.description).trim();
+
+  if (doc.tags) {
+    const rawTags = doc.tags.tag;
+    result.tags = Array.isArray(rawTags)
+      ? rawTags.map(t => String(t).trim())
+      : rawTags ? [String(rawTags).trim()] : [];
+  }
+
+  if (doc['search-queries']) {
+    const rawQueries = doc['search-queries'].query;
+    result.searchQueries = Array.isArray(rawQueries)
+      ? rawQueries.map(q => String(q).trim())
+      : rawQueries ? [String(rawQueries).trim()] : [];
+  }
+
+  return result;
+}
+
+function parseBatchXmlResponse(xmlResponse, count) {
+  const wrapped = `<root>${xmlResponse}</root>`;
+  const parsed = xmlParser.parse(wrapped);
+  const root = parsed.root || {};
+  const results = [];
+
+  for (let i = 0; i < count; i++) {
+    const key = `component-${i + 1}`;
+    const component = root[key] || (root['batch-analysis'] && root['batch-analysis'][key]);
+    if (!component) {
+      results.push({});
+      continue;
+    }
+    // Re-serialize the component back to extract fields
+    const result = {};
+    if (component['screen-name']) result.screenName = String(component['screen-name']).trim();
+    if (component.description) result.description = String(component.description).trim();
+    if (component.tags) {
+      const rawTags = component.tags.tag;
+      result.tags = Array.isArray(rawTags)
+        ? rawTags.map(t => String(t).trim())
+        : rawTags ? [String(rawTags).trim()] : [];
+    }
+    if (component['search-queries']) {
+      const rawQueries = component['search-queries'].query;
+      result.searchQueries = Array.isArray(rawQueries)
+        ? rawQueries.map(q => String(q).trim())
+        : rawQueries ? [String(rawQueries).trim()] : [];
+    }
+    results.push(result);
+  }
+
+  return results;
+}
+
+// ───────────────────────── Prompt ─────────────────────────
+
+const IMAGE_UPLOAD_INSPECTOR_PROMPT = `# UI Screenshot Documentation Instructions
+
+## Overview
+You will analyze UI screenshots (mobile app screens, web pages, or other user interface captures) and generate standardized documentation in XML format consisting of a screen name, description, tags, and search queries.
+
+## Input Materials
+- **Screenshot**: Visual representation of a UI screen
+
+## Output Format (XML Structure)
+
+\`\`\`xml
+<component-documentation>
+  <screen-name>
+    [Short, descriptive name for this screen, e.g. "Home Feed", "Login Page", "Settings Menu"]
+  </screen-name>
+  <description>
+    [2-3 sentence description following the template below]
+  </description>
+  <tags>
+    <tag>Screen Type</tag>
+    <tag>App Category</tag>
+    <tag>Visual Descriptor</tag>
+    <tag>UI Pattern</tag>
+    <tag>Functional Category</tag>
+    <!-- 8-15 total tags -->
+  </tags>
+  <search-queries>
+    <query>UI screen type keyword</query>
+    <query>Visual description phrase</query>
+    <query>User-friendly search phrase</query>
+    <query>Functional description</query>
+    <query>Design pattern query</query>
+    <!-- 5-7 total queries -->
+  </search-queries>
+</component-documentation>
+\`\`\`
+
+## Content Guidelines
+
+### 1. Screen Name (short label)
+- A concise, human-readable name for the screen
+- Examples: "Home Feed", "Product Detail", "Search Results", "User Profile", "Checkout Flow"
+
+### 2. Description (2-3 sentences)
+- **First sentence**: Screen type and primary purpose
+- **Second sentence**: Visual characteristics and key UI elements
+- **Third sentence** (if needed): Notable features or interaction patterns
+
+**Template**: "This is a [screen type] that [primary function]. It features [key UI elements and visual characteristics]. [Additional notable features]."
+
+### 3. Tags (8-15 keywords)
+List relevant tags in this priority order:
+1. Screen type (Home, Settings, Profile, etc.)
+2. App category (Social, E-commerce, Productivity, etc.)
+3. Visual descriptors (colors, layout style)
+4. UI patterns (tab bar, card layout, list view, etc.)
+5. Functional categories (navigation, content, form, etc.)
+6. Platform indicators (iOS, Android, Web)
+
+### 4. Search Queries (5-7 phrases)
+Create search-friendly phrases without quotes:
+- Include screen type + descriptive terms
+- Use common UI/UX terminology
+- Consider both technical and casual language
+- Include design pattern references
+
+## Quality Standards
+- **Accuracy**: Description must match the visual exactly
+- **Completeness**: Include all significant visual and functional aspects
+- **Consistency**: Use the same terminology and format for similar screens
+- **Searchability**: Tags and queries should help users find this screen easily
+- **Valid XML**: Ensure all tags are properly closed and content is escaped if needed
+
+Remember: Accuracy and consistency are critical. When in doubt, describe exactly what you see in the screenshot.`;
+
+// ───────────────────────── Batch Processor ─────────────────────────
+
+async function processBatches(items, batchSize, maxConcurrent, processFn, options = {}) {
+  if (items.length === 0) return [];
+
+  const batches = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    batches.push(items.slice(i, i + batchSize));
+  }
+
+  const results = [];
+  let batchIndex = 0;
+  let completedItems = 0;
+
+  const processBatch = async () => {
+    while (batchIndex < batches.length) {
+      const currentIndex = batchIndex++;
+      const batch = batches[currentIndex];
+
+      if (options.delayMs && currentIndex > 0) {
+        await new Promise(resolve => setTimeout(resolve, options.delayMs));
+      }
+
+      const batchResults = await processFn(batch);
+      results.push(...batchResults);
+      completedItems += batch.length;
+
+      if (options.onProgress) {
+        options.onProgress(completedItems, items.length);
+      }
+    }
+  };
+
+  const workers = Array.from(
+    { length: Math.min(maxConcurrent, batches.length) },
+    () => processBatch()
+  );
+  await Promise.all(workers);
+
+  return results;
+}
+
+// ───────────────────────── Vector Utils ─────────────────────────
+
+const DEFAULT_TARGET_DIM = 2048;
+
+function padVector(vector, targetDim) {
+  if (!vector || !Array.isArray(vector)) {
+    return new Array(targetDim).fill(0);
+  }
+  if (vector.length === targetDim) return vector;
+  if (vector.length > targetDim) return vector.slice(0, targetDim);
+  const padded = [...vector];
+  while (padded.length < targetDim) padded.push(0);
+  return padded;
+}
+
+// ───────────────────────── LLM Inspector ─────────────────────────
+
+function createImageBatchPrompt(count) {
+  const batchInstructions = `
+
+## Batch Analysis Instructions
+
+You will analyze ${count} UI screenshot(s) in a single request.
+
+**Format your response as:**
+\`\`\`xml
+<batch-analysis>
+  <component-1>
+    <screen-name>...</screen-name>
+    <description>...</description>
+    <tags><tag>...</tag>...</tags>
+    <search-queries><query>...</query>...</search-queries>
+  </component-1>
+  ${count > 1 ? `<component-2>...</component-2>` : ''}
+  ${count > 2 ? `<!-- ... up to component-${count} -->` : ''}
+</batch-analysis>
+\`\`\`
+
+- Component numbers must match the image order exactly (1st image = component-1, etc.)
+- Each screenshot must have complete documentation including screen-name
+`;
+
+  return IMAGE_UPLOAD_INSPECTOR_PROMPT + batchInstructions;
+}
+
+async function batchInspectImages(images, apiKey, options = {}) {
+  const model = options.model || 'gpt-5-mini';
+  const maxRetries = options.maxRetries ?? 2;
+
+  const batchPrompt = createImageBatchPrompt(images.length);
+
+  const content = [
+    {
+      type: 'text',
+      text: batchPrompt + `\n\nAnalyze these ${images.length} UI screenshots and provide numbered documentation for each.`,
+    },
+  ];
+
+  for (const image of images) {
+    const base64 = image.screenshotBytes.toString('base64');
+    const ext = image.filename.toLowerCase().endsWith('.png') ? 'png' : 'jpeg';
+    content.push({
+      type: 'image_url',
+      image_url: {
+        url: `data:image/${ext};base64,${base64}`,
+        detail: 'high',
+      },
+    });
+  }
+
+  let lastError = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch('https://api.openai.com/v1/chat/completions', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model,
+          max_completion_tokens: 1500 * images.length,
+          messages: [{ role: 'user', content }],
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`OpenAI API error ${response.status}: ${errorText}`);
+      }
+
+      const data = await response.json();
+      const xmlResponse = data.choices?.[0]?.message?.content;
+
+      if (!xmlResponse) {
+        throw new Error('No response content from OpenAI API');
+      }
+
+      const parsedComponents = parseBatchXmlResponse(xmlResponse, images.length);
+
+      return parsedComponents.map((parsed, i) => ({
+        screenName: parsed.screenName || images[i].filename.replace(/\.[^.]+$/, ''),
+        description: parsed.description || '',
+        tags: parsed.tags || [],
+        searchQueries: parsed.searchQueries || [],
+        metadata: {
+          imagePath: images[i].screenshotPath,
+          model,
+          timestamp: new Date().toISOString(),
+          batchIndex: i + 1,
+        },
+      }));
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      console.error(`[LLM] Image batch inspection attempt ${attempt + 1} failed:`, lastError.message);
+
+      if (attempt < maxRetries) {
+        await new Promise(resolve => setTimeout(resolve, 2000 * (attempt + 1)));
+      }
+    }
+  }
+
+  throw lastError || new Error('Image batch inspection failed');
+}
+
+// ───────────────────────── Searchable Text ─────────────────────────
+
+function createSearchableTextFromImage(inspection) {
+  if (!inspection) return '';
+
+  const parts = [
+    inspection.screenName || '',
+    inspection.description || '',
+    ...(inspection.tags || []).map(tag => `${tag} element`),
+    ...(inspection.searchQueries || []),
+    'mobile app screen',
+    'UI screenshot',
+    'user interface',
+  ];
+
+  return parts
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// ───────────────────────── Embedding Generator ─────────────────────────
+
+async function callJinaEmbeddings(input, apiKey, maxRetries = 4) {
+  let lastError = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch('https://api.jina.ai/v1/embeddings', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: 'jina-embeddings-v4',
+          task: 'retrieval.document',
+          input,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        const is429 = response.status === 429;
+        const err = new Error(`Jina API error ${response.status}: ${errorText}`);
+        if (is429 && attempt < maxRetries) {
+          const backoff = 15000 * Math.pow(2, attempt);
+          console.warn(`[EMBEDDINGS] Rate limited, waiting ${backoff / 1000}s before retry...`);
+          await new Promise(resolve => setTimeout(resolve, backoff));
+          lastError = err;
+          continue;
+        }
+        throw err;
+      }
+
+      const data = await response.json();
+      if (!data.data) {
+        throw new Error('No embedding data in Jina API response');
+      }
+      return data.data.map(d => d.embedding);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      console.error(`[EMBEDDINGS] Attempt ${attempt + 1} failed:`, lastError.message);
+
+      if (attempt < maxRetries) {
+        await new Promise(resolve => setTimeout(resolve, 2000 * (attempt + 1)));
+      }
+    }
+  }
+
+  throw lastError || new Error('Embedding generation failed');
+}
+
+async function generateImageEmbeddings(imageBuffers, apiKey) {
+  const input = imageBuffers.map(buf => ({
+    image: `data:image/png;base64,${buf.toString('base64')}`,
+  }));
+  return callJinaEmbeddings(input, apiKey);
+}
+
+async function generateTextEmbeddings(texts, apiKey) {
+  const input = texts.map(text => ({ text }));
+  return callJinaEmbeddings(input, apiKey);
+}
+
+// ───────────────────────── Vector Inserter ─────────────────────────
+
+function transformImageData(image, index, projectId, uploadId, targetDim) {
+  const timestamp = Date.now();
+
+  return {
+    primary_key: crypto.randomUUID(),
+    text_embedding: padVector(image.textEmbedding, targetDim),
+    image_embedding: padVector(image.imageEmbedding, targetDim),
+    searchable_text: (image.searchableText || '').substring(0, 65535),
+    component_name: image.screenName || 'unknown',
+    project_id: projectId,
+    timestamp,
+    json_content: {
+      source_type: 'upload',
+      uploadId,
+      filename: image.filename,
+      screenName: image.screenName,
+      screenshotPath: image.screenshotPath,
+      inspection: image.inspection,
+    },
+  };
+}
+
+async function insertImageVectors(images, projectId, uploadId, milvusConfig, options = {}) {
+  const batchSize = options.batchSize || 50;
+  const maxRetries = options.maxRetries || 1;
+  const targetDim = options.targetDim || DEFAULT_TARGET_DIM;
+  let totalInserted = 0;
+
+  for (let i = 0; i < images.length; i += batchSize) {
+    const batch = images.slice(i, i + batchSize);
+    const records = batch.map((image, idx) => transformImageData(image, i + idx, projectId, uploadId, targetDim));
+
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const base = milvusConfig.address.startsWith('https://') || milvusConfig.address.startsWith('http://')
+          ? milvusConfig.address
+          : `https://${milvusConfig.address}`;
+        const url = `${base.replace(/\/+$/, '')}/v2/vectordb/entities/insert`;
+
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${milvusConfig.token}`,
+          },
+          body: JSON.stringify({
+            collectionName: milvusConfig.collectionName,
+            data: records,
+          }),
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(`Milvus HTTP error ${response.status}: ${errorText}`);
+        }
+
+        const result = await response.json();
+
+        if (result.code && result.code !== 0) {
+          throw new Error(`Milvus API error (code ${result.code}): ${result.message || JSON.stringify(result)}`);
+        }
+
+        const insertCount = result.data?.insertCount ?? 0;
+        totalInserted += insertCount;
+        lastError = null;
+        break;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        console.error(`[MILVUS] Insert attempt ${attempt + 1} failed:`, lastError.message);
+
+        if (attempt < maxRetries) {
+          await new Promise(resolve => setTimeout(resolve, 2000));
+        }
+      }
+    }
+
+    if (lastError) throw lastError;
+  }
+
+  return { insertCount: totalInserted };
+}
+
+// ───────────────────────── Orchestrator ─────────────────────────
+
+/**
+ * Run the full local image processing pipeline.
+ * Replicates the worker processUpload() flow but reads from local disk.
+ *
+ * @param {object} config
+ * @param {string} config.dir - Path to image directory
+ * @param {string} config.project - Project identifier
+ * @param {string} config.openaiApiKey - OpenAI API key
+ * @param {string} config.jinaApiKey - Jina API key
+ * @param {string} config.milvusAddress - Milvus/Zilliz endpoint
+ * @param {string} config.milvusToken - Milvus/Zilliz auth token
+ * @param {string} config.milvusCollection - Milvus collection name
+ * @param {boolean} [config.verbose]
+ */
+async function runLocalImageProcessing(config) {
+  const logger = createLogger(config);
+  const startTime = Date.now();
+  const elapsed = () => `${((Date.now() - startTime) / 1000).toFixed(1)}s`;
+
+  // Generate a local upload ID
+  const uploadId = `local-${Date.now()}`;
+
+  logger.info('=== Local Image Processing Pipeline ===');
+  logger.info(`Project: ${config.project}`);
+  logger.info(`Upload ID: ${uploadId}`);
+
+  // Step 1: Find images
+  logger.info('Step 1: Scanning for images...');
+  const imageFiles = findImageFiles(config.dir);
+  if (imageFiles.length === 0) {
+    throw new Error(`No image files (.png, .jpg, .jpeg) found in: ${config.dir}`);
+  }
+  logger.success(`Found ${imageFiles.length} images (${elapsed()})`);
+
+  // Build image items with file bytes
+  const images = imageFiles.map(filePath => {
+    const relativePath = path.relative(config.dir, filePath);
+    return {
+      filename: path.basename(filePath),
+      screenshotPath: relativePath,
+      screenshotBytes: fs.readFileSync(filePath),
+    };
+  });
+
+  // Step 2: LLM Vision Inspection
+  logger.info(`Step 2: LLM inspection for ${images.length} images (batch=5, concurrency=2)...`);
+  const inspectionResults = await processBatches(
+    images,
+    5,
+    2,
+    async (batch) => batchInspectImages(batch, config.openaiApiKey),
+    {
+      delayMs: 2000,
+      onProgress: (done, total) => logger.debug(`  LLM inspection: ${done}/${total} images`),
+    }
+  );
+  logger.success(`LLM inspection complete (${elapsed()})`);
+
+  // Step 3: Create searchable text
+  logger.info('Step 3: Creating searchable text...');
+  const searchableTexts = inspectionResults.map(inspection => createSearchableTextFromImage(inspection));
+  logger.success(`Searchable text created (${elapsed()})`);
+
+  // Step 4: Generate image embeddings
+  logger.info(`Step 4: Generating image embeddings (batch=3, delay=3s)...`);
+  const imageEmbeddings = await processBatches(
+    images.map(img => img.screenshotBytes),
+    3,
+    1,
+    async (batch) => generateImageEmbeddings(batch, config.jinaApiKey),
+    {
+      delayMs: 3000,
+      onProgress: (done, total) => logger.debug(`  Image embeddings: ${done}/${total}`),
+    }
+  );
+  logger.success(`Image embeddings complete (${elapsed()})`);
+
+  // Step 5: Generate text embeddings
+  logger.info(`Step 5: Generating text embeddings (batch=5, delay=2s)...`);
+  const textEmbeddings = await processBatches(
+    searchableTexts,
+    5,
+    1,
+    async (batch) => generateTextEmbeddings(batch, config.jinaApiKey),
+    {
+      delayMs: 2000,
+      onProgress: (done, total) => logger.debug(`  Text embeddings: ${done}/${total}`),
+    }
+  );
+  logger.success(`Text embeddings complete (${elapsed()})`);
+
+  // Step 6: Assemble
+  logger.info('Step 6: Assembling processed images...');
+  const processedImages = [];
+  let failedCount = 0;
+
+  for (let i = 0; i < images.length; i++) {
+    const image = images[i];
+    const inspection = inspectionResults[i];
+    const searchableText = searchableTexts[i];
+    const imageEmbedding = imageEmbeddings[i];
+    const textEmbedding = textEmbeddings[i];
+
+    if (!inspection || !imageEmbedding || !textEmbedding) {
+      failedCount++;
+      continue;
+    }
+
+    processedImages.push({
+      filename: image.filename,
+      screenName: inspection.screenName,
+      screenshotPath: image.screenshotPath,
+      inspection,
+      searchableText,
+      imageEmbedding,
+      textEmbedding,
+    });
+  }
+  logger.success(`Assembled: ${processedImages.length} ok, ${failedCount} failed (${elapsed()})`);
+
+  // Step 7: Insert into Milvus
+  if (processedImages.length > 0) {
+    logger.info(`Step 7: Inserting ${processedImages.length} vectors into Milvus...`);
+    const insertResult = await insertImageVectors(
+      processedImages,
+      config.project,
+      uploadId,
+      {
+        address: config.milvusAddress,
+        token: config.milvusToken,
+        collectionName: config.milvusCollection,
+      }
+    );
+    logger.success(`Milvus insert complete: ${insertResult.insertCount} records (${elapsed()})`);
+  } else {
+    logger.info('Step 7: No images to insert into Milvus');
+  }
+
+  // Summary
+  const status = failedCount === 0
+    ? 'completed'
+    : processedImages.length > 0
+      ? 'partial'
+      : 'failed';
+
+  logger.success(`\n=== Processing Complete (${elapsed()}) ===`);
+  logger.info(`Status: ${status}`);
+  logger.info(`Processed: ${processedImages.length}/${images.length} images`);
+  if (failedCount > 0) logger.info(`Failed: ${failedCount} images`);
+  logger.info(`Upload ID: ${uploadId}`);
+
+  return {
+    uploadId,
+    projectId: config.project,
+    totalImages: images.length,
+    processedImages: processedImages.length,
+    failedImages: failedCount,
+    status,
+  };
+}
+
+module.exports = {
+  runLocalImageProcessing,
+};

package/lib/logger.js

@@ -5,7 +5,7 @@ const chalk = require('chalk');
  * The logger's behavior is controlled by the arguments passed to the CLI.
  * @param {object} argv The arguments object from yargs.
  * @param {boolean} argv.verbose Whether to enable verbose (debug) logging.
- * @returns {{info: Function, error: Function, debug: Function, success: Function}}
+ * @returns {{info: Function, warn: Function, error: Function, debug: Function, success: Function}}
  */
 function createLogger({ verbose = false }) {
   const Sentry = require('@sentry/node');
@@ -31,6 +31,21 @@ function createLogger({ verbose = false }) {
       console.log(chalk.green(message));
     },
 
+    /**
+     * Logs a warning: something the operator must act on, but which did not
+     * fail the command. Distinct from error() so it does not read as a failed
+     * deployment.
+     * @param {string} message The message to log.
+     */
+    warn: (message) => {
+      console.warn(chalk.yellow(message));
+      Sentry.addBreadcrumb({
+        category: 'log',
+        message: message,
+        level: 'warning',
+      });
+    },
+
     /**
      * Logs an error message.
      * @param {string} message The message to log.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrymore/scry-deployer",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A CLI to automate the deployment of Storybook static builds.",
   "main": "index.js",
   "bin": {
@@ -43,6 +43,7 @@
     "axios": "^1.12.2",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
+    "fast-xml-parser": "^5.5.7",
     "form-data": "^4.0.0",
     "inquirer": "^8.2.6",
     "open": "^8.4.2",