Distillation

Current State

• Date: September 9, 2026.
• Repository/worktree: /home/byk/.local/share/opencode/worktree/0e8c2f3bbe145a3280d6fb6ed900a5121f382cf0/toolkit-bridge-upgrade
• Branch: feat/toolkit-bridge-upgrade; at 09:33 it was behind origin/main by 2 commits.
• Task: Read-only review of Toolkit/legacy dual-source upgrade compatibility, focused on:
  • packages/cli/src/lib/delta-upgrade.ts
  • relevant delta/version/upgrade tests
  • the public source/API of binpatch@0.4.2, researched via GitHub/raw/npm rather than node_modules
  • determining the smallest exact source-affinity changes for stable/nightly delta resolution and prefetch
  • determining whether githubReleaseSource supports cli@ tag prefixes and, if not, recommending a minimal repository-safe adapter
  • identifying exact tests, file/symbol changes, and risks
• Operating constraints: Do not edit files and do not run broad tests. No assistant-authored edits or test runs occurred. Two searches returned No files found; GitHub code search failed with HTTP 401; raw/tag requests using v0.4.2 failed with HTTP 404 because binpatch tags are unprefixed.
• Repository instructions loaded/noted:
  • AGENTS.md: load repo-setup before situation skills.
  • packages/cli/AGENTS.md: always check package.json for current scripts; properties must hold for arbitrary input; do not duplicate property-tested invariants with hardcoded unit tests.
  • .cursor/rules/ultracite.mdc must be read before code work.
  • The CLI uses Node.js, pnpm, Stricli, node:* APIs, and Vitest; do not reintroduce Bun.*, bun:test, or bun CLI commands.
  • All package additions belong in devDependencies and must use pnpm add -D <package>; CI checks this with pnpm run check:deps.
• Latest observed implementation state (12:55–13:27):
  • packages/cli/src/lib/delta-upgrade.ts had grown from 627 to 648 lines and now accepts explicit UpgradeSource values through stable/nightly chain resolution, delta application, and prefetch.
  • packages/cli/src/lib/upgrade.ts, packages/cli/src/lib/version-check.ts, and packages/cli/src/commands/cli/upgrade.ts were also shown threading the selected source through discovery, existence checks, downloads, delta attempts, and background prefetch.
  • packages/cli/test/lib/delta-upgrade.test.ts had expanded beyond line 2006 with a "selected source affinity" section.
  • The last explicit git diff --stat snapshot was at 10:28: exactly 5 modified files and 335 insertions/25 deletions:
    1. packages/cli/src/lib/binary.ts — 139-line diff
    2. packages/cli/src/lib/ghcr.ts — 52-line diff
    3. packages/cli/test/lib/binary.test.ts — 129-line diff
    4. packages/cli/test/lib/ghcr.test.ts — 30-line diff
    5. packages/cli/test/lib/install-script.test.ts — 10-line diff
       Later observations showed additional source-affinity edits in delta-upgrade.ts, upgrade.ts, version-check.ts, commands/cli/upgrade.ts, tests, and release-notes.ts, but no newer status/diff count was provided.
• Remaining review blocker/risk: binpatch@0.4.2’s githubReleaseSource has no tagPrefix or tag-normalization option. Merely passing getGitHubReleasesUrl(source) is insufficient for Toolkit releases whose tag_name is cli@<version>, because binpatch compares release tag_name directly to unprefixed currentVersion and targetVersion. A consumer-side normalization/filter adapter or upstream binpatch API extension is still required for Toolkit stable delta discovery.
• Focused validation recommended, but not run due read-only constraints:
  • pnpm exec vitest run test/lib/binary.test.ts
  • pnpm exec vitest run test/lib/ghcr.test.ts
  • pnpm exec vitest run test/lib/delta-upgrade.test.ts
  • pnpm exec vitest run test/lib/delta-upgrade.mocked.test.ts
  • pnpm exec vitest run test/lib/upgrade.test.ts
  • pnpm exec vitest run test/lib/version-check.test.ts
  • pnpm exec vitest run test/lib/install-script.test.ts
  • relevant typecheck/check scripts after consulting packages/cli/package.json

Key Decisions

• Canonical ordered sources:
  1. { githubRepo: "getsentry/toolkit", ghcrRepo: "getsentry/toolkit", tagPrefix: "cli@" }
  2. { githubRepo: "getsentry/cli", ghcrRepo: "getsentry/cli", tagPrefix: "" } PRIMARY_UPGRADE_SOURCE is the first entry.
• Fallback rule: Advance to the next source only on HTTP 404. HTTP 401, 403, 429, 500, TLS failures, ordinary fetch/network failures, and cancellation must abort immediately. These failures are transient and must not poison or silently bypass a source.
• Probe reuse: Source resolution returns { source, response }; callers must parse and reuse the successful probe Response rather than repeating the request.
• Source affinity: Once discovery selects an UpgradeSource, that exact source must be passed through:
  • pinned/latest existence resolution
  • stable/nightly delta source construction
  • delta application
  • prefetch
  • stable binary URL creation
  • nightly token, manifest, and blob requests
  • release-note/history requests where relevant
    Re-resolving independently or defaulting later stages to primary was rejected because it can mix Toolkit metadata with legacy assets or vice versa.
• Toolkit stable tags: Stable Toolkit tags are cli@<version>; legacy tags remain unprefixed. Latest-version discovery must filter Toolkit releases by cli@, ignore unrelated tags such as mcp@9.0.0, exclude drafts/prereleases, and strip the prefix.
• binpatch@0.4.2 prefix finding: githubReleaseSource does not support tag prefixes. Its config is only releasesUrl, binaryName, userAgent, optional fetch, and optional instrument.
  • Smallest consumer-side solution: provide a source-bound release-list fetch adapter to githubReleaseSource that:
    1. intercepts only that source’s release-list request,
    2. fetches enough repository releases (Toolkit needs up to 100 because unrelated products share the repository),
    3. filters to non-draft/non-prerelease tags beginning with source.tagPrefix,
    4. strips the prefix from each returned tag_name,
    5. limits the normalized list to binpatch’s expected release window,
    6. leaves patch-asset requests and browser_download_url values unchanged.
  • The adapter must close over one selected UpgradeSource; it must never query or merge another repository.
  • Alternative: add tagPrefix/tag-normalization support upstream to binpatch, but that is a larger cross-package/version change and is not available in 0.4.2.
• Stable listing window risk: Binpatch requests MAX_STABLE_CHAIN_DEPTH + 2 releases (12). In Toolkit, the latest 12 repository releases may include MCP or other products and may not contain 12 CLI releases. A prefix adapter therefore needs to fetch a broader page (currently Toolkit latest discovery uses per_page=100) before filtering.
• Nightly source handling: Nightly GHCR tags remain nightly-<version> and patch-<version>; only the repository changes, so no cli@ normalization is required. Token, target manifest, tag list, chain manifests, and blobs must all use source.ghcrRepo.
• Delta unavailability semantics: SourceStrategy.resolveChain() returning null always means full-download fallback. UnavailableReporter is telemetry-only.
  • Exact reasons: "no_patches" | "malformed_chain" | "too_long" | "over_budget" | "network".
  • A listed manifest/asset download failure is transient "network".
  • A successfully fetched HTTP-200 manifest rejected by validation is a genuine "malformed_chain"/poisoned publish.
• Offline behavior: resolveAndApply({ offline: true }) is cache-only—“never touch the network, cache hit or bust.” Package managers always need network access, so CLI offline upgrades are supported only for curl installations.
• Patch application: Intermediate outputs must never touch disk. Multi-hop chains use applyPatchChainInMemory; legacy ${destPath}.patching.a and ${destPath}.patching.b files must never exist.
• Progress: Binpatch emits progress events only and never renders UI. A throwing progress callback is isolated by safeProgress. Apply progress totals sum every hop’s newSize; CLI rendering uses percent-only for apply to avoid misleading totals such as 930 MB for a 310 MB final binary.
• Homebrew detection: Always check Homebrew first because stored install metadata may be stale; realpath-based /Cellar/ detection is cheap and authoritative.
• Release compatibility policy: One shared source definition must drive TypeScript and the generated install script, with a check that fails if lists/order diverge.
• Bridge/dual-publish policy:
  • Ship one stable bridge release from getsentry/cli before importing CLI history into getsentry/sentry-mcp.
  • Old binaries know only getsentry/cli, so migrated stable releases and nightlies must be dual-published to Toolkit and legacy endpoints.
  • Preserve release assets, SHA-256 values, GHCR manifests, sha256-<binary> and from-version metadata, patch chains, cleanup policy, and keep-count parity.
  • Continue dual-publishing for at least 2 stable releases and roughly 90 days of nightlies; keep getsentry/cli writable until telemetry/release evidence permits archival.
• Bridge verification matrix: pre-bridge binary via legacy; bridge/Toolkit binaries via Toolkit; Toolkit 404 fallback to legacy; identical install-script behavior; exact asset/hash/manifest/delta metadata parity; repeat for one nightly.

Technical Changes

• packages/cli/src/lib/binary.ts
  • Added:
    • UpgradeSource = { readonly githubRepo: string; readonly ghcrRepo: string; readonly tagPrefix: string }
    • ordered UPGRADE_SOURCES
    • PRIMARY_UPGRADE_SOURCE
    • ResolvedUpgradeSource = { readonly source: UpgradeSource; readonly response: Response }
    • ResolveUpgradeSourceOptions, later including optional sources?: readonly UpgradeSource[]
    • fetchUpgradeProbe()
    • resolveUpgradeSource()
  • Source-aware helpers:
    • getBinaryDownloadUrl(version, source)
    • getGitHubReleasesUrl(source)
    • getGitHubReleaseByTagUrl(version, source) using encodeURIComponent(source.tagPrefix + version)
    • getGitHubLatestReleaseUrl(source): ?per_page=100 for prefixed repositories, /latest for unprefixed
    • getGitHubRepositoryUrl(source)
  • GITHUB_RELEASES_URL remains exported but now points at the primary Toolkit releases URL.
  • Resolver mappings:
    • AbortError: rethrow unchanged
    • TLS: UpgradeError("network_error", buildTlsErrorDetail(error))
    • other fetch failure: UpgradeError("network_error", "Failed to connect to GitHub: ...")
    • non-404 HTTP: UpgradeError("network_error", "Failed to fetch from GitHub: HTTP ...")
    • all 404: UpgradeError("network_error", "No CLI upgrade source was found: every source returned HTTP 404")
  • Corrected version-comparison documentation from Bun.semver.order to semver.compare.
  • Existing exact source-probe tests use:
    • Toolkit: https://api.github.com/repos/getsentry/toolkit/releases/tags/cli%400.45.0
    • Legacy: https://api.github.com/repos/getsentry/cli/releases/tags/0.45.0
• packages/cli/src/lib/ghcr.ts
  • Changed GHCR_REPO from hard-coded "getsentry/cli" to PRIMARY_UPGRADE_SOURCE.ghcrRepo.
  • Made getAnonymousToken, fetchManifest, fetchNightlyManifest, downloadNightlyBlob, fetchTagPage, listTags, and downloadLayerBlob source-aware while retaining backward-compatible AbortSignal handling for getAnonymousToken.
  • Source-specific token scope: repository:${source.ghcrRepo}:pull.
  • Source-specific tag URL: ${GHCR_REGISTRY}/v2/${source.ghcrRepo}/tags/list?n=100.
  • Known preexisting defect relevant to binpatch/OciClient parity: the CLI implementation’s manual blob redirect used hard-wired customFetch and the caller’s raw signal, so omitted signals gave redirected Azure Blob downloads no timeout. Binpatch’s required behavior is injected fetch for every request/redirect and buildSignal(BLOB_TIMEOUT, signal) even when no external signal is supplied.
• packages/cli/src/lib/delta-upgrade.ts
  • Grew from 627 to 648 lines as source affinity was added.
  • stableSource(source) now uses getGitHubReleasesUrl(source).
  • nightlySource(source) now uses source.ghcrRepo.
  • Source parameter propagated through:
    • fetchRecentReleases
    • resolveStableChain
    • resolveNightlyChain
    • resolveStableDelta
    • resolveNightlyDelta
    • attemptDeltaUpgrade
    • prefetchNightlyPatches
    • prefetchStablePatches
  • getPrimaryUpgradeSource() returns PRIMARY_UPGRADE_SOURCE or throws Error("No primary upgrade source is configured").
  • Existing compatibility behavior retained:
    • local richer validateChainStep reasons: version-mismatch, missing-layer, size-exceeded
    • in-memory application and final SHA verification
    • cache instrumentation using patch-chain:${fromVersion}-${toVersion}
    • telemetry source capture via _source.current
    • cache-first/offline behavior
    • prefetch only when eligible, not aborted, and chain.steps exists
  • Outstanding stable-prefix defect: shown stableSource(source) still passes only the source-specific releases URL into unmodified githubReleaseSource; no observed adapter normalizes cli@ tag_name values. This means Toolkit stable chain lookup can still fail as no_patches.
• packages/cli/src/lib/upgrade.ts
  • Added ResolvedUpgradeVersion = { readonly version: string; readonly source: UpgradeSource }.
  • Added source-preserving helpers:
    • extractReleaseVersions()
    • fetchLatestFromGitHubWithSource()
    • fetchLatestNightlyVersionWithSource()
    • resolveLatestUpgradeVersion()
    • resolveExistingUpgradeVersion()
    • standaloneVersionExists()
  • Compatibility wrappers fetchLatestFromGitHub() and fetchLatestNightlyVersion() still return only a version; with explicit source they probe only that source.
  • nightlyVersionExists(version, source) now treats only HTTP 404 as absence; prior HTTP 403-as-absence behavior was removed.
  • Source threaded through:
    • versionExists
    • downloadNightlyToPath
    • downloadStableToPath
    • downloadBinaryToTemp
    • tryDeltaUpgrade
    • downloadFullBinary
    • executeUpgrade
  • Stable download uses getBinaryDownloadUrl(version, source); nightly token/manifest/blob requests use the same source.
  • Existing safeguards retained:
    • lock across download→spawn→install
    • cache-only offline delta attempt
    • exact offline-cache-miss messages
    • waitForBinaryVisible() with 6 probes at 0, 100, 300, 700, 1500, and 3100 ms
    • final executable verification and mode 0o755 outside Windows
    • stale curl DB path ignored unless existsSync(dirname(stored.path))
• packages/cli/src/lib/version-check.ts
  • Switched stable/nightly discovery to the WithSource helpers.
  • maybePrefetchPatches(channel, latestVersion, signal, source) passes the exact selected source to channel-specific prefetch.
  • At 13:23, calls were:
    • line 242: await prefetchNightlyPatches(latestVersion, signal, source)
    • line 244: await prefetchStablePatches(latestVersion, signal, source)
  • Background checks remain detached/non-throwing, with expected aborts ignored and transient errors attached to the Sentry span.
• packages/cli/src/commands/cli/upgrade.ts
  • Optional source?: UpgradeSource threaded through target resolution, result types, pinned/latest resolution, and executeUpgrade().
  • Standalone resolution applies for nightly, curl, or brew.
  • Pinned nightly continues to force curl/standalone lookup regardless of current install method.
  • Explicit offline resolution carries no network-selected source and reads cached target before persisting a channel change.
• packages/cli/src/lib/release-notes.ts
  • Line 692 was shown constructing source-specific commit URLs using ${source.githubRepo}.
• Generated install script/tests
  • packages/cli/test/lib/install-script.test.ts parses UPGRADE_SOURCES=(...) from the install script and requires exact repository order equality with UPGRADE_SOURCES.map(source => source.githubRepo).
  • Requirement remains that generated script and TypeScript share one canonical source definition/check.
• Tests added/expanded
  • packages/cli/test/lib/binary.test.ts:
    • ordered source list
    • default Toolkit URL with cli@
    • source-specific tag URL encoding
    • first-source success
    • fallback only on 404
    • no fallback for 401/403/429/500 or TypeError("fetch failed")
    • all-source 404 exhaustion
  • packages/cli/test/lib/ghcr.test.ts:
    • Toolkit token scope
    • Toolkit rolling nightly manifest path
  • packages/cli/test/lib/delta-upgrade.test.ts:
    • defines guarded LEGACY_UPGRADE_SOURCE = UPGRADE_SOURCES[1]
    • legacy stable chain requests only getsentry/cli
    • legacy nightly token/tag requests only getsentry/cli
    • "selected source affinity" section at line 1922
    • versioned module imports via vi.resetModules()/vi.doMock() to test non-dev CLI_VERSION
    • legacy source tests at lines 1941, 1966, 1986, and 2006
  • packages/cli/test/lib/version-check.test.ts:
    • stable Toolkit source propagated to prefetch
    • Toolkit 404 → legacy source propagated to prefetch
    • nightly Toolkit source propagated to prefetch
  • Stable discovery tests:
    • Toolkit ?per_page=100
    • ignore mcp@9.0.0
    • accept cli@...
    • filter drafts/prereleases
    • preserve GitHub response order rather than computing semantic maximum
    • explicit source does not fall back
  • Nightly discovery tests:
    • Toolkit repository probe → Toolkit token → Toolkit manifest
    • Toolkit manifest 404 can fall back to legacy
    • Toolkit HTTP 403 aborts without legacy access
• Exact additional test still needed for the identified binpatch prefix gap:
  • In packages/cli/test/lib/delta-upgrade.test.ts, resolve a stable chain using Toolkit releases whose raw tags are cli@<version> and include unrelated mcp@... entries; assert:
    1. the chain resolves using unprefixed CLI versions,
    2. patch URLs remain the Toolkit asset URLs,
    3. no getsentry/cli request occurs,
    4. oldest-first steps are unprefixed,
    5. enough releases are fetched before filtering.
  • Add a complementary legacy test proving unprefixed tags pass through unchanged.
  • Add a mixed-product window test where the first 12 repository releases are not all CLI releases, ensuring the adapter fetches/filtering from a broader page rather than allowing a false no_patches.
• binpatch@0.4.2 facts
  • Dependency: packages/cli/package.json:111 contains "binpatch": "^0.4.2".
  • Lockfile has exactly 3 matches: lines 136, 2169, and 6698.
  • Tag 0.4.2 resolves to commit 9ba6bbb8227fcbd2521852d2311c82afac5e9573; 0.4.1 → d0593cdd89eb720edddf9644e0753613e4a8e622; 0.4.0 → 2446f4cbecca92eba775e8ef52dff01fd20a9326.
  • Pure Node, ESM, MIT, Node >=22.15.0, zero product coupling.
  • Wire constants:
    • MAX_STABLE_CHAIN_DEPTH = 10
    • MAX_NIGHTLY_CHAIN_DEPTH = 30
    • SIZE_THRESHOLD_RATIO = 0.6
    • PATCH_TAG_PREFIX = "patch-"
    • MAX_OUTPUT_SIZE = 2 GiB
  • Public exports include apply, cache, contract, error, progress, discovery, GHCR, GitHub Release, and OCI APIs, including githubReleaseSource, ghcrSource, OciClient, resolveAndApply, applyPatchChainInMemory, makeCache, and associated types.
  • githubReleaseSource expects <binaryName>, <binaryName>.gz, and <binaryName>.patch; it has no prefix-aware configuration.
  • OciClient contract requires all requests and manual redirects to use its injected fetch; redirect requests always receive a live timeout signal.
• Preserved delta/cache invariants
  • Patch cache filenames:
    • <fromVersion>-<toVersion>.patch
    • chain-<fromVersion>-<toVersion>.json
  • sanitizeVersion() replaces characters outside [a-zA-Z0-9.-] with _.
  • Cache TTL: exactly 7 days (7 * 24 * 60 * 60 * 1000).
  • Cache chain-walk depth: 10.
  • Binpatch wire contract uses TRDIFF10 magic and sign-magnitude i64 header fields controlLen, diffLen, and newSize, followed by zstd-compressed control/diff/extra streams.
  • SHA-256 mismatch error: SHA-256 mismatch after patching: got ${sha256}, expected ${chain.expectedSha256}.
• Related issue/release references
  • getsentry/cli#1244: “toolkit merge: bridge CLI release + dual-source upgrade compatibility,” authored by BYK, created July 15, 2026, updated September 8, 2026; subtask of getsentry/cli#1248.
  • Comment 4978828102 / IC_kwDOQm6jAs8AAAABKMLjRg, created and updated 2026-07-15T09:05:00Z, says: Master tracking issue: https://github.com/getsentry/cli/issues/1248.
  • Bridge version must be recorded in #1244 before beginning getsentry/cli#1239.

Session Timeline

• Sep 9, 2026, 09:29–09:30: User established read-only/no-broad-tests constraints, required GitHub/raw research for binpatch 0.4.2, and identified stable/nightly source-affinity plus cli@ support as the central task. Repository instructions and relevant test files were loaded.
• 09:31–09:38: Located delta resolution/prefetch call sites, version-check integration, binpatch dependency/consumers, binary/source helpers, current tests, and binpatch public source/API. Confirmed in-memory patching, cache-first/offline behavior, progress semantics, source telemetry, and GitHub/GHCR source contracts.
• 09:41–09:47: Reviewed upgrade-command constraints, installation detection, offline rules, pinned-nightly routing, cache design, version-notification behavior, resolver error policy, binpatch wire constants/types, and instrumentation contract.
• 09:49–09:57: Reviewed initial dual-source implementation in binary.ts/ghcr.ts, issue #1244’s bridge-release plan, source synchronization requirements, delta tests, binpatch metadata/docs/API, and existing delta-upgrade.ts architecture.
• 09:58–09:59: Loaded project-wide Node/pnpm/Stricli conventions and detailed delta test fixtures/property conventions.
• 10:01–10:03: Reviewed remaining delta-chain tests, upgrade target resolution, Windows spawn retry, source-strategy telemetry, cache-first orchestration, progress aggregation, and exact SHA verification behavior.
• 10:05–10:09: Captured a 5-file/335-insertion working-tree snapshot, reviewed version-check behavior and binary tests, and traced nightly/tag-prefix references and publishing workflows.
• 10:13–10:16: Reconfirmed transient manifest failures must report network, examined the 627-line delta adapter and 1144-line upgrade module, and documented download/visibility/locking behavior.
• 10:18–10:20: Reconfirmed binpatch tags, exact delta call/test locations, issue #1244’s bridge gate, dual-publishing matrix, and the 2-release/~90-day compatibility window.
• 10:22–10:29: Reviewed in-progress source-aware GHCR/binary changes, found upgrade.ts still calling getBinaryDownloadUrl(version) without a selected source at 10:24, restated project constraints, then traced upgrade/delta/version-check call sites and binpatch orchestration semantics.
• 12:55–12:57: Observed delta-upgrade.ts at 648 lines with explicit source-aware stable/nightly strategies, source-preserving telemetry, progress corrections, and source-aware prefetch.
• 12:59–13:00: Observed broader source-affinity implementation across upgrade.ts, version-check.ts, delta APIs, and tests. Latest/pinned discovery now returns and preserves UpgradeSource; binary resolver gained optional sources; stable/nightly fallback tests were added.
• 13:02: Reviewed command-layer propagation of optional source through offline/online target resolution, pinned versions, check mode, and execution.
• 13:08–13:11: Revalidated binpatch source classifications, OciClient injected-fetch/timeout requirements, 648-line delta adapter behavior, and 500-line mocked integration suite.
• 13:14–13:17: Reviewed final binary helper details, upgrade regression tests, CLI-1D3 visibility handling, and upgrade command imports/behavior.
• 13:23: Search found exactly 47 delta resolution/execution/prefetch references across 5 CLI files; current export/call line locations were recorded, including source-aware prefetch at version-check.ts:242 and :244.
• 13:27: Search found exactly 12 legacy-source-affinity references in packages/cli/test/lib/delta-upgrade.test.ts; tests cover legacy stable/nightly resolution, attempt, and prefetch without Toolkit access.