Distillation

Date: Sep 10, 2026

• 🔴 (04:38) User requires detectInstallationMethod() to always check Homebrew first because stored installation information may be stale; the Homebrew realpath check is cheap and authoritative.
• 🔴 (04:38) User requires upgrade file-readiness handling to throw UpgradeError when the file never becomes visible or stays empty.
• 🟡 (04:38) packages/cli/src/lib/upgrade.ts installation detection priority is: 1. Homebrew realpath check overriding stale stored info, 2. stored install info in DB, 3. legacy detection via curl paths, subprocess calls, then node_modules path, 4. auto-save the detected method.
• 🟡 (04:38) packages/cli/src/lib/upgrade.ts now imports prerelease as semverPrerelease and valid as semverValid from semver, plus compareVersions from the binary helpers.
• 🟡 (04:38) packages/cli/src/lib/upgrade.ts defines PAGE_NUMBER_REGEX = /^[1-9]\d*$/ and includes cyclic GitHub release-pagination detection with the error detail GitHub returned cyclic release pagination.
• 🟡 (04:38) getKnownCurlPaths() in packages/cli/src/lib/upgrade.ts lazily memoizes buildKnownCurlPaths(homedir(), process.env) in _knownCurlPaths; lazy initialization avoids TDZ issues from circular imports before KNOWN_CURL_DIRS is initialized.
• 🟡 (04:38) Standalone upgrade handling in packages/cli/src/lib/upgrade.ts now resolves both the latest version and selected source through resolveUpgradeSource().
• 🟡 (04:38) Nightly binary handling in packages/cli/src/lib/upgrade.ts uses GHCR gzip filenames returned by getNightlyGzFilename() as ${getPlatformBinaryName()}.gz; these correspond to the OCI layer’s org.opencontainers.image.title annotation, including sentry-windows-x64.exe.gz on Windows.
• 🟡 (04:38) Package-manager spawning in packages/cli/src/lib/upgrade.ts uses shell: process.platform === "win32" because npm, pnpm, and yarn executables are .cmd batch files on Windows and otherwise fail with ENOENT.