@aloth/olcli 0.4.1 → 0.6.0

package/README.md

@@ -27,8 +27,10 @@ Work with Overleaf projects directly from your command line. Edit locally with y
 - 📄 **Compile** PDFs using Overleaf's remote compiler
 - 📦 **Download** individual files or full project archives
 - 📤 **Upload** files to projects
-- 💬 **Review comments** — list comments with source locations, add, resolve, reopen, and delete threads
+- 💬 **Review comments** — list comments with source locations, add, resolve, reopen, delete threads, and **reply** to existing threads
 - 🗂️ **Preserve folder structure** when pushing nested files
+- ⏱️ **Configurable timeout** — global `--timeout <ms>` flag, `OVERLEAF_TIMEOUT` env var, or `config set-timeout` for slow connections
+- 🔑 **Password login** — `olcli auth --email --password` for self-hosted instances (no browser required)
 - ⚙️ **Support self-hosted Overleaf/ShareLaTeX instances** via configurable base URL and session cookie name
 - 📊 **Output** compile artifacts (`.bbl`, `.log`, `.aux` for arXiv submissions)
 
@@ -94,18 +96,24 @@ makepkg -si
 
 ### 1. Authenticate with Overleaf
 
-Get your session cookie from Overleaf.com:
+**Option A: Session cookie** (overleaf.com and self-hosted)
 
 1. Log into [overleaf.com](https://www.overleaf.com)
 2. Open Developer Tools (F12 or Cmd+Option+I) → Application/Storage → Cookies
 3. Copy the value of `overleaf_session2`
 
-Store it with olcli:
-
 ```bash
 olcli auth --cookie "your_session_cookie_value"
 ```
 
+**Option B: Email/password** (self-hosted instances without reCAPTCHA)
+
+```bash
+olcli auth --email "you@example.com" --password "your_password"
+```
+
+Credentials are stored securely and the session auto-refreshes on expiry.
+
 **Tip:** The cookie stays valid for weeks. Just refresh it when authentication fails.
 
 ### 2. List Your Projects
@@ -158,7 +166,7 @@ All commands auto-detect the project when run from a synced directory (contains
 
 | Command | Description |
 |---------|-------------|
-| `olcli auth` | Set session cookie |
+| `olcli auth` | Set session cookie or login with email/password |
 | `olcli whoami` | Check authentication status |
 | `olcli logout` | Clear stored credentials |
 | `olcli list` | List all projects |
@@ -171,6 +179,7 @@ All commands auto-detect the project when run from a synced directory (contains
 | `olcli comments list [project]` | List comments with source text and file locations (`--status`, `--context`) |
 | `olcli comments add <file> <message> [project]` | Add a comment to selected text |
 | `olcli comments resolve <threadId> [project]` | Resolve a comment thread |
+| `olcli comments reply <threadId> <body> [project]` | Reply to a comment thread |
 | `olcli comments reopen <threadId> [project]` | Reopen a resolved comment thread |
 | `olcli comments delete <threadId> [project]` | Permanently delete a comment thread |
 | `olcli delete <file> [project]` | Delete a remote file or folder by path (alias: `rm`) |
@@ -182,6 +191,8 @@ All commands auto-detect the project when run from a synced directory (contains
 | `olcli output [type]` | Download compile output files |
 | `olcli config set-url <url>` | Set a self-hosted Overleaf base URL |
 | `olcli config set-cookie-name <name>` | Set the session cookie name |
+| `olcli config set-timeout <ms>` | Set default HTTP request timeout |
+| `olcli config get-timeout` | Show current timeout setting |
 | `olcli check` | Show config paths and credential sources |
 
 ### Review comments
@@ -191,6 +202,7 @@ olcli comments list "My Paper" --status open --context 2
 olcli comments list "My Paper" --status resolved --json
 olcli comments add main.tex "Please clarify this definition" "My Paper" --text "A Skill is"
 olcli comments add main.tex "Check this sentence" "My Paper" --line 42 --column 1 --length 20 --json
+olcli comments reply 6a1a5fedbf90b811e1000001 "Good point, I'll fix this" "My Paper"
 olcli comments resolve 6a1a5fedbf90b811e1000001 "My Paper" --json
 olcli comments reopen 6a1a5fedbf90b811e1000001 "My Paper"
 olcli comments delete 6a1a5fedbf90b811e1000001 "My Paper" --json
@@ -205,6 +217,7 @@ These flags work with **every** command and may be placed before or after the co
 | `--verbose` | Print every HTTP request, status, content-type, and (on errors) a response-body snippet to stderr. Useful for debugging failed compiles, 404s on `pdf`/`output`, auth issues, or unexpected upload behavior. |
 | `--base-url <url>` | Override the Overleaf instance base URL (also `OVERLEAF_BASE_URL` env var or `olcli config set-url`). |
 | `--cookie-name <name>` | Override the session cookie name (default `overleaf_session2`; older instances use `overleaf.sid`). |
+| `--timeout <ms>` | Override the HTTP request timeout in milliseconds (also `OVERLEAF_TIMEOUT` env var or `olcli config set-timeout`). Default: 10000. |
 
 Examples:
 
@@ -388,6 +401,24 @@ olcli config set-url https://latex.example.org
 olcli config set-cookie-name overleaf.sid
 ```
 
+### Timeout configuration
+
+For slow connections or large projects, increase the HTTP request timeout:
+
+```bash
+# One-off: pass as a flag
+olcli --timeout 60000 pull "Large Thesis"
+
+# Persist as default
+olcli config set-timeout 60000
+
+# Or use environment variable
+export OVERLEAF_TIMEOUT=60000
+olcli pull "Large Thesis"
+```
+
+Precedence: `--timeout` flag > `OVERLEAF_TIMEOUT` env > `config set-timeout` > default (10000ms).
+
 ## Examples
 
 ### Work on a thesis
@@ -438,6 +469,198 @@ olcli output bbl -o main.bbl
 olcli zip -o arxiv-submission.zip
 ```
 
+## Programmatic Usage (Library API)
+
+`@aloth/olcli` exposes `OverleafClient` and all public interfaces as a proper library so you can use it in your own scripts, tools, and AI agents.
+
+### Install
+
+```bash
+npm install @aloth/olcli
+```
+
+### Basic example
+
+```ts
+import { OverleafClient } from '@aloth/olcli';
+
+// Create a client from an Overleaf session cookie
+const client = await OverleafClient.fromSessionCookie(cookie);
+
+// List all projects
+const projects = await client.listProjects();
+console.log(projects);
+
+// Get detailed info (file tree) for a project
+const info = await client.getProjectInfo(projectId);
+
+// Download project as a zip buffer
+const zipBuf = await client.downloadProject(projectId);
+
+// Compile and download PDF
+const pdfBuf = await client.downloadPdf(projectId);
+
+// Upload a file
+import { readFileSync } from 'node:fs';
+await client.uploadFile(projectId, null, 'main.tex', readFileSync('main.tex'));
+
+// List review comments
+const comments = await client.listComments(projectId, { status: 'open' });
+```
+
+### Available exports
+
+```ts
+import {
+  // Core client
+  OverleafClient,
+
+  // Types / interfaces
+  Project, ProjectInfo, FolderEntry, DocEntry, FileEntry,
+  CommentMessage, ProjectComment, CommentContext, CommentStatus,
+  ListCommentsOptions, AddCommentOptions, Credentials, SessionCookiePair,
+
+  // Configuration utilities
+  getBaseUrl, setBaseUrl, getSessionCookie, setSessionCookie,
+  getSessionCookieName, setSessionCookieName, getCsrf, setCsrf,
+  getLastProject, setLastProject, clearConfig, getConfigPath, saveOlAuth,
+  getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials,
+  clearPasswordCredentials, type PasswordCredentials,
+
+  // Ignore utilities
+  DEFAULT_IGNORE_PATTERNS, loadIgnore, shouldIgnore, buildTexSiblingSet,
+  IgnoreContext, LoadIgnoreOptions,
+} from '@aloth/olcli';
+```
+
+---
+
+## MCP Server
+
+`@aloth/olcli` ships an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server so AI assistants like **Claude Desktop**, **Cursor**, and **Windsurf** can interact with your Overleaf projects directly.
+
+### MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all Overleaf projects |
+| `get_project_info` | Get file tree and metadata for a project |
+| `pull_project` | Download and extract a project to a local directory |
+| `push_file` | Upload a local file to a project |
+| `compile` | Compile a project and get the PDF URL |
+| `download_pdf` | Compile a project and save the PDF locally |
+| `list_comments` | List review comments (filter: all / open / resolved) |
+| `get_entities` | Get a flat list of all files in a project |
+| `download_file` | Download a specific file by its remote path |
+| `add_comment` | Add a review comment to a document |
+| `reply_to_comment` | Reply to an existing comment thread |
+| `resolve_comment` | Mark a comment thread as resolved |
+| `delete_entity` | Delete a file or document by path |
+| `rename_entity` | Rename a file or document |
+| `compile_with_outputs` | Compile and return all output files (PDF, BBL, logs…) |
+
+### Authentication
+
+The MCP server reads credentials in this order:
+
+1. **`OVERLEAF_SESSION` environment variable** — set in your MCP config (recommended)
+2. **`OVERLEAF_EMAIL` + `OVERLEAF_PASSWORD` environment variables** — for password login (self-hosted)
+3. **`.olauth` file in cwd** — written by `olcli auth`
+4. **Stored config** — written by `olcli auth` (including saved password credentials)
+
+When a session cookie expires and password credentials are available, the MCP server automatically re-authenticates.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "npx",
+      "args": ["-y", "@aloth/olcli-mcp"],
+      "env": {
+        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
+      }
+    }
+  }
+}
+```
+
+Or if you have olcli installed globally (`npm install -g @aloth/olcli`):
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "olcli-mcp",
+      "env": {
+        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "npx",
+      "args": ["-y", "@aloth/olcli-mcp"],
+      "env": {
+        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "npx",
+      "args": ["-y", "@aloth/olcli-mcp"],
+      "env": {
+        "OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
+      }
+    }
+  }
+}
+```
+
+### Getting your session cookie
+
+1. Open Overleaf in your browser and log in
+2. Open DevTools → Application (Chrome) or Storage (Firefox) → Cookies
+3. Find `overleaf_session2` (or `sharelatex.sid` for self-hosted)
+4. Copy the value — that's your `OVERLEAF_SESSION`
+
+Or run `olcli auth` and then the MCP server will pick it up automatically.
+
+### Self-hosted Overleaf
+
+Set `OVERLEAF_BASE_URL` in your MCP env:
+
+```json
+"env": {
+  "OVERLEAF_SESSION": "<cookie>",
+  "OVERLEAF_BASE_URL": "https://overleaf.yourcompany.com"
+}
+```
+
+---
+
 ## Troubleshooting
 
 ### Session expired

package/dist/cli.js

@@ -17,7 +17,7 @@ import { loadIgnore, shouldIgnore, buildTexSiblingSet, } from './ignore.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const VERSION = pkg.version;
-import { getSessionCookie, setSessionCookie, setLastProject, getConfigPath, saveOlAuth, clearConfig, getBaseUrl, setBaseUrl, getSessionCookieName, setSessionCookieName } from './config.js';
+import { getSessionCookie, setSessionCookie, setLastProject, getConfigPath, saveOlAuth, clearConfig, getBaseUrl, setBaseUrl, getSessionCookieName, setSessionCookieName, getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials } from './config.js';
 const program = new Command();
 program
     .name('olcli')
@@ -25,26 +25,57 @@ program
     .version(VERSION)
     .option('--base-url <url>', 'Overleaf instance base URL (overrides OVERLEAF_BASE_URL and config)')
     .option('--cookie-name <name>', 'Session cookie name (default: overleaf_session2, use overleaf.sid for older instances)')
+    .option('--timeout <ms>', 'HTTP request timeout in milliseconds', parseInt)
     .option('--verbose', 'Print every HTTP request, status, and error response body to stderr');
 /**
  * Helper to get authenticated client
  */
 async function getClient(cookieOpt, baseUrlOpt) {
-    const cookie = cookieOpt || getSessionCookie();
-    if (!cookie) {
-        console.error(chalk.red('No session cookie found.'));
-        console.error('Set one with: olcli auth --cookie <session_cookie>');
-        console.error('Or set OVERLEAF_SESSION environment variable');
-        console.error('Or create .olauth file in current directory');
-        process.exit(1);
-    }
     const baseUrl = baseUrlOpt || program.opts().baseUrl || getBaseUrl();
     const cookieName = program.opts().cookieName || getSessionCookieName();
-    const client = await OverleafClient.fromSessionCookie(cookie, baseUrl, cookieName);
+    const cookie = cookieOpt || getSessionCookie();
+    const passwordCredentials = cookieOpt ? undefined : getPasswordCredentials();
+    if (cookie) {
+        try {
+            const client = await OverleafClient.fromSessionCookie(cookie, baseUrl, cookieName);
+            if (program.opts().verbose)
+                client.setVerbose(true);
+            const timeout = program.opts().timeout || getTimeout();
+            client.setGlobalTimeout(timeout);
+            return client;
+        }
+        catch (error) {
+            if (!passwordCredentials)
+                throw error;
+        }
+    }
+    if (passwordCredentials) {
+        return loginWithSavedPassword(passwordCredentials, baseUrl, cookieName);
+    }
+    console.error(chalk.red('No session cookie or password credentials found.'));
+    console.error('Set one with: olcli auth --cookie <session_cookie>');
+    console.error('Or use: olcli auth --email <email> --password <password>');
+    console.error('Or set OVERLEAF_SESSION environment variable');
+    console.error('Or create .olauth file in current directory');
+    process.exit(1);
+}
+async function loginWithSavedPassword(credentials, baseUrl, cookieName) {
+    const client = await OverleafClient.fromPasswordLogin(credentials.email, credentials.password, baseUrl);
+    persistClientSession(client, cookieName);
     if (program.opts().verbose)
         client.setVerbose(true);
+    const timeout = program.opts().timeout || getTimeout();
+    client.setGlobalTimeout(timeout);
     return client;
 }
+function persistClientSession(client, preferredCookieName) {
+    const sessionCookie = client.getSessionCookiePair(preferredCookieName);
+    if (!sessionCookie) {
+        throw new Error('Password login succeeded, but no session cookie was returned.');
+    }
+    setSessionCookieName(sessionCookie.name);
+    setSessionCookie(sessionCookie.value);
+}
 async function resolveProject(client, projectArg, dir = '.') {
     // If project argument provided, use it
     if (projectArg) {
@@ -76,12 +107,15 @@ async function resolveProject(client, projectArg, dir = '.') {
 // ─────────────────────────────────────────────────────────────────────────────
 program
     .command('auth')
-    .description('Authenticate with Overleaf using session cookie')
+    .description('Authenticate with Overleaf using a session cookie or email/password')
     .option('--cookie <session>', 'Session cookie (overleaf_session2 value)')
+    .option('--email <email>', 'Account email for password login')
+    .option('--password <password>', 'Account password for password login')
+    .option('--no-save-password', 'Do not persist email/password credentials')
     .option('--save-local', 'Save to .olauth in current directory')
     .action(async (options) => {
-    if (!options.cookie) {
-        console.log(chalk.yellow('To authenticate, provide your session cookie:'));
+    if (!options.cookie && !options.email && !options.password) {
+        console.log(chalk.yellow('To authenticate, provide a session cookie:'));
         console.log();
         console.log('1. Log into overleaf.com in your browser');
         console.log('2. Open Developer Tools (F12) → Application → Cookies');
@@ -90,22 +124,46 @@ program
         console.log();
         console.log(chalk.cyan('  olcli auth --cookie "your_session_cookie_value"'));
         console.log();
+        console.log('Or log in with email/password:');
+        console.log(chalk.cyan('  olcli auth --email "you@example.com" --password "your_password"'));
+        console.log();
         console.log('Or set OVERLEAF_SESSION environment variable');
         return;
     }
+    if (options.cookie && (options.email || options.password)) {
+        console.error(chalk.red('Use either --cookie or --email/--password, not both.'));
+        process.exit(1);
+    }
+    if (!options.cookie && (!options.email || !options.password)) {
+        console.error(chalk.red('Both --email and --password are required for password login.'));
+        process.exit(1);
+    }
     const spinner = ora('Verifying session...').start();
     try {
         const baseUrl = program.opts().baseUrl || getBaseUrl();
         const cookieName = program.opts().cookieName || getSessionCookieName();
-        const client = await OverleafClient.fromSessionCookie(options.cookie, baseUrl, cookieName);
-        const projects = await client.listProjects();
-        setSessionCookie(options.cookie);
-        if (options.saveLocal) {
-            saveOlAuth(options.cookie);
-            spinner.succeed(`Authenticated! Found ${projects.length} projects. Saved to .olauth`);
+        if (options.cookie) {
+            const client = await OverleafClient.fromSessionCookie(options.cookie, baseUrl, cookieName);
+            const projects = await client.listProjects();
+            setSessionCookie(options.cookie);
+            if (options.saveLocal) {
+                saveOlAuth(options.cookie);
+                spinner.succeed(`Authenticated! Found ${projects.length} projects. Saved to .olauth`);
+            }
+            else {
+                spinner.succeed(`Authenticated! Found ${projects.length} projects.`);
+            }
         }
         else {
-            spinner.succeed(`Authenticated! Found ${projects.length} projects.`);
+            spinner.text = 'Logging in with email/password...';
+            const client = await OverleafClient.fromPasswordLogin(options.email, options.password, baseUrl);
+            const projects = await client.listProjects();
+            persistClientSession(client, cookieName);
+            setBaseUrl(baseUrl);
+            if (options.savePassword !== false) {
+                setPasswordCredentials(options.email, options.password);
+            }
+            spinner.succeed(`Authenticated! Found ${projects.length} projects. Password login saved.`);
         }
         console.log(chalk.dim(`Config saved to: ${getConfigPath()}`));
     }
@@ -303,6 +361,30 @@ commentsCmd
         process.exit(1);
     }
 });
+commentsCmd
+    .command('reply <threadId> <body> [project]')
+    .description('Reply to a comment thread with a message')
+    .option('--json', 'Output as JSON')
+    .option('--cookie <session>', 'Session cookie override')
+    .action(async (threadId, body, project, options) => {
+    const spinner = ora('Posting reply...').start();
+    try {
+        const client = await getClient(options.cookie);
+        const proj = await resolveProject(client, project);
+        const message = await client.postCommentMessage(proj.id, threadId, body);
+        if (options.json) {
+            spinner.stop();
+            console.log(JSON.stringify({ replied: true, message }, null, 2));
+            return;
+        }
+        spinner.succeed(`Replied to ${threadId}`);
+        setLastProject(proj.id);
+    }
+    catch (error) {
+        spinner.fail(`Failed: ${error.message}`);
+        process.exit(1);
+    }
+});
 commentsCmd
     .command('resolve <threadId> [project]')
     .description('Resolve a comment thread')
@@ -1261,6 +1343,24 @@ configCmd
     .action(() => {
     console.log(getSessionCookieName());
 });
+configCmd
+    .command('set-timeout <ms>')
+    .description('Set the default HTTP request timeout in milliseconds')
+    .action((ms) => {
+    const timeout = parseInt(ms, 10);
+    if (isNaN(timeout)) {
+        console.error(chalk.red('Invalid timeout value. Must be a number.'));
+        process.exit(1);
+    }
+    setTimeout(timeout);
+    console.log(chalk.green(`Default timeout set to: ${timeout}ms`));
+});
+configCmd
+    .command('get-timeout')
+    .description('Get the current default HTTP request timeout')
+    .action(() => {
+    console.log(`${getTimeout()}ms`);
+});
 program
     .command('ignored [dir]')
     .description('Show ignore patterns currently in effect for a project directory')