Fix folder_not_found errors for imported projects

- Add --probe-folder flag to push command to find correct root folder ID
- Store discovered rootFolderId in .olcli.json for future pushes
- Expand probing range to handle projects with non-standard folder offsets
- Show helpful tip when folder_not_found errors occur

Fixes upload failures for projects imported from external sources (ZIP, Git)
where the root folder ID doesn't follow the standard projectId - 1 pattern.

Author: aloth

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloth/olcli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Overleaf CLI - sync and manage LaTeX projects from the command line",
   "type": "module",
   "bin": {

package.json

@@ -662,6 +662,7 @@ program
   .option('--project <name>', 'Project name or ID (overrides .olcli.json)')
   .option('--all', 'Upload all files (not just changed)')
   .option('--dry-run', 'Show what would be uploaded without uploading')
+  .option('--probe-folder', 'Probe for correct folder ID (use if uploads fail with folder_not_found)')
   .option('--cookie <session>', 'Session cookie override')
   .action(async (dir, options) => {
     const targetDir = dir || '.';
@@ -671,12 +672,14 @@ program
     let projectId: string | undefined;
     let projectName: string | undefined;
     let lastPull: Date | undefined;
+    let rootFolderId: string | undefined;
 
     if (existsSync(metaPath)) {
       const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
       projectId = meta.projectId;
       projectName = meta.projectName;
       lastPull = meta.lastPull ? new Date(meta.lastPull) : undefined;
+      rootFolderId = meta.rootFolderId;
     }
 
     if (options.project) {
@@ -757,32 +760,59 @@ program
         return;
       }
 
+      // If --probe-folder is set, or if we don't have a cached rootFolderId, try probing
+      if (options.probeFolder && !rootFolderId) {
+        spinner.text = 'Probing for correct folder ID...';
+        rootFolderId = await client.probeRootFolderId(projectId!) ?? undefined;
+        if (rootFolderId) {
+          // Save the discovered folder ID
+          if (existsSync(metaPath)) {
+            const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+            meta.rootFolderId = rootFolderId;
+            writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+          }
+          spinner.succeed(`Found root folder ID: ${rootFolderId}`);
+          spinner.start(`Uploading ${filesToUpload.length} file(s)...`);
+        } else {
+          spinner.fail('Could not find valid root folder ID');
+          console.log(chalk.yellow('Try manually specifying rootFolderId in .olcli.json'));
+          process.exit(1);
+        }
+      }
+
       spinner.text = `Uploading ${filesToUpload.length} file(s)...`;
 
       let uploaded = 0;
       let failed = 0;
+      let folderNotFoundCount = 0;
 
       for (const file of filesToUpload) {
         try {
           const content = readFileSync(file.path);
-          await client.uploadFile(projectId!, null, file.relativePath, content);
+          await client.uploadFile(projectId!, rootFolderId || null, file.relativePath, content);
           uploaded++;
           spinner.text = `Uploading... (${uploaded}/${filesToUpload.length})`;
         } catch (error: any) {
           console.error(chalk.yellow(`\n  Warning: Failed to upload ${file.relativePath}: ${error.message}`));
           failed++;
+          if (error.message.includes('folder_not_found')) {
+            folderNotFoundCount++;
+          }
         }
       }
 
-      // Update last pull time
+      // Update last push time
       if (existsSync(metaPath)) {
         const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
         meta.lastPush = new Date().toISOString();
         writeFileSync(metaPath, JSON.stringify(meta, null, 2));
       }
 
       if (failed > 0) {
-        spinner.warn(`Uploaded ${uploaded} files, ${failed} failed`);
+        spinner.warn(`Uploaded ${uploaded} file(s), ${failed} failed`);
+        if (folderNotFoundCount > 0 && !rootFolderId) {
+          console.log(chalk.yellow('  Tip: Try running with --probe-folder to find the correct folder ID'));
+        }
       } else {
         spinner.succeed(`Uploaded ${uploaded} file(s) to "${projectName}"`);
       }

src/cli.ts

@@ -420,6 +420,69 @@ export class OverleafClient {
     return this.computeRootFolderId(projectId);
   }
 
+  /**
+   * Find root folder ID by probing multiple candidates
+   * This handles cases where projectId - 1 doesn't work
+   */
+  async probeRootFolderId(projectId: string): Promise<string | null> {
+    const candidates: string[] = [];
+    
+    // Method 1: Try projectId - 1 (most common)
+    candidates.push(this.computeRootFolderId(projectId));
+    
+    const prefix = projectId.slice(0, 16);
+    const suffix = parseInt(projectId.slice(16), 16);
+    
+    // Method 2: Try a wide range around the project ID
+    // Some projects have root folder created with different offsets
+    for (let i = 2; i <= 50; i++) {
+      if (suffix - i >= 0) {
+        candidates.push(prefix + (suffix - i).toString(16).padStart(8, '0'));
+      }
+    }
+    for (let i = 1; i <= 50; i++) {
+      candidates.push(prefix + (suffix + i).toString(16).padStart(8, '0'));
+    }
+
+    // Test each candidate with a minimal probe request
+    for (const folderId of candidates) {
+      try {
+        // Try to create a temp file to probe the folder
+        const testFileName = `.olcli-probe-${Date.now()}.tmp`;
+        const formData = new FormData();
+        formData.append('targetFolderId', folderId);
+        formData.append('name', testFileName);
+        formData.append('type', 'text/plain');
+        formData.append('qqfile', new Blob(['probe']), testFileName);
+
+        const response = await fetch(`${UPLOAD_URL.replace('{id}', projectId)}?folder_id=${folderId}`, {
+          method: 'POST',
+          headers: {
+            'Cookie': this.getCookieHeader(),
+            'User-Agent': USER_AGENT,
+            'X-Csrf-Token': this.csrf
+          },
+          body: formData
+        });
+
+        const data = await response.json() as any;
+        if (data.success !== false && data.entity_id) {
+          // Success! Delete the probe file and return this folder ID
+          try {
+            await this.deleteEntity(projectId, data.entity_id, 'doc');
+          } catch (e) {
+            // Ignore delete errors for probe file
+          }
+          return folderId;
+        }
+      } catch (e) {
+        // Continue to next candidate
+      }
+    }
+
+    return null;
+  }
+
   /**
    * Upload a file to a project
    */
@@ -430,7 +493,7 @@ export class OverleafClient {
     content: Buffer
   ): Promise<{ success: boolean; entityId?: string; entityType?: string }> {
     // If no folder ID provided, get the root folder
-    const targetFolderId = folderId || await this.getRootFolderId(projectId);
+    let targetFolderId = folderId || await this.getRootFolderId(projectId);
 
     // Extract just the filename without path (PR #73 fix)
     const baseName = fileName.split('/').pop() || fileName;
@@ -452,33 +515,60 @@ export class OverleafClient {
     };
     const mimeType = mimeTypes[ext] || 'application/octet-stream';
 
-    const formData = new FormData();
-    // Match Overleaf-Workshop: include targetFolderId in form data
-    formData.append('targetFolderId', targetFolderId);
-    formData.append('name', baseName);
-    formData.append('type', mimeType);
-    formData.append('qqfile', new Blob([content]), baseName);
+    // Helper function to attempt upload with a specific folder ID
+    const tryUpload = async (fid: string): Promise<{ success: boolean; entityId?: string; entityType?: string; error?: string }> => {
+      const formData = new FormData();
+      formData.append('targetFolderId', fid);
+      formData.append('name', baseName);
+      formData.append('type', mimeType);
+      formData.append('qqfile', new Blob([content]), baseName);
+
+      const response = await fetch(`${UPLOAD_URL.replace('{id}', projectId)}?folder_id=${fid}`, {
+        method: 'POST',
+        headers: {
+          'Cookie': this.getCookieHeader(),
+          'User-Agent': USER_AGENT,
+          'X-Csrf-Token': this.csrf
+        },
+        body: formData
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        return { success: false, error: `${response.status} - ${text}` };
+      }
 
-    const response = await fetch(`${UPLOAD_URL.replace('{id}', projectId)}?folder_id=${targetFolderId}`, {
-      method: 'POST',
-      headers: {
-        'Cookie': this.getCookieHeader(),
-        'User-Agent': USER_AGENT,
-        'X-Csrf-Token': this.csrf
-      },
-      body: formData
-    });
+      const data = await response.json() as any;
+      if (data.success === false && data.error === 'folder_not_found') {
+        return { success: false, error: 'folder_not_found' };
+      }
+      return {
+        success: data.success !== false,
+        entityId: data.entity_id,
+        entityType: data.entity_type
+      };
+    };
 
-    if (!response.ok) {
-      const text = await response.text();
-      throw new Error(`Failed to upload file: ${response.status} - ${text}`);
+    // First attempt with computed/cached folder ID
+    let result = await tryUpload(targetFolderId);
+    
+    // If folder not found, probe for the correct folder ID
+    if (!result.success && result.error === 'folder_not_found') {
+      const probedFolderId = await this.probeRootFolderId(projectId);
+      if (probedFolderId && probedFolderId !== targetFolderId) {
+        targetFolderId = probedFolderId;
+        result = await tryUpload(targetFolderId);
+      }
+    }
+
+    if (!result.success) {
+      throw new Error(`Failed to upload file: ${result.error || 'unknown error'}`);
     }
 
-    const data = await response.json() as any;
     return {
-      success: data.success !== false,
-      entityId: data.entity_id,
-      entityType: data.entity_type
+      success: result.success,
+      entityId: result.entityId,
+      entityType: result.entityType
     };
   }