gloomberb 0.16.2 → 0.16.4

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

@@ -10,6 +10,7 @@ import type { ManualChartResolution } from "../time-series/resolution";
 import type { SnapshotMarketData } from "../market-data/snapshot-provider";
 import type { InstrumentRef } from "../market-data/request-types";
 import type { TickerRecord } from "../types/ticker";
+import type { BrokerAccount } from "../types/trading";
 import type { PaneRuntimeState } from "../core/state/app/state";
 import type { RemoteUiNodeSnapshot } from "../remote/types";
 import type { DatedObservation } from "../plugins/builtin/market-valuation/series";
@@ -17,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 {
@@ -53,7 +55,14 @@ 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[]>;
   financials: Array<[string, TickerFinancials]>;
   instrumentFinancials?: SnapshotMarketData["instrumentFinancials"];
   historyVariants?: SnapshotMarketData["historyVariants"];
@@ -108,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 }>;
@@ -122,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;
@@ -160,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;
@@ -179,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);
@@ -399,6 +425,7 @@ async function capturePageScreenshot({
   deviceScaleFactor,
   userDataDir,
   captureImage,
+  statusLine,
 }: {
   chrome: string;
   url: string;
@@ -408,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);
@@ -454,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",
@@ -512,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[] {
@@ -538,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 : [];
@@ -583,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 {
@@ -595,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,
             });
           });
         });
@@ -639,6 +702,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         rows,
         truncated: truncationReasons.size > 0,
         truncationReasons: [...truncationReasons],
+        ...(reportedTables.size > 0 ? { reportRows, reportTruncationReasons: [...reportTruncationReasons] } : {}),
         semanticUi,
       };
     })()`,
@@ -657,6 +721,8 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         rows?: DesktopPaneShotRenderedRow[];
         truncated?: boolean;
         truncationReasons?: string[];
+        reportRows?: DesktopPaneShotRenderedRow[];
+        reportTruncationReasons?: string[];
         semanticUi?: RemoteUiNodeSnapshot[];
       };
     };
@@ -684,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,
@@ -694,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)})`;
+}

package/src/cli/help.ts

@@ -10,6 +10,12 @@ import {
   wrapText,
 } from "../utils/cli-output";
 
+/** `--section` of a command whose report has several tables. */
+export const TABLE_SECTION_OPTION = {
+  flags: "--section <title|n>",
+  description: "With --csv or --ndjson, write only that table, by its title or number",
+};
+
 /** Headings of `gloomberb help`, in display order. */
 export const CLI_COMMAND_GROUPS = {
   research: "Research",
@@ -28,13 +34,25 @@ const INDENT = 2;
 const MAX_HELP_WIDTH = 100;
 const PIPED_HELP_WIDTH = 80;
 
+/** Commands that run as written, for someone who has just installed it. */
+const START_HERE: Array<[string, string]> = [
+  ["gloomberb search apple", "Find a ticker from a company name"],
+  ["gloomberb quote AAPL", "Show the latest price"],
+  ["gloomberb ticker AAPL", "Open the full research report"],
+  ["gloomberb catalog earnings", "Find a function, then run it with fn"],
+];
+
 const GLOBAL_OPTIONS: Array<[string, string]> = [
-  ["--json, --csv, --ndjson", "Print machine-readable output instead of text"],
-  ["--limit <n>", "Show at most n rows"],
+  ["--json", "Print the full result as JSON"],
+  ["--csv", "Print rows as CSV under the columns the text shows; fn reports and fundamentals put each table under # section: and end with # source lines"],
+  ["--ndjson", "Print one JSON object per table row"],
+  ["--limit <n>", "Show at most n rows, the first n as printed"],
+  ["--tail <n>", "Show the newest n rows of a dated series (history, fred, econ) in their printed order, or the last n of another list"],
   ["--refresh", "Fetch fresh data instead of reading the cache"],
   ["--dry-run", "Preview config, cache, notes, alerts, plugin on/off, and remote changes without saving"],
   ["-q, --quiet", "Print no results or errors in text mode, for commands that print results"],
   ["--color, --no-color", "Force or turn off colors (NO_COLOR=1 also turns them off)"],
+  ["--width <n>", "Fit tables to n columns (default: the terminal width; piped output is not fitted). shot takes its own --width in pixels"],
 ];
 
 export interface CliHelpEntry {
@@ -90,6 +108,9 @@ export function renderCliHelp(entries: CliHelpEntry[], version: string, descript
     `${cliStyles.bold("gloomberb")} ${cliStyles.muted(version)}`,
     ...wrapText(description, width),
     "",
+    renderSection("Start here"),
+    ...renderDefinitions(START_HERE, { width, termStyle: cliStyles.command }),
+    "",
     renderSection("Usage"),
     ...renderDefinitions([
       ["gloomberb", "Open the terminal UI"],
@@ -178,14 +199,10 @@ function editDistance(left: string, right: string): number {
   return previous[right.length]!;
 }
 
-/** The closest command token to a mistyped one, or null when nothing is plausibly meant. */
-export function suggestCliCommand(token: string, candidates: Iterable<string>): string | null {
-  const needle = token.trim().toLowerCase();
-  if (!needle || needle.startsWith("-")) return null;
+function closestName(needle: string, candidates: Iterable<string>): string | null {
   const allowed = needle.length <= 4 ? 1 : 2;
   let best: { name: string; score: number } | null = null;
   for (const candidate of candidates) {
-    if (candidate.startsWith("-")) continue;
     // A clear prefix ("tick" for "ticker") beats an edit of the same size.
     const score = needle.length >= 3 && candidate.startsWith(needle)
       ? 0.5
@@ -195,3 +212,19 @@ export function suggestCliCommand(token: string, candidates: Iterable<string>):
   }
   return best?.name ?? null;
 }
+
+/** The closest command token to a mistyped one, or null when nothing is plausibly meant. */
+export function suggestCliCommand(token: string, candidates: Iterable<string>): string | null {
+  const needle = token.trim().toLowerCase();
+  if (!needle || needle.startsWith("-")) return null;
+  return closestName(needle, [...candidates].filter((candidate) => !candidate.startsWith("-")));
+}
+
+/** The closest of a command's options to a mistyped one (`--rnage` for `--range`), or null. */
+export function suggestCliOption(flag: string, options: Iterable<string>): string | null {
+  const needle = flag.trim().toLowerCase().replace(/^-+/, "");
+  if (!needle) return null;
+  const byName = new Map([...options].map((option) => [option.replace(/^-+/, ""), option] as const));
+  const name = closestName(needle, byName.keys());
+  return name == null ? null : byName.get(name)!;
+}