@aloth/olcli 0.15.3 → 0.16.1

package/dist/cli.js

@@ -7,14 +7,15 @@
  */
 import { Command } from 'commander';
 import chalk from 'chalk';
-import ora from 'ora';
+import { colorDisabled, createSpinner as ora, icon } from './term.js';
+import { formatError } from './errors.js';
 import { writeFileSync, readFileSync, existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { OverleafClient, resolveCommentConcurrency } from './client.js';
 import { formatAuthor } from './tracked-changes.js';
-import { resolveRemotePath, resolveWithin, normalizeRemotePath } from './paths.js';
+import { resolveRemotePath, resolveWithin, normalizeRemotePath, safeLocalName, legacyLocalName } from './paths.js';
 import { planProjectRenames } from './rename-plan.js';
 import { scanLocalFiles } from './scan.js';
 import { compareTrees, DIFF_EXIT_FAILURE, differencesExitCode, filterRemoteTree, renderFileDiff, statusLetter, } from './diff.js';
@@ -24,17 +25,92 @@ 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, clearOlAuth, inspectStoredCredentials } from './config.js';
+import { getSessionCookie, setSessionCookie, setLastProject, getConfigPath, saveOlAuth, clearConfig, getBaseUrl, setBaseUrl, getSessionCookieName, setSessionCookieName, getTimeout, setTimeout, getPasswordCredentials, setPasswordCredentials, clearOlAuth, inspectStoredCredentials, parseCookieInput, resolveSessionCookie, maskSecret } from './config.js';
 import { promptHidden, PromptCancelled, NotATerminal } from './prompt.js';
+import { BrowserSignInAborted, browserSignIn, chromiumLauncher, findBrowser, requireWebSocket } from './browser-auth.js';
+// NO_COLOR (no-color.org) and --no-color. chalk handles --no-color and a
+// non-TTY stdout by itself, but not NO_COLOR; ora and log-symbols share this
+// chalk instance, so one assignment covers them too.
+if (colorDisabled())
+    chalk.level = 0;
 const program = new Command();
 program
     .name('olcli')
     .description('Overleaf CLI - interact with Overleaf projects from the command line')
     .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('--base-url <url>', 'Overleaf instance URL (overrides OVERLEAF_BASE_URL and config)')
+    .option('--cookie-name <name>', 'Session cookie name (default: overleaf_session2; or overleaf.sid)')
     .option('--timeout <ms>', 'HTTP request timeout in milliseconds', parseInt)
-    .option('--verbose', 'Print every HTTP request, status, and error response body to stderr');
+    .option('--verbose', 'Print every HTTP request, status and error body to stderr')
+    .option('--no-color', 'Turn off color (same as setting NO_COLOR)')
+    .addHelpText('after', `
+Environment:
+  OVERLEAF_SESSION        session cookie (instead of olcli auth)
+  OVERLEAF_EMAIL, OVERLEAF_PASSWORD
+                          password login when no session cookie works
+  OVERLEAF_BASE_URL       instance URL, like --base-url
+  OVERLEAF_COOKIE_NAME    session cookie name, like --cookie-name
+  OVERLEAF_TIMEOUT        HTTP timeout in milliseconds, like --timeout
+  OLCLI_CONCURRENCY       documents fetched in parallel by comments list
+  HTTPS_PROXY             proxy for https:// instances (CONNECT tunnel)
+  HTTP_PROXY              proxy for http:// instances
+  NO_PROXY                comma-separated hosts that bypass the proxy
+                          (localhost and 127.0.0.1 are always direct)
+  NO_COLOR                turn off color`);
+/**
+ * The one way a command reports a failure: the cause (and the command that
+ * fixes it) on the spinner line, details such as the HTTP status on stderr
+ * after it. Exits with `code`, 1 unless the command reserves 1 for something
+ * else (`diff --exit-code`).
+ */
+function failWith(spinner, error, code = 1) {
+    const verbose = Boolean(program.opts().verbose);
+    const [first, ...rest] = formatError(error, { verbose });
+    spinner.fail(first);
+    for (const line of rest)
+        console.error(chalk.dim(`  ${line}`));
+    process.exit(code);
+}
+/** Everything on stdin, as text. Used by `auth --cookie -`. */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * What to run after a successful `auth`. Names a real project when there is
+ * one whose name can be quoted safely, the placeholder otherwise.
+ */
+function nextStepCommands(projects) {
+    const first = projects.find((p) => p.name && !/["$`\\]/.test(p.name));
+    return ['olcli list', `olcli pull "${first ? first.name : '<name>'}"`];
+}
+/**
+ * Where `pull <project>` puts a project when no directory is given.
+ *
+ * Normally `safeLocalName(name)`. Up to 0.15 every non-ASCII letter became
+ * "_", so a directory pulled back then has a different name; when that one
+ * exists and its .olcli.json points at the same project, and the new name is
+ * not taken yet, it is reused rather than downloading a second copy.
+ */
+function defaultProjectDir(projectId, name, cwd = '.') {
+    const current = safeLocalName(name);
+    const legacy = legacyLocalName(name);
+    if (legacy === current || existsSync(join(cwd, current)))
+        return current;
+    const legacyMeta = join(cwd, legacy, '.olcli.json');
+    if (existsSync(legacyMeta)) {
+        try {
+            if (JSON.parse(readFileSync(legacyMeta, 'utf-8')).projectId === projectId)
+                return legacy;
+        }
+        catch {
+            // Unreadable metadata: not provably ours, use the new name.
+        }
+    }
+    return current;
+}
 /**
  * Helper to get authenticated client
  *
@@ -65,10 +141,8 @@ async function getClient(cookieOpt, baseUrlOpt, failureCode = 1) {
         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');
+    console.error('Sign in with: olcli auth --cookie   (prompts for the cookie; see olcli auth --help)');
+    console.error('Or set the OVERLEAF_SESSION environment variable.');
     process.exit(failureCode);
 }
 async function loginWithSavedPassword(credentials, baseUrl, cookieName) {
@@ -97,10 +171,7 @@ async function resolveProject(client, projectArg, dir = '.') {
             return { id: projectArg, name: projectArg };
         }
         // Otherwise, look up by name
-        const proj = await client.getProject(projectArg);
-        if (!proj) {
-            throw new Error(`Project not found: ${projectArg}`);
-        }
+        const proj = await client.findProject(projectArg);
         return { id: proj.id, name: proj.name };
     }
     // Otherwise, check for .olcli.json
@@ -117,16 +188,33 @@ async function resolveProject(client, projectArg, dir = '.') {
 // ─────────────────────────────────────────────────────────────────────────────
 // AUTH COMMANDS
 // ─────────────────────────────────────────────────────────────────────────────
-program
+const authCmd = program
     .command('auth')
     .description('Authenticate with Overleaf using a session cookie or email/password')
-    .option('--cookie <session>', 'Session cookie (overleaf_session2 value)')
+    .option('--cookie [session]', 'Session cookie; omit the value to be prompted, "-" reads stdin')
     .option('--email <email>', 'Account email for password login')
     .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')
+    .option('--browser', 'Sign in in a browser window; only the session cookie is kept')
     .addHelpText('after', `
+Easiest: olcli auth --browser opens the login page of the instance in Chrome,
+Edge, Chromium or Brave, with a new temporary profile (not your own), and
+waits up to 5 minutes until you have signed in. Works with SSO, Google, ORCID
+and two-factor logins. olcli keeps only the session cookie; it never sees your
+password. The browser and the profile are removed afterwards. Set
+OLCLI_BROWSER to the browser (an .app bundle or the executable) when it is
+not found. Needs Node 22 or newer.
+
+Get your session cookie: sign in to Overleaf in a browser, open the developer
+tools (F12), then Application (Chrome, Edge) or Storage (Firefox), Cookies,
+and copy the value of overleaf_session2 (overleaf.sid on older self-hosted
+instances). Then either:
+  olcli auth --cookie                       prompts, input stays hidden
+  pbpaste | olcli auth --cookie -           reads the cookie from stdin
+A value given on the command line works too, but lands in your shell history.
+
 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.
@@ -135,15 +223,28 @@ 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.browser) {
+        if (options.cookie || options.email || options.password) {
+            console.error(chalk.red('Use either --browser or --cookie or --email/--password, not several.'));
+            process.exit(1);
+        }
+        await authWithBrowser(options);
+        return;
+    }
     if (!options.cookie && !options.email && !options.password) {
-        console.log(chalk.yellow('To authenticate, provide a session cookie:'));
+        console.log(chalk.yellow('To authenticate, sign in in a browser window:'));
+        console.log();
+        console.log(chalk.cyan('  olcli auth --browser'));
+        console.log();
+        console.log(chalk.yellow('Or 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');
-        console.log('3. Find the cookie named "overleaf_session2"');
-        console.log('4. Copy its value and run:');
+        console.log('1. Sign in to Overleaf in your browser');
+        console.log('2. Open the developer tools (F12), then Application (Chrome, Edge) or Storage (Firefox), then Cookies');
+        console.log('3. Copy the value of the cookie named "overleaf_session2"');
+        console.log('4. Run this and paste it when asked (input stays hidden):');
         console.log();
-        console.log(chalk.cyan('  olcli auth --cookie "your_session_cookie_value"'));
+        console.log(chalk.cyan('  olcli auth --cookie'));
+        console.log(chalk.dim('  (or pipe it: pbpaste | olcli auth --cookie -)'));
         console.log();
         console.log('Or log in with email/password:');
         console.log(chalk.cyan('  olcli auth --email "you@example.com"'));
@@ -160,12 +261,50 @@ command reads without needing 'auth' at all.`)
         console.error(chalk.red('--email is required for password login.'));
         process.exit(1);
     }
+    // The cookie is a secret, so it does not have to travel through argv:
+    // no value prompts with hidden input, "-" reads stdin. Resolved before
+    // the spinner for the same reason as the password below.
+    const promptCookieName = program.opts().cookieName || getSessionCookieName();
+    let cookie;
+    if (options.cookie === true) {
+        try {
+            cookie = parseCookieInput(await promptHidden(`Paste the ${promptCookieName} cookie (input hidden): `), promptCookieName);
+        }
+        catch (error) {
+            if (error instanceof NotATerminal) {
+                console.error(chalk.red('No terminal available to prompt for the cookie.'));
+                console.error('Pipe it instead: olcli auth --cookie - < cookie.txt');
+                console.error('Or set OVERLEAF_SESSION, which every command reads.');
+                process.exit(1);
+            }
+            if (error instanceof PromptCancelled) {
+                console.error(chalk.red('Cancelled.'));
+                process.exit(1);
+            }
+            throw error;
+        }
+    }
+    else if (options.cookie === '-') {
+        if (process.stdin.isTTY) {
+            console.error(chalk.dim('Reading the cookie from stdin; paste it, then press Ctrl+D.'));
+        }
+        cookie = parseCookieInput(await readStdin(), promptCookieName);
+    }
+    else if (typeof options.cookie === 'string') {
+        cookie = parseCookieInput(options.cookie, promptCookieName);
+        console.error(chalk.yellow('Warning: the cookie is now in your shell history.'));
+        console.error(chalk.dim('  Next time run olcli auth --cookie to be prompted, or pipe it to olcli auth --cookie -'));
+    }
+    if (options.cookie && !cookie) {
+        console.error(chalk.red('The session cookie must not be empty.'));
+        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.yellow(icon('⚠ ', '') + '--password is now in your shell history.'));
             console.log(chalk.dim('  Omit it to be prompted, or set OVERLEAF_EMAIL/OVERLEAF_PASSWORD.'));
         }
         else {
@@ -195,12 +334,13 @@ command reads without needing 'auth' at all.`)
     try {
         const baseUrl = program.opts().baseUrl || getBaseUrl();
         const cookieName = program.opts().cookieName || getSessionCookieName();
-        if (options.cookie) {
-            const client = await OverleafClient.fromSessionCookie(options.cookie, baseUrl, cookieName);
-            const projects = await client.listProjects();
-            setSessionCookie(options.cookie);
+        let projects;
+        if (cookie) {
+            const client = await OverleafClient.fromSessionCookie(cookie, baseUrl, cookieName);
+            projects = await client.listProjects();
+            setSessionCookie(cookie);
             if (options.saveLocal) {
-                saveOlAuth(options.cookie);
+                saveOlAuth(cookie);
                 spinner.succeed(`Authenticated! Found ${projects.length} projects. Saved to .olauth`);
             }
             else {
@@ -210,7 +350,7 @@ command reads without needing 'auth' at all.`)
         else {
             spinner.text = 'Logging in with email/password...';
             const client = await OverleafClient.fromPasswordLogin(options.email, password, baseUrl);
-            const projects = await client.listProjects();
+            projects = await client.listProjects();
             persistClientSession(client, cookieName);
             setBaseUrl(baseUrl);
             // Opt-in, not opt-out. The session cookie persisted just above is what
@@ -233,38 +373,201 @@ command reads without needing 'auth' at all.`)
                 console.log(chalk.dim('olcli auth when the session expires, or use --save-password.'));
             }
         }
-        console.log(chalk.dim(`Config saved to: ${getConfigPath()}`));
+        printNextSteps(projects);
     }
     catch (error) {
-        spinner.fail(`Authentication failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
-program
-    .command('whoami')
-    .description('Show current authentication status')
-    .action(async () => {
-    // Status 1 on both failure paths, so `olcli whoami || olcli auth` works.
-    // exitCode rather than exit(): the message still has to reach a pipe.
-    const cookie = getSessionCookie();
-    if (!cookie) {
-        console.log(chalk.yellow('Not authenticated'));
-        process.exitCode = 1;
-        return;
+/** Print the same lines as every successful `auth`. */
+function printNextSteps(projects) {
+    console.log(chalk.dim(`Config saved to: ${getConfigPath()}`));
+    console.log();
+    console.log('Next steps:');
+    for (const line of nextStepCommands(projects))
+        console.log(`  ${chalk.cyan(line)}`);
+}
+/**
+ * `auth --browser`. The cookie found in the browser is validated with the
+ * same client call as `auth --cookie` (the project list) before it is
+ * stored, and only its name and value are stored. Ctrl-C and SIGTERM abort
+ * the wait; browserSignIn closes the browser and deletes the profile.
+ */
+async function authWithBrowser(options) {
+    const baseUrl = program.opts().baseUrl || getBaseUrl();
+    const cookieName = program.opts().cookieName || getSessionCookieName();
+    const timeout = program.opts().timeout || getTimeout();
+    let browser;
+    try {
+        requireWebSocket();
+        browser = findBrowser();
+    }
+    catch (error) {
+        console.error(chalk.red(error.message));
+        process.exit(1);
     }
-    const spinner = ora('Checking session...').start();
+    const abort = new AbortController();
+    const onSignal = () => abort.abort();
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    console.error(`Opening ${browser.name} at ${baseUrl}/login with a temporary profile.`);
+    console.error(chalk.dim('Sign in there. olcli waits up to 5 minutes; Ctrl-C cancels.'));
+    const spinner = ora('Waiting for the sign-in...').start();
+    let projects = [];
     try {
-        const baseUrl = program.opts().baseUrl || getBaseUrl();
-        const cookieName = program.opts().cookieName || getSessionCookieName();
-        const client = await OverleafClient.fromSessionCookie(cookie, baseUrl, cookieName);
-        const projects = await client.listProjects();
-        spinner.succeed(`Authenticated with access to ${projects.length} projects`);
+        const session = await browserSignIn({
+            baseUrl,
+            cookieName,
+            startBrowser: chromiumLauncher(browser.path),
+            signal: abort.signal,
+            validate: async (candidate) => {
+                const client = await OverleafClient.fromSessionCookie(candidate.value, baseUrl, candidate.name);
+                client.setGlobalTimeout(timeout);
+                projects = await client.listProjects();
+                return true;
+            },
+        });
+        if (session.name !== cookieName)
+            setSessionCookieName(session.name);
+        setSessionCookie(session.value);
+        if (options.saveLocal) {
+            saveOlAuth(session.value);
+            spinner.succeed(`Authenticated! Found ${projects.length} projects. Saved to .olauth`);
+        }
+        else {
+            spinner.succeed(`Authenticated! Found ${projects.length} projects.`);
+        }
+        printNextSteps(projects);
     }
     catch (error) {
-        spinner.fail(`Session invalid: ${error.message}`);
+        if (error instanceof BrowserSignInAborted) {
+            spinner.fail('Cancelled. The browser was closed and its temporary profile deleted.');
+            process.exit(130);
+        }
+        failWith(spinner, error);
+    }
+    finally {
+        process.off('SIGINT', onSignal);
+        process.off('SIGTERM', onSignal);
+    }
+}
+/**
+ * `auth status`: one answer to "am I set up". Replaces `whoami` (is the
+ * session valid) and `check` (where do credentials come from), which both
+ * stay as hidden aliases.
+ *
+ * Exit status 1 when no credential is found or the session is rejected, so
+ * `olcli auth status || olcli auth` works. exitCode rather than exit(): the
+ * report still has to reach a pipe.
+ */
+async function authStatus(options) {
+    const baseUrl = program.opts().baseUrl || getBaseUrl();
+    const cookieName = program.opts().cookieName || getSessionCookieName();
+    const resolved = resolveSessionCookie();
+    const stored = inspectStoredCredentials();
+    const password = resolved ? undefined : getPasswordCredentials();
+    const sourceLabel = !resolved
+        ? (password ? (stored.envPassword ? 'OVERLEAF_EMAIL/OVERLEAF_PASSWORD' : 'saved password (config file)') : 'none')
+        : resolved.source === 'env' ? 'OVERLEAF_SESSION environment variable'
+            : resolved.source === 'olauth' ? `.olauth (${resolved.path})`
+                : `config file (${resolved.path})`;
+    const report = {
+        instance: baseUrl,
+        account: null,
+        credentialSource: sourceLabel,
+        cookieName,
+        cookie: resolved ? maskSecret(resolved.value) : null,
+        configFile: getConfigPath(),
+        passwordStored: stored.password,
+        signedIn: false,
+    };
+    const print = () => {
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        const row = (label, value) => console.log(`  ${label.padEnd(12)} ${value}`);
+        row('Instance', report.instance);
+        row('Account', report.account ?? chalk.dim(report.signedIn ? 'unknown' : '-'));
+        row('Credential', report.credentialSource);
+        row('Cookie', report.cookie ? `${report.cookieName} = ${report.cookie}` : chalk.dim('-'));
+        row('Config file', report.configFile);
+        if (report.passwordStored) {
+            row('Password', chalk.yellow('stored in plaintext in the config file (olcli logout removes it)'));
+        }
+        if (report.signedIn) {
+            row('Session', chalk.green(`valid, ${report.projects} project(s)`));
+        }
+    };
+    let failure;
+    if (!resolved && !password) {
+        report.error = 'Not signed in';
+    }
+    else {
+        const spinner = options.json ? null : ora('Checking session...').start();
+        try {
+            const client = resolved
+                ? await OverleafClient.fromSessionCookie(resolved.value, baseUrl, cookieName)
+                : await OverleafClient.fromPasswordLogin(password.email, password.password, baseUrl);
+            const timeout = program.opts().timeout || getTimeout();
+            client.setGlobalTimeout(timeout);
+            const projects = await client.listProjects();
+            report.signedIn = true;
+            report.projects = projects.length;
+            report.account = client.accountEmail ?? (password ? password.email : null);
+            spinner?.stop();
+        }
+        catch (error) {
+            spinner?.stop();
+            failure = error;
+            report.error = formatError(error, { verbose: true })[0];
+        }
+    }
+    print();
+    if (!report.signedIn) {
         process.exitCode = 1;
+        if (options.json)
+            return;
+        console.log();
+        if (!resolved && !password) {
+            console.log(chalk.yellow('Not signed in.'));
+            console.log(`Run: ${chalk.cyan('olcli auth')}`);
+        }
+        else {
+            const [first, ...rest] = formatError(failure, { verbose: Boolean(program.opts().verbose) });
+            console.error(chalk.red(first));
+            for (const line of rest)
+                console.error(chalk.dim(`  ${line}`));
+        }
     }
-});
+}
+/** Hidden alias for a command folded into `auth status`. */
+function deprecatedAlias(name, description) {
+    program
+        .command(name, { hidden: true })
+        .description(description)
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        console.error(chalk.dim(`'olcli ${name}' is now 'olcli auth status'.`));
+        await authStatus(options);
+    });
+}
+authCmd
+    .command('status')
+    .description('Show instance, account, credential source and a masked cookie')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', `
+Exits 1 when no credential is found or Overleaf rejects the session, so
+'olcli auth status || olcli auth' signs in only when needed. The cookie is
+shown masked: its last four characters and its length.
+
+Credential sources, first match wins:
+  1. OVERLEAF_SESSION environment variable
+  2. .olauth file in the current directory
+  3. Global config file
+  4. OVERLEAF_EMAIL/OVERLEAF_PASSWORD, or a password saved with --save-password`)
+    .action(authStatus);
+deprecatedAlias('whoami', 'Alias of: auth status');
 program
     .command('logout')
     .description('Clear stored credentials')
@@ -342,8 +645,7 @@ program
         }
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -371,14 +673,13 @@ program
         // Sort entities by path for nice display
         const sorted = entities.sort((a, b) => a.path.localeCompare(b.path));
         for (const entity of sorted) {
-            const icon = entity.type === 'doc' ? '📄' : '📎';
-            console.log(`  ${icon} ${entity.path}`);
+            const marker = entity.type === 'doc' ? icon('📄', 'doc ') : icon('📎', 'file');
+            console.log(`  ${marker} ${entity.path}`);
         }
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 const commentsCmd = program
@@ -478,8 +779,7 @@ commentsCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 commentsCmd
@@ -502,8 +802,7 @@ commentsCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 commentsCmd
@@ -526,8 +825,7 @@ commentsCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 commentsCmd
@@ -550,8 +848,7 @@ commentsCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 commentsCmd
@@ -574,8 +871,7 @@ commentsCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 commentsCmd
@@ -613,8 +909,7 @@ commentsCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
@@ -622,7 +917,10 @@ commentsCmd
 // ─────────────────────────────────────────────────────────────────────────────
 const changesCmd = program
     .command('changes')
-    .description('Review Overleaf tracked changes (suggested edits). Requires a project whose owner has an Overleaf premium plan; collaborators on any plan can then use it');
+    .description('Accept or reject tracked changes (needs a premium project owner)')
+    .addHelpText('after', `
+Tracked changes need a project whose owner has an Overleaf premium plan;
+collaborators on any plan can then accept and reject them.`);
 changesCmd
     .command('accept <ids...>')
     .description('Accept tracked changes by id (ids from: olcli comments list --changes)')
@@ -648,8 +946,7 @@ changesCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 changesCmd
@@ -688,8 +985,7 @@ changesCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -709,8 +1005,7 @@ program
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -724,14 +1019,13 @@ program
         const client = await getClient(options.cookie);
         const proj = await resolveProject(client, project);
         const zip = await client.downloadProject(proj.id);
-        const outputPath = options.output || `${proj.name.replace(/[^a-zA-Z0-9-_]/g, '_')}.zip`;
+        const outputPath = options.output || `${safeLocalName(proj.name)}.zip`;
         writeFileSync(outputPath, zip);
         spinner.succeed(`Downloaded: ${outputPath} (${(zip.length / 1024).toFixed(1)} KB)`);
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -747,14 +1041,13 @@ program
         const proj = await resolveProject(client, project);
         spinner.text = 'Compiling...';
         const pdf = await client.downloadPdf(proj.id, undefined, options.resource);
-        const outputPath = options.output || `${proj.name.replace(/[^a-zA-Z0-9-_]/g, '_')}.pdf`;
+        const outputPath = options.output || `${safeLocalName(proj.name)}.pdf`;
         writeFileSync(outputPath, pdf);
         spinner.succeed(`Downloaded PDF: ${outputPath} (${(pdf.length / 1024).toFixed(1)} KB)`);
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -812,8 +1105,7 @@ program
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
@@ -853,8 +1145,7 @@ program
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
@@ -877,8 +1168,7 @@ program
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -919,8 +1209,7 @@ Examples:
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
@@ -957,8 +1246,7 @@ projectCmd
         console.log(`  ${chalk.cyan(created.url)}`);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 projectCmd
@@ -986,8 +1274,7 @@ projectCmd
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 projectCmd
@@ -1085,8 +1372,7 @@ projectCmd
         }
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1108,8 +1394,7 @@ program
         setLastProject(proj.id);
     }
     catch (error) {
-        spinner.fail(`Compilation failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1142,19 +1427,16 @@ program
         const client = await getClient(options.cookie);
         // Resolve project if needed
         if (!projectId) {
-            let proj = await client.getProjectById(project);
-            if (!proj) {
-                proj = await client.getProject(project);
-            }
-            if (!proj) {
-                spinner.fail(`Project not found: ${project}`);
-                process.exit(1);
-            }
+            const proj = await client.findProject(project);
             projectId = proj.id;
             projectName = proj.name;
-            // Default directory is project name (sanitized) if not specified
+            // Default directory is the project name, made safe for a path
             if (!dir) {
-                targetDir = proj.name.replace(/[^a-zA-Z0-9-_]/g, '_');
+                targetDir = defaultProjectDir(proj.id, proj.name);
+                if (targetDir === legacyLocalName(proj.name) && targetDir !== safeLocalName(proj.name)) {
+                    spinner.info(`Using existing directory ${targetDir}/ (created by an earlier olcli)`);
+                    spinner.start('Downloading project...');
+                }
             }
         }
         spinner.text = 'Downloading project...';
@@ -1248,8 +1530,7 @@ program
         setLastProject(projectId);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -1303,14 +1584,7 @@ program
         const client = await getClient(options.cookie);
         // Resolve project if needed
         if (!projectId) {
-            let proj = await client.getProjectById(projectName);
-            if (!proj) {
-                proj = await client.getProject(projectName);
-            }
-            if (!proj) {
-                spinner.fail(`Project not found: ${projectName}`);
-                process.exit(1);
-            }
+            const proj = await client.findProject(projectName);
             projectId = proj.id;
             projectName = proj.name;
         }
@@ -1473,7 +1747,7 @@ program
             spinner.succeed(`Uploaded ${uploaded} file(s) to "${projectName}"`);
         }
         if (deleted > 0) {
-            console.log(chalk.dim(`  ✖ ${deleted} deleted on remote`));
+            console.log(chalk.dim(`  ${icon('✖', '-')} ${deleted} deleted on remote`));
         }
         if (deleteSkipped.length > 0) {
             console.log(chalk.yellow(`  ${deleteSkipped.length} deletion(s) skipped:`));
@@ -1487,8 +1761,7 @@ program
         setLastProject(projectId);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
@@ -1530,14 +1803,7 @@ skipped, or pushed. Combine it with --dry-run to preview deletions:
         const client = await getClient(options.cookie);
         // Resolve project
         if (!projectId) {
-            let proj = await client.getProjectById(projectName);
-            if (!proj) {
-                proj = await client.getProject(projectName);
-            }
-            if (!proj) {
-                spinner.fail(`Project not found: ${projectName}`);
-                process.exit(1);
-            }
+            const proj = await client.findProject(projectName);
             projectId = proj.id;
             projectName = proj.name;
         }
@@ -1711,13 +1977,13 @@ skipped, or pushed. Combine it with --dry-run to preview deletions:
             spinner.succeed(`Synced "${projectName}"`);
         }
         // Summary
-        console.log(chalk.dim(`  ↓ ${filesUpdatedLocally.length} pulled from remote`));
-        console.log(chalk.dim(`  ↑ ${filesToUpload.length} pushed to remote`));
+        console.log(chalk.dim(`  ${icon('↓', '<')} ${filesUpdatedLocally.length} pulled from remote`));
+        console.log(chalk.dim(`  ${icon('↑', '>')} ${filesToUpload.length} pushed to remote`));
         if (filesDeletedRemote.length > 0) {
-            console.log(chalk.dim(`  ✖ ${filesDeletedRemote.length} deleted on remote`));
+            console.log(chalk.dim(`  ${icon('✖', '-')} ${filesDeletedRemote.length} deleted on remote`));
         }
         if (filesDeleteSkipped.length > 0) {
-            console.log(chalk.yellow(`  ⚠ ${filesDeleteSkipped.length} deletion(s) failed (kept remote)`));
+            console.log(chalk.yellow(`  ${icon('⚠', '!')} ${filesDeleteSkipped.length} deletion(s) failed (kept remote)`));
         }
         // The program-level --verbose, not a sync option: commander assigns a
         // flag declared on both levels to the program, so a local --verbose here
@@ -1751,13 +2017,12 @@ skipped, or pushed. Combine it with --dry-run to preview deletions:
         setLastProject(projectId);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(1);
+        failWith(spinner, error);
     }
 });
 program
     .command('diff [project] [dir]')
-    .description('Show content-level differences between local files and the remote project')
+    .description('Show content 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)
@@ -1952,8 +2217,7 @@ where the markup only covers the root document.`)
             process.exitCode = differencesExitCode(entries);
     }
     catch (error) {
-        spinner.fail(`Failed: ${error.message}`);
-        process.exit(failureCode);
+        failWith(spinner, error, failureCode);
     }
 });
 /**
@@ -2258,41 +2522,32 @@ program
         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')
-    .action(() => {
-    console.log(chalk.bold('Configuration:'));
-    console.log(`  Config file: ${getConfigPath()}`);
-    console.log();
-    console.log(chalk.bold('Credential sources (in order):'));
-    console.log('  1. OVERLEAF_SESSION environment variable');
-    console.log('  2. .olauth file in current directory');
-    console.log('  3. Global config file');
-    console.log();
-    const cookie = getSessionCookie();
-    if (cookie) {
-        console.log(chalk.green('✓ Session cookie found'));
-        console.log(chalk.dim(`  Value: ${cookie.substring(0, 20)}...`));
-    }
-    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}`));
-    }
-});
+deprecatedAlias('check', 'Alias of: auth status');
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOT HELP GROUPS
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow order: sign in, find a project, sync it, touch single files, build,
+// review, settings. A visible top-level command without a group fails a test.
+const HELP_GROUPS = [
+    ['Account:', ['auth', 'logout']],
+    ['Projects:', ['list', 'info', 'project']],
+    ['Sync:', ['pull', 'push', 'sync', 'diff']],
+    ['Files:', ['download', 'upload', 'delete', 'rename', 'zip']],
+    ['Build:', ['compile', 'pdf', 'output']],
+    ['Review:', ['comments', 'changes']],
+    ['Settings:', ['config', 'ignored']],
+];
+{
+    const order = new Map();
+    HELP_GROUPS.forEach(([heading, names], group) => {
+        names.forEach((name, position) => {
+            program.commands.find((c) => c.name() === name)?.helpGroup(heading);
+            order.set(name, group * 100 + position);
+        });
+    });
+    // Commander lists groups in the order their first command appears.
+    program.commands.sort((a, b) => (order.get(a.name()) ?? 9999) - (order.get(b.name()) ?? 9999));
+    program.commandsGroup('Help:').helpCommand(true);
+}
 program.parse(process.argv);
 //# sourceMappingURL=cli.js.map