@aloth/olcli 0.9.1 → 0.11.0

package/README.md

@@ -17,9 +17,11 @@ Work with Overleaf projects directly from your command line. Edit locally with y
 ## Features
 
 - 📋 **List** all your Overleaf projects
+- ✨ **Create** blank or example projects
 - ⬇️ **Pull** project files to local directory for offline editing
 - ⬆️ **Push** local changes back to Overleaf
 - 🔄 **Sync** bidirectionally with smart conflict detection
+- 🔍 **Diff** local files against the live remote before pushing
 - 🔀 **Git remote** — use Overleaf as a native git remote ([docs](docs/GIT-REMOTE.md))
 - ✌️ **Two-way deletions** — files removed locally are deleted on Overleaf on next sync
 - 🗑️ **Delete** and ✏️ **rename** remote files by path
@@ -132,10 +134,12 @@ All commands auto-detect the project when run from a synced directory (contains
 | `olcli pull [project] [dir]` | Download project files to local directory |
 | `olcli push [dir]` | Upload local changes to Overleaf (`--delete` also removes files deleted locally) |
 | `olcli sync [dir]` | Bidirectional sync (pull + push) |
+| `olcli diff [project] [dir]` | Show content-level changes between local files and the remote |
 | `olcli upload <file> [project]` | Upload a single file (`--to <path>` sets the remote destination) |
 | `olcli download <file> [project]` | Download a single file |
 | `olcli delete <file> [project]` | Delete a remote file or folder (alias: `rm`) |
 | `olcli rename <old> <new> [project]` | Rename a remote file or folder (alias: `mv`) |
+| `olcli project create <name>` | Create a blank or example project (`--template blank\|example`) |
 | `olcli project rename <new> [project]` | Rename the project itself (`--dry-run`) |
 | `olcli project rename-bulk` | Rename many projects by pattern (dry-run unless `--apply`) |
 | `olcli compile [project]` | Trigger PDF compilation |
@@ -150,8 +154,11 @@ All commands auto-detect the project when run from a synced directory (contains
 | `olcli comments delete <id>` | Delete a comment thread |
 | `olcli ignored [dir]` | List ignore patterns in effect |
 | `olcli config set-url <url>` | Set self-hosted base URL |
+| `olcli config get-url` | Show the configured base URL |
 | `olcli config set-cookie-name <name>` | Set session cookie name |
+| `olcli config get-cookie-name` | Show the configured session cookie name |
 | `olcli config set-timeout <ms>` | Set default HTTP timeout |
+| `olcli config get-timeout` | Show the configured HTTP timeout |
 | `olcli check` | Show config paths and credential sources |
 
 ### Compile Options
@@ -192,6 +199,39 @@ Useful in multi-doc projects: each `-r` run compiles the file as if it were the
 - **Propagates local deletions** — use `--no-delete` to opt out
 - Use `--dry-run` to preview without applying
 
+### Diff
+
+`olcli diff` compares the bytes of your local files against the project's
+current contents and prints a unified diff.
+
+```bash
+olcli diff                 # every changed file, as patches
+olcli diff --name-only     # just the changed paths
+olcli diff --file main.tex # one file
+olcli diff -U 8            # wider context
+```
+
+**The remote side is fetched fresh on every run.** The diff describes the
+project as it is at that moment — which is what a subsequent `push` would
+overwrite — not a comparison against your last `pull`. `.olcli.json` records
+remote *paths*, never remote *contents*, so there is no stored snapshot to
+compare against; and the whole project arrives in a single request, the same
+one `pull` makes, so fetching fresh costs one round trip rather than one per
+file. A collaborator editing between `diff` and `push` can still change the
+outcome, which is why the fetch time is printed.
+
+In the output, `a/` is the remote and `b/` is local: a `+` line is content
+`push` would upload, a `-` line is content it would overwrite. Files that
+differ only in bytes that are not text (PDFs, images) are reported as
+`Binary files ... differ`. Both sides pass through the same ignore layers, so
+build artifacts sitting on Overleaf are not reported as locally deleted.
+
+`diff --name-only` and `push --dry-run` answer different questions and will
+disagree. `push --dry-run` lists files whose **modification time** is newer
+than the last pull, because that is what `push` uploads; `diff` lists files
+whose **contents** actually differ. A file you touched without editing appears
+in the first and not the second.
+
 #### How deletion propagation works
 
 `olcli` records a manifest of remote files in `.olcli.json`. On next sync:
@@ -234,7 +274,15 @@ Credentials are checked in order:
 
 1. `OVERLEAF_SESSION` environment variable
 2. `.olauth` file in current directory
-3. Global config: `~/.config/olcli-nodejs/config.json`
+3. Global config — run `olcli check` to see the exact path
+
+The global config path is platform-dependent (`conf` resolves it), so it is not
+hardcoded here: on macOS it lands under `~/Library/Preferences/`, on Linux under
+`~/.config/`. `olcli auth` prints the path it wrote to.
+
+⚠️ `olcli auth --save-local` writes `.olauth` into the **current directory**,
+which is usually your LaTeX project. Add it to that project's `.gitignore`
+before committing.
 
 ### Self-hosted Overleaf
 
@@ -303,6 +351,7 @@ import { OverleafClient } from '@aloth/olcli';
 
 const client = await OverleafClient.fromSessionCookie(cookie);
 
+const created = await client.createProject('My Paper');
 const projects = await client.listProjects();
 const info = await client.getProjectInfo(projectId);
 const zipBuf = await client.downloadProject(projectId);
@@ -319,7 +368,8 @@ const comments = await client.listComments(projectId, { status: 'open' });
 import {
   OverleafClient,
   // Types
-  Project, ProjectInfo, FolderEntry, DocEntry, FileEntry,
+  Project, ProjectInfo, ProjectTemplate, CreateProjectOptions, CreatedProject,
+  FolderEntry, DocEntry, FileEntry,
   CommentMessage, ProjectComment, CommentContext, CommentStatus,
   ListCommentsOptions, AddCommentOptions, Credentials, SessionCookiePair,
   // Config utilities

package/dist/cli.js

@@ -12,9 +12,11 @@ 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 { resolveRemotePath, resolveWithin } from './paths.js';
+import { resolveRemotePath, resolveWithin, normalizeRemotePath } from './paths.js';
 import { planProjectRenames } from './rename-plan.js';
-import { loadIgnore, shouldIgnore, buildTexSiblingSet, } from './ignore.js';
+import { scanLocalFiles } from './scan.js';
+import { compareTrees, filterRemoteTree, renderFileDiff, statusLetter } from './diff.js';
+import { loadIgnore } 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'));
@@ -87,7 +89,7 @@ async function resolveProject(client, projectArg, dir = '.') {
             return { id: projectArg, name: projectArg };
         }
         // Otherwise, look up by name
-        let proj = await client.getProject(projectArg);
+        const proj = await client.getProject(projectArg);
         if (!proj) {
             throw new Error(`Project not found: ${projectArg}`);
         }
@@ -276,21 +278,6 @@ program
         process.exit(1);
     }
 });
-function printFolder(folder, indent) {
-    // Print subfolders
-    for (const f of folder.folders || []) {
-        console.log(`${indent}📁 ${chalk.blue(f.name)}/`);
-        printFolder(f, indent + '  ');
-    }
-    // Print docs
-    for (const d of folder.docs || []) {
-        console.log(`${indent}📄 ${d.name}`);
-    }
-    // Print files
-    for (const f of folder.fileRefs || []) {
-        console.log(`${indent}📎 ${f.name}`);
-    }
-}
 const commentsCmd = program
     .command('comments')
     .description('View and manage Overleaf comments');
@@ -714,7 +701,39 @@ program
 // ─────────────────────────────────────────────────────────────────────────────
 const projectCmd = program
     .command('project')
-    .description('Operate on projects themselves (rename, bulk rename)');
+    .description('Operate on projects themselves (create, rename, bulk rename)');
+projectCmd
+    .command('create <name>')
+    .description('Create a new project')
+    .option('-t, --template <type>', 'Project template: blank or example', 'blank')
+    .option('--json', 'Output as JSON')
+    .option('--cookie <session>', 'Session cookie override')
+    .action(async (name, options) => {
+    const template = options.template;
+    if (template !== 'blank' && template !== 'example') {
+        console.error(chalk.red(`Unsupported project template: ${template}`));
+        console.error('Supported templates: blank, example');
+        process.exit(1);
+    }
+    const spinner = ora('Creating project...').start();
+    try {
+        const client = await getClient(options.cookie);
+        const created = await client.createProject(name, { template });
+        setLastProject(created.id);
+        if (options.json) {
+            spinner.stop();
+            console.log(JSON.stringify(created, null, 2));
+            return;
+        }
+        spinner.succeed(`Created project: ${created.name}`);
+        console.log(`  ${chalk.cyan(created.id)}`);
+        console.log(`  ${chalk.cyan(created.url)}`);
+    }
+    catch (error) {
+        spinner.fail(`Failed: ${error.message}`);
+        process.exit(1);
+    }
+});
 projectCmd
     .command('rename <newname> [project]')
     .description('Rename a project')
@@ -955,7 +974,7 @@ program
                             continue;
                         }
                     }
-                    catch (e) {
+                    catch {
                         // File doesn't exist or can't stat, proceed with download
                     }
                 }
@@ -1075,51 +1094,19 @@ program
             disableAll: options.ignore === false,
         });
         // Get list of files to upload
-        const { readdirSync, statSync } = await import('node:fs');
+        const { files: localFileList, ignored: filesIgnored } = scanLocalFiles(targetDir, ignoreCtx);
         const filesToUpload = [];
-        const filesIgnored = [];
         // Every local file that survives ignore filtering, regardless of mtime.
         // filesToUpload is mtime-filtered and therefore useless as a deletion
         // baseline: an unchanged file would look "absent" and get deleted.
         const allLocalPaths = new Set();
-        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 (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()) {
-                    // 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;
-                    }
-                    allLocalPaths.add(relativePath);
-                    // Check if file is newer than last pull (unless --all)
-                    if (options.all || !lastPull) {
-                        filesToUpload.push({ path: fullPath, relativePath });
-                    }
-                    else {
-                        const stats = statSync(fullPath);
-                        if (stats.mtime > lastPull) {
-                            filesToUpload.push({ path: fullPath, relativePath });
-                        }
-                    }
-                }
+        for (const file of localFileList) {
+            allLocalPaths.add(file.relativePath);
+            // Check if file is newer than last pull (unless --all)
+            if (options.all || !lastPull || file.mtime > lastPull) {
+                filesToUpload.push({ path: file.path, relativePath: file.relativePath });
             }
         }
-        scanDir(targetDir);
         if (options.showIgnored && filesIgnored.length > 0) {
             spinner.stop();
             console.log(chalk.bold(chalk.dim(`Ignored ${filesIgnored.length} file(s)/dir(s):`)));
@@ -1169,6 +1156,12 @@ program
             if (noBaseline) {
                 console.log(chalk.dim('  --delete skipped: no manifest yet (first push from this directory)'));
             }
+            // This list is mtime-based: a file touched but not edited is in it, and
+            // a file whose bytes already match the remote is too. `olcli diff`
+            // compares content instead.
+            if (filesToUpload.length > 0) {
+                console.log(chalk.dim('  selected by modification time — run `olcli diff` to see content changes'));
+            }
             return;
         }
         // If --probe-folder is set, or if we don't have a cached rootFolderId, try probing
@@ -1334,41 +1327,17 @@ program
         });
         // 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,
-                        content: readFileSync(fullPath)
-                    });
-                }
-            }
-        }
+        let filesIgnored = [];
         // Read local files before overwriting
-        if (existsSync(metaPath)) {
-            scanLocalFiles(targetDir);
+        if (existsSync(targetDir) && existsSync(metaPath)) {
+            const scan = scanLocalFiles(targetDir, ignoreCtx);
+            filesIgnored = scan.ignored;
+            for (const file of scan.files) {
+                localFiles.set(file.relativePath, {
+                    mtime: file.mtime,
+                    content: readFileSync(file.path)
+                });
+            }
         }
         if (options.showIgnored && filesIgnored.length > 0) {
             spinner.stop();
@@ -1553,6 +1522,142 @@ program
         process.exit(1);
     }
 });
+program
+    .command('diff [project] [dir]')
+    .description('Show content-level differences between local files and the remote project')
+    .option('--name-only', 'List changed paths instead of printing patches')
+    .option('--file <path>', 'Diff a single file')
+    .option('-U, --unified <n>', 'Lines of context around each hunk (default: 3)', parseInt)
+    .option('--no-default-ignore', 'Disable built-in LaTeX artifact ignore list (only .olignore applies)')
+    .option('--no-ignore', 'Disable all ignore filtering')
+    .option('--cookie <session>', 'Session cookie override')
+    .addHelpText('after', `
+The remote side is fetched fresh on every run, so the diff describes the
+project as it is right now - which is what a subsequent push would overwrite.
+It is not a comparison against the last pull. A collaborator editing between
+diff and push can still change the outcome; the fetch time is printed for that
+reason.`)
+    .action(async (project, dir, options) => {
+    const targetDir = dir || '.';
+    if (!existsSync(targetDir)) {
+        console.error(chalk.red(`Directory not found: ${targetDir}`));
+        process.exit(1);
+    }
+    const spinner = ora('Connecting...').start();
+    try {
+        const client = await getClient(options.cookie);
+        let resolved;
+        try {
+            resolved = await resolveProject(client, project, targetDir);
+        }
+        catch (error) {
+            spinner.fail(error.message);
+            console.error('Either run from a directory with .olcli.json or pass a project name/ID');
+            process.exit(1);
+        }
+        const { id: projectId, name: projectName } = resolved;
+        // The whole project arrives as one zip in a single request - the same
+        // call pull and sync already make. Fetching per-file would mean one
+        // request per file and could not tell us which files differ without
+        // downloading them anyway.
+        spinner.text = 'Fetching remote project...';
+        const zipBuffer = await client.downloadProject(projectId);
+        const fetchedAt = new Date();
+        const AdmZip = (await import('adm-zip')).default;
+        const zip = new AdmZip(zipBuffer);
+        const ignoreCtx = loadIgnore(targetDir, {
+            noDefaults: options.defaultIgnore === false,
+            disableAll: options.ignore === false,
+        });
+        // Both sides go through the same filters; see filterRemoteTree.
+        const remoteFiles = filterRemoteTree(zip.getEntries()
+            .filter((e) => !e.isDirectory)
+            .map((e) => ({ path: e.entryName, data: e.getData() })), ignoreCtx, (path) => resolveWithin(targetDir, path) !== null);
+        const scan = scanLocalFiles(targetDir, ignoreCtx);
+        const localFiles = new Map();
+        for (const file of scan.files) {
+            localFiles.set(file.relativePath, readFileSync(file.path));
+        }
+        let entries = compareTrees(localFiles, remoteFiles).filter((e) => e.status !== 'unchanged');
+        if (options.file) {
+            const wanted = normalizeRemotePath(options.file);
+            entries = entries.filter((e) => e.path === wanted);
+            if (entries.length === 0) {
+                spinner.info(`No differences in ${wanted}`);
+                if (!localFiles.has(wanted) && !remoteFiles.has(wanted)) {
+                    console.log(chalk.dim('  (file is on neither side, or is filtered by an ignore rule)'));
+                }
+                return;
+            }
+        }
+        spinner.stop();
+        if (entries.length === 0) {
+            console.log(chalk.green(`No differences — local files match "${projectName}"`));
+            console.log(chalk.dim(`  remote fetched ${fetchedAt.toISOString()}`));
+            return;
+        }
+        if (options.nameOnly) {
+            for (const e of entries) {
+                const colour = e.status === 'added' ? chalk.green
+                    : e.status === 'deleted' ? chalk.red
+                        : chalk.yellow;
+                console.log(`${colour(statusLetter(e.status))}  ${e.path}`);
+            }
+        }
+        else {
+            for (const e of entries) {
+                const patch = renderFileDiff(e, localFiles.get(e.path), remoteFiles.get(e.path), { context: options.unified });
+                patch.replace(/\n$/, '').split('\n').forEach((line, index) => {
+                    console.log(colourizeDiffLine(line, index, e.binary));
+                });
+            }
+        }
+        console.log();
+        // With --file the summary would count only the one file asked for, which
+        // reads as "this is all that differs". Report totals only for a full run.
+        if (!options.file) {
+            const counts = {
+                added: entries.filter((e) => e.status === 'added').length,
+                modified: entries.filter((e) => e.status === 'modified').length,
+                deleted: entries.filter((e) => e.status === 'deleted').length,
+            };
+            console.log(chalk.bold(`${entries.length} file(s) differ from "${projectName}": ` +
+                `${counts.added} added, ${counts.modified} modified, ${counts.deleted} remote-only`));
+            if (counts.deleted > 0) {
+                console.log(chalk.dim('  remote-only files are left alone by push; use push --delete to remove them'));
+            }
+        }
+        console.log(chalk.dim(`  a/ = remote as of ${fetchedAt.toISOString()}, b/ = local`));
+        setLastProject(projectId);
+    }
+    catch (error) {
+        spinner.fail(`Failed: ${error.message}`);
+        process.exit(1);
+    }
+});
+/**
+ * Colourize one line of a rendered patch. chalk already no-ops when stdout is
+ * not a TTY, so this needs no flag of its own.
+ *
+ * The file headers are identified by position, not by prefix: a removed line
+ * whose own content starts with `--` renders as `--- something` and would
+ * otherwise be mistaken for the `---` header and shown as unchanged.
+ */
+function colourizeDiffLine(line, index, binary) {
+    if (index === 0)
+        return chalk.bold(line); // our `diff --olcli` header
+    if (binary)
+        return chalk.magenta(line); // the single summary line
+    if (index <= 2)
+        return chalk.bold(line); // `---` / `+++`
+    if (line.startsWith('@@'))
+        return chalk.cyan(line);
+    if (line.startsWith('+'))
+        return chalk.green(line);
+    if (line.startsWith('-'))
+        return chalk.red(line);
+    return line;
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // HELP
 // ─────────────────────────────────────────────────────────────────────────────