Distillation

Date: Sep 10, 2026

• 🔴 (04:38) User specified that callers must always pass field when constructing a ValidationError; unfielded validation errors collapse into one Sentry fingerprint.
• 🟡 (04:38) packages/cli/src/lib/errors.ts adds buildValidationMessage(headline: string, examples: string[], note?: string): string, formatting a validation headline followed by an optional blank line and Try: section with each example indented by 2 spaces, plus an optional blank line and Note: ${note} diagnostic section.
• 🟡 (04:38) packages/cli/src/lib/errors.ts adds validationError(headline: string, examples: string[], field?: string, note?: string): ValidationError, which wraps buildValidationMessage() and supplies the field name to ValidationError.
• 🟡 (04:38) packages/cli/src/lib/errors.ts defines AbortError extends Error with name = "AbortError" to follow the cancellation-detection convention already used in version-check.ts, sentry-client.ts, and binary.ts; cancellation errors are intended to be silently swallowed.
• 🟡 (04:38) packages/cli/src/lib/release-notes.ts documents that release-note parsing uses marked.lexer() for AST-based section extraction and retains exactly 3 user-facing categories: 1. New Features (✨), sourced from ### New Features sections or feat: commits; 2. Bug Fixes (🐛), sourced from ### Bug Fixes sections or fix: commits; 3. Performance (⚡), sourced from ### Performance sections or perf: commits. All other categories are filtered out.
• 🟡 (04:38) packages/cli/src/lib/release-notes.ts defines buildNightlyChangelogSummary(commits, fromVersion, toVersion, maxItems?), separating nightly changelog construction from fetching for testability; it parses commit messages with parseCommitMessages() and passes the resulting sections to buildSummaryFromSections().
• 🟡 (04:38) packages/cli/src/lib/release-notes.ts defaults its upgrade source to PRIMARY_UPGRADE_SOURCE.
• 🟡 (04:38) packages/cli/src/lib/version-check.ts now imports type UpgradeSource from ./binary.js and replaces fetchLatestFromGitHub / fetchLatestNightlyVersion imports with source-aware fetchLatestFromGitHubWithSource / fetchLatestNightlyVersionWithSource from ./upgrade.js.
• 🔴 (04:38) User specified that checkForUpdateInBackgroundImpl() never throws: all errors are caught and reported to Sentry.
• 🟡 (04:38) checkForUpdateInBackgroundImpl() in packages/cli/src/lib/version-check.ts remains fire-and-forget and non-blocking; if shouldCheckForUpdate() throws because DB access failed, it calls Sentry.captureException(error) and returns without crashing the CLI.
• 🔴 (04:38) User specified that getUpdateNotificationWithCopy() never throws: on error it returns null, catches the error, and reports it to Sentry.
• 🟡 (04:38) getUpdateNotificationWithCopy(formatNotification) in packages/cli/src/lib/version-check.ts returns null when the CLI is up to date, cached version information is absent, notification is rate-limited, stderr is non-TTY, or an error occurs. Its first gate checks isStderrTTY().
• 🟡 (04:38) When getUpdateNotificationWithCopy() returns a non-null update message, it persists last_notified = now through markUpdateNotified, causing later invocations within the rate-limit window to return null.