Dashboard › cli › Distillation
7fa232e8-8b65-4c97-81c4-c8786dfa4526["lore_tm_v1_mx6vdLkhuXLXJA_Drxp0Kptmu8RqrcEY88nIL1N1WKc","lore_tm_v1_aUS0x-NPnnwBcrIoUgnFReUIada5qaat4xvpR7adYBw","lore_tm_v1_K0l6nJEXb6fryqfGdT6OIUIebn4K0vErGP8_xP7jMPg","lore_tm_v1_Pi2n4ljeUeB3uIQMNcFGWzcKk_QAL9oRqJg4rOe8PPY","lore_tm_v1_xqOdCPbS4ATBUOpe4CGGR-0D684N4SdD4MQF-Nt-4uc","lore_tm_v1_DBnx89LKAmOpab8XtDjuJ8bnLnPLIx0PbKe6iADELuU","lore_tm_v1_qcFL-Y_GEYC-CA81pv27rihjDqBmKoeCKzRf1K0E7ac"]
packages/cli/src/lib/delta-upgrade.ts is a 615-line binpatch-backed delta-upgrade implementation. It imports applyPatchChainInMemory, chain-discovery/validation helpers, MAX_NIGHTLY_CHAIN_DEPTH, PATCH_TAG_PREFIX, SIZE_THRESHOLD_RATIO, makeCache, OciClient, ghcrSource, githubReleaseSource, and resolveAndApply from "binpatch", while preserving its existing public API through type/function re-exports.DeltaResult contains exact fields sha256: string, patchBytes: number, and chainLength: number.GHCR_REPO import from packages/cli/src/lib/ghcr.ts rather than a duplicated string literal; this establishes a single source of truth and fixes/prevents the silent 404 previously caused by the literal.makeCache(join(getConfigDir(), "patch-cache")), wrapped by instrumentCache(). Cache tracing keys use patch-chain:${fromVersion}-${toVersion}; load spans use operation "cache.get" with cache.key, cache.hit, and conditional cache.item_size, while save spans use "cache.put" with summed patch bytes as cache.item_size.stableSource() uses githubReleaseSource() with releasesUrl: GITHUB_RELEASES_URL, binaryName: getPlatformBinaryName(), userAgent: sentry-cli/${CLI_VERSION}, fetch: customFetch, and HTTP tracing through instrument; nightlySource() uses ghcrSource() with registry "https://ghcr.io", repo: GHCR_REPO, target tags nightly-${version}, compareVersions, the same binary name/user agent/fetch/instrument setup.canAttemptDelta(targetVersion) rejects delta upgrades when CLI_VERSION === "0.0.0-dev", when current and target versions belong to different stable/nightly channels, or when the target is a downgrade.fetchRecentReleases(signal?) requests ${GITHUB_RELEASES_URL}?per_page=12 with GitHub API Accept header, User-Agent: sentry-cli/${CLI_VERSION}, and optional abort signal. It returns [] for non-OK responses, non-array JSON, or exceptions, logging malformed payloads and fetch failures through the "delta-upgrade" logger.downloadStablePatch(url, signal?) downloads through customFetch, supplies User-Agent: sentry-cli/${CLI_VERSION}, returns response bytes as Uint8Array only for an OK response, and returns null on non-OK responses or exceptions.extractStableChain(opts) converts binpatch failure results to null; filterAndSortChainTags(allTags, currentVersion, targetVersion) delegates to binpatch with local compareVersions; resolveStableChain() delegates to stableSource().resolveChain().validateChainStep(manifest, opts) intentionally preserves 3 rich failure classifications—"version-mismatch" with expected/actual versions, "missing-layer" with layerName, and "size-exceeded" with layerSize/budget—instead of binpatch’s coarser "malformed" / "over_budget" reasons.resolveNightlyChain() gets GHCR tags from optional preloadedTags or OciClient.listTags(token, PATCH_TAG_PREFIX, signal), filters/sorts them between current and target versions, and rejects empty chains or chains exceeding MAX_NIGHTLY_CHAIN_DEPTH. It fetches all manifests concurrently, expects patch layer ${getPlatformBinaryName()}.patch, validates contiguous fromVersion values and the remaining size budget fullGzSize * SIZE_THRESHOLD_RATIO - totalSize, stamps telemetry_reason on validation failures, requires the final version to equal targetVersion, requires a target SHA-256, downloads blobs concurrently, and returns patches, total size, expected SHA-256, and version steps.applyPatchChain() traces "apply-patches" with operation "upgrade.delta.apply", records patches.count and patches.total_bytes, applies all patch data in memory via applyPatchChainInMemory(), and throws SHA-256 mismatch after patching: got ${sha256}, expected ${chain.expectedSha256} if the resulting digest differs from the chain target.makeProgressHandler() labels byte phases as "Applying patch(es)" for the "apply" phase and "Processing patch(es)" otherwise; it converts cumulative written-byte events into deltas for makeByteProgress() and calls done() on completion._source.current; onResolved sets delta.source and logs patch count/total size, onOfflineMiss records "offline_miss", and onUnavailable sets telemetry_reason. Capturing the source fixes loss of network/cache/offline attribution when patch application throws after successful chain resolution.resolveDelta() calls binpatch resolveAndApply() with currentVersion: CLI_VERSION, target/source/path arguments, instrumented cache, optional offline mode, progress handling, and telemetry; it returns both the DeltaResult | null and captured source. resolveStableDelta() and resolveNightlyDelta() preserve their public call shapes and discard the returned source.attemptDeltaUpgrade() selects "nightly" or "stable" from the target version and traces "upgrade.delta" with delta.from_version, delta.to_version, and delta.channel. Success records delta.patch_bytes, delta.chain_length, and Sentry distributions upgrade.delta.patch_bytes / upgrade.delta.chain_length keyed by channel; unavailable results set delta.result = "unavailable".attemptDeltaUpgrade() captures a warning-level Sentry exception tagged with from-version, to-version, and channel; restores delta.source from the captured chain source when available; logs Delta upgrade failed (${message}), falling back to full download; marks the span error with delta.result = "error" and delta.error; and returns null to trigger full-download fallback.prefetch() exits when delta is ineligible or the signal is aborted, resolves the chain from CLI_VERSION to the target, exits if no chain.steps or aborted, then saves the chain to the patch cache. prefetchNightlyPatches() and prefetchStablePatches() select their corresponding sources.packages/cli/src/lib/binary.ts defines InstallationMethod as "curl" | "brew" | "npm" | "pnpm" | "bun" | "yarn" | "unknown", while valid --method inputs are ordered "curl", "brew", "npm", "pnpm", "bun", "yarn"; parseInstallationMethod() lowercases input and rejects unsupported values with Invalid method: ${value}. Must be one of: ${VALID_METHODS.join(", ")}.isMusl() applies 2 cached Linux-only heuristics in order: 1. check /lib/ld-musl-${muslArch}.so.1, where x64 maps to x86_64 and other supported architecture maps to aarch64; 2. run ldd --version, concatenate stdout and stderr, lowercase it, and search for "musl". Non-Linux returns false, and a missing/failing ldd defaults to glibc (false).getPlatformBinaryName() follows sentry-<os>-<arch>[-musl][.exe]: Darwin maps to "darwin", Win32 to "windows", all other platforms to "linux"; arm64 maps to "arm64" and all other architectures to "x64"; musl adds "-musl" and Windows adds ".exe".getBinaryDownloadUrl(version) returns https://github.com/getsentry/cli/releases/download/${version}/${getPlatformBinaryName()}. GITHUB_RELEASES_URL is exactly "https://api.github.com/repos/getsentry/cli/releases".isNightlyVersion(version) detects nightlies using version.includes("-dev."); compareVersions(a, b) delegates to semverCompare(a, b) and returns -1 | 0 | 1, supporting stable and numeric nightly prerelease ordering.packages/cli/test/lib/delta-upgrade.test.ts, packages/cli/test/lib/delta-upgrade.mocked.test.ts, packages/cli/test/e2e/delta-upgrade.test.ts, packages/cli/test/lib/release-notes.test.ts, packages/cli/test/lib/release-notes.property.test.ts, packages/cli/test/lib/binary.test.ts, packages/cli/test/lib/binary.mocked.test.ts, packages/cli/test/lib/ghcr.test.ts, packages/cli/test/lib/version-check.test.ts, packages/cli/test/lib/upgrade.test.ts, and packages/cli/test/commands/cli/upgrade.test.ts.