Distillation

Date: September 10, 2026

• 🔴 (03:06) User stated installation detection must always check Homebrew first because stored install information may be stale—for example, a user may switch from a recorded curl installation to Homebrew; the cheap realpath check is authoritative.
• 🔴 (03:06) User-provided detectInstallationMethod() priority is: 1. Homebrew via cheap realpath check, overriding stale stored information; 2. stored DB install information as a fast path; 3. legacy detection through curl paths, subprocess calls, then node_modules path; 4. automatically save the detected method for future runs.
• 🔴 (03:06) User-provided getCurlInstallPaths() priority is: 1. use the DB-stored path only when stored.method === "curl" and existsSync(dirname(stored.path)); 2. use process.execPath when it is in a known curl installation location; 3. default to the XDG-aware installation directory.
• 🔴 (03:06) A stale curl installation path—such as one created through SENTRY_INSTALL_DIR under /tmp/sentry-test-install and retained after that directory was purged—could make an upgrade lock/install into a dead location and crash with ENOENT ... open '.../sentry.lock', as reported in #discuss-cli. The fix is to ignore a stored path when its directory does not exist and fall through to execPath or the default install location.
• 🔴 (03:06) User-provided curl-path handling accepts that existsSync() also returns false for EACCES or a transiently unmounted parent: an unreadable stored hint is ignored because the running binary’s own execPath directory is accessible.
• 🔴 (03:06) getKnownCurlPaths() lazily memoizes buildKnownCurlPaths(homedir(), process.env) in _knownCurlPaths: string[] | undefined to avoid temporal-dead-zone issues from circular imports before KNOWN_CURL_DIRS is fully initialized.
• 🔴 (03:06) downloadStableToPath(version, destPath, setMessage?, source: UpgradeSource = PRIMARY_UPGRADE_SOURCE) now passes source to getBinaryDownloadUrl(version, source).
• 🔴 (03:06) Stable binary download first tries the gzip URL {url}.gz (~37 MB versus ~99 MB), streams it through DecompressionStream, and falls back to the raw binary URL on any failure; it throws UpgradeError if both attempts fail.
• 🔴 (03:06) User stated the relevant file-availability routine throws UpgradeError when the file never becomes visible or stays empty.
• 🔴 (03:06) maybePrefetchPatches(channel, latestVersion, signal, source) now propagates source to both prefetchNightlyPatches(latestVersion, signal, source) and prefetchStablePatches(latestVersion, signal, source). It only prefetches when semverCompare(latestVersion, CLI_VERSION) === 1; failures remain best-effort and are logged with logger.debug("Delta patch pre-fetch failed (best-effort)", error).
• 🔴 (03:06) User stated checkForUpdateInBackgroundImpl() never throws: errors are caught and reported to Sentry. In particular, failure in shouldCheckForUpdate() is handled with Sentry.captureException(error) and an immediate return.
• 🔴 (03:06) User stated getUpdateNotificationWithCopy() never throws: errors are caught and reported to Sentry. It returns null when up to date, when cached version information is absent, when rate-limited, when stderr is non-TTY, or on error; a non-null notification persists last_notified = now through markUpdateNotified.
• 🔴 (03:06) The enumerated relevant test-file line counts were: packages/cli/test/commands/cli.test.ts 231; packages/cli/test/commands/cli/upgrade.test.ts 1,296; packages/cli/test/lib/binary.test.ts 916; packages/cli/test/lib/delta-upgrade.mocked.test.ts 500; packages/cli/test/lib/delta-upgrade.test.ts 2,015; packages/cli/test/lib/ghcr.test.ts 655; packages/cli/test/lib/release-notes.test.ts 476; packages/cli/test/lib/upgrade.test.ts 2,613; packages/cli/test/lib/version-check.test.ts 670; total 9,372 lines.