gloomberb 0.16.3 → 0.16.4

package/src/cli/commands/themes.ts

@@ -0,0 +1,64 @@
+import { DEFAULT_THEME, listThemes, resolveThemeId, themes, type ThemeSummary } from "../../theme/themes";
+import { fail } from "../errors";
+
+const THEME_TRAIT_NOTES = { "high-contrast": "high contrast", "colorblind-safe": "color-blind safe" } as const;
+
+/** `white (White Phosphor)`, or what the app shows instead of an id it does not know. */
+export function describeThemeId(id: string): string {
+  const theme = themes[id];
+  if (theme) return `${id} (${theme.name})`;
+  return `${id}, not a theme: the app shows ${describeThemeId(DEFAULT_THEME)}`;
+}
+
+/** Every id with its name, from the registry, for an error that has to say what would have worked. */
+function themeChoicesText(): string {
+  const choices = listThemes().map(({ id, name }) => `${id} (${name})`).join(", ");
+  return `Themes: ${choices}. gloomberb config themes lists them with notes.`;
+}
+
+/**
+ * The id `input` names, by id or display name in any case. Anything else
+ * fails with the closest id when there is one, and every id with its name.
+ */
+export function requireThemeId(input: string): string {
+  const lookup = resolveThemeId(input);
+  if (lookup.ok) return lookup.id;
+  const hint = lookup.suggestion ? ` Did you mean ${describeThemeId(lookup.suggestion)}?` : "";
+  return fail(`Unknown theme "${input.trim()}".${hint}`, themeChoicesText());
+}
+
+export interface ThemeListRow extends Record<string, unknown> {
+  id: string;
+  name: string;
+  appearance: ThemeSummary["appearance"];
+  colorblindSafe: boolean;
+  highContrast: boolean;
+  default: boolean;
+  current: boolean;
+}
+
+export function themeListRows(currentThemeId: string | null): ThemeListRow[] {
+  return listThemes().map((theme) => ({
+    id: theme.id,
+    name: theme.name,
+    appearance: theme.appearance,
+    colorblindSafe: theme.traits.includes("colorblind-safe"),
+    highContrast: theme.traits.includes("high-contrast"),
+    default: theme.id === DEFAULT_THEME,
+    current: theme.id === currentThemeId,
+  }));
+}
+
+export function themeListNote(row: ThemeListRow): string {
+  const notes: string[] = [];
+  if (row.highContrast) notes.push(THEME_TRAIT_NOTES["high-contrast"]);
+  if (row.colorblindSafe) notes.push(THEME_TRAIT_NOTES["colorblind-safe"]);
+  if (row.default) notes.push("default");
+  if (row.current) notes.push("current");
+  return notes.join(", ");
+}
+
+/** The name of a theme id the registry knows, null for one it does not. */
+export function themeName(id: string): string | null {
+  return themes[id]?.name ?? null;
+}

package/src/cli/commands/ticker.ts

@@ -22,8 +22,10 @@ import {
   type CliStatEntry,
 } from "../../utils/cli-output";
 import {
+  EXTENDED_SESSION_LABELS,
   exchangeShortName,
   getExtendedSessionDisplay,
+  getQuoteSessionFields,
   getRegularSessionDisplay,
   marketStateLabel,
 } from "../../market-data/market/status";
@@ -49,11 +51,13 @@ import {
   formatWatchlistNames,
 } from "../helpers";
 import { NotesFiles } from "../../plugins/builtin/notes/files";
-import { isUsEquityTicker } from "../../utils/sec";
+import { isKnownNonUsListing } from "../../utils/sec";
 import { canonicalExchange, exchangeLabel, isKnownExchangeCode } from "../../utils/exchanges";
 import { failIfNotTraded, ListingArgError, listingIdentity, resolveCliListing, type CliListing } from "../listing-arg";
+import { isNotATickerMessage } from "../not-a-ticker";
 import { sharesOutstandingInReceipts } from "../../utils/depositary-receipt";
 import { cliFreshnessFooter } from "../result";
+import { providerMissReason } from "../../sources/provider-errors";
 import { exportEntriesTable, reportFooterLines, type CliReportTables } from "../report-tables";
 import type { ReportFreshness } from "../pane-functions/freshness";
 import { fundamentalsFreshness, quotesFreshness } from "../freshness";
@@ -178,26 +182,35 @@ function getFilingDescription(filing: SecFilingItem): string | undefined {
   return description;
 }
 
-function shouldFetchSecFilings(tickerFile: TickerRecord | null, financials: TickerFinancials): boolean {
-  if (isUsEquityTicker(tickerFile)) {
-    return true;
-  }
-
-  const quote = financials.quote;
-  if (!quote || quote.currency.toUpperCase() !== "USD") {
-    return false;
-  }
-
-  const exchangeHints = [
-    tickerFile?.metadata.exchange,
-    quote.exchangeName,
-    quote.fullExchangeName,
-  ]
-    .filter((value): value is string => !!value)
-    .join(" ")
-    .toUpperCase();
-
-  return /(NASDAQ|NYSE|AMEX|ARCA|IEX|BATS|PINK|OTC|NMS)/.test(exchangeHints);
+/**
+ * SEC filings are asked for unless the listing is known to be outside the US:
+ * by the saved ticker, the requested venue, the quote, or the listing the
+ * source still describes when it has no current quote. A symbol nothing is
+ * known about yet is looked up as a US ticker.
+ */
+function shouldFetchSecFilings(
+  symbol: string,
+  exchange: string,
+  tickerFile: TickerRecord | null,
+  financials: TickerFinancials,
+): boolean {
+  const saved = tickerFile?.metadata;
+  const { quote, quoteMetadata } = financials;
+  return !isKnownNonUsListing({
+    metadata: {
+      ticker: saved?.ticker ?? symbol,
+      exchange: saved?.exchange || exchange || quote?.listingExchangeName || quote?.exchangeName
+        || quoteMetadata?.listingExchangeName || "",
+      currency: saved?.currency || quote?.currency || quoteMetadata?.currency || "",
+      name: saved?.name ?? symbol,
+      broker_contracts: saved?.broker_contracts,
+      portfolios: [],
+      watchlists: [],
+      positions: [],
+      custom: {},
+      tags: [],
+    },
+  });
 }
 
 async function appendTickerPositions(lines: string[], tickerFile: TickerRecord | null, quote: TickerFinancials["quote"],
@@ -430,6 +443,7 @@ export async function buildTickerReport({
   config,
   toBase,
   notes,
+  quoteNote,
   recentNews = [],
   recentSecFilings = [],
 }: {
@@ -441,6 +455,8 @@ export async function buildTickerReport({
   config: AppConfig;
   toBase: (value: number, fromCurrency: string) => Promise<number>;
   notes?: string;
+  /** Why there is no quote, when a source said; "Quote unavailable." otherwise. */
+  quoteNote?: string;
   recentNews?: NewsArticle[];
   recentSecFilings?: SecFilingItem[];
 }): Promise<string> {
@@ -455,7 +471,7 @@ export async function buildTickerReport({
   const lines: string[] = [];
 
   lines.push(`${cliStyles.accent(quote?.symbol ?? symbol)} ${cliStyles.bold(name)}`);
-  if (!quote) lines.push(cliStyles.muted("Quote unavailable."));
+  if (!quote) lines.push(cliStyles.muted(quoteNote ?? QUOTE_UNAVAILABLE));
 
   const summaryParts = [
     listingVenueLabel(listingExchange, quote, financials, tickerFile) || undefined,
@@ -537,8 +553,8 @@ export async function buildTickerReport({
     ]);
 
     appendMetricSection(lines, "Extended Hours", [
-      ["Pre-Market", extendedRow("PRE")],
-      ["After Hours", extendedRow("POST")],
+      [EXTENDED_SESSION_LABELS.PRE, extendedRow("PRE")],
+      [EXTENDED_SESSION_LABELS.POST, extendedRow("POST")],
     ]);
   }
 
@@ -627,10 +643,9 @@ function buildTickerStructuredData({
       symbol: quote.symbol,
       instrumentType: quote.instrumentType,
       name: quote.name,
-      price: quote.price,
+      // Last and Change as the text report reads them, then the extended print from that close.
+      ...getQuoteSessionFields(quote),
       priceBasis: quote.priceBasis ?? null,
-      change: quote.change,
-      changePercent: quote.changePercent,
       currency: quote.currency,
       marketCap: quote.marketCap ?? null,
       volume: quote.volume ?? null,
@@ -682,6 +697,18 @@ function buildTickerStructuredData({
   };
 }
 
+const QUOTE_UNAVAILABLE = "Quote unavailable.";
+
+/** Asks for the quote the report lacks once more, for the reason the data service gave when it had none. */
+async function quoteUnavailableNote(dataProvider: MarketContext["dataProvider"], symbol: string, exchange: string): Promise<string> {
+  try {
+    await dataProvider.getQuote(symbol, exchange);
+  } catch (error) {
+    return providerMissReason(error) ?? QUOTE_UNAVAILABLE;
+  }
+  return QUOTE_UNAVAILABLE;
+}
+
 export async function ticker(symbol: string, dependencies: TickerCommandDependencies = {}) {
   const initMarketDataFn = dependencies.initMarketData ?? initMarketData;
   const failCommand = dependencies.fail ?? fail;
@@ -705,7 +732,10 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     } catch (error) {
       // A known exchange the symbol is not listed on: say where it is.
       await failIfNotTraded(listing, { store, dataProvider }, { fail: failCommand });
-      failCommand(`Failed to fetch data for ${normalized}.`, error instanceof Error ? error.message : String(error));
+      const reason = error instanceof Error ? error.message : String(error);
+      // A symbol no listing carries is not a failed fetch, and the message already names it.
+      if (isNotATickerMessage(reason)) failCommand(reason);
+      failCommand(`Failed to fetch data for ${normalized}.`, reason);
     }
 
     const hasResearchData = financials && (
@@ -742,7 +772,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
       }),
       // Outside the US the lookup checks the SEC registrant against the listing's company,
       // and refuses another company's filings.
-      shouldFetchSecFilings(tickerFile, resolvedFinancials) && dataProvider.getSecFilings
+      shouldFetchSecFilings(requestSymbol, exchange, tickerFile, resolvedFinancials) && dataProvider.getSecFilings
         ? dataProvider.getSecFilings(requestSymbol, SEC_FILING_LIMIT, exchange || quote?.exchangeName || "",
           listingName ? { listingName } : undefined)
         : Promise.resolve([]),
@@ -754,10 +784,11 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
 
     // The quote is the feed in this report; without one, the fundamentals date it.
     const freshness = quote ? quotesFreshness([quote]) : fundamentalsFreshness(resolvedFinancials);
+    const quoteNote = quote ? undefined : await quoteUnavailableNote(dataProvider, requestSymbol, exchange);
     if (dependencies.printResult) {
       dependencies.printResult({
         freshness,
-        warnings: quote ? undefined : ["Quote unavailable."],
+        warnings: quote ? undefined : [quoteNote!],
         data: buildTickerStructuredData({
           symbol: normalized,
           listing,
@@ -780,6 +811,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
         config,
         toBase,
         notes,
+        quoteNote,
         recentNews,
         recentSecFilings,
     }));

package/src/cli/desktop-pane-shot.ts

@@ -18,6 +18,7 @@ import type { DesktopExternalPluginBundle } from "../renderers/electrobun/shared
 import type { HttpProxyRequestEnvelope, HttpProxyResponseEnvelope } from "../utils/http-proxy-response";
 import type { PaneAccessGate } from "./pane-functions/access-gate";
 import { readVisibleKeyValues } from "./visible-key-values";
+import { scrollTruncationReasons } from "./scroll-truncation";
 import { SHOT_API_PROXY_PREFIX, SHOT_HTTP_BRIDGE_PATH, SHOT_MARKET_BRIDGE_PATH } from "./desktop-pane-shot-routes";
 import { SESSION_COOKIE_NAMES } from "../api-client/session-cookie";
 import {
@@ -54,6 +55,11 @@ export interface DesktopPaneShotPayload {
   deviceScaleFactor?: number;
   /** Label drawn at the right edge of the pane title bar; null draws nothing. */
   watermark?: string | null;
+  /**
+   * The pane footer keeps a row for the capture's dated status line, filled
+   * once the pane has loaded. Absent for `--no-status` and for reports.
+   */
+  statusLine?: boolean;
   tickers: TickerRecord[];
   /** Broker accounts as last synced, by profile, so a broker portfolio shows its equity and cash. */
   brokerAccounts?: Record<string, BrokerAccount[]>;
@@ -111,6 +117,14 @@ export interface DesktopPaneShotRenderedRow {
 
 export interface DesktopPaneShotRenderResult {
   visibleText: string;
+  /**
+   * The rows a report reads, when a table reports every row (an option chain's
+   * strike window) rather than those in the viewport; `rows` stays what the
+   * capture shows. Absent when every table is read from the viewport.
+   */
+  reportRows?: DesktopPaneShotRenderedRow[];
+  /** `truncationReasons` without the cuts of tables whose every row is in `reportRows`. */
+  reportTruncationReasons?: string[];
   /** Text of the pane footers, where a pane says whether its data is live, delayed or stale. */
   footerText?: string;
   visibleKeyValues?: Array<{ label: string; text: string }>;
@@ -125,8 +139,16 @@ export interface DesktopPaneShotRenderResult {
   /** A wall that needs an account, or a Pro lock on part of the pane. */
   accessGate?: PaneAccessGate | null;
   semanticUi: RemoteUiNodeSnapshot[];
+  /** The status line drawn in the capture's footer, as it fit the width. */
+  statusLine?: string | null;
 }
 
+/**
+ * The status line variants for a capture, longest first, worked out from what
+ * the pane rendered; null leaves the footer row empty.
+ */
+type ShotStatusLine = (rendered: DesktopPaneShotRenderResult) => readonly string[] | null | Promise<readonly string[] | null>;
+
 type CdpResponse = {
   id?: number;
   result?: unknown;
@@ -163,7 +185,7 @@ export async function renderDesktopPaneScreenshot(
   payload: DesktopPaneShotPayload,
   outputPath: string,
   apiProxy: DesktopPaneShotApiProxy,
-  options: { captureImage?: boolean; bridge?: DesktopPaneShotBridge } = {},
+  options: { captureImage?: boolean; bridge?: DesktopPaneShotBridge; statusLine?: ShotStatusLine } = {},
 ): Promise<DesktopPaneShotRenderResult> {
   const tempDir = await mkdtemp(join(tmpdir(), "gloom-pane-shot-"));
   let server: ReturnType<typeof Bun.serve> | null = null;
@@ -182,6 +204,7 @@ export async function renderDesktopPaneScreenshot(
       deviceScaleFactor: payload.deviceScaleFactor ?? DEFAULT_DEVICE_SCALE_FACTOR,
       userDataDir: join(tempDir, "chrome-profile"),
       captureImage: options.captureImage !== false,
+      statusLine: payload.statusLine ? options.statusLine : undefined,
     });
   } finally {
     server?.stop(true);
@@ -402,6 +425,7 @@ async function capturePageScreenshot({
   deviceScaleFactor,
   userDataDir,
   captureImage,
+  statusLine,
 }: {
   chrome: string;
   url: string;
@@ -411,6 +435,7 @@ async function capturePageScreenshot({
   deviceScaleFactor: number;
   userDataDir: string;
   captureImage: boolean;
+  statusLine?: ShotStatusLine;
 }): Promise<DesktopPaneShotRenderResult> {
   await mkdir(userDataDir, { recursive: true });
   const port = 43000 + Math.floor(Math.random() * 10000);
@@ -457,6 +482,10 @@ async function capturePageScreenshot({
     });
     await waitForShotReady(session);
     const rendered = await readRenderedPaneState(session);
+    if (captureImage && statusLine) {
+      const variants = await statusLine(rendered);
+      rendered.statusLine = variants?.length ? await fitShotStatusLine(session, variants) : null;
+    }
     if (captureImage) {
       const screenshot = await session.send("Page.captureScreenshot", {
         format: "png",
@@ -515,6 +544,8 @@ const EMPTY_STATE_PATTERNS = [
   /\bNo transcribed calls(?: for [^.]+)? yet\b/gi,
   /\bNo short interest (?:data|found)\b/gi,
   /\bNo (?:House PTR |insider )?(?:trades|members|transactions|filings)\b/gi,
+  // OMON on an expiry the chain does not list, with the dates nearest it.
+  /\bNo (?:option contracts returned for )?expiry \d{4}-\d{2}-\d{2}(?:; (?:available|nearest others): \d{4}-\d{2}-\d{2}(?:, \d{4}-\d{2}-\d{2})*(?: \(\+\d+ more\))?|; the chain lists no expiries)?/gi,
 ];
 
 function stateMarkers(text: string, patterns: RegExp[]): string[] {
@@ -541,26 +572,39 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
       const semanticTables = semanticUi.filter((node) => node && node.role === "table");
       const rows = [];
       const truncationReasons = new Set();
+      const scrollReasons = (${scrollTruncationReasons.toString()});
+      const visibleTables = [...root.querySelectorAll('[data-gloom-role="data-table"]')].filter(isVisible);
+      // A table that publishes every row has nothing cut from a report, whatever the viewport shows.
+      const reportedRowsOf = (tableIndex) => {
+        const metadata = semanticTables[tableIndex] && semanticTables[tableIndex].metadata;
+        return metadata && Array.isArray(metadata.rows) ? metadata.rows : null;
+      };
+      const reportedTables = new Set(visibleTables.filter((_table, tableIndex) => reportedRowsOf(tableIndex)));
+      const reportRows = [];
+      const reportTruncationReasons = new Set();
+      const inReportedTable = (element) => {
+        const table = element.closest('[data-gloom-role="data-table"]');
+        return !!table && reportedTables.has(table);
+      };
       const markScrollTruncation = (element) => {
         if (!(element instanceof HTMLElement) || !isVisible(element)) return;
-        if (
-          element.getAttribute("data-gloom-scrollbar-y") === "visible"
-          || element.scrollHeight > element.clientHeight + 1
-        ) {
-          truncationReasons.add("rows extend below the rendered viewport");
-        }
-        if (
-          element.getAttribute("data-gloom-scrollbar-x") === "visible"
-          || element.scrollWidth > element.clientWidth + 1
-        ) {
-          truncationReasons.add("columns extend beyond the rendered viewport");
-        }
+        const reasons = scrollReasons({
+          scrollTop: element.scrollTop,
+          scrollHeight: element.scrollHeight,
+          clientHeight: element.clientHeight,
+          scrollLeft: element.scrollLeft,
+          scrollWidth: element.scrollWidth,
+          clientWidth: element.clientWidth,
+          scrollbarY: element.getAttribute("data-gloom-scrollbar-y") === "visible",
+          scrollbarX: element.getAttribute("data-gloom-scrollbar-x") === "visible",
+        });
+        reasons.forEach((reason) => truncationReasons.add(reason));
+        if (!inReportedTable(element)) reasons.forEach((reason) => reportTruncationReasons.add(reason));
       };
       [...root.querySelectorAll(
         '[data-gloom-scrollbar-x="visible"], [data-gloom-scrollbar-y="visible"], [data-gloom-role="data-table-body-scroll"]',
       )].forEach(markScrollTruncation);
-      [...root.querySelectorAll('[data-gloom-role="data-table"]')]
-        .filter(isVisible)
+      visibleTables
         .forEach((table, tableIndex) => {
           const tableMetadata = semanticTables[tableIndex] && semanticTables[tableIndex].metadata || {};
           const semanticColumns = Array.isArray(tableMetadata.columns) ? tableMetadata.columns : [];
@@ -586,6 +630,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
                 ))
               ) {
                 truncationReasons.add("one or more cells are visibly clipped");
+                if (!reportedTables.has(table)) reportTruncationReasons.add("one or more cells are visibly clipped");
               }
               const instant = cell.getAttribute("data-gloom-cell-instant");
               return {
@@ -598,12 +643,27 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
               };
             }).filter((cell) => cell.text.length > 0);
             if (cells.length === 0) return;
-            rows.push({
+            const captured = {
               tableIndex,
               rowIndex,
               ...(rowKey ? { key: rowKey } : {}),
               selected: row.getAttribute("data-selected") === "true",
               cells,
+            };
+            rows.push(captured);
+            if (!reportedTables.has(table)) reportRows.push(captured);
+          });
+          const reported = reportedRowsOf(tableIndex);
+          if (!reported) return;
+          reported.forEach((row, rowIndex) => {
+            const cells = Array.isArray(row && row.cells) ? row.cells.filter((cell) => cell && cell.text) : [];
+            if (cells.length === 0) return;
+            reportRows.push({
+              tableIndex,
+              rowIndex,
+              ...(typeof row.key === "string" ? { key: row.key } : {}),
+              selected: row.selected === true,
+              cells,
             });
           });
         });
@@ -642,6 +702,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         rows,
         truncated: truncationReasons.size > 0,
         truncationReasons: [...truncationReasons],
+        ...(reportedTables.size > 0 ? { reportRows, reportTruncationReasons: [...reportTruncationReasons] } : {}),
         semanticUi,
       };
     })()`,
@@ -660,6 +721,8 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         rows?: DesktopPaneShotRenderedRow[];
         truncated?: boolean;
         truncationReasons?: string[];
+        reportRows?: DesktopPaneShotRenderedRow[];
+        reportTruncationReasons?: string[];
         semanticUi?: RemoteUiNodeSnapshot[];
       };
     };
@@ -687,6 +750,10 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
     rows,
     truncated: value?.truncated === true || textShowsEllipsis,
     truncationReasons,
+    ...(Array.isArray(value?.reportRows) ? {
+      reportRows: value.reportRows,
+      reportTruncationReasons: (value.reportTruncationReasons ?? []).filter((reason): reason is string => typeof reason === "string"),
+    } : {}),
     loadingStateDetected: value?.loadingStateDetected === true || loadingStateMarkers.length > 0,
     errorStateDetected: value?.errorStateDetected === true || errorStateMarkers.length > 0,
     errorStateMarkers,
@@ -697,6 +764,20 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   };
 }
 
+/** Draws the first variant that fits the pane footer, and returns what it drew. */
+async function fitShotStatusLine(session: CdpSession, variants: readonly string[]): Promise<string | null> {
+  const result = await session.send("Runtime.evaluate", {
+    expression: `(() => {
+      const fit = window.__GLOOM_CLI_SHOT_FIT_STATUS__;
+      return fit ? fit(${JSON.stringify(variants)}) : null;
+    })()`,
+    awaitPromise: true,
+    returnByValue: true,
+  }) as { result?: { value?: unknown } };
+  const value = result.result?.value;
+  return typeof value === "string" ? value : null;
+}
+
 async function waitForPageWebSocket(port: number, targetUrl: string): Promise<string> {
   for (let attempt = 0; attempt < CHROME_POLL_ATTEMPTS; attempt += 1) {
     try {

package/src/cli/errors.ts

@@ -1,13 +1,19 @@
 import type { AppPersistence } from "../data/app-persistence";
+import { ApiRequestError } from "../api-client/errors";
 import { DEFAULT_CLI_OPTIONS, type CliGlobalOptions } from "./options";
 import { serializeCliError, type CliErrorObject } from "./result";
 import { cliStyles, cliTerminalWidth, wrapText } from "../utils/cli-output";
+import { withSearchHints } from "./not-a-ticker";
 
 const USAGE_PREFIX = "Usage: ";
+/** The code of every error a command fails with: bad input, nothing found, an option it does not take. */
+const CLI_ERROR_CODE = "cli_error";
 
 export interface CliErrorContext {
   /** The command that failed, used to point at its help. */
   command?: string;
+  /** What the user typed after the command, so a hint can repeat their own spelling of a symbol. */
+  args?: readonly string[];
 }
 
 class CliFailure extends Error {
@@ -15,7 +21,7 @@ class CliFailure extends Error {
   readonly details?: unknown;
   readonly retryable?: boolean;
 
-  constructor(message: string, details?: unknown, code = "cli_error", retryable?: boolean) {
+  constructor(message: string, details?: unknown, code = CLI_ERROR_CODE, retryable?: boolean) {
     super(message);
     this.name = "CliFailure";
     this.code = code;
@@ -37,6 +43,11 @@ function isCliFailure(error: unknown): error is CliFailure {
   return error instanceof CliFailure;
 }
 
+/** A global option that does not parse is a usage error like any other, not an unexpected one. */
+export function asUsageError(error: unknown): Error {
+  return isCliFailure(error) ? error : new CliFailure(error instanceof Error ? error.message : String(error));
+}
+
 function cliErrorObject(error: unknown): CliErrorObject {
   if (isCliFailure(error)) {
     return {
@@ -46,6 +57,10 @@ function cliErrorObject(error: unknown): CliErrorObject {
       retryable: error.retryable,
     };
   }
+  // Gloom Cloud refused what was asked (an unknown series, a bad date): the input was wrong, not the program.
+  if (error instanceof ApiRequestError && error.status === 400) {
+    return { code: CLI_ERROR_CODE, message: error.message };
+  }
   return {
     code: "unexpected_error",
     message: error instanceof Error ? error.message : String(error),
@@ -87,10 +102,18 @@ function formatCliErrorText(error: CliErrorObject, context: CliErrorContext): st
   ].join("\n");
 }
 
+function hintedError(error: CliErrorObject, args: readonly string[]): CliErrorObject {
+  return {
+    ...error,
+    message: withSearchHints(error.message, args),
+    ...(typeof error.details === "string" ? { details: withSearchHints(error.details, args) } : {}),
+  };
+}
+
 export function printCliError(error: unknown, options: CliGlobalOptions, context: CliErrorContext = {}): void {
   if (options.quiet && options.format === "text") return;
   const errorObject = cliErrorObject(error);
   console.error(options.format === "text"
-    ? formatCliErrorText(errorObject, context)
+    ? formatCliErrorText(hintedError(errorObject, context.args ?? []), context)
     : serializeCliError(errorObject, options));
 }

package/src/cli/freshness.ts

@@ -25,17 +25,20 @@ export function rowsFreshness(
 }
 
 /** One row per quote shown, as `fn` quote reports carry them: live, delayed or stale for its session. */
-function quoteFreshnessRow(quote: Quote): HeadlessPaneRow {
-  return { ...quoteFreshnessFields(quote), updatedAt: quote.lastUpdated };
+function quoteFreshnessRow(quote: Quote, now: number): HeadlessPaneRow {
+  return { ...quoteFreshnessFields(quote, now), updatedAt: quote.lastUpdated };
 }
 
-/** Worst of across the quotes shown, dated by the newest. Quotes that failed to load say nothing. */
+/**
+ * Worst of across the quotes shown, dated by the newest, with their delay and
+ * where their markets stand. Quotes that failed to load say nothing.
+ */
 export function quotesFreshness(
   quotes: Iterable<Quote | null | undefined>,
   declared?: HeadlessPaneFreshness,
   now = Date.now(),
 ): ReportFreshness | undefined {
-  const rows = [...quotes].filter((quote): quote is Quote => quote != null).map(quoteFreshnessRow);
+  const rows = [...quotes].filter((quote): quote is Quote => quote != null).map((quote) => quoteFreshnessRow(quote, now));
   return rows.length > 0 ? rowsFreshness(rows, declared, undefined, now) : undefined;
 }
 

package/src/cli/fx-pair.ts

@@ -0,0 +1,57 @@
+/**
+ * What `gloomberb fx` is asked for. A bare code is one unit of it in the base
+ * currency (`NGN`: USD per 1 NGN). A pair is market convention, BASE/QUOTE:
+ * `USD/NGN` is how many NGN one USD buys, and `ZAR/NGN` a cross of two codes
+ * with neither in USD.
+ */
+export interface FxRequest {
+  /** The currency one unit of which is priced: NGN in `NGN`, USD in `USD/NGN`. */
+  currency: string;
+  /** The currency the price is in: the base currency for a bare code, the quote of a pair. */
+  baseCurrency: string;
+}
+
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+
+/** The request, or the sentence saying what is wrong with the argument. */
+export function parseFxRequest(raw: string, baseCurrency: string): FxRequest | { error: string } {
+  const text = raw.trim().toUpperCase();
+  const parts = text.split("/").map((part) => part.trim());
+  if (parts.length > 2 || parts.some((part) => !part)) return { error: `"${raw}" is not a currency or a pair such as USD/NGN.` };
+  const bad = parts.filter((part) => !CURRENCY_CODE.test(part));
+  if (bad.length > 0) return { error: `${bad.join(" and ")} ${bad.length > 1 ? "are not currency codes" : "is not a currency code"}; use three letters such as NGN.` };
+  return parts.length === 2
+    ? { currency: parts[0]!, baseCurrency: parts[1]! }
+    : { currency: parts[0]!, baseCurrency: baseCurrency.trim().toUpperCase() };
+}
+
+/**
+ * The rate of `currency` in `baseCurrency` from each one's USD value (USD per
+ * unit), the way every cross is built. NaN when a leg is missing or unusable.
+ */
+export function crossRate(currencyInUsd: number | null | undefined, baseInUsd: number | null | undefined): number {
+  if (!isUsableRate(currencyInUsd) || !isUsableRate(baseInUsd)) return Number.NaN;
+  return currencyInUsd / baseInUsd;
+}
+
+export function isUsableRate(value: number | null | undefined): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+/**
+ * A rate to six significant digits, so a tiny one keeps its figures
+ * (0.000752791) and float noise goes; from 1000 up, to the cent (1328.39).
+ * Never in exponent notation, and without trailing zeros.
+ */
+export function formatFxRate(rate: number): string {
+  if (!Number.isFinite(rate)) return String(rate);
+  const size = Math.abs(rate);
+  const decimals = size >= 1000 || size === 0 ? 2 : Math.min(15, Math.max(0, 5 - Math.floor(Math.log10(size))));
+  const fixed = rate.toFixed(decimals);
+  return fixed.includes(".") ? fixed.replace(/\.?0+$/, "") : fixed;
+}
+
+/** Both directions on one line: `1 NGN = 0.000752791 USD  (USD/NGN 1328.39)`. */
+export function describeFxRate(request: FxRequest, rate: number): string {
+  return `1 ${request.currency} = ${formatFxRate(rate)} ${request.baseCurrency}  (${request.baseCurrency}/${request.currency} ${formatFxRate(1 / rate)})`;
+}