feat(diff): content-level diff between local files and the remote project

[Waynting]

Draft PR for the core olcli diff command from #45, split as you asked — no latexdiff, no --pdf, nothing that shells out or touches the compiler.

The design question you raised: what is "remote"?

diff fetches the remote fresh on every run, and says so. The reasoning turned out to be settled by the data model rather than by preference:

.olcli.json records remote paths (remoteManifest, pushManifest), never remote contents. So "compare against the last pulled state" was not the cheap-and-stable option it looked like in my proposal — there is no snapshot stored to compare against. It would have meant designing and maintaining a content cache, which is a much larger change than the command itself.

Fetching fresh is also the semantics that makes the command honest: a diff that does not describe what the push will overwrite is worse than no diff, as you put it.

I should also correct my own sketch in the issue. I wrote that it would "only fetch remote content for files that differ" — that is not possible, since you cannot know which files differ without fetching them. It is also unnecessary: downloadProject returns the entire project as a single archive, the same call pull and sync already make. Fetching fresh costs one request, not one per file.

The limit is stated rather than hidden: a collaborator editing between diff and push can still change the outcome, so every run prints the fetch time.

  a/ = remote as of 2026-09-03T08:41:50.013Z, b/ = local

--name-only vs push --dry-run

They answer different questions and should keep disagreeing:

• push --dry-run lists files whose modification time is newer than the last pull, because that is what push actually uploads.
• diff --name-only lists files whose contents differ.

A file you touched without editing appears in the first and not the second. Merging the behaviour would make one of them lie. Verified on a real project — push --dry-run listed 3 mtime-selected files while diff reported 4 differing ones, including a remote-only file push would not have touched at all.

What they genuinely do share is the local walk-and-filter loop. That existed twice already, once in push and once in sync, and the two copies had drifted (sync guarded against a missing directory, push did not). diff would have made three, so it moves to src/scan.ts and all three call it. Same reasoning as rename-plan.ts in 0.9.0.

For the discoverability side of the overlap, push --dry-run now says what it measures:

  selected by modification time — run `olcli diff` to see content changes

What the command does

olcli diff                 # unified diff of every changed file
olcli diff --name-only     # changed paths, with A/M/D prefixes
olcli diff --file main.tex # a single file
olcli diff -U 8            # context width

a/ is the remote and b/ is local, so + is content push would upload and - is content it would overwrite. Reading it the other way round would invert the meaning of every hunk, so the orientation is pinned by a test.

Binary handling is exactly what you asked for — reported, never guessed at:

diff --olcli a/figures/plot.pdf b/figures/plot.pdf
Binary files a/figures/plot.pdf and b/figures/plot.pdf differ

Detection is a NUL byte in the first 8000 bytes, git's heuristic. No per-extension sniffing.

Two things worth flagging because they are decisions, not details:

• Both sides pass through the same ignore layers and the same dotfile rule. Filtering only the local side would have reported output.pdf and every stray .aux sitting on Overleaf as a local deletion on every single run. A freshly pulled directory now diffs to "No differences", which is the check that this filtering actually agrees.
• Remote-only files are reported but labelled as untouched by a plain push, since only push --delete removes them. Calling them "deleted" without that line would misdescribe what would happen.

Archive entries whose names escape the target directory are dropped, consistent with what pull refuses to extract (#44). diff writes nothing, but an entry pull will not extract is not part of the project as far as that directory is concerned, and showing it would suggest a difference no push could resolve.

Dependency

diff@^9.0.0. npm view diff dependencies is empty — no transitive tree.

Structure and tests

Comparison, rendering and remote-tree filtering are pure functions in src/diff.ts, so they are unit-tested with no Overleaf account and no network: 34 tests across test/diff.test.ts and test/scan.test.ts under the existing npm test. Following the rename-plan.ts precedent, none of it is re-exported from the package root — happy to export it if you would rather it were public.

test/e2e.sh gains a Diff section between the pull and push tests: clean tree diffs to nothing, a modification shows as M with the right hunk, a local-only file shows as A, build artifacts are ignored on both sides, and the tree is restored and re-verified clean so the push tests below are unaffected.

Also exercised by hand against a real 26-file project: clean pull → no differences; then an edited .tex, a new file, a deleted figure and a corrupted PDF → all four statuses correct, with push --dry-run and sync --dry-run still behaving as before the scan.ts extraction.

Follow-ups, not in this PR

• --latexdiff / --pdf, as agreed
• --exit-code, if you want olcli diff usable as a CI gate

Refs #45

[aloth]

Thanks for the quick turnaround on this. I pushed a merge of main into your branch rather than asking you to rebase, because the conflicts were mine to clean up: three commits landed on main after you opened this PR, and two of them touched exactly the lines you were working in.

What landed on main in the meantime:

• Dead code removal, which took out the DEFAULT_IGNORE_PATTERNS, IgnoreContext and getLastProject imports in cli.ts
• Pull request CI and a working npm run lint, neither of which the repository had before
• engines corrected to >=20.18.1

How the three conflicts were resolved:

src/cli.ts. Both sides of this one were unused imports. Your branch imports DEFAULT_IGNORE_PATTERNS, IgnoreContext and getLastProject but references none of them outside the import statement, and main had removed them for that reason. main in turn still imported shouldIgnore and buildTexSiblingSet, which your scanLocalFiles replaced. Resolved against what the merged file actually uses: loadIgnore, four references, and nothing else from ignore.js.

CHANGELOG.md. Both sections kept as they are. Your [Unreleased] entry and the [0.9.2] entry from main describe different work, and consolidating them into a single release entry is a separate step.

package-lock.json. Regenerated rather than resolved by hand.

Two notes, neither affecting this PR:

The CI is new, and this PR is the first thing to run through it. Both legs pass, Node 20.18.1 and 24.

The engines change came out of that CI on its first run. cheerio@1.2.0 pulls undici@7.x, which references File as a global, and Node only exposes that from 20 onwards, so olcli did not start at all on Node 18 while the manifest claimed >=18. Unrelated to your change, but it is why the floor moved.

Beyond the 34 unit tests, the full e2e suite ran against a real Overleaf project: 79 of 79, including the Diff section you added.

Merging this now and shipping it as part of 0.10.0.