Dashboard › cli › Distillation
2259ad2c-d966-4315-bd93-48795ed87391["lore_tm_v1_-mQn8ZXtz5QsodRwnmqOQyeD6nOhOCiVkspsFPsvE-0","lore_tm_v1_0JZWLtJlTSHMTi6dZWY8_RXEsJq_ZTqlqEIxkoxMpOg","lore_tm_v1_el4SEaHvhEtAM55o5FuwsGBSW97Lur5zvifyp7Tpoo4","lore_tm_v1_6Df_hOePnlgjCFAMzyuZfZvaffFOaOdvX903XjPChok","lore_tm_v1_FlA2ALKyi4s5T8h2ni3EXPaj3JDbvpcvQCsraR7MYYg","lore_tm_v1_AE8ad_5G2SKDlQxn_C3Wbd0HqESVHM4OLVR4vSeDd7s","lore_tm_v1_1GoWE7DV3lU2AWm0e4KLqNAcP4rXkQfw2u2CCu5YbLM","lore_tm_v1_rR1iFtIa7iDACyGB65PCqfcADbB_3gT8868LmJ2azvk","lore_tm_v1_97LmM7HWdS_ZTSFQiUcy5EpwcPxJczvA_Ic_VsJvVMQ","lore_tm_v1_FcKq8xvqMe-CtV6fAYBJVmSWomPxqpT83qzQfY_YvRI"]
binpatch public entrypoint describes a reusable, pure-Node (node:* built-ins only), zero-product-coupling binary delta-update engine with two components joined by one README wire contract: (1) an apply core that parses/applies a TRDIFF10/bsdiff patch chain to a binary; (2) discovery that resolves a patch chain through a pluggable SourceStrategy using OCI/GHCR tags or GitHub Release assets, then applies and verifies it. Consumers inject the cache directory, download source, version comparison, progress handling, and telemetry.binpatch public entrypoint exports apply-core APIs from ./bspatch: addDiffChunk, applyPatch, applyPatchChainInMemory, applyPatchToMemory, MAX_OUTPUT_SIZE, offtin, parsePatchHeader, and type PatchHeader.binpatch public entrypoint exports cache APIs from ./patch-cache: types ChainMeta, PatchCache, PatchStepMeta, plus chainFileName, makeCache, and patchFileName.binpatch public entrypoint exports wire-contract constants/types from ./contract: types ChainStep, DeltaResult, InstrumentHook, PatchChain, PatchLink; constants MAX_NIGHTLY_CHAIN_DEPTH, MAX_STABLE_CHAIN_DEPTH, PATCH_TAG_PREFIX, and SIZE_THRESHOLD_RATIO.binpatch public entrypoint exports BinpatchError and type BinpatchErrorReason from ./errors.binpatch library never renders progress; it emits progress events. Its public entrypoint exports types ProgressEvent, ProgressHandler, ProgressPhase, and safeProgress from ./events.binpatch public entrypoint exports discovery/orchestration APIs from ./discover: types DeltaSource, DeltaTelemetry, DeltaUnavailableReason, ResolveAndApplyOpts, SourceStrategy, UnavailableReporter, plus resolveAndApply.binpatch public entrypoint exports GHCR source APIs from ./sources/ghcr: type GhcrSourceConfig, ghcrSource, getPatchFromVersion, getPatchTargetSha256, filterAndSortChainTags, types NightlyChainFailure and StepFailureReason, and validateChainStep.binpatch public entrypoint exports GitHub Release source APIs from ./sources/github-release: extractSha256, extractStableChain, type ExtractStableChainOpts, types GitHubAsset, GitHubRelease, GitHubReleaseSourceConfig, githubReleaseSource, getStableTargetSha256, and types StableChainFailure and StableChainInfo.binpatch public entrypoint exports OciClient and types OciClientConfig, OciLayer, and OciManifest from ./sources/oci.fetchWithUpgradeError has 7 references in packages/cli/src/lib/upgrade.ts: import/reference at line 28 and calls at lines 476, 677, 709, 919, and 933; its implementation is in packages/cli/src/lib/binary.ts line 482.packages/cli/src/lib/binary.ts lines 461–503 define getGitHubHeaders() and fetchWithUpgradeError(url, init, serviceName). getGitHubHeaders() returns Accept: "application/vnd.github.v3+json" and "User-Agent": getUserAgent(). fetchWithUpgradeError() delegates to customFetch(url, init), rethrows an AbortError unchanged, maps TLS certificate errors to new UpgradeError("network_error", buildTlsErrorDetail(error)), and maps other failures to new UpgradeError("network_error", \Failed to connect to ${serviceName}: ${stringifyUnknown(error)}`)`.packages/cli/src/lib/binary.ts lines 505–540 define synchronous replaceBinarySync(tempPath, installPath): on Unix it atomically renames tempPath over installPath; on Windows it attempts installPath → ${installPath}.old, retries after unlinking an existing .old, tolerates a still-failing rename as a possible fresh install, then renames the temp binary into place. The synchronous multi-step sequence is intentional so interruption cannot leave the install path broken.packages/cli/src/lib/binary.ts lines 543–554 document cleanupOldBinary(oldPath): CLI startup removes .old files left by Windows upgrades, but intentionally does not clean .download files because another upgrade may be active; .download cleanup occurs inside the upgrade flow under its exclusive lock.packages/cli/src/lib/release-notes.ts parses stable GitHub Release bodies or nightly conventional commits into structured markdown for renderMarkdown(). It retains exactly 3 user-facing categories in display order: 1. features / “New Features” (✨, feat:), 2. fixes / “Bug Fixes” (🐛, fix:), 3. performance / “Performance” (⚡, perf:); all other categories are filtered out.packages/cli/src/lib/release-notes.ts imports marked/Token/Tokens from marked; compareVersions, getGitHubHeaders, getGitHubReleasesUrl, PRIMARY_UPGRADE_SOURCE, and type UpgradeSource from ./binary.js; customFetch from ./custom-ca.js; type GitHubRelease from ./delta-upgrade.js; and logger from ./logger.js. Its tagged logger is logger.withTag("release-notes").packages/cli/src/lib/release-notes.ts constants include EMOJI_RE=/[\u{2000}-\u{2BFF}\u{FE00}-\u{FE0F}\u{1F000}-\u{1FFFF}]/gu, AUTHOR_SUFFIX_RE=/\s+by\s+@\S+\s+in\s+\[?#\d+\]?(?:\([^)]*\))?\s*$/, NIGHTLY_VERSION_RE=/^[\d.]+(?:-\w+)?-dev\.(\d+)$/, CONVENTIONAL_COMMIT_RE=/^(\w+)(?:\([^)]*\))?:\s*(.+)$/, and VERSION_PREFIX_RE=/^v/.packages/cli/src/lib/release-notes.ts defines ChangeCategory = "features" | "fixes" | "performance", ChangeSection with category and raw markdown, and ChangelogSummary with fromVersion, toVersion, flattened sections, totalItems, truncated, and pre-truncation originalCount.extractSections(body) in packages/cli/src/lib/release-notes.ts returns [] for blank input, tokenizes via marked.lexer(), recognizes only depth-3 (###) top-level section headings after emoji stripping, whitespace trimming, and lowercasing, and retains intervening tokens including depth-4 scope subheadings and list entries.CHANGELOG_MAX_RELEASES in packages/cli/src/lib/release-notes.ts is exactly 30, versus the delta-upgrade cap of 12; GitHub’s per_page maximum is 100, and the comment says 30 covers approximately 6+ months of weekly releases.fetchReleasesForChangelog(source) in packages/cli/src/lib/release-notes.ts requests ${getGitHubReleasesUrl(source)}?per_page=${CHANGELOG_MAX_RELEASES} through customFetch with getGitHubHeaders(). It returns [] on a thrown fetch error, non-OK response, JSON parse failure, or non-array response, logging debug details for fetch, parse, and non-array failures; otherwise it casts the data to GitHubRelease[].fetchStableChangelog(options) accepts fromVersion, toVersion, maxItems, prefetchedReleases, and source; it uses prefetchedReleases when supplied to avoid a duplicate API call, otherwise calls fetchReleasesForChangelog(source), returns null for an empty release list, and delegates to buildChangelogSummaryForSource(..., { maxItems, source }).fetchNightlyChangelog(fromVersion, toVersion, source, maxItems?) derives Unix-second timestamps from nightly versions, returns null if either is invalid, offsets both bounds by +1s because GitHub since is inclusive and until is exclusive, and requests https://api.github.com/repos/${source.githubRepo}/commits?sha=main&since=${sinceDate}&until=${untilDate}&per_page=100.fetchNightlyChangelog() uses customFetch(url, { headers: getGitHubHeaders() }); it returns null on fetch failure, non-OK HTTP status, non-JSON data, a non-array response, or an empty commit array, and otherwise calls buildNightlyChangelogSummary(commits as GitHubCommit[], fromVersion, toVersion, maxItems).mergeSectionsByCategory(releases) in packages/cli/src/lib/release-notes.ts skips releases without a body, runs extractSections(release.body), removes attribution suffixes via stripAttributions(section.markdown), groups markdown by category, and emits merged sections in CATEGORY_ORDER, joining same-category markdown with "\n".buildChangelogSummaryForSource(releases, fromVersion, toVersion, options) in packages/cli/src/lib/release-notes.ts optionally filters release tags by source.tagPrefix, rejects tags without that prefix, strips the prefix and then a leading v, and includes versions strictly greater than fromVersion and less than or equal to toVersion using compareVersions. It returns null when no releases are in range; otherwise it merges category sections and calls buildSummaryFromSections(..., maxItems).buildChangelogSummary(releases, fromVersion, toVersion, maxItems?) handles legacy unprefixed tags by delegating to buildChangelogSummaryForSource without a source; its lower version bound is exclusive and upper bound inclusive.COMMIT_PREFIX_TO_CATEGORY maps exactly feat → features, fix → fixes, and perf → performance.fetchRecentReleases() implementation at packages/cli/src/lib/delta-upgrade.ts line 160, calls/tests at packages/cli/test/lib/delta-upgrade.test.ts lines 843, 855, 865, and 874, and a comparison reference in packages/cli/src/lib/release-notes.ts line 580.versionExists is implemented in packages/cli/src/lib/upgrade.ts line 700 and called by packages/cli/src/commands/cli/upgrade.ts line 297 as if (!(await versionExists(lookupMethod, target))).packages/cli/test/lib/upgrade.test.ts contains 21 listed versionExists call/assertion matches across lines 601–801, covering package methods "curl", "npm", "pnpm", "bun", "brew", and "yarn"; versions "1.0.0", "99.99.99", "0.14.0-dev.1772661724", and "0.14.0-dev.9999999999"; explicit UPGRADE_SOURCES[0]; and network-error expectations using UpgradeError.