@aloth/olcli 0.10.0 → 0.12.0

package/README.md

@@ -2,6 +2,7 @@
 
 **Command-line interface for Overleaf** — Sync, manage, and compile LaTeX projects from your terminal.
 
+[![CI](https://github.com/aloth/olcli/actions/workflows/ci.yml/badge.svg)](https://github.com/aloth/olcli/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@aloth/olcli.svg)](https://www.npmjs.com/package/@aloth/olcli)
 [![npm downloads](https://img.shields.io/npm/dm/@aloth/olcli.svg)](https://www.npmjs.com/package/@aloth/olcli)
 [![GitHub stars](https://img.shields.io/github/stars/aloth/olcli)](https://github.com/aloth/olcli)
@@ -17,6 +18,7 @@ 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
@@ -82,9 +84,16 @@ olcli auth --cookie "your_session_cookie_value"
 **Email/password** (self-hosted without reCAPTCHA):
 
 ```bash
-olcli auth --email "you@example.com" --password "your_password"
+olcli auth --email "you@example.com"
+# prompts for the password, so it stays out of your shell history
 ```
 
+The password is **not stored** unless you pass `--save-password`. A session
+cookie is saved either way and is what later commands use; the password only
+buys an automatic re-login once that cookie expires. For scripts, set
+`OVERLEAF_EMAIL` and `OVERLEAF_PASSWORD` — every command reads them, so a
+scripted run never needs `olcli auth` at all.
+
 ### 2. List Projects
 
 ```bash
@@ -127,7 +136,7 @@ All commands auto-detect the project when run from a synced directory (contains
 |---------|-------------|
 | `olcli auth` | Set session cookie or login with email/password |
 | `olcli whoami` | Check authentication status |
-| `olcli logout` | Clear stored credentials |
+| `olcli logout` | Clear the global config and the local `.olauth`, reporting each |
 | `olcli list` | List all projects |
 | `olcli info [project]` | Show project details and file list |
 | `olcli pull [project] [dir]` | Download project files to local directory |
@@ -138,6 +147,7 @@ All commands auto-detect the project when run from a synced directory (contains
 | `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 |
@@ -272,7 +282,32 @@ 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.
+
+### What is stored, and how to clear it
+
+Everything is stored in plaintext, so it is worth knowing what is on disk:
+
+| Credential | Stored by default | Where |
+|---|---|---|
+| Session cookie | yes | global config, or `.olauth` with `--save-local` |
+| Email + password | **no** — only with `--save-password` | global config |
+
+`olcli check` reports what exists without printing any secret.
+
+`olcli logout` clears the global config **and** the `.olauth` file in the
+current directory, then lists what it removed. It cannot unset environment
+variables, so if `OVERLEAF_SESSION` or `OVERLEAF_EMAIL`/`OVERLEAF_PASSWORD` are
+set, it says so instead of implying you are logged out — those take precedence
+over anything on disk.
 
 ### Self-hosted Overleaf
 
@@ -341,6 +376,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);
@@ -357,7 +393,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
@@ -387,6 +424,12 @@ import {
 
 Contributions are welcome! Please open an issue or submit a pull request.
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, which tests need a real
+Overleaf account, and what to expect from CI on a pull request.
+
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains how the client works —
+there is no public Overleaf API, so it authenticates as a browser session.
+
 ## License
 
 MIT © [Alexander Loth](https://alexloth.com)

package/dist/cli.js

@@ -21,7 +21,8 @@ import { loadIgnore } 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, getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials } from './config.js';
+import { getSessionCookie, setSessionCookie, setLastProject, getConfigPath, saveOlAuth, clearConfig, getBaseUrl, setBaseUrl, getSessionCookieName, setSessionCookieName, getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials, clearOlAuth, inspectStoredCredentials } from './config.js';
+import { promptHidden, PromptCancelled, NotATerminal } from './prompt.js';
 const program = new Command();
 program
     .name('olcli')
@@ -114,9 +115,18 @@ program
     .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('--password <password>', 'Account password (omit to be prompted; see warning below)')
+    .option('--save-password', 'Persist the password in the config file, in plaintext')
+    .option('--no-save-password', 'Do not persist the password (the default; kept for existing scripts)')
     .option('--save-local', 'Save to .olauth in current directory')
+    .addHelpText('after', `
+The password is not stored unless you ask for it with --save-password. A
+session cookie is stored either way, and that is what later commands use; the
+password only buys an automatic re-login once the cookie expires.
+
+Passing --password puts the password in your shell history. Omit it to be
+prompted instead, or set OVERLEAF_EMAIL and OVERLEAF_PASSWORD, which every
+command reads without needing 'auth' at all.`)
     .action(async (options) => {
     if (!options.cookie && !options.email && !options.password) {
         console.log(chalk.yellow('To authenticate, provide a session cookie:'));
@@ -129,7 +139,8 @@ program
         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(chalk.cyan('  olcli auth --email "you@example.com"'));
+        console.log(chalk.dim('  (prompts for the password, so it stays out of your shell history)'));
         console.log();
         console.log('Or set OVERLEAF_SESSION environment variable');
         return;
@@ -138,10 +149,41 @@ program
         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.'));
+    if (!options.cookie && !options.email) {
+        console.error(chalk.red('--email is required for password login.'));
         process.exit(1);
     }
+    // Resolve the password before the spinner starts: a prompt and a spinner
+    // both own the terminal, and ora would redraw over the prompt line.
+    let password = options.password;
+    if (!options.cookie) {
+        if (password) {
+            console.log(chalk.yellow('⚠ --password is now in your shell history.'));
+            console.log(chalk.dim('  Omit it to be prompted, or set OVERLEAF_EMAIL/OVERLEAF_PASSWORD.'));
+        }
+        else {
+            try {
+                password = await promptHidden(`Password for ${options.email}: `);
+            }
+            catch (error) {
+                if (error instanceof NotATerminal) {
+                    console.error(chalk.red('No terminal available to prompt for a password.'));
+                    console.error('Set OVERLEAF_EMAIL and OVERLEAF_PASSWORD instead — every command reads them,');
+                    console.error("so a scripted run does not need 'olcli auth' at all.");
+                    process.exit(1);
+                }
+                if (error instanceof PromptCancelled) {
+                    console.error(chalk.red('Cancelled.'));
+                    process.exit(1);
+                }
+                throw error;
+            }
+            if (!password) {
+                console.error(chalk.red('Password must not be empty.'));
+                process.exit(1);
+            }
+        }
+    }
     const spinner = ora('Verifying session...').start();
     try {
         const baseUrl = program.opts().baseUrl || getBaseUrl();
@@ -160,14 +202,29 @@ program
         }
         else {
             spinner.text = 'Logging in with email/password...';
-            const client = await OverleafClient.fromPasswordLogin(options.email, options.password, baseUrl);
+            const client = await OverleafClient.fromPasswordLogin(options.email, password, baseUrl);
             const projects = await client.listProjects();
             persistClientSession(client, cookieName);
             setBaseUrl(baseUrl);
-            if (options.savePassword !== false) {
-                setPasswordCredentials(options.email, options.password);
+            // Opt-in, not opt-out. The session cookie persisted just above is what
+            // later commands actually use; the password only buys an automatic
+            // re-login after that cookie expires, and it is stored in plaintext.
+            // A cookie is scoped to olcli and rotates; a password is reusable
+            // everywhere and cannot be revoked without changing it. See issue #50.
+            const savePassword = options.savePassword === true;
+            if (savePassword) {
+                setPasswordCredentials(options.email, password);
+            }
+            // The old message said "Password login saved." unconditionally - even
+            // under --no-save-password, which had just prevented exactly that.
+            spinner.succeed(`Authenticated! Found ${projects.length} projects.`);
+            if (savePassword) {
+                console.log(chalk.yellow('Password stored in plaintext in the config file.'));
+            }
+            else {
+                console.log(chalk.dim('Session cookie stored. The password was not saved; re-run'));
+                console.log(chalk.dim('olcli auth when the session expires, or use --save-password.'));
             }
-            spinner.succeed(`Authenticated! Found ${projects.length} projects. Password login saved.`);
         }
         console.log(chalk.dim(`Config saved to: ${getConfigPath()}`));
     }
@@ -200,9 +257,44 @@ program
 program
     .command('logout')
     .description('Clear stored credentials')
+    .addHelpText('after', `
+Clears the global config and the .olauth file in the current directory, and
+reports each one separately. Environment variables cannot be cleared by a
+child process, so OVERLEAF_SESSION and OVERLEAF_EMAIL/OVERLEAF_PASSWORD are
+reported instead of silently ignored - both take precedence over anything on
+disk.`)
     .action(() => {
+    // Read before clearing: afterwards there is nothing left to report on.
+    const before = inspectStoredCredentials();
     clearConfig();
-    console.log(chalk.green('Credentials cleared'));
+    const removedOlAuth = clearOlAuth();
+    const cleared = [];
+    if (before.sessionCookie)
+        cleared.push('session cookie (global config)');
+    if (before.password)
+        cleared.push('saved password (global config)');
+    if (removedOlAuth)
+        cleared.push(removedOlAuth);
+    if (cleared.length === 0) {
+        console.log('Nothing stored to clear.');
+    }
+    else {
+        console.log(chalk.green('Cleared:'));
+        for (const item of cleared)
+            console.log(`  ${item}`);
+    }
+    // The reason this command was wrong before: it announced success while a
+    // higher-precedence source kept the user authenticated. Anything olcli
+    // cannot clear has to be said out loud, or the message is a lie again.
+    if (before.envSession || before.envPassword) {
+        console.log();
+        console.log(chalk.yellow('Still authenticated in this shell:'));
+        if (before.envSession)
+            console.log('  OVERLEAF_SESSION is set');
+        if (before.envPassword)
+            console.log('  OVERLEAF_EMAIL and OVERLEAF_PASSWORD are set');
+        console.log(chalk.dim('  These outrank anything on disk. Unset them to finish logging out.'));
+    }
 });
 // ─────────────────────────────────────────────────────────────────────────────
 // PROJECT COMMANDS
@@ -701,7 +793,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')
@@ -1732,6 +1856,21 @@ program
     else {
         console.log(chalk.yellow('✗ No session cookie found'));
     }
+    // A stored password is a credential source this command used to omit,
+    // which made it impossible to answer "is my password on disk?" without
+    // opening the config file. Never print the value - only whether it exists
+    // and which source it came from.
+    const stored = inspectStoredCredentials();
+    if (stored.envPassword) {
+        console.log(chalk.yellow('⚠ Password set via OVERLEAF_EMAIL/OVERLEAF_PASSWORD'));
+    }
+    else if (stored.password) {
+        console.log(chalk.yellow('⚠ Password stored in plaintext in the config file'));
+        console.log(chalk.dim("  Remove it with 'olcli logout', then re-auth without --save-password."));
+    }
+    if (stored.olAuthPath) {
+        console.log(chalk.dim(`  .olauth present: ${stored.olAuthPath}`));
+    }
 });
 program.parse(process.argv);
 //# sourceMappingURL=cli.js.map