Distillation

Date: Sep 9, 2026

• 🔴 (09:33) User specified that the caller receives the successful upgrade-source probe response so it never repeats the request; only HTTP 404 advances to the next source, while every other HTTP or network failure aborts immediately.
• 🔴 (09:34) User specified that the in-memory patch chain never creates scratch files on disk.
• 🟡 (09:32) downloadBinaryToTemp(version, downloadTag?, offline?, setMessage?) in packages/cli/src/lib/upgrade.ts:902-973 acquires the curl-install lock, removes any interrupted-download temp file, tries tryDeltaUpgrade() first, throws UpgradeError("offline_cache_miss", ...) when offline with no cached delta, otherwise calls downloadFullBinary(), verifies the resulting non-empty file via waitForBinaryVisible(), clears the consumed patch cache best-effort, applies mode 0o755 outside Windows, and returns { tempBinaryPath, lockPath, patchBytes }; errors release the lock before rethrowing.
• 🟡 (09:32) waitForBinaryVisible() in packages/cli/src/lib/upgrade.ts:851-874 polls probeBinaryFile(path) for up to VERIFY_MAX_ATTEMPTS, using exponential delays VERIFY_BASE_DELAY_MS * 2 ** (attempt - 1); this addresses a Windows + Bun 1.3.9 filesystem-visibility race (CLI-1D3) where Bun.file(path).writer() may finish before Bun.spawn can see ...sentry.exe.download.
• 🟡 (09:32) tryDeltaUpgrade() in packages/cli/src/lib/upgrade.ts:985-998 delegates to attemptDeltaUpgrade(version, process.execPath, destPath, offline, setMessage), using the currently running executable as the patch base.
• 🟡 (09:32) downloadFullBinary() in packages/cli/src/lib/upgrade.ts:1007-1018 routes nightly versions to downloadNightlyToPath(destPath, version, setMessage) and stable versions to downloadStableToPath(downloadTag ?? version, destPath, setMessage).
• 🟡 (09:32) Successful downloadBinaryToTemp() calls retain the parent lock across the download→spawn→install pipeline; the caller must release it after the child exits. If the child resolves to the same install path, acquireLock recognizes process.ppid, takes over the lock, and makes the parent’s later release a harmless no-op.
• 🟡 (09:32) executeUpgradeHomebrew() runs brew upgrade getsentry/tools/sentry; Homebrew controls the formula version and cannot pin an arbitrary requested release. Nonzero exit produces UpgradeError("execution_failed", "brew upgrade failed with exit code ..."), and spawn errors produce UpgradeError("execution_failed", "brew failed: ...").
• 🟡 (09:32) executeUpgradePackageManager(pm, version) uses ["global", "add", \sentry@${version}`]for Yarn and["install", "-g", `sentry@${version}`]for npm/pnpm;shellis enabled on Windows because these package managers are.cmdfiles that otherwise fail withENOENT`.
• 🟡 (09:33) Git status showed branch feat/toolkit-bridge-upgrade behind origin/main by 2 commits, with 4 modified files: packages/cli/src/lib/binary.ts, packages/cli/test/lib/binary.test.ts, packages/cli/test/lib/ghcr.test.ts, and packages/cli/test/lib/install-script.test.ts; diff size was 232 insertions and 5 deletions.
• 🟡 (09:33) packages/cli/test/lib/delta-upgrade.test.ts totals 1,846 lines and imports/tests applyPatchChain, attemptDeltaUpgrade, canAttemptDelta, downloadStablePatch, extractSha256, extractStableChain, fetchRecentReleases, filterAndSortChainTags, getPatchFromVersion, getPatchTargetSha256, getStableTargetSha256, prefetchNightlyPatches, prefetchStablePatches, resolveNightlyChain, resolveNightlyDelta, resolveStableChain, resolveStableDelta, and validateChainStep.
• 🟡 (09:33) resolveStableChain tests cover: a single hop from 0.13.0 to 0.14.0; a parallel-download two-hop chain applied oldest-first (0.13.0→0.14.0→0.15.0); target absent; releases API HTTP 500; failed patch download; and a 14-hop chain across 15 releases rejected because it exceeds MAX_STABLE_CHAIN_DEPTH of 10.
• 🟡 (09:34) validateChainStep tests use a 100_000 byte size limit and verify exact failure variants: version-mismatch with expected/actual versions, missing-layer with layerName, and size-exceeded with layerSize: 200_000 and budget: 100_000; a valid 500-byte layer returns { ok: true, digest, size: 500 }.
• 🟡 (09:34) fetchRecentReleases tests expect GitHub release API URLs containing api.github.com/repos/getsentry/cli/releases and per_page=; successful responses preserve releases such as 0.14.0 and 0.13.0, while HTTP 500 and network failures return [].
• 🟡 (09:33) downloadStablePatch tests verify a successful response returns the exact Uint8Array, while HTTP 404 and a TypeError("fetch failed") network failure return null.
• 🟡 (09:34) applyPatchChain tests verify two patches remain in memory without creating intermediateA or intermediateB scratch files, even when the second patch fails verification, and verify a successful one-patch chain creates a readable destination file with SHA-256 derived via createHash("sha256").
• 🟡 (09:34) resolveStableDelta has a test-mode guard because CLI_VERSION is "0.0.0-dev"; resolving target 0.14.0 from /tmp/fake-old to /tmp/fake-out returns null.
• 🟡 (09:34) resolveNightlyDelta tests verify null results for: GHCR token HTTP 401, no patch tags for target 0.14.0-dev.200, and a target manifest lacking the required ${getPlatformBinaryName()}.gz layer used for the size threshold.
• 🟡 (09:34) attemptDeltaUpgrade("0.14.0", "/tmp/fake-old", "/tmp/fake-out") returns null in tests when canAttemptDelta rejects the dev-build context.
• 🟡 (09:34) prefetchNightlyPatches("0.14.0-dev.123") and prefetchStablePatches("0.14.0") return immediately under test CLI_VERSION = "0.0.0-dev"; mocked fetch throws "fetch should not be called" to verify neither function performs network requests.