Distillation

Date: Sep 9, 2026

• 🔴 (23:54) User specified installation detection must always check Homebrew first because stored install information may be stale—for example, a user may switch from a recorded curl install to Homebrew; the cheap realpath check is authoritative and overrides stale stored data.
• 🔴 (23:54) User specified the downloaded-file visibility check must throw an UpgradeError when the file never becomes visible or stays empty.
• 🟡 (23:54) packages/cli/src/lib/upgrade.ts changed detectInstallationMethod() priority to: 1. Homebrew via authoritative realpath check, 2. stored install info in the DB as a fast path, 3. legacy detection through curl paths, subprocess calls, and the node_modules path, 4. auto-save the detected method for future runs; inability to determine the method returns "unknown".
• 🟡 (23:54) packages/cli/src/lib/upgrade.ts added valid as semverValid from semver, added compareVersions, and replaced direct use of static GITHUB_RELEASES_URL with source-aware upgrade-resolution imports from ./binary.js.
• 🟡 (23:54) Version resolution in packages/cli/src/lib/upgrade.ts now returns ResolvedUpgradeVersion containing both version and the selected source, specifically { version, source: resolved.source }.
• 🟡 (23:54) Nightly-version handling in packages/cli/src/lib/upgrade.ts remains based on GHCR tags such as nightly-0.14.0-dev.1772661724 and now obtains credentials with getAnonymousToken(source), preserving the selected upgrade source.
• 🟡 (23:54) packages/cli/src/lib/upgrade.ts added standaloneVersionExists(...); it checks source-aware standalone-version resolution and returns whether the result is non-null.
• 🟡 (23:54) 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:54) Binary downloading in packages/cli/src/lib/upgrade.ts now fully consumes the response with await response.arrayBuffer() and writes new Uint8Array(body) via writeFile(destPath, ...); this avoids Bun issue https://github.com/oven-sh/bun/issues/13237, where Bun.write(path, Response) with a large streaming body can let the process exit before the download finishes.
• 🟡 (23:54) packages/cli/src/lib/upgrade.ts documents downloaded-file polling backoff beginning with attempt 1 at 0 ms and then 100 ms; failure occurs if the file never appears or remains zero-length.
• 🟡 (23:54) Upgrade download results in packages/cli/src/lib/upgrade.ts now carry downloadTag, allowing downstream installation logic to retain the exact selected tag.
• 🟡 (23:55) Test search in packages/cli/test/commands/cli/upgrade.test.ts found coverage titled "uses the selected legacy source for the check-mode changelog" at line 412, plus an npm-registry fallback case near line 234, a pre-network validation error case near line 378, an unexpected HTTP 500 guard near line 428, and an EBUSY: resource busy or locked, uv_spawn error fixture near line 1155.