gdrive-syncer 3.0.0 → 3.1.1

package/src/envSync.js

@@ -565,6 +565,313 @@ 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
+ * @param {string} pattern - File pattern to match
+ * @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<{id: string, name: string, relativePath: string, isFolder: boolean}>}
+ */
+const listDriveFilesRecursive = (folderId, pattern, ignore, prefix = '', includeFolders = false) => {
+  const results = [];
+
+  const listResult = gdrive.list({
+    query: `'${folderId}' in parents and trashed = false`,
+    noHeader: true,
+    max: 1000,
+  });
+
+  if (listResult.code !== 0) {
+    return results;
+  }
+
+  const stdout = listResult.stdout.trim();
+  if (!stdout) return results;
+
+  const parsed = gdrive.parseListOutput(stdout);
+
+  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) {
+      // Add folder to results if requested
+      if (includeFolders) {
+        results.push({
+          id: file.id,
+          name: file.name,
+          relativePath,
+          isFolder: true,
+        });
+      }
+      // Recursively list folder contents
+      const subFiles = listDriveFilesRecursive(file.id, pattern, ignore, relativePath, includeFolders);
+      results.push(...subFiles);
+    } else {
+      // Only add files that match the pattern
+      if (matchPattern(file.name, pattern, ignore)) {
+        results.push({
+          id: file.id,
+          name: file.name,
+          relativePath,
+          isFolder: false,
+        });
+      }
+    }
+  }
+
+  return results;
+};
+
+/**
+ * Recursively list local files and folders
+ * @param {string} dir - Directory to list
+ * @param {string} pattern - File pattern to match
+ * @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, sizeBytes: number, modifiedTime: Date|null}>}
+ */
+const listLocalFilesRecursive = (dir, pattern, ignore, prefix = '', includeFolders = false) => {
+  const results = [];
+
+  if (!fs.existsSync(dir)) {
+    return results;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  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
+      if (includeFolders) {
+        results.push({
+          name: entry.name,
+          relativePath,
+          isFolder: true,
+          sizeBytes: 0,
+          modifiedTime: null,
+        });
+      }
+      // Recursively list subdirectory
+      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,
+        });
+      }
+    }
+  }
+
+  return results;
+};
+
+/**
+ * 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
+ */
+const findOrCreateDriveFolder = (parentId, folderPath) => {
+  const parts = folderPath.split('/').filter(Boolean);
+  let currentParentId = parentId;
+
+  for (const folderName of parts) {
+    // Check cache first to avoid redundant API calls
+    let folderId = getCachedFolderId(currentParentId, folderName);
+
+    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 (!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}`);
+      }
+
+      // Cache the result for subsequent lookups within this operation
+      cacheFolderId(currentParentId, folderName, folderId);
+    }
+
+    currentParentId = folderId;
+  }
+
+  return currentParentId;
+};
+
 /**
  * Convert a glob pattern to a regex pattern
  * Supports:
@@ -887,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, '');
@@ -908,76 +1218,164 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
   fs.ensureDirSync(tempDir);
 
   try {
-    // Fetch file list from Drive
+    // 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...');
+    s.start('Fetching files from Google Drive (including nested folders)...');
+
+    const driveItems = await listDriveFilesRecursiveOptimized(folderId, pattern, ignore, true);
+    const driveFiles = driveItems.filter((f) => !f.isFolder);
+    const driveFolders = driveItems.filter((f) => f.isFolder);
+
+    if (driveFiles.length === 0) {
+      // Check if the folder exists at all
+      const testResult = gdrive.list({
+        query: `'${folderId}' in parents and trashed = false`,
+        noHeader: true,
+        max: 1,
+      });
+      if (testResult.code !== 0) {
+        s.stop(color.red('Failed to fetch from Drive'));
+        log.error('Could not list files from Google Drive. Check folder ID and permissions.');
+        if (testResult.stderr) log.error(testResult.stderr);
+        return;
+      }
+    }
 
-    const listResult = gdrive.list({
-      query: `'${folderId}' in parents`,
-      noHeader: true,
-    });
+    // 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);
 
-    if (listResult.code !== 0) {
-      s.stop(color.red('Failed to fetch from Drive'));
-      log.error('Could not list files from Google Drive. Check folder ID and permissions.');
-      if (listResult.stderr) log.error(listResult.stderr);
-      return;
+    // Build local file lookup map for delta sync
+    const localFileMap = new Map();
+    for (const file of localFiles) {
+      localFileMap.set(file.relativePath, file);
     }
 
-    const driveFiles = [];
-    const stdout = listResult.stdout.trim();
-    if (stdout) {
-      const parsed = gdrive.parseListOutput(stdout);
-      for (const file of parsed) {
-        if (file.id && file.name && matchPattern(file.name, pattern, ignore)) {
-          driveFiles.push({ id: file.id, name: file.name });
+    // 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 Drive files to temp for comparison
-    s.message('Downloading Drive files for comparison...');
-    for (const file of driveFiles) {
-      gdrive.download(file.id, { destination: tempDir, overwrite: true });
+    // 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);
     }
-    s.stop(color.green(`Found ${driveFiles.length} matching file(s) on Drive`));
 
-    // Get local files
-    fs.ensureDirSync(envDir);
-    const localFiles = fs.readdirSync(envDir).filter((f) => matchPattern(f, pattern, ignore));
+    // 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
+    // Compare files using relativePath
     const changes = {
       modified: [],
       localOnly: [],
       driveOnly: [],
+      orphanDriveFolders: [], // Folders on Drive with no local equivalent
     };
 
+    // 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 filename of localFiles) {
-      const localFile = path.join(envDir, filename);
-      const driveFile = path.join(tempDir, filename);
-
-      if (fs.existsSync(driveFile)) {
-        const localContent = fs.readFileSync(localFile, 'utf-8');
-        const driveContent = fs.readFileSync(driveFile, 'utf-8');
-        if (localContent !== driveContent) {
-          changes.modified.push(filename);
+    for (const localFile of localFiles) {
+      const localFilePath = path.join(envDir, localFile.relativePath);
+      const driveFilePath = path.join(tempDir, localFile.relativePath);
+
+      if (driveFilePaths.has(localFile.relativePath)) {
+        // 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');
+          if (localContent !== driveContent) {
+            changes.modified.push(localFile.relativePath);
+          }
         }
       } else {
-        changes.localOnly.push(filename);
+        changes.localOnly.push(localFile.relativePath);
       }
     }
 
     // Check Drive-only files
-    for (const file of driveFiles) {
-      if (!localFiles.includes(file.name)) {
-        changes.driveOnly.push(file.name);
+    for (const driveFile of driveFiles) {
+      if (!localFilePaths.has(driveFile.relativePath)) {
+        changes.driveOnly.push(driveFile.relativePath);
+      }
+    }
+
+    // Check for orphan Drive folders (folders on Drive with no local equivalent)
+    for (const driveFolder of driveFolders) {
+      if (!localFolderPaths.has(driveFolder.relativePath)) {
+        // Only mark as orphan if no local files exist under this folder path
+        const hasLocalFilesUnder = localFiles.some((f) =>
+          f.relativePath.startsWith(driveFolder.relativePath + '/')
+        );
+        if (!hasLocalFilesUnder) {
+          changes.orphanDriveFolders.push(driveFolder);
+        }
       }
     }
 
     const hasChanges =
-      changes.modified.length > 0 || changes.localOnly.length > 0 || changes.driveOnly.length > 0;
+      changes.modified.length > 0 ||
+      changes.localOnly.length > 0 ||
+      changes.driveOnly.length > 0 ||
+      changes.orphanDriveFolders.length > 0;
 
     if (!hasChanges) {
       log.success('No changes detected. Local and Drive are in sync.');
@@ -991,21 +1389,21 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
     log.info(color.bold('Changes Preview:'));
     console.log('');
 
-    for (const filename of changes.modified) {
-      const localFile = path.join(envDir, filename);
-      const driveFile = path.join(tempDir, filename);
+    for (const relativePath of changes.modified) {
+      const localFilePath = path.join(envDir, relativePath);
+      const driveFilePath = path.join(tempDir, relativePath);
       // Swap order based on action: upload shows drive->local, download shows local->drive
       const diffResult = isUpload
-        ? shell.exec(`diff -u "${driveFile}" "${localFile}"`, { silent: true })
-        : shell.exec(`diff -u "${localFile}" "${driveFile}"`, { silent: true });
+        ? shell.exec(`diff -u "${driveFilePath}" "${localFilePath}"`, { silent: true })
+        : shell.exec(`diff -u "${localFilePath}" "${driveFilePath}"`, { silent: true });
 
       if (diffResult.stdout) {
         const lines = diffResult.stdout.split('\n');
         lines.forEach((line) => {
           if (line.startsWith('---')) {
-            console.log(color.cyan(`--- ${filename} (${isUpload ? 'Drive' : 'Local'})`));
+            console.log(color.cyan(`--- ${relativePath} (${isUpload ? 'Drive' : 'Local'})`));
           } else if (line.startsWith('+++')) {
-            console.log(color.cyan(`+++ ${filename} (${isUpload ? 'Local' : 'Drive'})`));
+            console.log(color.cyan(`+++ ${relativePath} (${isUpload ? 'Local' : 'Drive'})`));
           } else if (line.startsWith('@@')) {
             console.log(color.cyan(line));
           } else if (line.startsWith('-')) {
@@ -1020,30 +1418,71 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       }
     }
 
-    for (const filename of changes.localOnly) {
-      console.log(color.cyan(`--- /dev/null`));
-      console.log(color.cyan(`+++ ${filename} (Local only)`));
-      console.log(color.green(`  [New local file - will be uploaded]`));
+    for (const relativePath of changes.localOnly) {
+      if (action === 'diff') {
+        console.log(color.green(`+ ${relativePath}`));
+        console.log(color.dim(`  Local only`));
+      } else if (isUpload) {
+        console.log(color.green(`+ ${relativePath}`));
+        console.log(color.dim(`  Local only → will be uploaded to Drive`));
+      } else {
+        console.log(color.red(`- ${relativePath}`));
+        console.log(color.dim(`  Local only → can be deleted (not on Drive)`));
+      }
       console.log('');
     }
 
-    for (const filename of changes.driveOnly) {
-      console.log(color.cyan(`--- /dev/null`));
-      console.log(color.cyan(`+++ ${filename} (Drive only)`));
-      console.log(color.green(`  [New Drive file - will be downloaded]`));
+    for (const relativePath of changes.driveOnly) {
+      if (action === 'diff') {
+        console.log(color.yellow(`+ ${relativePath}`));
+        console.log(color.dim(`  Drive only`));
+      } else if (isUpload) {
+        console.log(color.red(`- ${relativePath}`));
+        console.log(color.dim(`  Drive only → can be deleted from Drive (not local)`));
+      } else {
+        console.log(color.green(`+ ${relativePath}`));
+        console.log(color.dim(`  Drive only → will be downloaded to local`));
+      }
+      console.log('');
+    }
+
+    // Show orphan Drive folders
+    for (const folder of changes.orphanDriveFolders) {
+      if (action === 'diff') {
+        console.log(color.yellow(`📁 ${folder.relativePath}/`));
+        console.log(color.dim(`  Empty folder on Drive only`));
+      } else if (isUpload) {
+        console.log(color.red(`- 📁 ${folder.relativePath}/`));
+        console.log(color.dim(`  Empty folder on Drive → can be deleted`));
+      }
       console.log('');
     }
 
     // Summary
     const summaryLines = [];
     if (changes.modified.length > 0) {
-      summaryLines.push(`${color.cyan('Modified:')} ${changes.modified.join(', ')}`);
+      summaryLines.push(`${color.cyan('Modified:')} ${changes.modified.length} file(s)`);
     }
     if (changes.localOnly.length > 0) {
-      summaryLines.push(`${color.green('Local only:')} ${changes.localOnly.join(', ')}`);
+      if (action === 'diff') {
+        summaryLines.push(`${color.green('Local only:')} ${changes.localOnly.length} file(s)`);
+      } else if (isUpload) {
+        summaryLines.push(`${color.green('To upload:')} ${changes.localOnly.length} file(s)`);
+      } else {
+        summaryLines.push(`${color.red('Local only (can delete):')} ${changes.localOnly.length} file(s)`);
+      }
     }
     if (changes.driveOnly.length > 0) {
-      summaryLines.push(`${color.yellow('Drive only:')} ${changes.driveOnly.join(', ')}`);
+      if (action === 'diff') {
+        summaryLines.push(`${color.yellow('Drive only:')} ${changes.driveOnly.length} file(s)`);
+      } else if (isUpload) {
+        summaryLines.push(`${color.red('Drive only (can delete):')} ${changes.driveOnly.length} file(s)`);
+      } else {
+        summaryLines.push(`${color.green('To download:')} ${changes.driveOnly.length} file(s)`);
+      }
+    }
+    if (changes.orphanDriveFolders.length > 0 && (action === 'diff' || isUpload)) {
+      summaryLines.push(`${color.red('Empty folders on Drive:')} ${changes.orphanDriveFolders.length} folder(s)`);
     }
     note(summaryLines.join('\n'), 'Summary');
 
@@ -1063,15 +1502,18 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
     }
 
     if (action === 'download') {
-      // Create backup first
-      const existingFiles = fs.readdirSync(envDir).filter((f) => matchPattern(f, pattern, ignore));
-      if (existingFiles.length > 0) {
+      // Create backup first (recursive)
+      const existingLocalFiles = listLocalFilesRecursive(envDir, pattern, ignore);
+      if (existingLocalFiles.length > 0) {
         const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
         const backupSubdir = path.join(backupPath, `${name}_${timestamp}`);
         fs.ensureDirSync(backupSubdir);
 
-        for (const file of existingFiles) {
-          fs.copyFileSync(path.join(envDir, file), path.join(backupSubdir, file));
+        for (const file of existingLocalFiles) {
+          const srcPath = path.join(envDir, file.relativePath);
+          const destPath = path.join(backupSubdir, file.relativePath);
+          fs.ensureDirSync(path.dirname(destPath));
+          fs.copyFileSync(srcPath, destPath);
         }
         log.info(`Backup created: ${backupSubdir}`);
       }
@@ -1081,13 +1523,19 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
 
       let downloaded = 0;
 
-      for (const filename of changes.modified) {
-        fs.copyFileSync(path.join(tempDir, filename), path.join(envDir, filename));
+      for (const relativePath of changes.modified) {
+        const srcPath = path.join(tempDir, relativePath);
+        const destPath = path.join(envDir, relativePath);
+        fs.ensureDirSync(path.dirname(destPath));
+        fs.copyFileSync(srcPath, destPath);
         downloaded++;
       }
 
-      for (const filename of changes.driveOnly) {
-        fs.copyFileSync(path.join(tempDir, filename), path.join(envDir, filename));
+      for (const relativePath of changes.driveOnly) {
+        const srcPath = path.join(tempDir, relativePath);
+        const destPath = path.join(envDir, relativePath);
+        fs.ensureDirSync(path.dirname(destPath));
+        fs.copyFileSync(srcPath, destPath);
         downloaded++;
       }
 
@@ -1099,20 +1547,134 @@ const runSyncOperation = async (syncConfig, action, projectRoot, backupPath, con
       let uploaded = 0;
       let replaced = 0;
 
-      for (const filename of changes.modified) {
-        const driveFile = driveFiles.find((f) => f.name === filename);
+      // Build a map of relativePath -> driveFile for quick lookup
+      const driveFileMap = new Map();
+      for (const df of driveFiles) {
+        driveFileMap.set(df.relativePath, df);
+      }
+
+      for (const relativePath of changes.modified) {
+        const driveFile = driveFileMap.get(relativePath);
         if (driveFile) {
-          gdrive.update(driveFile.id, path.join(envDir, filename));
+          gdrive.update(driveFile.id, path.join(envDir, relativePath));
           replaced++;
         }
       }
 
-      for (const filename of changes.localOnly) {
-        gdrive.upload(path.join(envDir, filename), { parent: folderId });
+      for (const relativePath of changes.localOnly) {
+        const localFilePath = path.join(envDir, relativePath);
+        const folderPath = path.dirname(relativePath);
+
+        // Find or create the parent folder on Drive
+        let parentId = folderId;
+        if (folderPath && folderPath !== '.') {
+          parentId = findOrCreateDriveFolder(folderId, folderPath);
+        }
+
+        gdrive.upload(localFilePath, { parent: parentId });
         uploaded++;
       }
 
       uploadSpinner.stop(color.green(`Replaced: ${replaced}, New: ${uploaded}`));
+
+      // Ask about deleting Drive-only files and orphan folders
+      const hasOrphanItems = changes.driveOnly.length > 0 || changes.orphanDriveFolders.length > 0;
+      if (hasOrphanItems) {
+        console.log('');
+        const totalItems = changes.driveOnly.length + changes.orphanDriveFolders.length;
+        log.warn(`${totalItems} item(s) exist on Drive but not locally:`);
+        for (const relativePath of changes.driveOnly) {
+          console.log(color.red(`  - ${relativePath}`));
+        }
+        for (const folder of changes.orphanDriveFolders) {
+          console.log(color.red(`  - 📁 ${folder.relativePath}/`));
+        }
+        console.log('');
+
+        const deleteFromDrive = await confirm({
+          message: `Delete these ${totalItems} item(s) from Drive?`,
+          initialValue: false,
+        });
+
+        if (!isCancel(deleteFromDrive) && deleteFromDrive) {
+          const deleteSpinner = spinner();
+          deleteSpinner.start('Deleting items from Drive...');
+
+          let deletedFiles = 0;
+          let deletedFolders = 0;
+
+          // Delete orphan files first
+          for (const relativePath of changes.driveOnly) {
+            const driveFile = driveFileMap.get(relativePath);
+            if (driveFile) {
+              gdrive.remove(driveFile.id);
+              deletedFiles++;
+            }
+          }
+
+          // Delete orphan folders (sort by depth, deepest first)
+          const sortedFolders = [...changes.orphanDriveFolders].sort((a, b) =>
+            b.relativePath.split('/').length - a.relativePath.split('/').length
+          );
+
+          for (const folder of sortedFolders) {
+            gdrive.remove(folder.id, { recursive: true });
+            deletedFolders++;
+          }
+
+          const resultParts = [];
+          if (deletedFiles > 0) resultParts.push(`${deletedFiles} file(s)`);
+          if (deletedFolders > 0) resultParts.push(`${deletedFolders} folder(s)`);
+          deleteSpinner.stop(color.green(`Deleted ${resultParts.join(' and ')} from Drive`));
+        }
+      }
+    }
+
+    // Ask about deleting local-only files during download
+    if (action === 'download' && changes.localOnly.length > 0) {
+      console.log('');
+      log.warn(`${changes.localOnly.length} file(s) exist locally but not on Drive:`);
+      for (const relativePath of changes.localOnly) {
+        console.log(color.red(`  - ${relativePath}`));
+      }
+      console.log('');
+      log.info(color.dim('(These files are included in the backup)'));
+
+      const deleteLocal = await confirm({
+        message: `Delete these ${changes.localOnly.length} local file(s)?`,
+        initialValue: false,
+      });
+
+      if (!isCancel(deleteLocal) && deleteLocal) {
+        const deleteSpinner = spinner();
+        deleteSpinner.start('Deleting local files...');
+
+        let deleted = 0;
+        for (const relativePath of changes.localOnly) {
+          const filePath = path.join(envDir, relativePath);
+          if (fs.existsSync(filePath)) {
+            fs.removeSync(filePath);
+            deleted++;
+          }
+        }
+
+        // Clean up empty directories
+        const cleanEmptyDirs = (dir) => {
+          if (!fs.existsSync(dir)) return;
+          const entries = fs.readdirSync(dir);
+          if (entries.length === 0 && dir !== envDir) {
+            fs.rmdirSync(dir);
+            cleanEmptyDirs(path.dirname(dir));
+          }
+        };
+
+        for (const relativePath of changes.localOnly) {
+          const dirPath = path.dirname(path.join(envDir, relativePath));
+          cleanEmptyDirs(dirPath);
+        }
+
+        deleteSpinner.stop(color.green(`Deleted ${deleted} local file(s)`));
+      }
     }
   } catch (e) {
     log.error(e.message);
@@ -1347,4 +1909,7 @@ module.exports = {
   // Exported for testing
   globToRegex,
   matchPattern,
+  listDriveFilesRecursive,
+  listLocalFilesRecursive,
+  findOrCreateDriveFolder,
 };