gloomberb 0.18.2 → 0.18.4

package/src/types/plugin.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
-import type { HeadlessPaneContext, HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessPaneOptionDef } from "./headless";
+import type { HeadlessPaneArgumentDef, HeadlessPaneContext, HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessPaneOptionDef } from "./headless";
 
 export type {
   HeadlessArgumentExpansion,
@@ -186,9 +186,23 @@ export interface PaneDef {
   /**
    * Options a rendered-view report takes (`fn OMON AAPL --strikes 10`):
    * each sets the pane setting of its key, is checked by its `normalize`, and
-   * is listed with its example by `gloomberb catalog`.
+   * is listed with its example by `gloom catalog`.
    */
   reportOptions?: readonly PaneReportOptionDef[];
+  /**
+   * A rendered-view report that takes its `reportOptions` and nothing else:
+   * any other option is refused with the ones it takes (`fn FUT --bogus 1`),
+   * as a `headless` report refuses one, instead of being set as a pane
+   * setting of that name.
+   */
+  reportOptionsOnly?: boolean;
+  /**
+   * What a rendered-view report takes after the function, for a pane whose
+   * template reads it with no shortcut to say so (X Feed's query): the
+   * catalog lists it, and `fn` refuses an argument from a function that
+   * declares none here, in its shortcut or in a `headless` model.
+   */
+  reportArgument?: Pick<HeadlessPaneArgumentDef, "kind" | "placeholder" | "description" | "optional">;
   /**
    * Lines a rendered-view report prints above its table, from the settings it
    * ran with: what the default view leaves out and how to see more. `--json`
@@ -207,7 +221,7 @@ export interface PaneDef {
   reportLockNote?(lock: PaneLock): string | Promise<string>;
   /**
    * What a rendered-view report needs before it shows anything, such as a
-   * sign-in: `gloomberb catalog` lists it under Requires, as it does a
+   * sign-in: `gloom catalog` lists it under Requires, as it does a
    * `headless` model's `discovery.dataRequirements`.
    */
   reportRequirements?: readonly string[];
@@ -260,9 +274,11 @@ export type PanePersonalData = "holdings" | "account" | "messages" | "personal";
 /**
  * An option of a rendered-view report, which sets the pane setting of its key,
  * or of `settingKey` when the flag reads better than the setting's name
- * (`--columns` for `optionColumnIds`).
+ * (`--columns` for `optionColumnIds`); with `pluginState`, the pane state the
+ * view reads it from (a workspace's tab), and the setting too when it also
+ * names a `settingKey`.
  */
-export interface PaneReportOptionDef extends Omit<HeadlessPaneOptionDef, "pluginState"> {
+export interface PaneReportOptionDef extends HeadlessPaneOptionDef {
   /** The value's name in the catalog's flag, `--currencies <codes>`; the type when absent. */
   placeholder?: string;
   /** The option in use as typed after the function, such as `--currencies USD,ZAR,NGN`; the catalog shows it as an example. */
@@ -349,11 +365,29 @@ interface PaneSettingOrderedMultiSelectField extends PaneSettingFieldBase {
   searchable?: boolean;
 }
 
+/** What an action row says of its own action (docs/pane-conventions.md, "Row messages"). */
+export interface PaneSettingRowNote {
+  /** A short state, where the row's action label is: `Connecting…`, `Sign-in failed`. */
+  status: string;
+  /** The full reason or the next step, in place of the row's description. */
+  text?: string;
+  tone: "warning" | "negative";
+}
+
 export interface PaneSettingActionContext extends PaneSettingsContext {
   surface: "pane-dialog" | "command-bar";
   close(): void;
   openCommandBar(query?: string): void;
   notify(notification: AppNotificationRequest): void;
+  /**
+   * Says on the row the action runs from what it is doing or what stopped it,
+   * or clears that with null. A success the row's own description and label
+   * show once they change needs no note. False once the row is off screen
+   * (the dialog closed, or the action removed its own field): say it with
+   * `notify` then, as a row that has left a list is a toast. Older hosts do
+   * not pass it.
+   */
+  setRowNote?(note: PaneSettingRowNote | null): boolean;
 }
 
 export type PaneSettingActionHandler = (
@@ -404,12 +438,22 @@ export interface ShortcutArgOption {
   label: string;
 }
 
+/** Why a typed argument opens nothing: the row's text, and the line under it saying what to type instead. */
+export interface ShortcutArgError {
+  message: string;
+  detail?: string;
+}
+
 interface PaneTemplateShortcut {
   prefix: string;
   /** Other mnemonics for the same view (FFIP for WIRP). They open it when typed but are not listed as separate rows. */
   aliases?: readonly string[];
   /** Keep this shortcut executable when typed, but omit its pane from command-bar browse rows. Defaults to true. */
   showInBrowse?: boolean;
+  /**
+   * What the shortcut takes after the prefix. Left out, it takes the argument
+   * the template's `headless` definition declares, as `gloom catalog` lists it.
+   */
   argPlaceholder?: string;
   argKind?: "text" | "ticker" | "ticker-list";
   /**
@@ -430,6 +474,12 @@ interface PaneTemplateShortcut {
    * from it instead of guessing the text; the command may accept others too.
    */
   argOptions?: () => readonly ShortcutArgOption[];
+  /**
+   * Why a typed argument opens nothing, or null when it opens the view:
+   * `PF Nope` names no portfolio or watchlist. The command bar shows it in
+   * place of the function's row, and the pane does not open for it.
+   */
+  argError?: (arg: string, context: PaneTemplateContext) => ShortcutArgError | null;
 }
 
 export interface PaneTemplateCreateOptions {
@@ -507,7 +557,8 @@ export interface WizardStep {
   required?: boolean;
   type?: "text" | "password" | "info" | "select" | "number" | "textarea";
   options?: Array<{ label: string; value: string }>;
-  dependsOn?: { key: string; value: string };
+  /** Shown only while the earlier answer holds the value; with several, while every one does. */
+  dependsOn?: { key: string; value: string } | ReadonlyArray<{ key: string; value: string }>;
   /** Later wizard values to clear when this selection changes from its default. */
   clearOnChange?: string[];
   body?: string[];
@@ -583,6 +634,12 @@ export interface CommandBarSearchProvider {
   minQueryLength?: number;
   /** Default 300. Ignored by `match`. */
   debounceMs?: number;
+  /**
+   * How long `provide` may take once it starts, in ms. Default 8000. Past it
+   * the bar aborts `signal`, drops a late answer and stops showing Searching.
+   * Ignored by `match`.
+   */
+  timeoutMs?: number;
   /**
    * Codes (`CHAT`) after which the provider is still asked, typed alone or
    * with text after them, with the whole query. Every other provider stays
@@ -624,14 +681,14 @@ interface CliCommandHelpOption {
 }
 
 interface CliCommandHelp {
-  /** Heading `gloomberb help` lists the command under. Plugin commands without one share a plugin heading. */
+  /** Heading `gloom help` lists the command under. Plugin commands without one share a plugin heading. */
   group?: string;
   /** Invocations without the leading `gloomberb`, e.g. `quote <symbol...>`. */
   usage?: string[];
   options?: CliCommandHelpOption[];
   /** Complete invocations without the leading `gloomberb`. */
   examples?: string[];
-  /** Extra blocks shown only in the command's own help (`gloomberb help <command>`). */
+  /** Extra blocks shown only in the command's own help (`gloom help <command>`). */
   sections?: CliCommandHelpSection[];
 }
 

package/src/types/price-history.ts

@@ -24,6 +24,8 @@ export interface PriceHistoryResult {
   session?: HistorySession;
   /** Router-selected provider or broker, never its preferred/default source. */
   sourceKey?: string;
+  /** The name of that provider or broker ("Gloom Cloud", a broker), set by the router as it answers. */
+  sourceName?: string;
   /** First date (YYYY-MM-DD) the source vouches for; it excluded earlier prices. */
   coverageStart?: string;
   /** Why nothing before `coverageStart` is served, when the source says: "old-shekel quotes before 1992 are not served". */

package/src/types/ticker.ts

@@ -48,6 +48,13 @@ export interface TickerMetadata {
   broker_contracts?: BrokerContractRef[];
   custom: Record<string, unknown>;
   tags: string[];
+  /**
+   * Lots this listing's row took from rows saved under a vendor's suffixed
+   * key (GARAN.IS:BIST into GARAN:BIST), by that key, each as the fields sync
+   * keeps: a copy an older build or sync brings back is not counted twice.
+   * Bookkeeping, never shown, and no reason on its own to keep a row.
+   */
+  mergedLots?: Record<string, string[]>;
 }
 
 export interface TickerRecord {
@@ -59,6 +66,12 @@ export interface Portfolio {
   name: string;
   description?: string;
   currency: string;
+  /**
+   * Set on a manual portfolio created in a currency (`portfolio create
+   * --currency`): it totals in `currency` whatever the base currency, and its
+   * first holding does not change it.
+   */
+  fixedCurrency?: boolean;
   brokerId?: string;
   brokerInstanceId?: string;
   brokerAccountId?: string;

package/src/types/trading.ts

@@ -1,7 +1,19 @@
 import type { BrokerContractRef } from "./instrument";
 
 type BrokerOrderAction = "BUY" | "SELL";
-export type BrokerOrderType = "MKT" | "LMT" | "STP" | "STP LMT";
+/** `TRAIL` is a trailing stop: its trigger follows the market by `trailingAmount` or `trailingPercent`. */
+export type BrokerOrderType = "MKT" | "LMT" | "STP" | "STP LMT" | "TRAIL";
+/**
+ * Orders a broker holds together as one, and runs itself.
+ * - `bracket`: the order is an entry, with a take-profit limit and a stop-loss stop (one or both) on the other side
+ *   for the same quantity. They work once the entry fills, and one filling cancels the other.
+ * - `oco`: a limit order and a stop order on the same side for the same quantity; one filling cancels the other.
+ */
+export type BrokerOrderClass = "bracket" | "oco";
+/** A trailing stop's distance, in price or in percent of the price. */
+export type BrokerTrailingUnit = "amount" | "percent";
+/** What an order is to the others the broker holds it with. */
+export type BrokerOrderLinkRole = "entry" | "takeProfit" | "stopLoss";
 
 /** Explicit account classification for order confirmation. Missing values are treated as unknown. */
 export type BrokerTradingMode = "simulation" | "live" | "unknown";
@@ -31,6 +43,14 @@ export interface BrokerTradingCapabilities {
    * for a combo contract (`secType: "BAG"`); omit when the broker takes none.
    */
   maxLegs?: number;
+  /**
+   * Linked orders the broker places and runs itself. The ticket never makes one
+   * from separate orders: a class missing here is shown unavailable, and an
+   * adapter that omits it never receives it.
+   */
+  orderClasses?: BrokerOrderClass[];
+  /** How a trailing stop (`TRAIL` in `orderTypes`) can be set: by price, by percent or both. */
+  trailing?: BrokerTrailingUnit[];
 }
 
 export interface BrokerCashBalance {
@@ -49,6 +69,11 @@ export interface BrokerAccount {
   currency?: string;
   /** "cloud" is a connection held by the user's Gloom Cloud account. */
   source?: "gateway" | "flex" | "cloud";
+  /**
+   * The account's own number at its brokerage, for one held through an
+   * aggregator (SnapTrade). Another profile that holds that number keeps it.
+   */
+  brokerageAccountId?: string;
   updatedAt?: number;
   asOfDate?: string;
   netLiquidation?: number;
@@ -128,6 +153,20 @@ export interface BrokerOrderRequest {
    * `limitPrice` is the positive net price of one spread.
    */
   legs?: BrokerOrderLeg[];
+  /** A trailing stop's distance in price. Exactly one of this and `trailingPercent` with `TRAIL`. */
+  trailingAmount?: number;
+  /** A trailing stop's distance in percent, such as 2 for 2%. */
+  trailingPercent?: number;
+  /**
+   * Orders placed with this one and held together by the broker. A bracket
+   * takes `takeProfitPrice`, `stopLossPrice` or both; an OCO is this limit order
+   * (`orderType: "LMT"`) with a stop at `stopLossPrice`.
+   */
+  orderClass?: BrokerOrderClass;
+  /** A bracket's take-profit limit. */
+  takeProfitPrice?: number;
+  /** A bracket's stop-loss trigger, or an OCO's stop. */
+  stopLossPrice?: number;
 }
 
 export interface BrokerOrderPreview {
@@ -149,6 +188,17 @@ export interface BrokerOrderPreview {
   commission?: number;
   commissionCurrency?: string;
   warningText?: string;
+  /**
+   * Where the figures come from, for a broker that says: its own preview, or none for this order
+   * (the ticket then names each figure "Not available", never zero). Omitted by a broker that does not say.
+   */
+  impactSource?: "broker" | "unavailable";
+  /** Whom the figures are credited to, e.g. "Robinhood via SnapTrade". */
+  impactSourceLabel?: string;
+  cashBefore?: number;
+  cashAfter?: number;
+  /** The broker's terms for these figures, shown with them before the order is confirmed. */
+  disclosure?: string;
 }
 
 export interface BrokerOrder {
@@ -174,6 +224,14 @@ export interface BrokerOrder {
   contract: BrokerContractRef;
   /** A multi-leg order's legs, as on its request. */
   legs?: BrokerOrderLeg[];
+  trailingAmount?: number;
+  trailingPercent?: number;
+  /**
+   * Orders the broker holds together (a bracket's entry and exits, an OCO
+   * pair) share this id; the broker cancels or activates them as one fills.
+   */
+  linkGroup?: string;
+  linkRole?: BrokerOrderLinkRole;
 }
 
 export interface BrokerExecution {

package/src/ui/ascii-font.ts

@@ -69,9 +69,21 @@ const GLOOMBERB_WORDMARK = [
   "▝▀  ▘▝▀ ▝▀ ▘▝ ▘▀▀ ▝▀▘▘  ▀▀ ",
 ];
 
+/** The first five letters of the wordmark above. */
+const GLOOM_WORDMARK = GLOOMBERB_WORDMARK.map((line) => line.slice(0, 15));
+
+/**
+ * The drawn wordmarks, by the text they spell. The app is Gloom; chart
+ * screenshots keep the Gloomberb watermark.
+ */
+const WORDMARKS = new Map<string, string[]>([
+  ["gloom", GLOOM_WORDMARK],
+  ["gloomberb", GLOOMBERB_WORDMARK],
+]);
+
 export function renderAsciiText(text: string, font: AsciiFontName = "tiny"): string[] {
   if (font === "wordmark") {
-    return text.trim().toLowerCase() === "gloomberb" ? GLOOMBERB_WORDMARK : [text];
+    return WORDMARKS.get(text.trim().toLowerCase()) ?? [text];
   }
 
   const lines = ["", ""];

package/src/ui/host.tsx

@@ -708,7 +708,12 @@ export interface RendererHost {
   requestExit(): void;
   startWindowDrag?(): Promise<void> | void;
   controlWindow?(action: "minimize" | "toggle-maximize" | "close"): Promise<void> | void;
-  openExternal(url: string): Promise<void>;
+  /**
+   * Opens a link in the person's browser. Resolves false when no browser could
+   * be shown from here (a terminal over SSH, or no opener installed), so the
+   * caller can show the link instead; void when the host cannot tell.
+   */
+  openExternal(url: string): Promise<boolean | void>;
   copyText(text: string): Promise<void>;
   copyPngImage?(pngBase64: string): Promise<void>;
   readText(): Promise<string>;

package/src/updater/command-names.ts

@@ -0,0 +1,175 @@
+import { lstatSync, symlinkSync } from "fs";
+import { lstat, readFile, readlink, stat, symlink, writeFile } from "fs/promises";
+import { basename, dirname, join, resolve } from "path";
+
+/**
+ * The terminal command is `gloom`. `gloomberb`, its name before 0.19, keeps
+ * working beside it, for scripts and habits.
+ *
+ * An install from before the rename has only `gloomberb`, and the ways it
+ * updates (the standalone binary replacing itself, the desktop app replacing
+ * its bundle) never add a command. So the new build adds `gloom` beside
+ * `gloomberb` when it runs. A `gloom` that is already there, whatever it is,
+ * is left alone, and a folder this user cannot write is skipped.
+ *
+ * The desktop app looks through PATH, which can hold a slow or unreachable
+ * network folder, so its half only reads and writes asynchronously and runs
+ * once the app is up.
+ */
+const COMMAND_NAME = "gloom";
+const LEGACY_COMMAND_NAME = "gloomberb";
+
+/** The file the desktop app's Windows command runs, which tells its `gloomberb.cmd` from another program's. */
+const WINDOWS_SHIM_ENTRY = "gloomberb-tui\\tui-entry.js";
+
+function pathExists(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    // Intentional ignore: a missing path, or one this user cannot see; either way nothing is added there.
+    return false;
+  }
+}
+
+function addSymlink(target: string, path: string): string | null {
+  try {
+    symlinkSync(target, path);
+    return path;
+  } catch {
+    // Intentional ignore: a read-only or root-owned folder keeps the command it has.
+    return null;
+  }
+}
+
+/**
+ * For the standalone binary, which updates by replacing itself: links the
+ * other name to it in its own folder, `gloom` beside a `gloomberb` installed
+ * before the rename (or `gloomberb` beside a `gloom`). Returns the link it
+ * added, or null. A binary under any other name is left as it is.
+ */
+export function linkStandaloneCommand(execPath: string): string | null {
+  const name = basename(execPath);
+  const other = name === COMMAND_NAME ? LEGACY_COMMAND_NAME : name === LEGACY_COMMAND_NAME ? COMMAND_NAME : null;
+  if (!other) return null;
+  const path = join(dirname(execPath), other);
+  if (pathExists(path)) return null;
+  // Relative, as install.sh links it, so the pair still works if the folder moves.
+  return addSymlink(name, path);
+}
+
+/** Homebrew's command folders on Apple Silicon and on Intel. */
+const HOMEBREW_BINS = ["/opt/homebrew/bin", "/usr/local/bin"];
+
+/**
+ * Where a Mac keeps the desktop app's command: install.sh's folder, Homebrew's,
+ * then the rest of PATH. A GUI app's PATH rarely has the first ones, so they
+ * are named outright.
+ */
+function macCommandFolders(homeDir: string, pathEnv: string, homebrewBins: readonly string[]): string[] {
+  return [...new Set([
+    homeDir ? join(homeDir, ".local", "bin") : "",
+    ...homebrewBins,
+    ...pathEnv.split(":"),
+  ].filter(Boolean))];
+}
+
+async function pathExistsAsync(path: string, followLinks = false): Promise<boolean> {
+  try {
+    await (followLinks ? stat(path) : lstat(path));
+    return true;
+  } catch {
+    // Intentional ignore: a missing path, or one this user cannot see; either way nothing is added there.
+    return false;
+  }
+}
+
+/**
+ * Next to a `gloomberb` link into an app bundle, adds `gloom` linked to the
+ * same bundle's `gloom`. The target is written the way Homebrew writes its
+ * own links, so a later `brew upgrade` sees the link as its own.
+ */
+async function linkMacCommand(folder: string): Promise<string | null> {
+  let target: string;
+  try {
+    target = await readlink(join(folder, LEGACY_COMMAND_NAME));
+  } catch {
+    // Intentional ignore: not there, or not a link; a standalone binary adds its own when it runs.
+    return null;
+  }
+  const absolute = resolve(folder, target);
+  if (!absolute.endsWith(`.app/Contents/Resources/${LEGACY_COMMAND_NAME}`)) return null;
+  const bundleCommand = join(dirname(absolute), COMMAND_NAME);
+  const path = join(folder, COMMAND_NAME);
+  if (!(await pathExistsAsync(bundleCommand, true)) || await pathExistsAsync(path)) return null;
+  try {
+    await symlink(bundleCommand, path);
+    return path;
+  } catch {
+    // Intentional ignore: a read-only or root-owned folder keeps the command it has.
+    return null;
+  }
+}
+
+/**
+ * Next to the desktop app's `gloomberb.cmd`, adds a `gloom.cmd` with the same
+ * contents. The command finds the app from its own folder, so the copy runs
+ * the same app.
+ */
+async function copyWindowsCommand(folder: string): Promise<string | null> {
+  let shim: string;
+  try {
+    shim = await readFile(join(folder, `${LEGACY_COMMAND_NAME}.cmd`), "utf8");
+  } catch {
+    // Intentional ignore: no gloomberb.cmd, so this PATH folder belongs to another program.
+    return null;
+  }
+  if (!shim.includes(WINDOWS_SHIM_ENTRY)) return null;
+  const path = join(folder, `${COMMAND_NAME}.cmd`);
+  if (await pathExistsAsync(path)) return null;
+  try {
+    await writeFile(path, shim, { flag: "wx" });
+    return path;
+  } catch {
+    // Intentional ignore: a folder this user cannot write keeps the command it has.
+    return null;
+  }
+}
+
+interface DesktopCommandOptions {
+  platform: string;
+  homeDir: string;
+  /** PATH as the app sees it. */
+  pathEnv: string;
+  /** `%LOCALAPPDATA%`, where the Windows installer puts the app by default. */
+  localAppData?: string;
+  /** Homebrew's command folders; tests pass none. */
+  homebrewBins?: readonly string[];
+}
+
+/**
+ * For the desktop app, which updates by replacing its bundle: adds `gloom`
+ * wherever an installer put the app's `gloomberb` command (install.sh and
+ * Homebrew links on a Mac, the installer's PATH folder on Windows). Resolves
+ * to the commands it added. Folders are looked at side by side, so a slow one
+ * holds up only itself.
+ */
+export async function linkDesktopCommands({
+  platform,
+  homeDir,
+  pathEnv,
+  localAppData,
+  homebrewBins = HOMEBREW_BINS,
+}: DesktopCommandOptions): Promise<string[]> {
+  let added: Array<string | null> = [];
+  if (platform === "darwin") {
+    added = await Promise.all(macCommandFolders(homeDir, pathEnv, homebrewBins).map(linkMacCommand));
+  } else if (platform === "win32") {
+    const folders = new Set([
+      localAppData ? join(localAppData, "Programs", "Gloomberb", "bin") : "",
+      ...pathEnv.split(";"),
+    ].filter(Boolean));
+    added = await Promise.all([...folders].map(copyWindowsCommand));
+  }
+  return added.filter((path): path is string => path !== null);
+}

package/src/updater/failure.ts

@@ -0,0 +1,163 @@
+/**
+ * Why an update step failed, as a fixed phase and code rather than the error
+ * text: the header says the reason in a few words, and error tracking gets
+ * the same two values, which carry no path, URL or account name.
+ */
+
+/** The step that failed. `relaunch` is getting back into the app after an install. */
+export type UpdateFailurePhase = "check" | "download" | "verify" | "apply" | "relaunch";
+
+const UPDATE_FAILURE_CODES = [
+  /** No route to the release server: offline, DNS, refused, TLS. */
+  "offline",
+  "timeout",
+  /** GitHub answered 403 or 429, its limit for requests without an account. */
+  "rate_limited",
+  "server_error",
+  /** The release has no such file (404). */
+  "not_found",
+  /** Any other refusal from the release server. */
+  "http_error",
+  /** The release list or manifest did not read as one. */
+  "bad_response",
+  /** The release has no build for this platform, or none with a checksum. */
+  "no_build",
+  /** The download stopped before the whole file arrived. */
+  "interrupted",
+  /** The file arrived whole but does not match its checksum, or does not unpack. */
+  "corrupt",
+  "permission_denied",
+  /** The macOS app runs from where it cannot be replaced: a disk image, App Translocation, another volume. */
+  "wrong_location",
+  /** The downloaded update and the installed app are on different disks, so the one cannot be moved onto the other. */
+  "cross_device",
+  "read_only",
+  "disk_full",
+  /** Another process holds the files being replaced. */
+  "file_in_use",
+  /** The update downloaded earlier is no longer where the install expects it. */
+  "staged_missing",
+  /** A restart into the update came back on the old version. */
+  "not_applied",
+  /** The app quit with a downloaded update waiting and was opened again on the old version. */
+  "not_restarted",
+  /** The install finished but the app did not come back by itself. */
+  "relaunch_missed",
+  "unknown",
+] as const;
+
+export type UpdateFailureCode = typeof UPDATE_FAILURE_CODES[number];
+
+export interface UpdateFailure {
+  phase: UpdateFailurePhase;
+  code: UpdateFailureCode;
+}
+
+/** What an HTTP status from the release server means for an update. */
+export function httpStatusFailureCode(status: number): UpdateFailureCode {
+  if (status === 403 || status === 429) return "rate_limited";
+  if (status === 404 || status === 410) return "not_found";
+  if (status >= 500) return "server_error";
+  return "http_error";
+}
+
+const OFFLINE_ERRNO = new Set([
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  // Bun's fetch
+  "ConnectionRefused",
+  "FailedToOpenSocket",
+  "UnableToConnect",
+  "CERT_HAS_EXPIRED",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+]);
+const INTERRUPTED_ERRNO = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED", "ConnectionClosed"]);
+
+/**
+ * The code for an error a step threw, from its system error code first and its
+ * message second. Only the code leaves the machine; the message stays local.
+ */
+export function classifyUpdateError(error: unknown): UpdateFailureCode {
+  const record = (error && typeof error === "object" ? error : {}) as { code?: unknown; name?: unknown; message?: unknown };
+  const message = typeof record.message === "string" ? record.message : typeof error === "string" ? error : "";
+  // A system error code, or one named in the message ("Failed to replace app: EACCES: ...").
+  const errno = typeof record.code === "string" ? record.code : /\b(E[A-Z]{3,})\b/.exec(message)?.[1] ?? "";
+  switch (errno) {
+    case "EACCES":
+    case "EPERM":
+      return "permission_denied";
+    case "EROFS":
+      return "read_only";
+    case "ENOSPC":
+    case "EDQUOT":
+      return "disk_full";
+    case "EBUSY":
+    case "ETXTBSY":
+      return "file_in_use";
+    case "EXDEV":
+      return "cross_device";
+    case "ETIMEDOUT":
+      return "timeout";
+  }
+  if (OFFLINE_ERRNO.has(errno)) return "offline";
+  if (INTERRUPTED_ERRNO.has(errno)) return "interrupted";
+  if (record.name === "TimeoutError" || record.name === "AbortError") return "timeout";
+
+  const status = /\b(?:HTTP|returned|status|failed:?)\s*\(?(\d{3})\b/i.exec(message)?.[1];
+  if (status) return httpStatusFailureCode(Number(status));
+  if (/checksum mismatch|hash mismatch/i.test(message)) return "corrupt";
+  if (/zstd|decompress|gunzip|incorrect header|unexpected end of (?:file|data)/i.test(message)) return "corrupt";
+  if (/timed? ?out/i.test(message)) return "timeout";
+  if (/rate limit/i.test(message)) return "rate_limited";
+  if (/read-only file system/i.test(message)) return "read_only";
+  if (/cross-device/i.test(message)) return "cross_device";
+  if (/permission denied|operation not permitted|access is denied/i.test(message)) return "permission_denied";
+  if (/no space left|disk full/i.test(message)) return "disk_full";
+  if (/resource busy|text file busy|being used by another process/i.test(message)) return "file_in_use";
+  if (/connection (?:reset|closed|aborted)|socket hang up|premature close|terminated/i.test(message)) return "interrupted";
+  if (/unable to connect|fetch failed|failed to fetch|network|getaddrinfo|could not resolve|certificate/i.test(message)) return "offline";
+  if (/invalid update\.json|unexpected .*payload|json/i.test(message)) return "bad_response";
+  return "unknown";
+}
+
+/** When the failure has no more specific reason: what the step was. */
+const PHASE_REASONS: Record<UpdateFailurePhase, string> = {
+  check: "check failed",
+  download: "download failed",
+  verify: "could not verify the download",
+  apply: "could not install",
+  relaunch: "could not restart",
+};
+
+const CODE_REASONS: Partial<Record<UpdateFailureCode, string>> = {
+  offline: "no connection",
+  timeout: "connection timed out",
+  rate_limited: "GitHub rate limit",
+  server_error: "release server error",
+  not_found: "release server error",
+  http_error: "release server error",
+  bad_response: "unreadable release data",
+  no_build: "no build for this system",
+  interrupted: "download interrupted",
+  corrupt: "download corrupted",
+  permission_denied: "no permission to replace the app",
+  wrong_location: "move the app to Applications",
+  cross_device: "app and update on different disks",
+  read_only: "install folder is read-only",
+  disk_full: "disk full",
+  file_in_use: "app files in use",
+  staged_missing: "downloaded update missing",
+};
+
+/**
+ * The reason in a few words, in English (the caller translates it), sized
+ * for the header: "download interrupted", "no permission to replace the app".
+ */
+export function updateFailureReason(failure: UpdateFailure): string {
+  return CODE_REASONS[failure.code] ?? PHASE_REASONS[failure.phase];
+}