de-shell 0.2.0__py3-none-any.whl

de_shell/js/main/sentryEnvelope.ts

@@ -0,0 +1,100 @@
+/**
+ * sentryEnvelope.ts — the wire format for a problem report, with no I/O.
+ *
+ * Sentry's ingest API is a documented HTTP endpoint, and a report is a small
+ * JSON document posted to it. That is the whole integration, so this is written
+ * against the protocol rather than against `@sentry/electron`: the SDK's value
+ * is automatic crash capture, and reports here are only ever sent because
+ * somebody clicked a button. Skipping it keeps a native crash handler out of a
+ * hardened-runtime, notarized macOS build and keeps the payload something a
+ * maintainer can read.
+ *
+ * Everything here is pure, so the parts that are easy to get wrong — the DSN
+ * split, the auth header, the envelope's length-prefixed framing — are unit
+ * tested on every OS without a network.
+ *
+ * Protocol reference: https://develop.sentry.dev/sdk/envelopes/
+ */
+
+/** The pieces of a DSN that the ingest request actually needs. */
+export interface SentryTarget {
+  /** Full URL to POST an envelope to. */
+  endpoint: string
+  /** The DSN's public key, for the X-Sentry-Auth header. */
+  publicKey: string
+  /** The DSN with any secret stripped — envelope headers carry it verbatim. */
+  dsn: string
+}
+
+/**
+ * Split a Sentry DSN into what an ingest POST needs, or null if it isn't one.
+ *
+ * A DSN looks like `https://<publicKey>@<host>/<projectId>`; older ones carry
+ * `<publicKey>:<secret>@`, and the secret is not used by the envelope endpoint.
+ * Returning null (rather than throwing) is what lets a build ship with no DSN
+ * configured and fall back to writing the report to disk.
+ */
+export function parseSentryDsn(dsn: string | undefined | null): SentryTarget | null {
+  if (!dsn) return null
+  let url: URL
+  try {
+    url = new URL(dsn.trim())
+  } catch {
+    return null
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') return null
+  const publicKey = url.username
+  const projectId = url.pathname.replace(/^\/+/, '').replace(/\/+$/, '')
+  if (!publicKey || !projectId || !/^\d+$/.test(projectId)) return null
+  const base = `${url.protocol}//${url.host}`
+  return {
+    endpoint: `${base}/api/${projectId}/envelope/`,
+    publicKey,
+    dsn: `${url.protocol}//${publicKey}@${url.host}/${projectId}`,
+  }
+}
+
+/** The `X-Sentry-Auth` header value for a target. */
+export function sentryAuthHeader(target: SentryTarget, client: string): string {
+  return [
+    'Sentry sentry_version=7',
+    `sentry_client=${client}`,
+    `sentry_key=${target.publicKey}`,
+  ].join(', ')
+}
+
+/**
+ * A 32-character lowercase hex id, the shape Sentry requires for `event_id`.
+ * Takes its randomness from the caller so this file stays pure and testable.
+ */
+export function formatEventId(bytes: Uint8Array): string {
+  let hex = ''
+  for (const b of bytes) hex += b.toString(16).padStart(2, '0')
+  return hex.slice(0, 32).padEnd(32, '0')
+}
+
+/**
+ * Frame an event as a Sentry envelope: newline-delimited JSON, where each item
+ * is preceded by a header naming its type and byte length. The length is in
+ * BYTES, not characters — a report containing a non-ASCII path or a stack trace
+ * with a smart quote would be rejected if this counted characters.
+ */
+export function buildEnvelope(
+  target: SentryTarget,
+  event: Record<string, unknown>,
+  sentAt: string,
+): string {
+  const body = JSON.stringify(event)
+  const length = Buffer.byteLength(body, 'utf8')
+  const envelopeHeader = JSON.stringify({
+    event_id: event.event_id,
+    sent_at: sentAt,
+    dsn: target.dsn,
+  })
+  const itemHeader = JSON.stringify({
+    type: 'event',
+    content_type: 'application/json',
+    length,
+  })
+  return `${envelopeHeader}\n${itemHeader}\n${body}\n`
+}

de_shell/js/main/updater.ts

@@ -0,0 +1,322 @@
+/**
+ * updater.ts — electron-updater wiring (check / download / install, stable vs
+ * beta channel).
+ *
+ * The GitHub `publish` provider (electron-builder.yml) is what release.yml
+ * populates: each tagged release gets latest.yml / latest-mac.yml /
+ * latest-linux.yml alongside the installers, which is what autoUpdater reads
+ * to detect a new version per platform. Plain vX.Y.Z tags are regular GitHub
+ * releases; vX.Y.Z-rc.N/-beta.N tags are marked `prerelease` (release.yml's
+ * `channel` job) — `allowPrerelease` is what gates whether autoUpdater will
+ * offer those to a given install.
+ *
+ * CHANNEL DEFAULT FOLLOWS THE RUNNING BUILD. The default channel is derived from
+ * THIS build's own version: a prerelease build (…-rc.N) tracks beta, a plain
+ * X.Y.Z tracks stable (defaultChannelForVersion in updaterErrors.ts). So an rc
+ * install checks the beta feed (where its updates actually are) instead of the
+ * stable feed — which, with no stable release published yet, would 404 and error.
+ * An explicit user choice (the dialog radio, persisted) always overrides the
+ * default. And a "no release for this channel" result is reported as up-to-date,
+ * not an error (isNoReleaseForChannel).
+ *
+ * autoDownload is OFF: check -> tell the renderer -> user clicks "Download" ->
+ * we call downloadUpdate() -> "Restart to install" -> quitAndInstall(). This
+ * matches the "click here to update" ask (not a silent background install).
+ *
+ * HARDENING (flaky GitHub can HANG, not just crash): every network step is
+ * bounded by a timeout so a half-open connection can't wedge the UI in
+ * 'checking'/'downloading' forever (with the "Check Now" button disabled in
+ * exactly those states → unrecoverable). A stall detector watches the download
+ * for silence. Any timeout/error leaves the updater RECHECKABLE (the in-flight
+ * guard clears), raw electron-updater strings are mapped to friendly text, and
+ * quitAndInstall() can no longer throw the process down.
+ */
+import { app, BrowserWindow } from 'electron'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { autoUpdater } from 'electron-updater'
+import { friendlyError, defaultChannelForVersion } from './updaterErrors'
+import { channel } from './config'
+import { stopBackend } from './backendProcess'
+import { recordProblem } from './problemLog'
+
+export type UpdateChannel = 'stable' | 'beta'
+
+export type UpdateStatus =
+  | { state: 'idle' }
+  | { state: 'checking' }
+  | { state: 'available'; version: string; releaseNotes?: string }
+  | { state: 'not-available' }
+  | { state: 'downloading'; percent: number }
+  | { state: 'downloaded'; version: string }
+  | { state: 'error'; message: string }
+
+// Bound the two network steps. A flaky/half-open GitHub connection otherwise
+// leaves autoUpdater's promise pending forever (the 'error' event never fires),
+// wedging the UI in 'checking'/'downloading'. Mirrors the PDF_EXPORT_TIMEOUT_MS
+// race idiom in index.ts.
+const CHECK_TIMEOUT_MS = 30_000
+// The download reports periodic 'download-progress' events; if none arrives for
+// this long while 'downloading', the transfer has stalled (a half-open socket
+// mid-stream doesn't reject, it just goes quiet).
+const DOWNLOAD_STALL_MS = 60_000
+
+let win: BrowserWindow | null = null
+let channelFilePath = ''
+let userDataDir = ''
+let lastStatus: UpdateStatus = { state: 'idle' }
+
+// In-flight guards. `checkInFlight` prevents overlapping checks AND is what a
+// timeout/error must CLEAR so a subsequent checkForUpdates() isn't blocked by a
+// stale belief that a check is still running (the "guaranteed recovery" rule).
+let checkInFlight = false
+let checkTimer: ReturnType<typeof setTimeout> | null = null
+let downloadStallTimer: ReturnType<typeof setTimeout> | null = null
+
+function clearCheckTimer(): void {
+  if (checkTimer) { clearTimeout(checkTimer); checkTimer = null }
+}
+function clearDownloadStallTimer(): void {
+  if (downloadStallTimer) { clearTimeout(downloadStallTimer); downloadStallTimer = null }
+}
+
+// friendlyError lives in updaterErrors.ts (pure, dependency-free) so it's unit-
+// testable with node:test on every OS. Imported above; re-exported to keep the
+// existing public API (some callers/tests import it from updater.ts).
+export { friendlyError } from './updaterErrors'
+
+/** Every error/timeout path funnels through here so state stays consistent:
+ *  friendly text out, in-flight guard + timers cleared so a retry works. */
+function reportError(rawMessage: string): void {
+  recordProblem('updater', rawMessage)
+  checkInFlight = false
+  clearCheckTimer()
+  clearDownloadStallTimer()
+  sendStatus({ state: 'error', message: friendlyError(rawMessage) })
+}
+
+function sendStatus(status: UpdateStatus): void {
+  lastStatus = status
+  if (win && !win.isDestroyed() && !win.webContents.isDestroyed()) {
+    win.webContents.send(channel('update-status'), status)
+  }
+}
+
+export function getLastUpdateStatus(): UpdateStatus {
+  return lastStatus
+}
+
+/** Read the effective update channel. An EXPLICIT persisted choice (the user
+ *  flipped the radio) always wins; otherwise the default follows the RUNNING
+ *  build's own version — a prerelease build (…-rc.N) tracks beta, a plain X.Y.Z
+ *  tracks stable. This is what stops an rc install from fruitlessly checking the
+ *  (non-existent) stable channel and erroring. Electron-side storage, separate
+ *  from the app's own settings file — readable before the Python sidecar is up. */
+export function readUpdateChannel(): UpdateChannel {
+  try {
+    const raw = readFileSync(channelFilePath, 'utf8').trim()
+    if (raw === 'beta' || raw === 'stable') return raw
+    // Any other/empty content → fall through to the version-derived default.
+  } catch {
+    // No persisted choice yet → derive from this build's version.
+  }
+  return defaultChannelForVersion(appVersion())
+}
+
+/** The running app's version. Wrapped so it's overridable/testable and safe if
+ *  called before `app` is ready (falls back to a stable-looking version). */
+function appVersion(): string {
+  try {
+    return app.getVersion()
+  } catch {
+    return '0.0.0'
+  }
+}
+
+export function setUpdateChannel(channel: UpdateChannel): void {
+  autoUpdater.allowPrerelease = channel === 'beta'
+  try {
+    mkdirSync(userDataDir, { recursive: true })
+    writeFileSync(channelFilePath, channel, 'utf8')
+  } catch (err) {
+    console.error('[updater] failed to persist update channel:', err)
+  }
+}
+
+/** Wire autoUpdater events + do the initial channel read. Call once from
+ *  app.whenReady() after the window exists (there's somewhere to show a
+ *  result). Does NOT check for updates itself — see checkForUpdates(). */
+export function initUpdater(mainWindow: BrowserWindow, userData: string): void {
+  win = mainWindow
+  userDataDir = userData
+  channelFilePath = join(userData, 'update-channel.json')
+
+  autoUpdater.autoDownload = false
+  autoUpdater.autoInstallOnAppQuit = false
+  autoUpdater.allowPrerelease = readUpdateChannel() === 'beta'
+
+  autoUpdater.on('checking-for-update', () => sendStatus({ state: 'checking' }))
+
+  autoUpdater.on('update-available', (info) => {
+    // A definite result arrived → the check is no longer in flight and its
+    // timeout must not later fire a spurious "timed out" over this state.
+    checkInFlight = false
+    clearCheckTimer()
+    sendStatus({ state: 'available', version: info.version, releaseNotes: releaseNotesText(info) })
+  })
+
+  autoUpdater.on('update-not-available', () => {
+    checkInFlight = false
+    clearCheckTimer()
+    sendStatus({ state: 'not-available' })
+  })
+
+  autoUpdater.on('download-progress', (progress) => {
+    // Each progress tick proves the transfer is alive — re-arm the stall watch.
+    armDownloadStall()
+    sendStatus({ state: 'downloading', percent: Math.round(progress.percent) })
+  })
+
+  autoUpdater.on('update-downloaded', (info) => {
+    clearDownloadStallTimer()
+    sendStatus({ state: 'downloaded', version: info.version })
+  })
+
+  // electron-updater surfaces network + verification failures here. But a
+  // "no release found for this channel" error (e.g. a STABLE build/channel when
+  // only prereleases exist yet — no stable release published) is NOT a failure —
+  // it means "you're up to date on your channel". Report THAT as not-available so
+  // the user sees a calm "up to date", not a scary error. Everything else routes
+  // through reportError (friendly + recheckable).
+  autoUpdater.on('error', (err) => {
+    const msg = err?.message ?? String(err)
+    if (isNoReleaseForChannel(msg)) {
+      checkInFlight = false
+      clearCheckTimer()
+      sendStatus({ state: 'not-available' })
+      return
+    }
+    reportError(msg)
+  })
+}
+
+/** Recognise electron-updater's "there is no release matching this channel" error
+ *  — the feed / release simply doesn't exist for the channel we asked for (a
+ *  stable build when only prereleases have shipped). That's "up to date", not a
+ *  fault. Kept conservative: only the shapes electron-updater/GitHubProvider emit
+ *  for a genuinely-absent release, so a real 404-from-network still surfaces. */
+function isNoReleaseForChannel(msg: string): boolean {
+  const s = String(msg || '')
+  return /Unable to find latest version on GitHub|No published versions on GitHub|latest-mac\.yml.*not found|Cannot find channel|No version found/i.test(s)
+}
+
+/** (Re)arm the download stall watchdog: if no progress event lands within
+ *  DOWNLOAD_STALL_MS, treat the transfer as failed (recheckable). */
+function armDownloadStall(): void {
+  clearDownloadStallTimer()
+  downloadStallTimer = setTimeout(() => {
+    downloadStallTimer = null
+    // Only fires while we still believe we're downloading — a completed/errored
+    // download clears the timer, so reaching here means genuine silence.
+    if (lastStatus.state === 'downloading') {
+      reportError('The download stalled — check your connection and try again.')
+    }
+  }, DOWNLOAD_STALL_MS)
+}
+
+function releaseNotesText(info: { releaseNotes?: string | Array<{ note?: string | null }> | null }): string | undefined {
+  if (typeof info.releaseNotes === 'string') return info.releaseNotes
+  if (Array.isArray(info.releaseNotes)) {
+    return info.releaseNotes.map((n) => n.note ?? '').filter(Boolean).join('\n\n')
+  }
+  return undefined
+}
+
+/** Force the updater back to a neutral, checkable state. Exposed so any external
+ *  recovery (e.g. a renderer "Retry" that wants a clean slate) can reset it; the
+ *  error path already leaves it recheckable, so this is belt-and-braces. */
+export function resetToIdle(): void {
+  checkInFlight = false
+  clearCheckTimer()
+  clearDownloadStallTimer()
+  sendStatus({ state: 'idle' })
+}
+
+/** Manual or startup check. Safe to call repeatedly — an in-flight check is a
+ *  no-op (guarded), and a prior timed-out/errored check has already cleared the
+ *  guard so a retry proceeds. Not packaged (dev/e2e) -> no-op, since there's no
+ *  installed app for electron-updater to reason about updating. */
+export function checkForUpdates(): void {
+  if (!app.isPackaged) {
+    sendStatus({ state: 'not-available' })
+    return
+  }
+  if (checkInFlight) return
+  checkInFlight = true
+
+  // Bound the check: a half-open GitHub connection never rejects the promise nor
+  // fires 'error', so without this the UI wedges in 'checking' forever with the
+  // "Check Now" button disabled. On timeout report + clear the guard so a retry
+  // works (mirrors index.ts's PDF_EXPORT_TIMEOUT_MS race).
+  clearCheckTimer()
+  checkTimer = setTimeout(() => {
+    checkTimer = null
+    if (checkInFlight) {
+      reportError('Update check timed out — check your connection and try again.')
+    }
+  }, CHECK_TIMEOUT_MS)
+
+  autoUpdater.checkForUpdates().catch((err) => reportError(err?.message ?? String(err)))
+}
+
+export function downloadUpdate(): void {
+  // A download that never starts producing progress (immediate half-open) would
+  // otherwise sit forever — arm the stall watch up front; each progress event
+  // re-arms it, downloaded/error clears it.
+  armDownloadStall()
+  autoUpdater.downloadUpdate().catch((err) => reportError(err?.message ?? String(err)))
+}
+
+/**
+ * Hand off to the downloaded installer.
+ *
+ * The handoff is a RACE, and losing it is what produced the Windows
+ * "SpyDE cannot be closed. Please close it manually and click Retry" dead end:
+ * electron-updater spawns the installer FIRST and only then asks the app to
+ * quit, so for a second or two both are alive. The installer opens by refusing
+ * to touch a directory anything is still running out of — and it counts the
+ * Python sidecar and its Dask workers, not just the app window. Electron's own
+ * quit is too slow and too conditional to win that race on its own, and the
+ * sidecar's tree-kill backstop is on a timer that an exiting process never
+ * lives long enough to fire.
+ *
+ * So: kill the sidecar tree synchronously, hand off, then guarantee this
+ * process is gone whether or not the graceful quit completes. There is nothing
+ * left to save past this point — the user asked to restart into an installer.
+ */
+const HANDOFF_EXIT_MS = 1500
+
+export function quitAndInstall(): void {
+  // The one call that used to be able to throw the process down. If the installer
+  // handoff fails (missing/locked installer, permissions), surface a friendly
+  // recoverable error instead of an uncaught exception crashing the app.
+  try {
+    clearDownloadStallTimer()
+    // Order matters: quitAndInstall() spawns the installer synchronously, so a
+    // throw here means the handoff never started and the app has to keep
+    // running — killing the sidecar first would leave it alive but useless.
+    // Everything after this line happens within microseconds of the spawn,
+    // whole seconds before the installer gets as far as looking for us.
+    autoUpdater.quitAndInstall()
+    stopBackend({ immediate: true })
+    setTimeout(() => { try { app.exit(0) } catch { /* already gone */ } }, HANDOFF_EXIT_MS)
+  } catch (err) {
+    reportError(`Couldn't start the installer — please download manually. (${(err as Error)?.message ?? String(err)})`)
+  }
+}
+
+/** Whether this is a build electron-builder/electron-updater can actually
+ *  act on (a real installed app, not `electron .` dev / the e2e harness). */
+export function updatesSupported(): boolean {
+  return app.isPackaged && existsSync(join(process.resourcesPath, 'app-update.yml'))
+}

de_shell/js/main/updaterErrors.test.ts

@@ -0,0 +1,111 @@
+/**
+ * updater_errors.test.ts — node:test unit tests for the pure updater error mapper.
+ *
+ * Runs on every CI push, every OS (`node --test`, native TS type-stripping on
+ * Node 24+). Guards the "mac auto-update failed spectacularly" regression: a raw
+ * releases.atom XML body must be collapsed to a short line, never passed through.
+ *
+ * Run: `node --test src/main/updater_errors.test.ts` (from electron/), or via the
+ * `test:unit` npm script.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  friendlyError, truncateMessage, isPrereleaseVersion, defaultChannelForVersion,
+} from './updaterErrors.ts'
+
+test('offline / DNS errors → offline message', () => {
+  for (const raw of ['net::ERR_INTERNET_DISCONNECTED', 'getaddrinfo ENOTFOUND github.com', 'EAI_AGAIN']) {
+    assert.match(friendlyError(raw), /offline/i)
+  }
+})
+
+test('timeout errors → try again', () => {
+  for (const raw of ['ETIMEDOUT', 'net::ERR_TIMED_OUT', 'request timed out']) {
+    assert.match(friendlyError(raw), /too long|try again/i)
+  }
+})
+
+test('connection reset/refused → could not reach', () => {
+  for (const raw of ['ECONNRESET', 'net::ERR_CONNECTION_REFUSED', 'socket hang up']) {
+    assert.match(friendlyError(raw), /reach the update server/i)
+  }
+})
+
+test('missing feed / 404 → no update info', () => {
+  for (const raw of ['Cannot find latest-mac.yml', 'HttpError: 404', 'status code 404']) {
+    assert.match(friendlyError(raw), /no update information/i)
+  }
+})
+
+test('RAW ATOM/HTML FEED is collapsed, never passed through (the regression)', () => {
+  const atom = '<?xml version="1.0" encoding="UTF-8"?>\n<feed xmlns="http://www.w3.org/2005/Atom">'
+    + '<entry><id>tag:github.com,2008:Repository/1/v0.2.0-rc.6</id>'.repeat(300) + '</feed>'
+  const out = friendlyError(atom)
+  assert.doesNotMatch(out, /<entry|<feed|<\?xml/i, 'markup leaked into the user message')
+  assert.ok(out.length < 200, `message not collapsed (len ${out.length})`)
+  assert.match(out, /unexpected response|manually/i)
+})
+
+test('a raw <html> error page is collapsed too', () => {
+  const html = '<!DOCTYPE html><html><body>' + '<div>error</div>'.repeat(500) + '</body></html>'
+  const out = friendlyError(html)
+  assert.doesNotMatch(out, /<html|<div|<!DOCTYPE/i)
+  assert.ok(out.length < 200)
+})
+
+test('an unrecognised long single-line blob is truncated, not verbatim', () => {
+  const blob = 'SomeUpstreamError: ' + 'x'.repeat(5000)
+  const out = friendlyError(blob)
+  assert.ok(out.length <= 300, `not truncated (len ${out.length})`)
+  assert.ok(out.endsWith('…'))
+})
+
+test('a short recognisable-enough message passes through (collapsed whitespace)', () => {
+  assert.equal(friendlyError('Update   failed\n  for reason X'), 'Update failed for reason X')
+})
+
+test('truncateMessage collapses whitespace and caps length', () => {
+  assert.equal(truncateMessage('a\n\n  b   c'), 'a b c')
+  const long = 'y'.repeat(400)
+  const t = truncateMessage(long, 100)
+  assert.equal(t.length, 100)
+  assert.ok(t.endsWith('…'))
+})
+
+test('empty / nullish input → empty string, never throws', () => {
+  assert.equal(friendlyError(''), '')
+  // @ts-expect-error deliberately exercising a nullish raw
+  assert.equal(friendlyError(null), '')
+  // @ts-expect-error deliberately exercising an undefined raw
+  assert.equal(friendlyError(undefined), '')
+})
+
+// ── channel detection (rc build → beta, stable build → stable) ────────────────
+
+test('prerelease versions are detected', () => {
+  for (const v of ['0.2.0-rc.8', '0.2.0-rc.1', '1.0.0-beta.2', '2.3.4-alpha.1',
+                   'v0.2.0-rc.8', '0.2.0-rc.8+build.5']) {
+    assert.equal(isPrereleaseVersion(v), true, `${v} should be prerelease`)
+  }
+})
+
+test('plain releases are NOT prerelease', () => {
+  for (const v of ['0.2.0', '1.0.0', 'v2.3.4', '0.2.0+build.5', '10.20.30']) {
+    assert.equal(isPrereleaseVersion(v), false, `${v} should be stable`)
+  }
+})
+
+test('defaultChannelForVersion: rc build → beta, stable build → stable', () => {
+  assert.equal(defaultChannelForVersion('0.2.0-rc.8'), 'beta')
+  assert.equal(defaultChannelForVersion('v1.0.0-beta.1'), 'beta')
+  assert.equal(defaultChannelForVersion('0.2.0'), 'stable')
+  assert.equal(defaultChannelForVersion('1.2.3'), 'stable')
+})
+
+test('channel detection tolerates empty/garbage version', () => {
+  assert.equal(isPrereleaseVersion(''), false)
+  // @ts-expect-error nullish
+  assert.equal(isPrereleaseVersion(null), false)
+  assert.equal(defaultChannelForVersion(''), 'stable')
+})

de_shell/js/main/updaterErrors.ts

@@ -0,0 +1,65 @@
+/**
+ * updater_errors.ts — PURE, dependency-free updater helpers (error mapping +
+ * channel detection).
+ *
+ * Split out of updater.ts (which imports `electron`, so it can't be loaded by a
+ * plain node unit test) so these can be unit-tested with `node:test` on every CI
+ * push, on every OS. The whole point of friendlyError: an updater error must NEVER
+ * reach the UI as a raw blob — the "mac auto-update failed spectacularly"
+ * screenshot was ~10 KB of raw releases.atom XML rendered full-screen because the
+ * fallback returned the provider's message verbatim. See updater_errors.test.ts.
+ */
+
+/** True when a semver string has a prerelease component (-rc.N / -beta.N /
+ *  -alpha.N / any `-suffix`). Used to pick the DEFAULT update channel from the
+ *  running build's OWN version: a prerelease build follows the beta channel, a
+ *  plain X.Y.Z follows stable — so an rc build never fruitlessly looks for a
+ *  (non-existent) stable release. Tolerant of a leading `v` and build metadata
+ *  (`+…`). */
+export function isPrereleaseVersion(version: string): boolean {
+  const v = String(version ?? '').trim().replace(/^v/i, '')
+  // Strip build metadata, then a prerelease is anything after the first '-'.
+  const core = v.split('+')[0]
+  return core.includes('-')
+}
+
+/** The channel a build should follow BY DEFAULT (before any explicit user
+ *  choice): beta if the running build is itself a prerelease, else stable. */
+export function defaultChannelForVersion(version: string): 'stable' | 'beta' {
+  return isPrereleaseVersion(version) ? 'beta' : 'stable'
+}
+
+/** Bound an unrecognised error message so a huge single-line payload can't blow
+ *  out the error box. Collapse whitespace, cap length, keep it one readable line. */
+export function truncateMessage(s: string, max = 300): string {
+  const flat = String(s ?? '').replace(/\s+/g, ' ').trim()
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat
+}
+
+/** Map a raw electron-updater / Chromium-net error to something a user can act
+ *  on. Falls back to a BOUNDED, sanitised version of the raw message when we
+ *  don't recognise it — never the raw blob verbatim. */
+export function friendlyError(raw: string): string {
+  const s = String(raw || '')
+  if (/ERR_INTERNET_DISCONNECTED|ENOTFOUND|EAI_AGAIN|ERR_NAME_NOT_RESOLVED|getaddrinfo/i.test(s)) {
+    return 'You appear to be offline — check your connection and try again.'
+  }
+  if (/ETIMEDOUT|ERR_TIMED_OUT|ERR_CONNECTION_TIMED_OUT|timed out/i.test(s)) {
+    return 'The update server took too long to respond — please try again.'
+  }
+  if (/ERR_CONNECTION_(REFUSED|RESET|CLOSED)|ECONNRESET|ECONNREFUSED|socket hang up/i.test(s)) {
+    return 'Could not reach the update server — please try again.'
+  }
+  if (/latest.*\.yml|Cannot find .*\.yml|status code 404|HttpError: 404|ERR_HTTP_RESPONSE_CODE_FAILURE/i.test(s)) {
+    return 'No update information available right now — please try again later.'
+  }
+  // A provider that can't resolve the platform feed can surface the GitHub
+  // releases.atom body (or an HTML error page) as the error message. That raw
+  // XML/HTML must NEVER reach the UI verbatim — it rendered as a full-screen wall
+  // of markup ("mac auto-update failed spectacularly"). Detect markup / an
+  // oversized blob and collapse it to a short, actionable line.
+  if (/<\?xml|<!DOCTYPE|<feed\b|<entry\b|<html\b|<rss\b/i.test(s)) {
+    return 'The update server returned an unexpected response — please try again later or update manually from GitHub.'
+  }
+  return truncateMessage(s)
+}