Distillation

Date: Sep 10, 2026

• 🔴 (13:01) User specified installation detection must always check for Homebrew first because stored install information may be stale; the cheap, authoritative realpath check must override previously recorded methods, such as a former curl installation after switching to Homebrew.
• 🟡 (13:01) packages/cli/src/lib/upgrade.ts expanded from 169 to 267+ lines and added source-aware upgrade resolution, GitHub release pagination, semver validation, nightly GHCR handling, and platform-specific package-manager execution.
• 🟡 (13:01) packages/cli/src/lib/upgrade.ts added imports prerelease as semverPrerelease and valid as semverValid from semver, plus compareVersions; it removed direct use of GITHUB_RELEASES_URL.
• 🟡 (13:01) GitHub release processing in packages/cli/src/lib/upgrade.ts filters out releases where release.draft || release.prerelease, tracks pagination using visitedPages.add(nextPage), and reports malformed pagination with "GitHub returned an invalid release pagination URL".
• 🟡 (13:01) Source-aware upgrade metadata resolution in packages/cli/src/lib/upgrade.ts returns Promise<ResolvedUpgradeVersion>, uses UPGRADE_SOURCES, and rejects malformed version metadata with GitHub returned invalid metadata for version ${version}.
• 🟡 (13:01) detectInstallationMethod() in packages/cli/src/lib/upgrade.ts now uses this exact priority: 1. Homebrew via cheap realpath check, overriding stale stored information; 2. stored install information in the DB as a fast path; 3. legacy detection in the order curl paths → subprocess calls → node_modules path; 4. auto-save the detected method for future runs. It returns "unknown" if detection fails.
• 🟡 (13:01) Nightly upgrades continue to use an anonymous token exchange plus manifest fetch totaling 2 HTTP requests.
• 🟡 (13:01) getNightlyGzFilename() in packages/cli/src/lib/upgrade.ts returns `${getPlatformBinaryName()}.gz`. GHCR nightly layers use names such as sentry-<os>-<arch>.gz, or sentry-windows-x64.exe.gz on Windows, as the matching OCI layer’s org.opencontainers.image.title annotation.
• 🔴 (13:01) User specified the upgrade file-visibility operation throws UpgradeError when the downloaded file never becomes visible or stays empty.
• 🟡 (13:01) Missing or zero-length downloaded binaries are reported with Downloaded binary is missing or empty at ${path}. .
• 🟡 (13:01) Package-manager upgrades in packages/cli/src/lib/upgrade.ts call spawn(pm, args, { stdio: "inherit", shell: process.platform === "win32" }); shell: true is required on Windows because npm/pnpm/yarn executables are .cmd batch files and otherwise fail with ENOENT.
• 🟡 (13:01) packages/cli/src/lib/version-check.ts now imports UpgradeSource from ./binary.js and replaces fetchLatestFromGitHub / fetchLatestNightlyVersion with fetchLatestFromGitHubWithSource / fetchLatestNightlyVersionWithSource from ./upgrade.js.
• 🟡 (13:01) maybePrefetchPatches(channel, latestVersion, signal, source) now accepts source: UpgradeSource; it calls prefetchNightlyPatches(latestVersion, signal, source) for nightly releases and prefetchStablePatches(latestVersion, signal, source) for stable releases. It only prefetches when semverCompare(latestVersion, CLI_VERSION) === 1, catches failures as best-effort, logs "Delta patch pre-fetch failed (best-effort)", and subsequently cleans stale cached patches.
• 🟡 (13:01) Background version checking now preserves source affinity: nightly uses fetchLatestNightlyVersionWithSource(signal), stable uses fetchLatestFromGitHubWithSource(signal), both return { version: latestVersion, source }, and that exact source is passed into delta-patch prefetching.
• 🔴 (13:01) User specified checkForUpdateInBackgroundImpl() never throws; errors are caught and reported to Sentry.
• 🟡 (13:01) checkForUpdateInBackgroundImpl() catches failures from shouldCheckForUpdate(), calls Sentry.captureException(error), and returns without crashing the CLI. Its detached manual Sentry span is named "version-check", uses operation "version.check", and sets forceTransaction: true.
• 🔴 (13:01) User specified update-notification generation never throws; errors are caught and reported to Sentry.
• 🟡 (13:01) getUpdateNotificationWithCopy(formatNotification) returns string | null; it returns null when the CLI is up to date, cached version information is absent, notification is rate-limited, stderr is non-TTY, or an error occurs. When it returns a non-null message, it persists last_notified = now via markUpdateNotified, causing later calls inside the rate-limit window to return null.
• 🟡 (13:01) shouldSuppressNotification(args) suppresses known arguments and the management commands cli setup and cli fix. It locates the cli group and resolves its subcommand past interleaved global flags, supporting forms such as --verbose cli setup and cli --verbose setup, while avoiding false positives such as --project setup.
• 🟡 (13:01) abortPendingVersionCheck() aborts pendingAbortController if present and then sets it to null, allowing the process to exit after the main CLI work completes.