GeezerVison

Summary

The bug

deepnote sync --all-files silently overwrote local edits to working files when it pulled.

• syncProjectFiles (packages/cloud-sync/src/sync-workspace.ts) downloads every working file whose Deepnote size or updatedAt moved since the last sync, for a project whose notebooks were pulled or are unchanged.
• It wrote the download over the local copy without checking it. So an edit to a file that also changed in Deepnote was lost.
• A local file that had never been synced was lost the same way, when Deepnote had a file at that path.
• Only the upload direction had a conflict (working-files-changed), although the module doc said allFiles "applies the same conflict policy to working-directory files".

It came up in deepnote/vscode-deepnote#609. The extension's "Sync First" runs this sync after a PublishDivergedError. That destroyed unpublished edits in <project>/.files/_deepnote_static, and the edits were nowhere else, not even in Deepnote. Reproduced against @deepnote/cloud-mock.

The fix

syncProjectFiles now plans every file before it downloads anything. A local copy is a conflict when both of these hold:

• It is not provably unedited. One of these is true:
  • It has no manifest record. Reason: exists locally but was never synced.
  • Its record has no hash. Reason: may have been edited locally; synced before local edits were tracked.
  • Its size or sha256 differs from the record. Reason: edited locally.
• It also differs from Deepnote's current copy.
  • A size different from the inventory proves this without a download.
  • At equal size, sync downloads the file once and compares sha256.

When the local copy already matches Deepnote's, it becomes the new baseline. This is the state an interrupted pull or push, or a deleted manifest, leaves behind. There is no write, no download count and no prompt; otherwise skip would keep the stale record forever.

The project's conflicted files go to the conflict policy as one new conflict, local-working-files-changed, shaped like working-files-changed:

• override replaces the local copies with the Deepnote versions.
• skip keeps the local copies and their old records. The next sync asks again, and prune does not delete them. A warning names the files, and the outcome's new localFilesKept field counts them.
• filesSkipped keeps its upload-only meaning.

CLI and docs

The CLI asks:

Local working files of "<project>" differ from their Deepnote versions: <path> (<reason>), …. Replace your local copies with the Deepnote versions?

The override label is Replace the local copies with the Deepnote versions (discards local changes). The summary prints N local file(s) kept.

The skip choice now reads Skip for now for every conflict, instead of Skip this project for now. Skipping a working-file conflict, in either direction, keeps only the listed files while the rest of the project syncs.

These are updated to match:

• docs/deepnote-cli-sync.md, including the static-site ownership section;
• the CLI README;
• the skill reference;
• the module, allFiles and manifest hash JSDoc.

The upload-side "Kept the Deepnote copy" hint no longer says that a pull replaces local copies.

Behavior changes

• Pulls ask now. A pull with --all-files that used to replace an edited local working file now asks. The CLI's default is ask on a TTY and skip without one.
• The transfer limit is checked earlier. The per-file 100 MiB check now runs while planning, before any file of the project is downloaded.
• TypeScript consumers stop compiling, on purpose. A new SyncConflict member breaks exhaustive switches over conflict.kind. The VS Code extension's askConflict will need a case when it upgrades. At runtime its default branch skips, which is safe.

Cost

• A same-size real conflict costs one extra download to decide, and a second one on override. Downloaded bytes are hashed and dropped, never held across the prompt.
• A different-size conflict needs no download.
• The local file is read only when its size equals a recorded or inventory size, so the read stays under the buffered transfer limit.

Not covered

• --prune deleting a local copy that was edited after Deepnote deleted the file.
• publishApp writing into the mirror. fix(cloud-sync): refuse a publish directory that overlaps the app mirror #603 refuses a publish directory that overlaps it. The other half is still open: a non-overlapping publish replacing a mirror file that was edited locally.
• A dry run of a renamed or moved project. It looks for working files at the new path, so it can miss a conflict the real run raises.
• Files judged unedited are not checked again right before they are written. So an edit made while another project's prompt is open can still be replaced.

Tests

packages/cloud-sync/src/sync-workspace.cloud-mock.test.ts has a new describe, "working files edited locally and changed in Deepnote":

• Same-size local edit:
  • asks once and keeps the copy on skip, with its record unchanged and localFilesKept: 1, then asks again on the next sync;
  • replaces the copy and records the new hash on override, with no warning;
  • in a dry run, skips without asking and writes nothing;
  • keeps the skipped copy on a sync with prune.
• A never-synced local file asks, whether its size differs from Deepnote's copy or is the same with different content.
• A record without a hash asks, even when the copy is unedited.
• A local copy that already matches Deepnote's becomes the baseline without asking or writing. The test checks the record and that the mtime is unchanged.
• Unchanged local files are adopted without asking after the manifest is deleted.
• Each edited-copy scenario also checks that an unedited file that changed in Deepnote downloads without a conflict.

Changed tests:

• packages/cloud-sync/src/sync-workspace.test.ts, "lets a kept re-created conflict fall back to ordinary sync instead of sticking": its last run still uses skip. It now also asserts that the file, which already matches Deepnote, gets the new baseline with no conflict.
• packages/cli/src/commands/sync.test.ts: a row for the new question, and a test that counts localFilesKept apart from filesSkipped.

Verification

• Seen failing first: every new test and changed assertion that targets the fix fails against main's syncProjectFiles and passes with this change. Three assertions guard the new code itself: same-size never-synced, mtime unchanged, and no localFilesKept after override. Each was seen to fail on a targeted mutation of the new code.
• Mutation checks: ignoring the hash comparison fails a test, and so does inverting the size check.
• Full suite: pnpm vitest run --bail 0: 3877 passed, 3 failed. The 3 failures are in packages/cli/src/commands/run.test.ts, the same 3 that fail on a clean main in this sandbox. A later wording change to the CLI question and the hash-less reason was checked with the cloud-sync and CLI sync suites only: 305 passed.
• Static checks:
  • pnpm typecheck passes.
  • pnpm biome:check reports only the 8 warnings main already has.
  • pnpm prettier:check and cspell on the changed files are clean.
• Not run:
  • the CLI against a real Deepnote workspace;
  • Windows.

Summary by CodeRabbit

• New Features
  • Sync checks for locally edited or untracked files before replacing them with Deepnote versions. Choose to keep local copies or overwrite them; kept files are reported separately.
  • Matching local files are recorded as synced without a conflict prompt.
  • Static-site file conflicts are surfaced when changes occur on either side.
  • A pending replacement whose cloud file reappears is treated as a conflict; keeping the cloud copy ends the retry, and a later pull handles the download.
• Documentation
  • Updated sync guidance to explain pull-side conflicts, available choices, and how skipped files are handled on the next sync.