Distillation

Date: Sep 9, 2026

• 🔴 (23:53) User specified that detectInstallationMethod() in packages/cli/src/lib/upgrade.ts must always check Homebrew first because stored installation information may be stale—for example, when a user switches from a recorded curl installation to Homebrew. The cheap realpath check is authoritative.
• 🟡 (23:53) detectInstallationMethod() installation-detection priority in packages/cli/src/lib/upgrade.ts is: 1. Homebrew realpath check, overriding stale stored information; 2. stored install information in the database as the fast path; 3. legacy detection in the order curl paths → subprocess calls → node_modules path; 4. automatically save the detected method for future runs. It returns "unknown" when detection fails.
• 🟡 (23:53) packages/cli/src/lib/upgrade.ts now imports valid as semverValid from semver, adds compareVersions to its imports from ./binary.js, and removes its dependency on the fixed GITHUB_RELEASES_URL.
• 🟡 (23:53) Upgrade version resolution in packages/cli/src/lib/upgrade.ts now returns Promise<ResolvedUpgradeVersion> and propagates both the resolved version and selected release source as { version, source: resolved.source }.
• 🟡 (23:53) Nightly version lookup in packages/cli/src/lib/upgrade.ts now passes the selected UpgradeSource to getAnonymousToken(source). Nightly builds remain published to GHCR with tags such as nightly-0.14.0-dev.1772661724.
• 🟡 (23:53) packages/cli/src/lib/upgrade.ts added standaloneVersionExists(...); it determines existence by resolving the standalone version and returns whether the result is non-null (resolved !== null).
• 🟡 (23:53) npm version existence checking in packages/cli/src/lib/upgrade.ts sends a HEAD request to ${NPM_REGISTRY_URL}/${version} through fetchWithUpgradeError(..., "npm registry") and returns response.ok.
• 🟡 (23:53) Binary downloads in packages/cli/src/lib/upgrade.ts fully consume response.arrayBuffer() before writing new Uint8Array(body) with writeFile(destPath, ...). This avoids a Bun event-loop bug where Bun.write(path, Response) with a large streaming body can let the process exit before the download completes; the referenced upstream issue is https://github.com/oven-sh/bun/issues/13237.
• 🔴 (23:53) User specified that the file-visibility wait operation in packages/cli/src/lib/upgrade.ts throws UpgradeError when the file never becomes visible or stays empty.
• 🟡 (23:53) startCleanupOldBinary() in packages/cli/src/lib/upgrade.ts remains a non-blocking, fire-and-forget startup cleanup: it obtains { oldPath } from getCurlInstallPaths() and calls cleanupOldBinary(oldPath).
• 🟡 (23:53) Package-manager process startup failures in packages/cli/src/lib/upgrade.ts reject with new UpgradeError("execution_failed", \${pm} failed: ${err.message}`)`.
• 🟡 (23:53) Upgrade installation now propagates downloadTag into the download flow in packages/cli/src/lib/upgrade.ts.
• 🟡 (23:53) packages/cli/src/lib/version-check.ts now imports the UpgradeSource type from ./binary.js and replaces fetchLatestFromGitHub / fetchLatestNightlyVersion with source-returning fetchLatestFromGitHubWithSource / fetchLatestNightlyVersionWithSource.
• 🟡 (23:53) maybePrefetchPatches(channel, latestVersion, signal, source) in packages/cli/src/lib/version-check.ts now accepts source: UpgradeSource. When latestVersion is newer than CLI_VERSION, it calls prefetchNightlyPatches(latestVersion, signal, source) for nightly or prefetchStablePatches(latestVersion, signal, source) for stable. Pre-fetch failures remain best-effort and are logged with logger.debug("Delta patch pre-fetch failed (best-effort)", error).
• 🟡 (23:53) Background version discovery in packages/cli/src/lib/version-check.ts now destructures { version: latestVersion, source }: nightly uses fetchLatestNightlyVersionWithSource(signal), while stable uses fetchLatestFromGitHubWithSource(signal). It stores latestVersion with setVersionCheckInfo(latestVersion) and passes the same selected source into maybePrefetchPatches(channel, latestVersion, signal, source), ensuring delta patch prefetch uses the source chosen during version discovery.
• 🔴 (23:53) User specified that checkForUpdateInBackgroundImpl() never throws: failures are caught and reported to Sentry.
• 🟡 (23:53) checkForUpdateInBackgroundImpl() catches synchronous shouldCheckForUpdate()/database-access failures, reports them through Sentry.captureException(error), and returns without crashing the CLI.
• 🟡 (23:53) The background check runs in a detached manual Sentry span configured with name: "version-check", op: "version.check", and forceTransaction: true. Success sets span status code 1; failure sets status code 2; cleanup sets pendingAbortController = null and ends the span.
• 🟡 (23:53) Expected AbortError failures during version checking are not reported. Other errors attach version_check.error and version_check.error_type span attributes rather than calling captureException, because network failures, GitHub rate limits, CDN errors, and JSON parsing failures are treated as transient infrastructure problems that should remain queryable in Discover without cluttering the Sentry Issues feed.
• 🔴 (23:53) User specified that update-notification generation never throws: errors are caught and reported to Sentry.
• 🟡 (23:53) getUpdateNotificationWithCopy(formatNotification) returns string | null and returns null when stderr is non-TTY, cached version information is absent, the current version is up to date, notification is rate-limited, or an error occurs. When it returns a non-null message, it also persists last_notified = now through markUpdateNotified, causing subsequent calls during the rate-limit window to return null.
• 🟡 (23:53) abortPendingVersionCheck() aborts pendingAbortController if present and then sets it to null, allowing the process to exit after primary CLI work completes.
• 🟡 (23:53) Version checks remain suppressed only for CLI management subcommands "setup" and "fix" when preceded by "cli", preventing unrelated arguments such as --project setup from suppressing notifications.