feat(cli): VIDEO-022 - Process video arguments with validation

memory-bank/progress.md

@@ -1,5 +1,58 @@
 # Project Progress
 
+## 🎬 **VIDEO-022: CLI VIDEO ARGUMENT PROCESSING** (2026-03-22)
+
+### **🏆 LATEST ACHIEVEMENT: COMPLETE VIDEO CLI INTEGRATION**
+
+**Objective**: Process video arguments in CLI commands to integrate with the SDK's video processing pipeline
+**Achievement**: Implemented comprehensive video file validation and processing in CLI commands
+**Impact**: Users can now analyze video files from CLI with proper error handling and validation
+**Ticket**: VIDEO-022
+
+**Core Implementation**:
+- ✅ **Video File Validation**: Added `validateVideoFiles()` with existence, extension, and permission checks
+- ✅ **Supported Formats**: `.mp4, .webm, .mov, .avi, .mkv, .m4v, .wmv, .flv`
+- ✅ **URL Bypass**: HTTP(S), file://, and data: URIs skip local validation (handled by SDK)
+- ✅ **Descriptive Errors**: Clear error messages with resolved paths for debugging
+- ✅ **Integration Tests**: 29 comprehensive tests in `test/cli/video-cli.test.ts`
+
+**Video Options Passed to SDK**:
+```typescript
+videoOptions: {
+  frames: argv.videoFrames,      // Number of frames to extract (default: 8)
+  quality: argv.videoQuality,    // Frame quality 0-100 (default: 85)
+  format: argv.videoFormat,      // jpeg or png (default: jpeg)
+  transcribeAudio: argv.transcribeAudio  // Audio transcription (default: false)
+}
+```
+
+**Error Handling**:
+- **Missing file**: Clear message with resolved path
+- **Unsupported format**: Lists all supported extensions
+- **Permission denied**: Suggests checking file permissions
+
+**Files Modified**:
+- `src/cli/factories/commandFactory.ts` - Added validation and processing
+- `test/cli/video-cli.test.ts` - 29 integration tests (NEW)
+- `memory-bank/cli/VIDEO-CLI-FLAGS-IMPLEMENTATION.md` - Updated documentation
+
+**Example Commands**:
+```bash
+# Basic video analysis
+neurolink generate "Describe this video" --video path/to/video.mp4
+
+# Custom frame extraction
+neurolink stream "Analyze" --video video.mp4 --video-frames 10 --video-quality 90
+
+# With audio transcription
+neurolink generate "Transcribe" --video video.mp4 --transcribe-audio
+```
+
+**Dependencies**: VIDEO-021 (flag definitions), VIDEO-013 (SDK processing)
+**Enables**: VIDEO-028, VIDEO-029 (video analysis workflows)
+
+---
+
 ## 🚀 **ENTERPRISE IMAGE CACHING SYSTEM IMPLEMENTED** (2026-01-30)
 
 ### **🏆 LATEST ACHIEVEMENT: INTELLIGENT IMAGE CACHE WITH LRU & DEDUPLICATION**

src/cli/factories/commandFactory.ts

@@ -547,14 +547,91 @@ export class CLICommandFactory {
     return resolveFilePaths(paths);
   }
 
-  // Helper method to process CLI video files
+  // Supported video file extensions for CLI validation
+  private static readonly SUPPORTED_VIDEO_EXTENSIONS = [
+    ".mp4",
+    ".webm",
+    ".mov",
+    ".avi",
+    ".mkv",
+    ".m4v",
+    ".wmv",
+    ".flv",
+  ];
+
+  /**
+   * Check if a string is a URL (http, https, file, or data URI)
+   */
+  private static isURL(str: string): boolean {
+    const lower = str.toLowerCase();
+    return (
+      lower.startsWith("http://") ||
+      lower.startsWith("https://") ||
+      lower.startsWith("file://") ||
+      lower.startsWith("data:")
+    );
+  }
+
+  /**
+   * Validate video file paths and throw descriptive errors for invalid files
+   *
+   * @param filePaths - Array of file paths to validate
+   * @throws Error if a file doesn't exist or has an unsupported extension
+   */
+  private static validateVideoFiles(filePaths: string[]): void {
+    for (const filePath of filePaths) {
+      // Skip URL validation - URLs are handled by the SDK
+      if (CLICommandFactory.isURL(filePath)) {
+        continue;
+      }
+
+      // Resolve relative paths to absolute
+      const absolutePath = path.resolve(process.cwd(), filePath);
+
+      // Check file exists
+      if (!fs.existsSync(absolutePath)) {
+        throw new Error(
+          `Video file not found: ${filePath}\n` +
+            `  Resolved path: ${absolutePath}\n` +
+            `  Please check the file path and try again.`,
+        );
+      }
+
+      // Check file extension
+      const ext = path.extname(absolutePath).toLowerCase();
+      if (!CLICommandFactory.SUPPORTED_VIDEO_EXTENSIONS.includes(ext)) {
+        throw new Error(
+          `Unsupported video format: ${ext}\n` +
+            `  File: ${filePath}\n` +
+            `  Supported formats: ${CLICommandFactory.SUPPORTED_VIDEO_EXTENSIONS.join(", ")}`,
+        );
+      }
+
+      // Check file is readable
+      try {
+        fs.accessSync(absolutePath, fs.constants.R_OK);
+      } catch {
+        throw new Error(
+          `Cannot read video file: ${filePath}\n` +
+            `  Resolved path: ${absolutePath}\n` +
+            `  Please check file permissions.`,
+        );
+      }
+    }
+  }
+
+  // Helper method to process CLI video files with validation
   private static processCliVideoFiles(
     videoFiles?: string | string[],
   ): Array<Buffer | string> | undefined {
     if (!videoFiles) {
       return undefined;
     }
     const paths = Array.isArray(videoFiles) ? videoFiles : [videoFiles];
+
+    // Validate video files before resolving paths
+    CLICommandFactory.validateVideoFiles(paths);
+
     // Resolve relative paths to absolute paths before returning
     // URLs are preserved as-is by resolveFilePaths
     return resolveFilePaths(paths);