feat(cloud-sync): move app publishing into @deepnote/cloud-sync - #566

Summary

Closes #564.

deepnote publish ran its whole upload flow inside a commander action: it printed as it went, signalled failure through process.exitCode, and the "Deepnote changed these files since the last sync" check existed only as an error message. This moves the flow into @deepnote/cloud-sync as publishApp(options), which reports per-file progress through onEvent, returns a structured result, and throws PublishError / PublishDivergedError. deepnote publish is now an adapter over it.

CLI behavior is unchanged: no change to flags, output, exit codes or the manifest format.

Changes

• packages/cloud-sync/src/publish-app.ts (new): publishApp, PublishError (reason: invalid-input | unreadable-directory | project-unavailable), PublishDivergedError (syncRoot, sorted paths), and the PublishAppOptions / PublishAppEvent / PublishAppResult types. PublishDivergedError is thrown before any delete or upload request unless force is set. The file helpers (collectFiles, isEnvFile, normalizeTargetPrefix, preparePublishFiles, appUrlWithPath) moved over unchanged.
• packages/cloud-sync/src/publish-mirror.ts and its test: moved with git mv from packages/cli/src/utils/. resolvePublishMirror takes an optional onMirrorSkipped callback in place of the CLI's debug call, and SyncRootOption is now string | false | undefined. Of its symbols, PublishMirrorError and SyncRootOption are exported from index.ts; PublishAppOptions.syncRoot and the CLI's publish options use SyncRootOption.
• packages/cli/src/commands/publish.ts: loads .env, resolves the token, calls publishApp, renders each event with the previous text, and maps errors to the previous exit codes. It no longer imports @deepnote/cloud.
• packages/cloud-sync/README.md: adds a publishApp usage example and rows for publishApp, PublishError, PublishDivergedError and PublishMirrorError to the API reference table. Options, events and result fields are documented on the exported types.
• packages/cloud-sync/src/index.ts: exports publishApp, PublishError, PublishDivergedError, PublishMirrorError and the PublishApp*, PublishErrorReason and SyncRootOption types.

Judgment calls

• index.ts keeps main's export set. After merging feat(cloud-sync): move the workspace sync engine into @deepnote/cloud-sync #568 and feat(cloud-sync): move Streamlit app registration into @deepnote/cloud-sync #573, nothing outside packages/cloud-sync imports sha256, baselineDiverged, assertNoSymbolicLinkAncestors, saveSyncManifest, isSafeRelativeFilePath or projectFilesDir, so issue step 5 would remove them. They stay because the README on main lists them as public helpers.
• PublishMirrorError and SyncRootOption are exported, unlike the rest of publish-mirror.ts (issue step 1). PublishMirrorError never reaches publishApp callers: publishApp rethrows it as PublishError with reason invalid-input.
• Events are emitted outside the per-file try. A throwing onEvent listener would otherwise be recorded as a failed upload. PublishAppOptions.onEvent documents that the listener must not throw.
• PublishOptions.quiet guards are kept in the adapter although Commander never populates it, to keep the diff a pure move.
• Beyond the seven contract tests the issue lists: failed removal and sharing paths, stale-file pruning (including the divergence check over stale paths), syncRoot: false, mirror-skipped, a failed manifest save reported before sharing, apiAccess true/false, and input errors. One extra publish-mirror test covers onMirrorSkipped.

Verification

Run on this branch after merging main (#568, #573):

• pnpm typecheck, pnpm prettier:check exit 0. pnpm biome:check and pnpm spell-check report nothing in any file this PR touches.
• pnpm install --frozen-lockfile accepts the lockfile. package.json, tsdown.config.ts and pnpm-lock.yaml no longer differ from main, which already declares @deepnote/database-integrations as a dependency and a tsdown external.
• pnpm build succeeds; the built @deepnote/cloud-sync exports PublishMirrorError from ESM, CJS and index.d.ts.
• pnpm test: 3569 passed in 189 files. This workspace had a python shim on PATH for the three cli/run.test.ts cases that need it.
• All 44 tests in commands/publish.test.ts pass with the file unchanged; all 18 original mirror tests pass.
• packages/cloud-sync/src (non-test) has no import of commander, chalk, ora, @inquirer/prompts, dotenv or @deepnote/cli, and no process. reference.
• Mutation checks (on 6f33d9e, before the merge, which changes no publish code). I broke publish-app.ts and publish-mirror.ts 22 ways (dropped divergence check, reordered mirror-incomplete before the save, unsorted divergent paths, wrong mirrorUpdated, skipped .env refusal, wrong hash, …); the new tests failed on every one. A first run of the tests passed everything, so this is what shows they can fail.
• Old-vs-new parity (on 6f33d9e). A throwaway harness (not committed) ran origin/main's publish.ts and the new adapter side by side over 47 scenarios (happy path, prune, every failure class, divergence with and without --force, mirror warnings, quiet/debug, bad flags, missing token). Console and stderr output, exit codes, API call order and arguments, and resulting file trees were identical.
• Reviewed by five reviewers (behavior parity, spec compliance, tests, robustness, design), each using /code-review-typescript, with two skeptics per finding. The one blocker (type errors in the new test file, which vitest does not catch) and the README inaccuracies are fixed.

Not verified: a live run against Deepnote Cloud, and Windows path behavior.

Pre-existing behavior, moved unchanged

Noticed during review and deliberately not changed here:

• A file over the 100 MiB buffered upload limit has its live remote copy deleted before the upload is rejected.
• The .env refusal is case-sensitive: .ENV and .envrc are published.
• Symlinked files and directories in the build directory are skipped without an event.
• Pruning a stale project file exactly at the target prefix prints ✓ removed with an empty name.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BYyMrxsMPw3Yu9zmWuusYP

Summary by CodeRabbit

• New Features
  • Added app publishing through the cloud sync package, with progress and result reporting, optional pruning, and sharing and API-access settings.
  • Publishing can update a matching sync mirror. Diverged files are detected unless force overwrite is enabled.
  • Publishing reports errors for invalid builds and failed uploads or removals; an app URL is provided when sharing succeeds.
• Documentation
  • Added publishing guidance, an example workflow, and descriptions of publishing-related errors.