Distillation

Date: Sep 9, 2026

• 🔴 [enforced-network-requirement] (23:51) User stated package managers always need network access to fetch and install packages; --offline upgrade is supported only for curl-installed binaries, and validateMethod() throws UpgradeError("unsupported_operation", "Offline upgrade is only supported for curl-installed binaries.") when offline && method !== "curl".
• 🔴 [enforced-upgrade-source] (23:51) User stated nightly builds are GitHub-only, so pinned nightly-version validation must always use the "curl" GitHub lookup regardless of the current installation method; implementation selects const lookupMethod = channel === "nightly" ? "curl" : method.
• 🔴 [documented-command-example] (23:51) User specified the command example sentry cli upgrade nightly # Switch to nightly channel and update.
• 🔴 [enforced-path-handling] (23:52) User stated trailing path separators should be stripped but never from a bare root such as /; stripTrailingSep(p: string) returns p.slice(0, -1) only when p.length > 1 && p.endsWith(sep).
• 🔴 [enforced-request-reuse] (23:52) User stated the caller receives the successful probe response so it never repeats the probe request.
• 🟡 (23:51) packages/cli/package.json identifies package sentry version 0.45.0-dev.0, repository git+https://github.com/getsentry/cli.git, license FSL-1.1-Apache-2.0, Node engine >=20.0, development runtime Node >=22.15, and package manager pnpm@10.11.0.
• 🟡 (23:51) packages/cli/package.json build/runtime artifacts are ./dist/index.cjs, ./dist/index.mjs, ./dist/index.d.cts, ./dist/index.d.mts, and binary sentry: ./dist/bin.cjs; published files additionally include dist/ink-app.js, dist/node-sqlite3-wasm.wasm, dist/assets/spleen-8x16.bin, dist/vendor/symbolic_bg.wasm, LICENSE.md, THIRD_PARTY_LICENSES.md, and README.md.
• 🟡 (23:51) Current packages/cli/package.json scripts include: tsx, cli, dev, build, build:all, bundle, typecheck, lint, lint:fix, test, test:unit, test:changed, test:e2e, test:init-eval, generate:parser, generate:sdk, generate:skill, generate:banner, generate:docs, generate:docs-sections, generate:schema, generate:command-docs, eval:skill, bench, bench:save, bench:compare, bench:sweep, check:fragments, check:deps, check:errors, check:patches, check:docs-sections, check:env-coverage, and check:stale-refs.
• 🟡 (23:51) Exact primary validation scripts in packages/cli/package.json are: typecheck: pnpm run generate:docs && pnpm run generate:sdk && tsc --noEmit; lint: biome check --no-errors-on-unmatched --error-on-warnings --max-diagnostics=none ./; lint:fix: biome check --write --no-errors-on-unmatched --max-diagnostics=none ./; test: pnpm run test:unit; test:unit: pnpm run generate:docs && pnpm run generate:sdk && vitest run test/lib test/commands test/types test/script --coverage; test:changed: pnpm run generate:docs && pnpm run generate:sdk && vitest run --changed; test:e2e: pnpm run generate:docs && pnpm run generate:sdk && vitest run test/e2e; test:init-eval: vitest run test/init-eval --testTimeout 600000.
• 🟡 (23:51) Exact package-check scripts are: check:fragments: pnpm tsx script/check-fragments.ts; check:deps: pnpm tsx script/check-no-deps.ts; check:errors: pnpm tsx script/check-error-patterns.ts; check:patches: pnpm tsx script/check-patches.ts; check:docs-sections: pnpm tsx script/generate-docs-sections.ts --check; check:env-coverage: pnpm tsx script/check-env-coverage.ts; check:stale-refs: pnpm tsx script/check-stale-references.ts.
• 🟡 (23:51) packages/cli/package.json has no production dependencies; notable exact devDependencies include @sentry/api@^0.256.0, @sentry/core@10.63.0, @sentry/node@10.65.0, @sentry/node-core@10.63.0, @sentry/sqlish@^1.0.1, @sentry/symbolic@13.7.0, @stricli/core@1.2.8, @vitest/coverage-v8@^4.1.9, esbuild@^0.28.1, fast-check@^4.8.0, ink@^7.1.0, node-sqlite3-wasm@0.8.59, react@^19.2.7, tsx@^4.22.4, typescript@^5.9.3, ultracite@6.3.10, and vitest@^4.1.9.
• 🟡 (23:51) Upgrade work changed 15 files with exactly 1,650 insertions and 291 deletions: packages/cli/src/commands/cli/upgrade.ts, packages/cli/src/lib/binary.ts, packages/cli/src/lib/delta-upgrade.ts, packages/cli/src/lib/ghcr.ts, packages/cli/src/lib/release-notes.ts, packages/cli/src/lib/upgrade.ts, packages/cli/src/lib/version-check.ts, packages/cli/test/commands/cli/upgrade.test.ts, packages/cli/test/lib/binary.test.ts, packages/cli/test/lib/delta-upgrade.mocked.test.ts, packages/cli/test/lib/delta-upgrade.test.ts, packages/cli/test/lib/ghcr.test.ts, packages/cli/test/lib/release-notes.test.ts, packages/cli/test/lib/upgrade.test.ts, and packages/cli/test/lib/version-check.test.ts.
• 🟡 (23:51) The compared revisions were 723375b6ce4e37884e760fa0f848e7e7e3effcc9 and ec83887a16f780f32fba4b7d710bad262dba3a22.
• 🟡 (23:51) packages/cli/src/commands/cli/upgrade.ts now imports UpgradeSource, resolveExistingUpgradeVersion, and resolveLatestUpgradeVersion; resolveTargetWithFallback() target results and done results can carry source?: UpgradeSource, allowing upgrade resolution to preserve the selected release source.
• 🟡 (23:51) packages/cli/src/commands/cli/upgrade.ts documents two persisted release channels: stable tracks the latest GitHub release by default, while nightly tracks the rolling prerelease built from main; users can choose via --channel or the positional values "nightly" / "stable", and later bare sentry cli upgrade calls reuse the stored channel.
• 🟡 (23:51) Specific pinned-version validation changed from Boolean versionExists(lookupMethod, target) plus a local version_not_found throw to source = (await resolvePinnedVersion(lookupMethod, target)) ?? source, preserving the source that resolved the requested version.
• 🟡 (23:51) Upgrade hints use sentry cli upgrade ${target} for an explicit non-channel pinned version and otherwise use sentry cli upgrade; no hint is needed when CLI_VERSION === target.
• 🟡 (23:52) packages/cli/src/lib/binary.ts defines known curl locations as KNOWN_CURL_DIRS = [".local/bin", "bin", ".sentry/bin"], but legacy migration is deliberately limited to LEGACY_INSTALL_SUBDIRS = [LEGACY_INSTALL_SUBDIR] where LEGACY_INSTALL_SUBDIR = join(".sentry", "bin"); ~/.local/bin and ~/bin remain valid current XDG install targets and must not be relocated.
• 🟡 (23:52) packages/cli/src/lib/binary.ts treats filesystems as case-insensitive by default on process.platform === "win32" or process.platform === "darwin" via module-level constant IS_CASE_INSENSITIVE_FS.
• 🟡 (23:52) packages/cli/src/lib/binary.ts musl detection uses two ordered heuristics: 1. check /lib/ld-musl-<arch>.so.1; 2. parse ldd --version, where musl writes "musl libc" to stderr and glibc writes "GNU C Library" to stdout. The result is cached in cachedIsMusl because libc cannot change at runtime.
• 🟡 (23:52) Source-aware GitHub helpers were added in packages/cli/src/lib/binary.ts: getBinaryDownloadUrl(version, source = PRIMARY_UPGRADE_SOURCE) builds https://github.com/${source.githubRepo}/releases/download/${source.tagPrefix}${version}/${getPlatformBinaryName()}; getGitHubReleasesUrl(source) builds the repository releases API base; getGitHubReleaseByTagUrl(version, source) appends /tags/${encodeURIComponent(tag)}; and getGitHubLatestReleaseUrl(source) uses ?per_page=100 for prefixed tags but /latest when source.tagPrefix is empty.
• 🟡 (23:52) GITHUB_RELEASES_URL is now derived by calling getGitHubReleasesUrl() with the default PRIMARY_UPGRADE_SOURCE.
• 🟡 (23:52) isNightlyVersion(version: string) recognizes nightly builds by version.includes("-dev."); documented nightly format is X.Y.Z-dev.<unix-seconds>.
• 🟡 (23:52) Install-directory selection gives explicit env.SENTRY_INSTALL_DIR first priority.