feat(diff): --exit-code so olcli diff can gate CI

Second follow-up left open by #48, alongside --latexdiff. Reports diff(1)'s
statuses: 0 when nothing differs, 1 when something does, 2 when the run
itself failed.

The 1-vs-2 split is the whole feature. A pipeline that cannot separate "the
project differs" from "the run failed" reads an expired session cookie as a
content change, and a job that goes red for the wrong reason sends whoever
reads the log looking for a diff that was never computed. All ten failure
paths in the command move to 2 together, so no failure can be mistaken for
a difference. Without the flag they stay 1, as in every other command, so
existing scripts are unaffected.

The status is set rather than exited on. process.exit discards whatever is
still buffered on a non-TTY stdout, and `olcli diff --exit-code > patch.txt`
is exactly a large patch going into a pipe: exiting outright truncated a
1.5 MB patch to the 128 KB pipe buffer here, losing 91% of it mid-hunk.

The gate covers whatever was compared, so --file narrows it the way a
git diff --exit-code pathspec does, and under --latexdiff it reports on the
project rather than on the markup - a changed figure is a real difference
even though a marked-up root document cannot show one.

Refs #48

Author: Waynting

CHANGELOG.md

@@ -17,6 +17,12 @@ All notable changes to this project will be documented in this file.
   - Placed next to the root document rather than at the project root, so relative `\includegraphics` and `\bibliography` paths resolve exactly as they do for the document it was built from
   - A compile failure writes the CLSI log next to the marked-up source instead of reporting only a status, and deletes a PDF left by an earlier run rather than leaving one that describes a different revision. The compile runs against the project, so a `.sty` or `.cls` that exists only locally is the usual cause and the message says so. A missing *figure* is not: Overleaf draws a placeholder box naming the file and still reports success
 - **`src/latexdiff.ts`** - root document detection, argument construction, output naming and failure interpretation are functions over data, unit-tested with no Overleaf account and no `latexdiff` binary. 21 tests, in the suite CI already runs
+- **`olcli diff --exit-code` makes the command a CI gate** ([#48](https://github.com/aloth/olcli/pull/48)) - the second follow-up left open when the core `diff` command shipped in 0.10.0. It reports `diff(1)`'s statuses: `0` when nothing differs, `1` when something does, `2` when the run itself failed
+  - The `1` vs `2` split is the whole feature. A pipeline that cannot separate "the project differs" from "the run failed" reads an expired session cookie as a content change, and a job that goes red for the wrong reason sends whoever reads the log looking for a diff that was never computed. All ten failure paths in the command move to `2` together - bad flag combinations, a missing directory, an unresolvable project, a `latexdiff` that is not installed, a failed remote compile - so no failure can be mistaken for a difference
+  - Failures stay `1` when the flag is absent, which is what every other command exits, so scripts that check `olcli diff` for success are unaffected
+  - The status is *set* rather than exited on. `process.exit` discards whatever is still buffered on a non-TTY stdout, and `olcli diff --exit-code > patch.txt` is exactly a large patch going into a pipe: measured here, exiting outright truncated a 1.5 MB patch to the 128 KB pipe buffer and lost 91% of it mid-hunk. Returning lets node flush first
+  - The gate covers whatever was compared, so `--file` narrows it to one file the way a `git diff --exit-code` pathspec does, and a `--file` matching nothing is `0` rather than an error. Under `--latexdiff` it reports on the project rather than on the markup - a changed figure is a real difference even though a marked-up root document cannot show one
+  - Exit statuses and the "unchanged files are not differences" rule are pinned by unit tests in `test/diff.test.ts`; `test/e2e.sh` gains eight cases covering the clean tree, a difference, `--file` narrowing, the redirected-output case and both failure statuses
 
 ## [0.12.0] - 2026-09-06
 

README.md

@@ -218,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
@@ -281,6 +282,40 @@ 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:

SKILL.md

@@ -157,12 +157,19 @@ olcli sync --no-delete  # Sync without propagating local deletions to remote
 olcli diff                 # unified diff of every changed file
 olcli diff --name-only     # changed paths only
 olcli diff --file main.tex # a single file
+olcli diff --exit-code     # CI gate: 0 same, 1 differs, 2 failed
 ```
 
 The remote side is fetched fresh each run, so this shows what a subsequent
 `push` would overwrite — not a comparison against the last `pull`. `a/` is the
 remote, `b/` is local. Binary files are reported as differing without a patch.
 
+`--exit-code` uses `diff(1)`'s statuses so the command can gate a pipeline:
+`0` nothing differs, `1` something does, `2` the run itself failed. The last
+one matters — without it a job cannot tell a changed file from an expired
+session. Failures stay `1` when the flag is absent, so existing scripts are
+unaffected.
+
 ### Delete or rename remote files
 
 ```bash
@@ -304,6 +311,7 @@ zip arxiv.zip *.tex main.bbl figures/*.pdf
 - **Auto-detect project**: Run commands from a synced directory (contains `.olcli.json`) to skip the project argument
 - **Dry run**: Use `olcli push --dry-run` or `olcli sync --dry-run` to preview before applying
 - **Preview content**: `push --dry-run` lists files by modification time; `olcli diff` compares actual contents, so the two lists can differ
+- **CI gate**: `olcli diff --exit-code` exits 1 when anything differs and 2 when the run failed, so a pipeline can distinguish drift from breakage
 - **Force overwrite**: Use `olcli pull --force` to overwrite local changes
 - **Two-way deletes**: `olcli sync` propagates *local* deletions to the remote; use `--no-delete` to opt out per run
 - **Build artifacts**: `.aux`, `.bbl`, `.log`, `.synctex.gz` etc. are filtered by default. Add custom patterns to a `.olignore` file (gitignore-style)

src/cli.ts

@@ -17,7 +17,15 @@ import { OverleafClient } from './client.js';
 import { resolveRemotePath, resolveWithin, normalizeRemotePath } from './paths.js';
 import { planProjectRenames } from './rename-plan.js';
 import { scanLocalFiles } from './scan.js';
-import { compareTrees, filterRemoteTree, renderFileDiff, statusLetter, type FileDiff } from './diff.js';
+import {
+  compareTrees,
+  DIFF_EXIT_FAILURE,
+  differencesExitCode,
+  filterRemoteTree,
+  renderFileDiff,
+  statusLetter,
+  type FileDiff,
+} from './diff.js';
 import {
   DIFF_OUTPUT_DIR,
   LatexdiffError,
@@ -1800,6 +1808,7 @@ program
   .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('--exit-code', 'Exit 1 if anything differs, 0 if nothing does, 2 on failure (for CI)')
   .option('--latexdiff', 'Mark the revision up inside the document with latexdiff (requires latexdiff on PATH)')
   .option('--pdf', 'Compile the marked-up document on Overleaf and download the PDF (implies --latexdiff)')
   .option('--main <path>', 'Root .tex document to mark up (default: the only file declaring \\documentclass)')
@@ -1821,13 +1830,26 @@ reason.
 inside the document instead: struck through is what a push would overwrite,
 underlined is what it would upload. --pdf additionally uploads the marked-up
 document to the project for one compile, downloads the PDF, and removes it
-again - so a reviewable PDF needs no local TeX installation.`)
+again - so a reviewable PDF needs no local TeX installation.
+
+--exit-code makes the command a CI gate, with diff(1)'s statuses: 0 when
+nothing differs, 1 when something does, and 2 when the run itself failed. The
+last one matters - without it a pipeline cannot tell a changed file from an
+expired session cookie. It applies to whatever was compared, so --file narrows
+the gate to one file, and it reports on the project even under --latexdiff,
+where the markup only covers the root document.`)
   .action(async (project, dir, options) => {
     const targetDir = dir || '.';
 
+    // Every way this command can fail, as opposed to finding differences.
+    // Under --exit-code that has to be distinguishable from status 1, or a
+    // pipeline reads "could not reach Overleaf" as "the paper changed"; with
+    // the flag absent it stays 1, which is what every other command exits.
+    const failureCode = options.exitCode ? DIFF_EXIT_FAILURE : 1;
+
     if (!existsSync(targetDir)) {
       console.error(chalk.red(`Directory not found: ${targetDir}`));
-      process.exit(1);
+      process.exit(failureCode);
     }
 
     // Checked before connecting: an unusable combination of flags should not
@@ -1842,7 +1864,7 @@ again - so a reviewable PDF needs no local TeX installation.`)
     if (latexdiffMode && conflicting.length > 0) {
       console.error(chalk.red(`--latexdiff cannot be combined with ${conflicting.join(', ')}`));
       console.error('It marks up one root document; those options select and shape unified patch output.');
-      process.exit(1);
+      process.exit(failureCode);
     }
 
     if (!latexdiffMode) {
@@ -1855,7 +1877,7 @@ again - so a reviewable PDF needs no local TeX installation.`)
       ].filter(Boolean);
       if (latexdiffOnly.length > 0) {
         console.error(chalk.red(`${latexdiffOnly.join(', ')} only applies with --latexdiff`));
-        process.exit(1);
+        process.exit(failureCode);
       }
     }
 
@@ -1869,7 +1891,7 @@ again - so a reviewable PDF needs no local TeX installation.`)
       } catch (error: any) {
         spinner.fail(error.message);
         console.error('Either run from a directory with .olcli.json or pass a project name/ID');
-        process.exit(1);
+        process.exit(failureCode);
       }
       const { id: projectId, name: projectName } = resolved;
 
@@ -1916,10 +1938,15 @@ again - so a reviewable PDF needs no local TeX installation.`)
           remoteFiles,
           entries,
           fetchedAt,
+          failureCode,
           options,
           spinner,
         });
         setLastProject(projectId);
+        // Reports on the comparison, not on the markup: a changed figure is a
+        // difference in the project even though a marked-up root document
+        // cannot show it. The `No .tex file differs` line above says as much.
+        if (options.exitCode) process.exitCode = differencesExitCode(entries);
         return;
       }
 
@@ -1984,9 +2011,14 @@ again - so a reviewable PDF needs no local TeX installation.`)
       console.log(chalk.dim(`  a/ = remote as of ${fetchedAt.toISOString()}, b/ = local`));
 
       setLastProject(projectId);
+      // Set rather than exited: `process.exit` drops whatever is still
+      // buffered on a non-TTY stdout, and `olcli diff --exit-code > patch.txt`
+      // is precisely a large patch going into a pipe. Returning lets node
+      // flush and then exit with this status on its own.
+      if (options.exitCode) process.exitCode = differencesExitCode(entries);
     } catch (error: any) {
       spinner.fail(`Failed: ${error.message}`);
-      process.exit(1);
+      process.exit(failureCode);
     }
   });
 
@@ -2010,6 +2042,8 @@ async function runLatexdiffMode(params: {
   remoteFiles: Map<string, Buffer>;
   entries: FileDiff[];
   fetchedAt: Date;
+  /** What to exit with when this mode fails; 2 under --exit-code, else 1. */
+  failureCode: number;
   /** Only the flags this mode reads; the rest of `diff`'s options are rejected. */
   options: {
     main?: string;
@@ -2022,7 +2056,7 @@ async function runLatexdiffMode(params: {
 }): Promise<void> {
   const {
     client, projectId, projectName, targetDir,
-    localFiles, remoteFiles, entries, fetchedAt, options, spinner,
+    localFiles, remoteFiles, entries, fetchedAt, failureCode, options, spinner,
   } = params;
 
   let root = '';
@@ -2035,7 +2069,7 @@ async function runLatexdiffMode(params: {
     for (const candidate of error.candidates) {
       console.error(chalk.dim(`    ${candidate}`));
     }
-    process.exit(1);
+    process.exit(failureCode);
   }
 
   // latexdiff needs two versions of the same document. A root document that
@@ -2045,7 +2079,7 @@ async function runLatexdiffMode(params: {
     spinner.stop();
     console.error(chalk.red(`${root} is not in "${projectName}" yet, so there is no earlier version to mark up.`));
     console.error(chalk.dim('  Push it first, or use --main to name a document that exists on both sides.'));
-    process.exit(1);
+    process.exit(failureCode);
   }
 
   if (!entries.some((e) => isTexPath(e.path))) {
@@ -2080,7 +2114,7 @@ async function runLatexdiffMode(params: {
         console.error(error.stderr);
       }
       cleanupTmp();
-      process.exit(1);
+      process.exit(failureCode);
     }
 
     // An explicit --output is a path the user chose, so it is taken relative to
@@ -2100,7 +2134,7 @@ async function runLatexdiffMode(params: {
     }
 
     if (options.pdf) {
-      await compileMarkupOnOverleaf({ client, projectId, projectName, root, markup, texPath, pdfPath, spinner });
+      await compileMarkupOnOverleaf({ client, projectId, projectName, root, markup, texPath, pdfPath, failureCode, spinner });
     }
 
     console.log();
@@ -2146,9 +2180,11 @@ async function compileMarkupOnOverleaf(params: {
   markup: string;
   texPath: string;
   pdfPath: string;
+  /** What to exit with when the compile fails; 2 under --exit-code, else 1. */
+  failureCode: number;
   spinner: ReturnType<typeof ora>;
 }): Promise<void> {
-  const { client, projectId, projectName, root, markup, texPath, pdfPath, spinner } = params;
+  const { client, projectId, projectName, root, markup, texPath, pdfPath, failureCode, spinner } = params;
   const scratch = remoteScratchPath(root);
 
   spinner.start(`Checking ${scratch} is free...`);
@@ -2157,7 +2193,7 @@ async function compileMarkupOnOverleaf(params: {
     console.error(chalk.dim('  --pdf uploads the marked-up document under that name for one compile and'));
     console.error(chalk.dim('  removes it again; it will not overwrite a file that is already there.'));
     console.error(chalk.dim(`  The marked-up source was still written: ${texPath}`));
-    process.exit(1);
+    process.exit(failureCode);
   }
 
   spinner.stop();
@@ -2226,7 +2262,7 @@ async function compileMarkupOnOverleaf(params: {
   if (failure) {
     spinner.fail(failure[0]);
     for (const line of failure.slice(1)) console.error(chalk.dim(line));
-    process.exit(1);
+    process.exit(failureCode);
   }
 }
 

src/diff.ts

@@ -217,3 +217,39 @@ export function statusLetter(status: FileStatus): string {
     case 'unchanged': return ' ';
   }
 }
+
+/**
+ * Exit statuses for `diff --exit-code`, following diff(1) rather than the
+ * plain success/failure every other olcli command reports.
+ *
+ * The 1-vs-2 split is the entire point of the flag. A gate that cannot
+ * separate "the project differs" from "the run failed" reads an expired
+ * cookie or a typo'd flag as a content change, and a pipeline that fails for
+ * the wrong reason is worse than one that does not fail at all - it sends
+ * whoever reads the log looking for a diff that was never computed.
+ *
+ * Only `--exit-code` moves failures to 2. Without it every failure stays 1,
+ * so existing scripts that check `olcli diff` for success keep working.
+ */
+export const DIFF_EXIT_CLEAN = 0;
+export const DIFF_EXIT_DIFFERENCES = 1;
+export const DIFF_EXIT_FAILURE = 2;
+
+/**
+ * The status `diff --exit-code` should finish with, given the comparison it
+ * just rendered.
+ *
+ * Takes the entries rather than a count so an unfiltered `compareTrees`
+ * result answers the same as the filtered list the command prints from: a
+ * gate that fired because every *unchanged* file was counted would report a
+ * difference on every run and be switched off within a day.
+ *
+ * The entries passed in are whatever was reported, so `--file main.tex`
+ * narrows the question to that file, the same way `git diff --exit-code`
+ * narrows to its pathspec.
+ */
+export function differencesExitCode(entries: FileDiff[]): number {
+  return entries.some((e) => e.status !== 'unchanged')
+    ? DIFF_EXIT_DIFFERENCES
+    : DIFF_EXIT_CLEAN;
+}

test/diff.test.ts

@@ -2,6 +2,10 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   compareTrees,
+  DIFF_EXIT_CLEAN,
+  DIFF_EXIT_DIFFERENCES,
+  DIFF_EXIT_FAILURE,
+  differencesExitCode,
   filterRemoteTree,
   renderFileDiff,
   isBinary,
@@ -217,3 +221,46 @@ test('renderFileDiff: a non-numeric context falls back to the default', () => {
   assert.equal(bad, good);
   assert.match(bad, /^\+line TEN$/m);
 });
+
+// ─── --exit-code ──────────────────────────────────────────────────────────────
+
+const entry = (status: 'added' | 'deleted' | 'modified' | 'unchanged') =>
+  ({ path: `${status}.tex`, status, binary: false });
+
+test('differencesExitCode: nothing to report is a clean gate', () => {
+  assert.equal(differencesExitCode([]), DIFF_EXIT_CLEAN);
+});
+
+test('differencesExitCode: unchanged files are not differences', () => {
+  // The command filters these out before printing, but the gate is fed
+  // whatever it is given: counting entries instead of inspecting their status
+  // would fire on every run of a project that matches its remote exactly.
+  const local = new Map([['a.tex', buf('same\n')], ['b.tex', buf('same\n')]]);
+  const unfiltered = compareTrees(local, new Map(local));
+
+  assert.equal(unfiltered.length, 2);
+  assert.equal(differencesExitCode(unfiltered), DIFF_EXIT_CLEAN);
+});
+
+test('differencesExitCode: every non-unchanged status is a difference', () => {
+  // A remote-only file included on purpose: plain `push` leaves it alone, but
+  // the two sides still do not match, and a gate that passed would be saying
+  // they do.
+  for (const status of ['added', 'deleted', 'modified'] as const) {
+    assert.equal(differencesExitCode([entry(status)]), DIFF_EXIT_DIFFERENCES, status);
+  }
+});
+
+test('differencesExitCode: one difference among unchanged files still fires', () => {
+  const entries = [entry('unchanged'), entry('modified'), entry('unchanged')];
+  assert.equal(differencesExitCode(entries), DIFF_EXIT_DIFFERENCES);
+});
+
+test('exit statuses follow diff(1), and failure is distinguishable', () => {
+  // The whole point of the flag: a CI job has to be able to tell a changed
+  // file from a run that never got as far as comparing anything.
+  assert.equal(DIFF_EXIT_CLEAN, 0);
+  assert.equal(DIFF_EXIT_DIFFERENCES, 1);
+  assert.equal(DIFF_EXIT_FAILURE, 2);
+  assert.notEqual(DIFF_EXIT_FAILURE, DIFF_EXIT_DIFFERENCES);
+});