gdrive-syncer 3.1.0 → 3.1.2

package/docs/PERFORMANCE_DECISIONS.md

@@ -0,0 +1,142 @@
+# Performance Optimization Decisions
+
+This document records design decisions made for performance optimizations, including rationale and trade-offs considered.
+
+## Overview
+
+The diff/sync operations were slow with nested folders and many files (e.g., 30+ files across multiple folder levels). Root cause: all Google Drive API calls were sequential and blocking.
+
+---
+
+## Decision 1: Parallel API Calls (Implemented)
+
+**Problem:** Sequential API calls caused O(n) latency where n = number of files + folders.
+
+**Solution:** Use async/parallel operations with batched concurrency.
+
+**Implementation:**
+- `listAsync()` - Non-blocking folder listing using `child_process.exec` with promises
+- `downloadAsync()` - Non-blocking file downloads
+- `downloadParallel()` - Batch downloads with configurable concurrency
+- `listDriveFilesRecursiveOptimized()` - Breadth-first traversal querying multiple folders in parallel
+
+**Concurrency Limit:** 5 concurrent requests per batch
+
+**Rationale for batch size of 5:**
+- Google Drive API limit: ~1,000 queries per 100 seconds per user (~10/sec sustained)
+- Batch size of 5 is conservative, allowing headroom for other operations
+- Can be increased to 8-10 if needed, but diminishing returns due to network latency
+
+**Expected Performance Improvement:**
+| Scenario | Before (sequential) | After (parallel, batch=5) |
+|----------|---------------------|---------------------------|
+| 30 files in nested folders | ~10-15 seconds | ~3-5 seconds |
+| Download 30 files | ~6-15 seconds | ~1.5-3 seconds |
+
+---
+
+## Decision 2: Session-Scoped Folder Caching (Implemented)
+
+**Problem:** When uploading multiple files to the same nested folder structure (e.g., 10 files to `root/a/b/c/`), the `findOrCreateDriveFolder` function would query the same parent folders repeatedly.
+
+**Solution:** Session-scoped folder cache that is cleared at the start of each sync operation.
+
+**Implementation:**
+- `folderCache` - Map structure: `parentId -> Map(folderName -> folderId)`
+- `clearFolderCache()` - Called at start of `runSyncOperation()` to ensure fresh data
+- `getCachedFolderId()` / `cacheFolderId()` - Cache lookup and storage helpers
+- Cache is used in `findOrCreateDriveFolder()` to avoid redundant API calls
+
+**Why this is safe:**
+1. **Fresh data on every operation** - Cache is cleared at start, so we always query Drive for current state
+2. **Short-lived** - Cache only exists for duration of single sync (seconds)
+3. **Consistent within operation** - Folder structure shouldn't change during a 3-5 second sync
+
+**Benefit:** If uploading 10 files to `root/a/b/c/`:
+- Without cache: Query `a`, `b`, `c` 10 times each = 30 API calls
+- With cache: Query `a`, `b`, `c` once each = 3 API calls
+
+**Trade-off considered:** Risk of stale data if folder modified mid-sync.
+- Acceptable risk given short operation duration (seconds)
+- User can simply re-run sync if concurrent modification occurs
+
+---
+
+## Decision 3: Breadth-First vs Depth-First Listing
+
+**Problem:** Original `listDriveFilesRecursive` used depth-first traversal, which creates a chain of blocking calls.
+
+**Solution:** Breadth-first traversal with level-by-level parallel queries.
+
+**How it works:**
+```
+Level 0: Query root folder (1 API call)
+Level 1: Query all subfolders in parallel (e.g., 5 folders = 1 batch)
+Level 2: Query all sub-subfolders in parallel (e.g., 10 folders = 2 batches)
+...
+```
+
+**Benefit:** Folders at the same depth are queried concurrently instead of sequentially.
+
+**Trade-off:** Slightly more memory usage to hold the queue, but negligible for typical folder structures.
+
+---
+
+## Decision 4: Delta Sync (Implemented)
+
+**Problem:** Previously, ALL files were downloaded from Drive to a temp directory for comparison, even if they hadn't changed. With 30 files, this meant 30 downloads every sync.
+
+**Solution:** Compare file metadata (size + modification time) before downloading. Only download files where metadata indicates a potential change.
+
+**Implementation:**
+- `parseListOutput()` now extracts `sizeBytes` and `modifiedTime` from gdrive output
+- `listLocalFilesRecursive()` now includes `sizeBytes` and `modifiedTime` from `fs.statSync()`
+- Comparison logic in `runSyncOperation()`:
+  1. Get local files with metadata
+  2. For each Drive file, check if local exists with same size AND local is not older
+  3. Skip download for unchanged files
+  4. Only download and compare files where metadata differs
+
+**Unchanged file detection:**
+```javascript
+const sizeMatch = driveFile.sizeBytes === localFile.sizeBytes;
+const timeMatch = driveTime <= localTime + 1000; // 1 second tolerance
+
+if (sizeMatch && timeMatch) {
+  // Skip download - metadata indicates unchanged
+}
+```
+
+**Performance improvement:**
+
+| Scenario | Before | After |
+|----------|--------|-------|
+| 30 files, none changed | Download 30 files | Download 0 files |
+| 30 files, 5 changed | Download 30 files | Download 5 files |
+| 30 files, all changed | Download 30 files | Download 30 files |
+
+**Trade-offs:**
+- Relies on accurate timestamps from Google Drive
+- 1-second tolerance to handle clock differences
+- Files with same size but different content AND older local time could be missed (rare edge case)
+
+**Why not use hashes?**
+- Google Drive provides `md5Checksum` but requires additional API call per file
+- Size + time comparison is sufficient for most use cases and much faster
+- Can add optional hash verification in future if needed
+
+---
+
+## Future Considerations
+
+1. **Configurable concurrency** - Allow users to adjust batch size via config if they have different rate limit needs
+2. **Progress callbacks** - Add progress reporting for large sync operations
+3. **Retry with exponential backoff** - Handle transient API failures gracefully
+4. **Optional hash verification** - Add `--verify` flag to compare MD5 checksums for critical syncs
+
+---
+
+## References
+
+- Google Drive API Quotas: https://developers.google.com/drive/api/guides/limits
+- Rate limit: 1,000 queries per 100 seconds per user

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdrive-syncer",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Google Drive Syncer",
   "main": "./index.js",
   "bin": "./run.js",

package/run.js

@@ -6,6 +6,7 @@ const { cfgAdd, cfgRm, cfgShow } = require('./src/cfgManager');
 const { runSync } = require('./src/sync');
 const { runList, runSearch, runDelete, runMkdir, runListSync } = require('./src/list');
 const { envInit, envRun, envShow, envRemove, envRegister, envUnregister, envMigrate } = require('./src/envSync');
+const { checkForUpdates } = require('./src/versionCheck');
 
 const [, , ...args] = process.argv;
 const [firstArg] = args;
@@ -81,10 +82,17 @@ const showHelp = () => {
   console.clear();
   intro(color.bgCyan(color.black(' GDrive Syncer ')));
 
+  // Check for updates and show at start if available
+  const updateMessage = await checkForUpdates();
+  if (updateMessage) {
+    note(updateMessage, 'Update Available');
+  }
+
   try {
     // Check for help
     if (firstArg === 'help' || firstArg === '--help' || firstArg === '-h') {
       showHelp();
+      if (updateMessage) note(updateMessage, 'Update Available');
       outro(color.green('Done!'));
       return;
     }
@@ -92,6 +100,7 @@ const showHelp = () => {
     // Check for direct command
     if (firstArg && commands[firstArg]) {
       await commands[firstArg].handler();
+      if (updateMessage) note(updateMessage, 'Update Available');
       outro(color.green('Done!'));
       return;
     }
@@ -119,6 +128,7 @@ const showHelp = () => {
 
     if (category === 'help') {
       showHelp();
+      if (updateMessage) note(updateMessage, 'Update Available');
       outro(color.green('Done!'));
       return;
     }
@@ -176,6 +186,8 @@ const showHelp = () => {
       await commands[action].handler();
     }
 
+    // Show update message at exit
+    if (updateMessage) note(updateMessage, 'Update Available');
     outro(color.green('Done!'));
   } catch (e) {
     log.error(e.message);

package/src/envSync.js

@@ -565,6 +565,129 @@ const envShow = async () => {
   }
 };
 
+// =============================================================================
+// Performance Optimization: Parallel API calls for faster sync operations
+// See docs/PERFORMANCE_DECISIONS.md for design rationale
+// =============================================================================
+
+/**
+ * Session-scoped folder cache to avoid repeated API calls within a single operation.
+ * Structure: parentId -> Map(folderName -> folderId)
+ * IMPORTANT: Must be cleared at the start of each sync/diff operation via clearFolderCache()
+ */
+let folderCache = new Map();
+
+/**
+ * Clear folder cache - MUST be called at start of each sync operation
+ * This ensures we always start with fresh data from Google Drive
+ */
+const clearFolderCache = () => {
+  folderCache = new Map();
+};
+
+/**
+ * Get cached folder ID or null if not cached
+ * @param {string} parentId - Parent folder ID
+ * @param {string} folderName - Folder name to look up
+ * @returns {string|null} - Folder ID if cached, null otherwise
+ */
+const getCachedFolderId = (parentId, folderName) => {
+  const parentCache = folderCache.get(parentId);
+  return parentCache ? parentCache.get(folderName) || null : null;
+};
+
+/**
+ * Cache a folder ID for later lookups within the same operation
+ * @param {string} parentId - Parent folder ID
+ * @param {string} folderName - Folder name
+ * @param {string} folderId - Folder ID to cache
+ */
+const cacheFolderId = (parentId, folderName, folderId) => {
+  if (!folderCache.has(parentId)) {
+    folderCache.set(parentId, new Map());
+  }
+  folderCache.get(parentId).set(folderName, folderId);
+};
+
+/**
+ * Optimized recursive listing using breadth-first traversal with parallel API calls
+ * This significantly improves performance for nested folder structures
+ * @param {string} folderId - Root folder ID
+ * @param {string} pattern - File pattern to match
+ * @param {string} [ignore] - Ignore pattern
+ * @param {boolean} [includeFolders=false] - Whether to include folders in results
+ * @returns {Promise<Array<{id: string, name: string, relativePath: string, isFolder: boolean, sizeBytes: number, modifiedTime: Date|null}>>}
+ */
+const listDriveFilesRecursiveOptimized = async (folderId, pattern, ignore, includeFolders = false) => {
+  const results = [];
+  // Queue of folders to process: { id, prefix }
+  let queue = [{ id: folderId, prefix: '' }];
+
+  while (queue.length > 0) {
+    // Process all folders at current level in parallel
+    const currentBatch = queue;
+    queue = [];
+
+    // Fetch all folder contents in parallel (limit concurrency to 5)
+    const batchSize = 5;
+    for (let i = 0; i < currentBatch.length; i += batchSize) {
+      const batch = currentBatch.slice(i, i + batchSize);
+      const listPromises = batch.map(async ({ id, prefix }) => {
+        const listResult = await gdrive.listAsync({
+          query: `'${id}' in parents and trashed = false`,
+          noHeader: true,
+          max: 1000,
+        });
+
+        if (listResult.code !== 0 || !listResult.stdout.trim()) {
+          return { items: [], folders: [] };
+        }
+
+        const parsed = gdrive.parseListOutput(listResult.stdout.trim());
+        const items = [];
+        const folders = [];
+
+        for (const file of parsed) {
+          if (!file.id || !file.name) continue;
+
+          const relativePath = prefix ? `${prefix}/${file.name}` : file.name;
+          const isFolder = file.type && file.type.toLowerCase().includes('folder');
+
+          if (isFolder) {
+            // Queue folder for next level processing
+            folders.push({ id: file.id, prefix: relativePath });
+            if (includeFolders) {
+              items.push({ id: file.id, name: file.name, relativePath, isFolder: true, sizeBytes: 0, modifiedTime: null });
+            }
+          } else {
+            // Only add files that match the pattern
+            if (matchPattern(file.name, pattern, ignore)) {
+              items.push({
+                id: file.id,
+                name: file.name,
+                relativePath,
+                isFolder: false,
+                sizeBytes: file.sizeBytes || 0,
+                modifiedTime: file.modifiedTime || null,
+              });
+            }
+          }
+        }
+
+        return { items, folders };
+      });
+
+      const batchResults = await Promise.all(listPromises);
+      for (const { items, folders } of batchResults) {
+        results.push(...items);
+        queue.push(...folders);
+      }
+    }
+  }
+
+  return results;
+};
+
 /**
  * Recursively list files and folders from Google Drive
  * @param {string} folderId - Root folder ID
@@ -634,7 +757,7 @@ const listDriveFilesRecursive = (folderId, pattern, ignore, prefix = '', include
  * @param {string} [ignore] - Ignore pattern
  * @param {string} [prefix=''] - Path prefix for nested files
  * @param {boolean} [includeFolders=false] - Whether to include folders in results
- * @returns {Array<{name: string, relativePath: string, isFolder: boolean}>}
+ * @returns {Array<{name: string, relativePath: string, isFolder: boolean, sizeBytes: number, modifiedTime: Date|null}>}
  */
 const listLocalFilesRecursive = (dir, pattern, ignore, prefix = '', includeFolders = false) => {
   const results = [];
@@ -647,6 +770,7 @@ const listLocalFilesRecursive = (dir, pattern, ignore, prefix = '', includeFolde
 
   for (const entry of entries) {
     const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const fullPath = path.join(dir, entry.name);
 
     if (entry.isDirectory()) {
       // Add folder to results if requested
@@ -655,19 +779,33 @@ const listLocalFilesRecursive = (dir, pattern, ignore, prefix = '', includeFolde
           name: entry.name,
           relativePath,
           isFolder: true,
+          sizeBytes: 0,
+          modifiedTime: null,
         });
       }
       // Recursively list subdirectory
-      const subDir = path.join(dir, entry.name);
-      const subFiles = listLocalFilesRecursive(subDir, pattern, ignore, relativePath, includeFolders);
+      const subFiles = listLocalFilesRecursive(fullPath, pattern, ignore, relativePath, includeFolders);
       results.push(...subFiles);
     } else if (entry.isFile()) {
       // Only add files that match the pattern
       if (matchPattern(entry.name, pattern, ignore)) {
+        // Get file stats for delta sync comparison
+        let sizeBytes = 0;
+        let modifiedTime = null;
+        try {
+          const stats = fs.statSync(fullPath);
+          sizeBytes = stats.size;
+          modifiedTime = stats.mtime;
+        } catch (e) {
+          // Ignore stat errors, use defaults
+        }
+
         results.push({
           name: entry.name,
           relativePath,
           isFolder: false,
+          sizeBytes,
+          modifiedTime,
         });
       }
     }
@@ -678,6 +816,7 @@ const listLocalFilesRecursive = (dir, pattern, ignore, prefix = '', includeFolde
 
 /**
  * Find or create a folder in Google Drive by path
+ * Uses session-scoped cache to avoid repeated API calls for same folder paths
  * @param {string} parentId - Parent folder ID
  * @param {string} folderPath - Folder path like "a/b/c"
  * @returns {string} - The folder ID of the deepest folder
@@ -687,38 +826,44 @@ const findOrCreateDriveFolder = (parentId, folderPath) => {
   let currentParentId = parentId;
 
   for (const folderName of parts) {
-    // Check if folder exists
-    const listResult = gdrive.list({
-      query: `'${currentParentId}' in parents and name = '${folderName}' and mimeType = 'application/vnd.google-apps.folder' and trashed = false`,
-      noHeader: true,
-      max: 1,
-    });
+    // Check cache first to avoid redundant API calls
+    let folderId = getCachedFolderId(currentParentId, folderName);
 
-    let folderId = null;
+    if (!folderId) {
+      // Not in cache, query the API
+      const listResult = gdrive.list({
+        query: `'${currentParentId}' in parents and name = '${folderName}' and mimeType = 'application/vnd.google-apps.folder' and trashed = false`,
+        noHeader: true,
+        max: 1,
+      });
 
-    if (listResult.code === 0 && listResult.stdout.trim()) {
-      const parsed = gdrive.parseListOutput(listResult.stdout.trim());
-      if (parsed.length > 0 && parsed[0].id) {
-        folderId = parsed[0].id;
+      if (listResult.code === 0 && listResult.stdout.trim()) {
+        const parsed = gdrive.parseListOutput(listResult.stdout.trim());
+        if (parsed.length > 0 && parsed[0].id) {
+          folderId = parsed[0].id;
+        }
       }
-    }
 
-    if (!folderId) {
-      // Create the folder
-      const mkdirResult = gdrive.mkdir(folderName, { parent: currentParentId });
-      if (mkdirResult.code === 0) {
-        // Parse the created folder ID from output
-        // gdrive@3 outputs: "Directory created: ID"
-        // gdrive@2 outputs: "Directory ID created"
-        const match = mkdirResult.stdout.match(/([a-zA-Z0-9_-]{20,})/);
-        if (match) {
-          folderId = match[1];
+      if (!folderId) {
+        // Create the folder
+        const mkdirResult = gdrive.mkdir(folderName, { parent: currentParentId });
+        if (mkdirResult.code === 0) {
+          // Parse the created folder ID from output
+          // gdrive@3 outputs: "Directory created: ID"
+          // gdrive@2 outputs: "Directory ID created"
+          const match = mkdirResult.stdout.match(/([a-zA-Z0-9_-]{20,})/);
+          if (match) {
+            folderId = match[1];
+          }
         }
       }
-    }
 
-    if (!folderId) {
-      throw new Error(`Failed to find or create folder: ${folderName}`);
+      if (!folderId) {
+        throw new Error(`Failed to find or create folder: ${folderName}`);
+      }
+
+      // Cache the result for subsequent lookups within this operation
+      cacheFolderId(currentParentId, folderName, folderId);
     }
 
     currentParentId = folderId;
@@ -1049,6 +1194,9 @@ const envRun = async (presetAction, presetConfigType) => {
  * Run a single sync operation
  */
 const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, configType) => {
+  // Clear folder cache at start of each operation to ensure fresh data
+  clearFolderCache();
+
   const { folderId, pattern, name, ignore } = syncConfig;
   // Strip quotes from paths (in case manually added)
   const localDir = syncConfig.localDir.replace(/^['"]|['"]$/g, '');
@@ -1071,10 +1219,11 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
 
   try {
     // Fetch file list from Drive (recursive, including folders for cleanup)
+    // Uses optimized breadth-first parallel listing for better performance
     const s = spinner();
     s.start('Fetching files from Google Drive (including nested folders)...');
 
-    const driveItems = listDriveFilesRecursive(folderId, pattern, ignore, '', true);
+    const driveItems = await listDriveFilesRecursiveOptimized(folderId, pattern, ignore, true);
     const driveFiles = driveItems.filter((f) => !f.isFolder);
     const driveFolders = driveItems.filter((f) => f.isFolder);
 
@@ -1093,21 +1242,77 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       }
     }
 
-    // Download Drive files to temp for comparison (preserving folder structure)
-    s.message('Downloading Drive files for comparison...');
-    for (const file of driveFiles) {
-      const destPath = path.join(tempDir, path.dirname(file.relativePath));
-      fs.ensureDirSync(destPath);
-      gdrive.download(file.id, { destination: destPath, overwrite: true });
-    }
-    s.stop(color.green(`Found ${driveFiles.length} matching file(s) on Drive`));
-
-    // Get local files (recursive, including folders for cleanup)
+    // Get local files first for delta sync comparison
     fs.ensureDirSync(envDir);
     const localItems = listLocalFilesRecursive(envDir, pattern, ignore, '', true);
     const localFiles = localItems.filter((f) => !f.isFolder);
     const localFolders = localItems.filter((f) => f.isFolder);
 
+    // Build local file lookup map for delta sync
+    const localFileMap = new Map();
+    for (const file of localFiles) {
+      localFileMap.set(file.relativePath, file);
+    }
+
+    // Delta sync: Determine which files need to be downloaded for comparison
+    // Skip files where metadata indicates no change (same size AND local is not older)
+    s.message('Analyzing file changes (delta sync)...');
+    const filesToDownload = [];
+    const unchangedFiles = [];
+
+    for (const driveFile of driveFiles) {
+      const localFile = localFileMap.get(driveFile.relativePath);
+
+      if (!localFile) {
+        // File only exists on Drive - need to download for diff
+        filesToDownload.push(driveFile);
+      } else {
+        // File exists in both places - check if metadata indicates change
+        const sizeMatch = driveFile.sizeBytes === localFile.sizeBytes;
+        const driveTime = driveFile.modifiedTime ? driveFile.modifiedTime.getTime() : 0;
+        const localTime = localFile.modifiedTime ? localFile.modifiedTime.getTime() : 0;
+
+        // Consider unchanged if: same size AND Drive is not newer
+        // (allow 1 second tolerance for time comparison)
+        const timeMatch = driveTime <= localTime + 1000;
+
+        if (sizeMatch && timeMatch) {
+          // Metadata suggests unchanged - skip download
+          unchangedFiles.push(driveFile.relativePath);
+        } else {
+          // Metadata differs - need to download for accurate comparison
+          filesToDownload.push(driveFile);
+        }
+      }
+    }
+
+    // Download only changed files to temp for comparison
+    s.message(
+      `Downloading ${filesToDownload.length} file(s) for comparison (${unchangedFiles.length} unchanged)...`
+    );
+
+    // Prepare destination directories first
+    for (const file of filesToDownload) {
+      const destPath = path.join(tempDir, path.dirname(file.relativePath));
+      fs.ensureDirSync(destPath);
+    }
+
+    // Download files in parallel batches (5 concurrent downloads) with progress
+    const downloads = filesToDownload.map((file) => ({
+      fileId: file.id,
+      options: {
+        destination: path.join(tempDir, path.dirname(file.relativePath)),
+        overwrite: true,
+      },
+    }));
+    if (downloads.length > 0) {
+      await gdrive.downloadParallel(downloads, 5, (completed, total) => {
+        s.message(`Downloading files for comparison... (${completed}/${total})`);
+      });
+    }
+
+    s.stop(color.green(`Found ${driveFiles.length} file(s) on Drive (${unchangedFiles.length} skipped via delta sync)`));
+
     // Compare files using relativePath
     const changes = {
       modified: [],
@@ -1116,10 +1321,11 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       orphanDriveFolders: [], // Folders on Drive with no local equivalent
     };
 
-    // Build a set of drive file paths for quick lookup
+    // Build sets for quick lookup
     const driveFilePaths = new Set(driveFiles.map((f) => f.relativePath));
     const localFilePaths = new Set(localFiles.map((f) => f.relativePath));
     const localFolderPaths = new Set(localFolders.map((f) => f.relativePath));
+    const unchangedSet = new Set(unchangedFiles);
 
     // Check local files
     for (const localFile of localFiles) {
@@ -1127,7 +1333,12 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       const driveFilePath = path.join(tempDir, localFile.relativePath);
 
       if (driveFilePaths.has(localFile.relativePath)) {
-        // File exists on both - check for modifications
+        // File exists on both
+        if (unchangedSet.has(localFile.relativePath)) {
+          // Delta sync determined this file is unchanged - skip comparison
+          continue;
+        }
+        // Check for modifications (only for files we downloaded)
         if (fs.existsSync(driveFilePath)) {
           const localContent = fs.readFileSync(localFilePath, 'utf-8');
           const driveContent = fs.readFileSync(driveFilePath, 'utf-8');
@@ -1308,11 +1519,13 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       }
 
       const downloadSpinner = spinner();
-      downloadSpinner.start('Downloading files...');
-
+      const totalToDownload = changes.modified.length + changes.driveOnly.length;
       let downloaded = 0;
 
+      downloadSpinner.start(`Downloading files... (0/${totalToDownload})`);
+
       for (const relativePath of changes.modified) {
+        downloadSpinner.message(`Downloading (${downloaded + 1}/${totalToDownload}): ${relativePath}`);
         const srcPath = path.join(tempDir, relativePath);
         const destPath = path.join(envDir, relativePath);
         fs.ensureDirSync(path.dirname(destPath));
@@ -1321,6 +1534,7 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       }
 
       for (const relativePath of changes.driveOnly) {
+        downloadSpinner.message(`Downloading (${downloaded + 1}/${totalToDownload}): ${relativePath}`);
         const srcPath = path.join(tempDir, relativePath);
         const destPath = path.join(envDir, relativePath);
         fs.ensureDirSync(path.dirname(destPath));
@@ -1331,11 +1545,13 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       downloadSpinner.stop(color.green(`Downloaded ${downloaded} file(s)`));
     } else if (action === 'upload') {
       const uploadSpinner = spinner();
-      uploadSpinner.start('Uploading files...');
-
+      const totalToUpload = changes.modified.length + changes.localOnly.length;
+      let completed = 0;
       let uploaded = 0;
       let replaced = 0;
 
+      uploadSpinner.start(`Uploading files... (0/${totalToUpload})`);
+
       // Build a map of relativePath -> driveFile for quick lookup
       const driveFileMap = new Map();
       for (const df of driveFiles) {
@@ -1343,14 +1559,17 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       }
 
       for (const relativePath of changes.modified) {
+        uploadSpinner.message(`Replacing (${completed + 1}/${totalToUpload}): ${relativePath}`);
         const driveFile = driveFileMap.get(relativePath);
         if (driveFile) {
           gdrive.update(driveFile.id, path.join(envDir, relativePath));
           replaced++;
+          completed++;
         }
       }
 
       for (const relativePath of changes.localOnly) {
+        uploadSpinner.message(`Uploading (${completed + 1}/${totalToUpload}): ${relativePath}`);
         const localFilePath = path.join(envDir, relativePath);
         const folderPath = path.dirname(relativePath);
 
@@ -1362,6 +1581,7 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
 
         gdrive.upload(localFilePath, { parent: parentId });
         uploaded++;
+        completed++;
       }
 
       uploadSpinner.stop(color.green(`Replaced: ${replaced}, New: ${uploaded}`));

package/src/gdriveCmd.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 const shell = require('shelljs');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const execAsync = promisify(exec);
 
 let cachedVersion = null;
 
@@ -254,7 +257,7 @@ const syncList = () => {
  * Parse list output into structured data
  * Works with both v2 and v3 output formats
  * @param {string} stdout - Raw stdout from list command
- * @returns {Array<{id: string, name: string, type: string, size: string, date: string}>}
+ * @returns {Array<{id: string, name: string, type: string, size: string, sizeBytes: number, date: string, modifiedTime: Date|null}>}
  */
 const parseListOutput = (stdout) => {
   const lines = stdout.trim().split('\n').filter((line) => line.trim());
@@ -267,16 +270,64 @@ const parseListOutput = (stdout) => {
 
   return lines.map((line) => {
     const parts = line.trim().split(separator);
+    const size = parts[3] || '';
+    const date = parts[4] || '';
+
     return {
       id: parts[0] || '',
       name: parts[1] || '',
       type: parts[2] || '',
-      size: parts[3] || '',
-      date: parts[4] || '',
+      size,
+      sizeBytes: parseSizeToBytes(size),
+      date,
+      modifiedTime: parseGdriveDate(date),
     };
   });
 };
 
+/**
+ * Parse size string to bytes (e.g., "1.5 KB" -> 1536)
+ * @param {string} sizeStr - Size string from gdrive output
+ * @returns {number} - Size in bytes, or 0 if unparseable
+ */
+const parseSizeToBytes = (sizeStr) => {
+  if (!sizeStr) return 0;
+
+  const match = sizeStr.match(/^([\d.]+)\s*(B|KB|MB|GB|TB)?$/i);
+  if (!match) return 0;
+
+  const value = parseFloat(match[1]);
+  const unit = (match[2] || 'B').toUpperCase();
+
+  const multipliers = {
+    B: 1,
+    KB: 1024,
+    MB: 1024 * 1024,
+    GB: 1024 * 1024 * 1024,
+    TB: 1024 * 1024 * 1024 * 1024,
+  };
+
+  return Math.round(value * (multipliers[unit] || 1));
+};
+
+/**
+ * Parse gdrive date string to Date object
+ * gdrive outputs dates like "2024-01-15 10:30:00" or ISO format
+ * @param {string} dateStr - Date string from gdrive output
+ * @returns {Date|null} - Date object or null if unparseable
+ */
+const parseGdriveDate = (dateStr) => {
+  if (!dateStr) return null;
+
+  // Try parsing as-is (handles ISO format and common formats)
+  const date = new Date(dateStr);
+  if (!isNaN(date.getTime())) {
+    return date;
+  }
+
+  return null;
+};
+
 /**
  * Clear the cached version (useful for testing)
  */
@@ -284,12 +335,112 @@ const clearCache = () => {
   cachedVersion = null;
 };
 
+/**
+ * Async version of list - for parallel operations
+ * @param {Object} options - Same options as list()
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+const listAsync = async (options = {}) => {
+  const version = detectVersion();
+  const { query, max = 30, noHeader = false, absolute = false, parent } = options;
+
+  let cmd;
+  if (version === 2) {
+    cmd = 'gdrive list';
+    if (max) cmd += ` --max ${max}`;
+    if (query) cmd += ` --query "${query}"`;
+    if (noHeader) cmd += ' --no-header';
+    if (absolute) cmd += ' --absolute';
+  } else {
+    cmd = 'gdrive files list';
+    if (max) cmd += ` --max ${max}`;
+    if (parent) {
+      cmd += ` --parent ${parent}`;
+    } else if (query) {
+      cmd += ` --query "${query}"`;
+    }
+    if (noHeader) cmd += ' --skip-header';
+  }
+
+  try {
+    const { stdout, stderr } = await execAsync(cmd);
+    return { code: 0, stdout: stdout || '', stderr: stderr || '' };
+  } catch (error) {
+    return { code: error.code || 1, stdout: error.stdout || '', stderr: error.stderr || error.message };
+  }
+};
+
+/**
+ * Async version of download - for parallel downloads
+ * @param {string} fileId - File ID to download
+ * @param {Object} options - Same options as download()
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+const downloadAsync = async (fileId, options = {}) => {
+  const version = detectVersion();
+  const { destination, overwrite = false, recursive = false } = options;
+
+  let cmd;
+  if (version === 2) {
+    cmd = `gdrive download "${fileId}"`;
+    if (destination) cmd += ` --path "${destination}"`;
+    if (overwrite) cmd += ' --force';
+    if (recursive) cmd += ' -r';
+  } else {
+    cmd = `gdrive files download "${fileId}"`;
+    if (destination) cmd += ` --destination "${destination}"`;
+    if (overwrite) cmd += ' --overwrite';
+    if (recursive) cmd += ' --recursive';
+  }
+
+  try {
+    const { stdout, stderr } = await execAsync(cmd);
+    return { code: 0, stdout: stdout || '', stderr: stderr || '' };
+  } catch (error) {
+    return { code: error.code || 1, stdout: error.stdout || '', stderr: error.stderr || error.message };
+  }
+};
+
+/**
+ * Download multiple files in parallel with concurrency limit and progress tracking
+ * @param {Array<{fileId: string, options: Object}>} downloads - Array of download requests
+ * @param {number} concurrency - Maximum concurrent downloads (default: 5)
+ * @param {Function} [onProgress] - Progress callback: (completed, total) => void
+ * @returns {Promise<Array<{code: number, stdout: string, stderr: string}>>}
+ */
+const downloadParallel = async (downloads, concurrency = 5, onProgress = null) => {
+  const results = [];
+  const total = downloads.length;
+  let completed = 0;
+
+  // Process in batches to limit concurrency
+  for (let i = 0; i < downloads.length; i += concurrency) {
+    const batch = downloads.slice(i, i + concurrency);
+    const batchResults = await Promise.all(
+      batch.map(async ({ fileId, options }) => {
+        const result = await downloadAsync(fileId, options);
+        completed++;
+        if (onProgress) {
+          onProgress(completed, total);
+        }
+        return result;
+      })
+    );
+    results.push(...batchResults);
+  }
+
+  return results;
+};
+
 module.exports = {
   detectVersion,
   getVersion,
   hasSyncSupport,
   list,
+  listAsync,
   download,
+  downloadAsync,
+  downloadParallel,
   upload,
   update,
   mkdir,
@@ -297,5 +448,7 @@ module.exports = {
   syncUpload,
   syncList,
   parseListOutput,
+  parseSizeToBytes,
+  parseGdriveDate,
   clearCache,
 };

package/src/versionCheck.js

@@ -0,0 +1,100 @@
+/**
+ * Version check utility - warns user if a newer version is available
+ */
+const https = require('https');
+const path = require('path');
+const color = require('picocolors');
+
+// Get current version from package.json
+const getLocalVersion = () => {
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  return pkg.version;
+};
+
+// Get package name from package.json
+const getPackageName = () => {
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  return pkg.name;
+};
+
+/**
+ * Fetch latest version from npm registry
+ * @param {string} packageName - npm package name
+ * @returns {Promise<string|null>} - Latest version or null on error
+ */
+const fetchLatestVersion = (packageName) => {
+  return new Promise((resolve) => {
+    const url = `https://registry.npmjs.org/${packageName}/latest`;
+
+    const req = https.get(url, { timeout: 3000 }, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          resolve(json.version || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+};
+
+/**
+ * Compare semver versions
+ * @param {string} current - Current version (e.g., "1.2.3")
+ * @param {string} latest - Latest version (e.g., "1.3.0")
+ * @returns {boolean} - True if latest is newer than current
+ */
+const isNewerVersion = (current, latest) => {
+  const currentParts = current.split('.').map(Number);
+  const latestParts = latest.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const c = currentParts[i] || 0;
+    const l = latestParts[i] || 0;
+    if (l > c) return true;
+    if (l < c) return false;
+  }
+  return false;
+};
+
+/**
+ * Check for updates and return message if newer version available
+ * Non-blocking - doesn't throw errors, just silently fails
+ * @returns {Promise<string|null>} - Update message or null if up to date/error
+ */
+const checkForUpdates = async () => {
+  try {
+    const packageName = getPackageName();
+    const currentVersion = getLocalVersion();
+    const latestVersion = await fetchLatestVersion(packageName);
+
+    if (latestVersion && isNewerVersion(currentVersion, latestVersion)) {
+      return `Update available: ${color.dim(currentVersion)} → ${color.green(latestVersion)} (${color.cyan(packageName)})`;
+    }
+    return null;
+  } catch {
+    // Silently ignore errors - don't disrupt user experience
+    return null;
+  }
+};
+
+module.exports = {
+  getLocalVersion,
+  getPackageName,
+  fetchLatestVersion,
+  isNewerVersion,
+  checkForUpdates,
+};