@aloth/olcli 0.11.0 → 0.13.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)
@@ -22,6 +23,7 @@ Work with Overleaf projects directly from your command line. Edit locally with y
 - ⬆️ **Push** local changes back to Overleaf
 - 🔄 **Sync** bidirectionally with smart conflict detection
 - 🔍 **Diff** local files against the live remote before pushing
+- 📝 **Marked-up revisions** — `diff --latexdiff` produces the struck-through/underlined PDF advisors and journals ask for
 - 🔀 **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
@@ -83,9 +85,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
@@ -128,7 +137,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 |
@@ -209,6 +218,7 @@ 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
+olcli diff --exit-code     # exit 1 if anything differs, for CI
 ```
 
 **The remote side is fetched fresh on every run.** The diff describes the
@@ -232,6 +242,80 @@ 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.
 
+#### Marked-up revisions with latexdiff
+
+A unified diff is the right artifact for a developer and the wrong one for a
+thesis advisor. `--latexdiff` marks the same revision up inside the document
+instead — deletions struck through, additions underlined — which is what
+advisors and journals ask for.
+
+```bash
+olcli diff --latexdiff          # write .olcli-diff/main-diff.tex
+olcli diff --latexdiff --pdf    # ...and compile it, download .olcli-diff/main-diff.pdf
+```
+
+Requires `latexdiff` on your PATH. It ships with TeX Live and MacTeX; nothing
+else in `olcli diff` needs an external tool.
+
+**`--pdf` compiles on Overleaf, so you do not need a local TeX installation.**
+The compile endpoint can only build a file that is in the project, so the
+marked-up document is uploaded as `olcli-latexdiff.tex` next to your root
+document, compiled, downloaded, and then removed. The command says so before it
+does it, refuses to overwrite a file of that name if one already exists, and
+prints the exact `olcli rm` command if the cleanup itself fails.
+
+`\input` and `\include` are inlined before comparing (`--no-flatten` to opt
+out). Without that, a remote compile would resolve those against the files
+sitting in the project — the old content — and quietly produce a PDF showing
+every input file as unchanged.
+
+Output goes to `.olcli-diff/`, which is dotted so that `push` and `sync` never
+pick it up; `-o <path>` puts it elsewhere. The root document is the `.tex` file
+declaring `\documentclass`; if several do, `--main <path>` picks one rather
+than the command guessing. `--latexdiff-opt` passes anything else straight
+through, e.g. `--latexdiff-opt --math-markup=0`.
+
+One limit worth knowing: `--pdf` compiles against the project, not against your
+working directory, so anything the markup needs must already be on Overleaf. A
+`.sty` or `.cls` you added locally fails the compile — the compiler log is
+written next to the marked-up source when that happens. A *figure* you added
+locally does not fail it; Overleaf draws a placeholder box naming the missing
+file and the rest of the PDF is fine.
+
+#### Using `diff` as a CI gate
+
+`--exit-code` turns the command into a check, with the statuses `diff(1)` uses:
+
+| Status | Meaning |
+|--------|---------|
+| `0` | Nothing differs |
+| `1` | Something differs |
+| `2` | The run failed — bad flags, no session, project unreachable |
+
+```yaml
+- name: Fail if the paper on Overleaf has drifted from the repo
+  run: olcli diff --exit-code --name-only
+  env:
+    OVERLEAF_SESSION: ${{ secrets.OVERLEAF_SESSION }}
+```
+
+**The `1` versus `2` split is the point of the flag.** Without it a pipeline
+cannot tell a changed file from an expired session cookie, and a job that goes
+red for the second reason sends whoever reads the log hunting for a diff that
+was never computed. Every other olcli command reports failure as `1`, and
+`olcli diff` still does when `--exit-code` is absent, so adding the flag does
+not change what existing scripts see.
+
+The gate covers whatever was compared: `--file main.tex` narrows it to one
+file, the way a `git diff --exit-code` pathspec does, and a `--file` that
+matches nothing is `0` rather than an error. Under `--latexdiff` it still
+reports on the project as a whole — a changed figure is a real difference even
+though a marked-up root document cannot show it.
+
+Note that this compares against Overleaf **now**, not against your last pull,
+so the check is "has anyone drifted from what is committed here", which is what
+makes it worth running on a schedule as well as on a push.
+
 #### How deletion propagation works
 
 `olcli` records a manifest of remote files in `.olcli.json`. On next sync:
@@ -284,6 +368,23 @@ hardcoded here: on macOS it lands under `~/Library/Preferences/`, on Linux under
 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
 
 ```bash
@@ -399,6 +500,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)