@aloth/olcli 0.1.8 → 0.3.0

package/README.md

@@ -21,11 +21,13 @@ Work with Overleaf projects directly from your command line. Edit locally with y
 - ⬇️ **Pull** project files to local directory for offline editing
 - ⬆️ **Push** local changes back to Overleaf
 - 🔄 **Sync** bidirectionally with smart conflict detection
+- ✌️ **Two-way deletions** — files removed locally are deleted on Overleaf on the next sync (opt out with `--no-delete`)
+- 🗑️ **Delete** and ✏️ **rename** remote files by path
+- 🚫 **Smart ignore** — LaTeX build artifacts (`.aux`, `.bbl`, `.log`, `.synctex.gz`, …) and OS noise are filtered out automatically; extend with `.olignore` (gitignore-style)
 - 📄 **Compile** PDFs using Overleaf's remote compiler
 - 📦 **Download** individual files or full project archives
 - 📤 **Upload** files to projects
 - 🗂️ **Preserve folder structure** when pushing nested files
-- 🧹 **Skip generated `output.pdf`** during push/sync so compiled artifacts are not uploaded back to Overleaf
 - ⚙️ **Support self-hosted Overleaf/ShareLaTeX instances** via configurable base URL and session cookie name
 - 📊 **Output** compile artifacts (`.bbl`, `.log`, `.aux` for arXiv submissions)
 
@@ -165,8 +167,9 @@ All commands auto-detect the project when run from a synced directory (contains
 | `olcli sync [dir]` | Bidirectional sync (pull + push) |
 | `olcli upload <file> [project]` | Upload a single file |
 | `olcli download <file> [project]` | Download a single file |
-| `olcli delete <file> [project]` | Delete a remote file by path |
-| `olcli rename <oldname> <newname> [project]` | Rename a remote file by path |
+| `olcli delete <file> [project]` | Delete a remote file or folder by path (alias: `rm`) |
+| `olcli rename <oldname> <newname> [project]` | Rename a remote file or folder by path (alias: `mv`) |
+| `olcli ignored [dir]` | List ignore patterns currently in effect |
 | `olcli zip [project]` | Download project as zip archive |
 | `olcli compile [project]` | Trigger PDF compilation |
 | `olcli pdf [project]` | Compile and download PDF |
@@ -252,16 +255,69 @@ olcli output --list
 ### Push
 - Uploads files modified after last pull
 - Preserves nested folder structure when uploading
-- Skips generated `output.pdf`
+- Filters out LaTeX build artifacts and OS noise (see [Ignoring files](#ignoring-files))
 - Use `--all` to upload all files
 - Use `--dry-run` to preview changes
+- Use `--show-ignored` to see what was filtered out
 
 ### Sync
 - Pulls remote changes
 - Preserves local modifications (local wins if newer)
 - Pushes local changes to remote
-- Skips generated `output.pdf` during upload phase
+- **Propagates local deletions to the remote** — if you delete a file locally, it's deleted on Overleaf on the next sync. Use `--no-delete` to opt out.
+- Filters out LaTeX build artifacts and OS noise
 - Use `--verbose` to see detailed file operations
+- Use `--dry-run` to preview without applying
+
+#### How deletion propagation works
+
+On every sync, `olcli` records a manifest of remote files in `.olcli.json`. The next sync compares the manifest against your local working tree:
+
+- File missing locally **and** still present on remote → deleted on Overleaf
+- File new locally → uploaded
+- File modified locally after last pull → uploaded (local wins)
+- File only on remote → downloaded
+
+First-time syncs skip the deletion phase (no manifest exists yet to distinguish "never had it" from "deleted it").
+
+## Ignoring files
+
+`olcli` automatically filters local files through a layered ignore list before uploading. This keeps LaTeX build artifacts (from local `pdflatex`/`latexmk` runs) and OS noise out of your Overleaf project.
+
+### Three layers
+
+| Layer | File | Purpose |
+|---|---|---|
+| 1 | (built-in) | LaTeX intermediates (`.aux`, `.bbl`, `.log`, `.fls`, `.synctex.gz`, beamer/biber/glossaries/minted), OS noise (`.DS_Store`, `Thumbs.db`, `*.swp`), common build dirs (`build/`, `out/`, `_minted-*/`). Always on; opt out with `--no-default-ignore`. |
+| 2 | `.olignore` | Project-level patterns, gitignore syntax. Commit alongside your `.tex` sources. |
+| 3 | `.olignore.local` | Machine-specific patterns. Add to `.gitignore`. |
+
+Later layers override earlier ones, just like git. Negation (`!important.aux`) is supported.
+
+### Special PDF rule
+
+`X.pdf` is ignored only if a same-named `X.tex` (or `.ltx`) exists in the same folder. So `thesis.pdf` next to `thesis.tex` is filtered, but a hand-uploaded `figures/diagram.pdf` still syncs.
+
+### Example `.olignore`
+
+```gitignore
+# Drafts that should never reach Overleaf
+*.draft.tex
+notes/
+chapters/scratch/
+
+# But keep this one auxiliary file
+!important.aux
+```
+
+### Inspecting and overriding
+
+```bash
+olcli ignored                  # list patterns currently in effect
+olcli push --show-ignored      # see what was skipped on this run
+olcli sync --no-default-ignore # only .olignore applies
+olcli sync --no-ignore         # escape hatch — upload everything
+```
 
 ## Configuration
 

package/dist/cli.js

@@ -12,6 +12,7 @@ import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { OverleafClient } from './client.js';
+import { loadIgnore, shouldIgnore, buildTexSiblingSet, } from './ignore.js';
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -387,47 +388,49 @@ program
         process.exit(1);
     }
 });
-// NOTE: delete and rename commands are disabled - they require entity IDs
-// which are not exposed via the current Overleaf API without Socket.IO.
-// Use the Overleaf web UI for these operations.
-//
-// program
-//   .command('delete <file> [project]')
-//   .alias('rm')
-//   .description('Delete a file from a project')
-//   .option('--cookie <session>', 'Session cookie override')
-//   .action(async (file, project, options) => {
-//     const spinner = ora('Deleting file...').start();
-//     try {
-//       const client = await getClient(options.cookie);
-//       const proj = await resolveProject(client, project);
-//       await client.deleteByPath(proj.id, file);
-//       spinner.succeed(`Deleted: ${file}`);
-//       setLastProject(proj.id);
-//     } catch (error: any) {
-//       spinner.fail(`Failed: ${error.message}`);
-//       process.exit(1);
-//     }
-//   });
-//
-// program
-//   .command('rename <oldname> <newname> [project]')
-//   .alias('mv')
-//   .description('Rename a file in a project')
-//   .option('--cookie <session>', 'Session cookie override')
-//   .action(async (oldname, newname, project, options) => {
-//     const spinner = ora('Renaming file...').start();
-//     try {
-//       const client = await getClient(options.cookie);
-//       const proj = await resolveProject(client, project);
-//       await client.renameByPath(proj.id, oldname, newname);
-//       spinner.succeed(`Renamed: ${oldname} → ${newname}`);
-//       setLastProject(proj.id);
-//     } catch (error: any) {
-//       spinner.fail(`Failed: ${error.message}`);
-//       process.exit(1);
-//     }
-//   });
+// ─────────────────────────────────────────────────────────────────────────────
+// DELETE / RENAME COMMANDS
+// ─────────────────────────────────────────────────────────────────────────────
+// Use deleteByPath / renameByPath which resolve a path to an entity id via
+// /project/<id>/entities, then call the documented delete/rename endpoints.
+program
+    .command('delete <file> [project]')
+    .alias('rm')
+    .description('Delete a file or folder from a project')
+    .option('--cookie <session>', 'Session cookie override')
+    .action(async (file, project, options) => {
+    const spinner = ora('Deleting file...').start();
+    try {
+        const client = await getClient(options.cookie);
+        const proj = await resolveProject(client, project);
+        await client.deleteByPath(proj.id, file);
+        spinner.succeed(`Deleted: ${file}`);
+        setLastProject(proj.id);
+    }
+    catch (error) {
+        spinner.fail(`Failed: ${error.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('rename <oldname> <newname> [project]')
+    .alias('mv')
+    .description('Rename a file or folder in a project')
+    .option('--cookie <session>', 'Session cookie override')
+    .action(async (oldname, newname, project, options) => {
+    const spinner = ora('Renaming file...').start();
+    try {
+        const client = await getClient(options.cookie);
+        const proj = await resolveProject(client, project);
+        await client.renameByPath(proj.id, oldname, newname);
+        spinner.succeed(`Renamed: ${oldname} → ${newname}`);
+        setLastProject(proj.id);
+    }
+    catch (error) {
+        spinner.fail(`Failed: ${error.message}`);
+        process.exit(1);
+    }
+});
 // ─────────────────────────────────────────────────────────────────────────────
 // COMPILE COMMAND
 // ─────────────────────────────────────────────────────────────────────────────
@@ -544,11 +547,17 @@ program
                 fileCount++;
             }
         }
-        // Save project metadata
+        // Save project metadata (with manifest of remote files for sync deletion tracking)
+        const remoteManifest = [];
+        for (const e of entries) {
+            if (!e.isDirectory)
+                remoteManifest.push(e.entryName);
+        }
         writeFileSync(join(targetDir, '.olcli.json'), JSON.stringify({
             projectId,
             projectName,
-            lastPull: new Date().toISOString()
+            lastPull: new Date().toISOString(),
+            remoteManifest
         }, null, 2));
         if (skippedCount > 0) {
             spinner.warn(`Downloaded ${fileCount} files, skipped ${skippedCount} locally modified files`);
@@ -578,6 +587,9 @@ program
     .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('--no-default-ignore', 'Disable built-in LaTeX artifact ignore list (only .olignore applies)')
+    .option('--no-ignore', 'Disable all ignore filtering (escape hatch — uploads everything)')
+    .option('--show-ignored', 'Print files skipped by ignore rules')
     .option('--cookie <session>', 'Session cookie override')
     .action(async (dir, options) => {
     const targetDir = dir || '.';
@@ -621,23 +633,38 @@ program
             projectName = proj.name;
         }
         spinner.text = 'Scanning files...';
+        // Build ignore context (defaults + .olignore + .olignore.local)
+        const ignoreCtx = loadIgnore(targetDir, {
+            noDefaults: options.defaultIgnore === false,
+            disableAll: options.ignore === false,
+        });
         // Get list of files to upload
         const { readdirSync, statSync } = await import('node:fs');
         const filesToUpload = [];
+        const filesIgnored = [];
         function scanDir(currentDir, relativeBase = '') {
             const entries = readdirSync(currentDir, { withFileTypes: true });
+            // Pre-compute sibling .tex set for the PDF special rule.
+            const texSiblings = buildTexSiblingSet(entries.filter((e) => !e.isDirectory()).map((e) => e.name));
             for (const entry of entries) {
-                // Skip hidden files and .olcli.json
+                // Skip hidden files and .olcli.json (always — predates ignore subsystem)
                 if (entry.name.startsWith('.'))
                     continue;
                 const fullPath = join(currentDir, entry.name);
                 const relativePath = relativeBase ? `${relativeBase}/${entry.name}` : entry.name;
-                if (!entry.isDirectory() && entry.name === 'output.pdf')
-                    continue;
                 if (entry.isDirectory()) {
+                    // Test directory ignore (gitignore semantics: trailing slash matches dir)
+                    if (shouldIgnore(`${relativePath}/`, ignoreCtx)) {
+                        filesIgnored.push(`${relativePath}/`);
+                        continue;
+                    }
                     scanDir(fullPath, relativePath);
                 }
                 else {
+                    if (shouldIgnore(relativePath, ignoreCtx, texSiblings)) {
+                        filesIgnored.push(relativePath);
+                        continue;
+                    }
                     // Check if file is newer than last pull (unless --all)
                     if (options.all || !lastPull) {
                         filesToUpload.push({ path: fullPath, relativePath });
@@ -652,6 +679,14 @@ program
             }
         }
         scanDir(targetDir);
+        if (options.showIgnored && filesIgnored.length > 0) {
+            spinner.stop();
+            console.log(chalk.bold(chalk.dim(`Ignored ${filesIgnored.length} file(s)/dir(s):`)));
+            for (const p of filesIgnored) {
+                console.log(chalk.dim(`  ${p}`));
+            }
+            spinner.start('Scanning files...');
+        }
         if (filesToUpload.length === 0) {
             spinner.info('No files to upload');
             return;
@@ -735,9 +770,14 @@ program
 });
 program
     .command('sync [dir]')
-    .description('Pull then push (bidirectional sync)')
+    .description('Pull then push (bidirectional sync, propagates local deletions)')
     .option('--project <name>', 'Project name or ID')
     .option('--verbose', 'Show detailed file operations')
+    .option('--no-delete', 'Do not propagate local deletions to the remote (safer)')
+    .option('--dry-run', 'Show what would change without applying')
+    .option('--no-default-ignore', 'Disable built-in LaTeX artifact ignore list (only .olignore applies)')
+    .option('--no-ignore', 'Disable all ignore filtering (escape hatch — uploads everything)')
+    .option('--show-ignored', 'Print files skipped by ignore rules')
     .option('--cookie <session>', 'Session cookie override')
     .action(async (dir, options) => {
     const targetDir = dir || '.';
@@ -784,22 +824,37 @@ program
         if (!existsSync(targetDir)) {
             mkdirSync(targetDir, { recursive: true });
         }
+        // Build ignore context (defaults + .olignore + .olignore.local)
+        const ignoreCtx = loadIgnore(targetDir, {
+            noDefaults: options.defaultIgnore === false,
+            disableAll: options.ignore === false,
+        });
         // Track local modifications
         const localFiles = new Map();
+        const filesIgnored = [];
         const { readdirSync, statSync } = await import('node:fs');
         function scanLocalFiles(currentDir, relativeBase = '') {
             if (!existsSync(currentDir))
                 return;
             const entries = readdirSync(currentDir, { withFileTypes: true });
+            const texSiblings = buildTexSiblingSet(entries.filter((e) => !e.isDirectory()).map((e) => e.name));
             for (const entry of entries) {
                 if (entry.name.startsWith('.'))
                     continue;
                 const fullPath = join(currentDir, entry.name);
                 const relativePath = relativeBase ? `${relativeBase}/${entry.name}` : entry.name;
                 if (entry.isDirectory()) {
+                    if (shouldIgnore(`${relativePath}/`, ignoreCtx)) {
+                        filesIgnored.push(`${relativePath}/`);
+                        continue;
+                    }
                     scanLocalFiles(fullPath, relativePath);
                 }
                 else {
+                    if (shouldIgnore(relativePath, ignoreCtx, texSiblings)) {
+                        filesIgnored.push(relativePath);
+                        continue;
+                    }
                     const stats = statSync(fullPath);
                     localFiles.set(relativePath, {
                         mtime: stats.mtime,
@@ -812,6 +867,14 @@ program
         if (existsSync(metaPath)) {
             scanLocalFiles(targetDir);
         }
+        if (options.showIgnored && filesIgnored.length > 0) {
+            spinner.stop();
+            console.log(chalk.bold(chalk.dim(`Ignored ${filesIgnored.length} local file(s)/dir(s):`)));
+            for (const p of filesIgnored) {
+                console.log(chalk.dim(`  ${p}`));
+            }
+            spinner.start();
+        }
         // Extract remote files
         const remoteFiles = new Map();
         for (const entry of zip.getEntries()) {
@@ -821,14 +884,56 @@ program
         }
         // Merge: local changes take precedence for files modified after last pull
         let lastPull;
+        let previousManifest = [];
         if (existsSync(metaPath)) {
             const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
             lastPull = meta.lastPull ? new Date(meta.lastPull) : undefined;
+            if (Array.isArray(meta.remoteManifest)) {
+                previousManifest = meta.remoteManifest;
+            }
         }
         const filesToUpload = [];
         const filesUpdatedLocally = [];
         const filesKeptLocal = [];
         const filesNewLocal = [];
+        const filesDeletedRemote = [];
+        const filesDeleteSkipped = [];
+        // Detect locally-deleted files: present in previous manifest, missing locally,
+        // still present on the remote. Propagate the deletion to the remote BEFORE
+        // we write remote contents back over the working tree (otherwise the file
+        // would be silently restored — the bug reported in #7).
+        // Conflict policy: if the project has no previous manifest yet (first sync),
+        // we cannot distinguish "never existed locally" from "deleted locally", so
+        // skip deletion propagation on the very first sync.
+        if (options.delete !== false && previousManifest.length > 0 && existsSync(metaPath)) {
+            const locallyDeleted = [];
+            for (const path of previousManifest) {
+                if (path === 'output.pdf' || path.endsWith('/output.pdf'))
+                    continue;
+                if (!localFiles.has(path) && remoteFiles.has(path)) {
+                    locallyDeleted.push(path);
+                }
+            }
+            if (locallyDeleted.length > 0) {
+                spinner.text = `Propagating ${locallyDeleted.length} local deletion(s) to remote...`;
+                for (const path of locallyDeleted) {
+                    if (options.dryRun) {
+                        filesDeletedRemote.push(path);
+                        remoteFiles.delete(path);
+                        continue;
+                    }
+                    try {
+                        await client.deleteByPath(projectId, path);
+                        filesDeletedRemote.push(path);
+                        // Drop from remoteFiles so we don't re-extract it below
+                        remoteFiles.delete(path);
+                    }
+                    catch (err) {
+                        filesDeleteSkipped.push({ path, reason: err.message || String(err) });
+                    }
+                }
+            }
+        }
         spinner.text = 'Comparing files...';
         // Write remote files, but preserve local modifications
         for (const [path, remoteContent] of remoteFiles) {
@@ -863,24 +968,56 @@ program
             }
         }
         // Upload local changes
-        if (filesToUpload.length > 0) {
+        if (filesToUpload.length > 0 && !options.dryRun) {
             spinner.text = `Uploading ${filesToUpload.length} local change(s)...`;
             for (const file of filesToUpload) {
                 await client.uploadFile(projectId, null, file.path, file.content);
             }
         }
+        // Refresh manifest of remote files post-sync (deletions out, new uploads in)
+        const newManifest = new Set(remoteFiles.keys());
+        for (const f of filesToUpload)
+            newManifest.add(f.path);
+        for (const p of filesDeletedRemote)
+            newManifest.delete(p);
         // Update metadata
-        writeFileSync(metaPath, JSON.stringify({
-            projectId,
-            projectName,
-            lastPull: new Date().toISOString(),
-            lastSync: new Date().toISOString()
-        }, null, 2));
-        spinner.succeed(`Synced "${projectName}"`);
+        if (!options.dryRun) {
+            writeFileSync(metaPath, JSON.stringify({
+                projectId,
+                projectName,
+                lastPull: new Date().toISOString(),
+                lastSync: new Date().toISOString(),
+                remoteManifest: Array.from(newManifest).sort()
+            }, null, 2));
+        }
+        if (options.dryRun) {
+            spinner.succeed(`Dry-run sync "${projectName}" (no changes applied)`);
+        }
+        else {
+            spinner.succeed(`Synced "${projectName}"`);
+        }
         // Summary
         console.log(chalk.dim(`  ↓ ${filesUpdatedLocally.length} pulled from remote`));
         console.log(chalk.dim(`  ↑ ${filesToUpload.length} pushed to remote`));
+        if (filesDeletedRemote.length > 0) {
+            console.log(chalk.dim(`  ✖ ${filesDeletedRemote.length} deleted on remote`));
+        }
+        if (filesDeleteSkipped.length > 0) {
+            console.log(chalk.yellow(`  ⚠ ${filesDeleteSkipped.length} deletion(s) failed (kept remote)`));
+        }
         if (options.verbose) {
+            if (filesDeletedRemote.length > 0) {
+                console.log(chalk.red('\n  Deleted on remote (matched local deletion):'));
+                for (const f of filesDeletedRemote) {
+                    console.log(chalk.dim(`    ${f}`));
+                }
+            }
+            if (filesDeleteSkipped.length > 0) {
+                console.log(chalk.yellow('\n  Deletion skipped (will retry on next sync):'));
+                for (const { path, reason } of filesDeleteSkipped) {
+                    console.log(chalk.dim(`    ${path}  —  ${reason}`));
+                }
+            }
             if (filesKeptLocal.length > 0) {
                 console.log(chalk.yellow('\n  Local changes pushed (local was newer):'));
                 for (const f of filesKeptLocal) {
@@ -933,6 +1070,42 @@ configCmd
     .action(() => {
     console.log(getSessionCookieName());
 });
+program
+    .command('ignored [dir]')
+    .description('Show ignore patterns currently in effect for a project directory')
+    .option('--no-default-ignore', 'Exclude built-in defaults from the listing')
+    .option('--no-ignore', 'Show what --no-ignore would do (lists nothing)')
+    .action((dir, options) => {
+    const targetDir = dir || '.';
+    const ctx = loadIgnore(targetDir, {
+        noDefaults: options.defaultIgnore === false,
+        disableAll: options.ignore === false,
+    });
+    if (!ctx.enabled) {
+        console.log(chalk.yellow('Ignore filtering is disabled (--no-ignore).'));
+        console.log(chalk.dim('Every local file would be uploaded.'));
+        return;
+    }
+    if (ctx.sources.length === 0) {
+        console.log(chalk.yellow('No ignore patterns active.'));
+        console.log(chalk.dim('Built-in defaults are disabled and no .olignore file was found.'));
+        return;
+    }
+    console.log(chalk.bold(`Ignore patterns in effect for ${targetDir}:`));
+    console.log(chalk.dim('(later sources override earlier ones; ! prefix negates)'));
+    for (const src of ctx.sources) {
+        console.log();
+        console.log(chalk.cyan(`── ${src.label} (${src.patterns.length}) ──`));
+        for (const p of src.patterns) {
+            console.log(`  ${p}`);
+        }
+    }
+    console.log();
+    console.log(chalk.dim(`Total: ${ctx.patterns.length} pattern(s)`));
+    if (ctx.defaultsEnabled) {
+        console.log(chalk.dim('Note: *.pdf is also ignored when a same-named *.tex/.ltx exists in the same folder.'));
+    }
+});
 program
     .command('check')
     .description('Show credential sources and config path')