Merge pull request #57 from Waynting/feat/diff-exit-code

CI gate from #48: olcli diff --exit-code reports diff(1)'s statuses, 0 when nothing differs, 1 when something does, 2 when the run itself failed.

Author: @Waynting. Stacked on #56, so only 86b078b is new here.

Verified before merging: npm ci, lint and build clean, 84 tests passing.

The 1 versus 2 split is the feature. All ten failure paths move to 2 together, so a pipeline cannot read an expired session cookie as a content change. Without the flag every failure stays 1, which is what every other command exits, so existing scripts are unaffected.

Author: aloth

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);
+});