gloomberb 0.16.0 → 0.16.2

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

@@ -15,6 +15,7 @@ import type { RemoteUiNodeSnapshot } from "../remote/types";
 import type { DatedObservation } from "../plugins/builtin/market-valuation/series";
 import type { DesktopExternalPluginBundle } from "../renderers/electrobun/shared/protocol";
 import type { HttpProxyRequestEnvelope, HttpProxyResponseEnvelope } from "../utils/http-proxy-response";
+import type { PaneAccessGate } from "./pane-functions/access-gate";
 import { readVisibleKeyValues } from "./visible-key-values";
 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";
@@ -93,6 +94,8 @@ interface DesktopPaneShotRenderedCell {
   columnId?: string;
   columnLabel: string;
   text: string;
+  /** The ISO instant behind a cell whose text shortens a time ("Wed 11:27"), from the table cell's export value. */
+  instant?: string;
 }
 
 export interface DesktopPaneShotRenderedRow {
@@ -105,6 +108,8 @@ export interface DesktopPaneShotRenderedRow {
 
 export interface DesktopPaneShotRenderResult {
   visibleText: 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 }>;
   rows: DesktopPaneShotRenderedRow[];
   truncated: boolean;
@@ -114,6 +119,8 @@ export interface DesktopPaneShotRenderResult {
   errorStateMarkers: string[];
   emptyStateDetected: boolean;
   emptyStateMarkers: string[];
+  /** A wall that needs an account, or a Pro lock on part of the pane. */
+  accessGate?: PaneAccessGate | null;
   semanticUi: RemoteUiNodeSnapshot[];
 }
 
@@ -472,14 +479,22 @@ const LOADING_STATE_PATTERNS = [
   /\bRendering pane\.{3}/gi,
 ];
 
-const ERROR_STATE_PATTERNS = [
-  /\b[^.]{1,100} unavailable\./gi,
-  /\bFailed to fetch\b/gi,
-  /\bCould not load\b/gi,
+const SIGN_IN_WALL_PATTERNS = [
   /\bSign in to\b/gi,
   /\bVerify your email\b/gi,
   /\brequires signup and email verification\b/gi,
+];
+
+const PRO_WALL_PATTERNS = [
   /\bpart of Gloom Cloud Pro\b/gi,
+];
+
+const ERROR_STATE_PATTERNS = [
+  /\b[^.]{1,100} unavailable\./gi,
+  /\bFailed to fetch\b/gi,
+  /\bCould not load\b/gi,
+  ...SIGN_IN_WALL_PATTERNS,
+  ...PRO_WALL_PATTERNS,
   /\bCloud API request failed\b/gi,
 ];
 
@@ -569,12 +584,14 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
               ) {
                 truncationReasons.add("one or more cells are visibly clipped");
               }
+              const instant = cell.getAttribute("data-gloom-cell-instant");
               return {
                 ...(typeof semanticColumn.id === "string" ? { columnId: semanticColumn.id } : {}),
                 columnLabel: typeof semanticColumn.label === "string"
                   ? semanticColumn.label
                   : headers[cellIndex] || (values.length === 1 ? "Row" : String(cellIndex + 1)),
                 text,
+                ...(instant ? { instant } : {}),
               };
             }).filter((cell) => cell.text.length > 0);
             if (cells.length === 0) return;
@@ -605,6 +622,10 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
       }
       return {
         visibleText: root.innerText || root.textContent || "",
+        footerText: [...root.querySelectorAll('[data-gloom-role="pane-footer"]')]
+          .map((footer) => normalize(footer.innerText || footer.textContent))
+          .filter(Boolean)
+          .join(" "),
         visibleKeyValues: (${readVisibleKeyValues.toString()})(root),
         error: window.__GLOOM_CLI_SHOT_ERROR__ || "",
         loadingStateDetected: root.querySelector('[data-gloom-status="loading"]') !== null,
@@ -612,6 +633,9 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         // An empty sub-section off screen, such as a ticker's news list below
         // the fold, does not make the captured view empty.
         emptyStateDetected: [...root.querySelectorAll('[data-gloom-status="empty"]')].some(isVisible),
+        // The shared sign-in wall and the Pro lock prompt every gated pane draws.
+        accessGate: [...root.querySelectorAll('[data-gloom-ui="sign-in-wall"]')].some(isVisible) ? "sign-in"
+          : [...root.querySelectorAll('[data-gloom-ui="pro-lock"]')].some(isVisible) ? "pro" : "",
         rows,
         truncated: truncationReasons.size > 0,
         truncationReasons: [...truncationReasons],
@@ -623,11 +647,13 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
     result?: {
       value?: {
         visibleText?: string;
+        footerText?: string;
         visibleKeyValues?: Array<{ label: string; text: string }>;
         error?: string;
         loadingStateDetected?: boolean;
         errorStateDetected?: boolean;
         emptyStateDetected?: boolean;
+        accessGate?: string;
         rows?: DesktopPaneShotRenderedRow[];
         truncated?: boolean;
         truncationReasons?: string[];
@@ -641,6 +667,8 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   const loadingStateMarkers = stateMarkers(visibleText, LOADING_STATE_PATTERNS);
   const errorStateMarkers = stateMarkers(visibleText, ERROR_STATE_PATTERNS);
   const emptyStateMarkers = stateMarkers(visibleText, EMPTY_STATE_PATTERNS);
+  const accessGate: PaneAccessGate | null = value?.accessGate === "sign-in" || stateMarkers(visibleText, SIGN_IN_WALL_PATTERNS).length > 0 ? "sign-in"
+    : value?.accessGate === "pro" || stateMarkers(visibleText, PRO_WALL_PATTERNS).length > 0 ? "pro" : null;
   const rows = Array.isArray(value?.rows) ? value.rows : [];
   const textShowsEllipsis = rows.some((row) => row.cells.some((cell) => /\u2026|\.\.\./.test(cell.text)));
   const truncationReasons = Array.isArray(value?.truncationReasons)
@@ -651,6 +679,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   }
   return {
     visibleText,
+    footerText: typeof value?.footerText === "string" ? value.footerText : "",
     visibleKeyValues: Array.isArray(value?.visibleKeyValues) ? value.visibleKeyValues : [],
     rows,
     truncated: value?.truncated === true || textShowsEllipsis,
@@ -660,6 +689,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
     errorStateMarkers,
     emptyStateDetected: value?.emptyStateDetected === true || emptyStateMarkers.length > 0,
     emptyStateMarkers,
+    accessGate,
     semanticUi: Array.isArray(value?.semanticUi) ? value.semanticUi : [],
   };
 }

package/src/cli/freshness.ts

@@ -0,0 +1,61 @@
+import type { FinancialStatement, Quote, TickerFinancials } from "../types/financials";
+import type { HeadlessPaneFreshness, HeadlessPaneRow } from "../types/headless";
+import { deriveHeadlessFreshness, type ReportFreshness } from "./pane-functions/freshness";
+import { quoteFreshnessFields, REPORTED_DATA } from "../plugins/builtin/shared/report-freshness";
+import { latestFinancialPeriod } from "../utils/latest-financial-period";
+
+/**
+ * The source, as-of and status line of a plain CLI command, derived exactly as
+ * an `fn` report derives it: rows read like a headless report's rows (quote
+ * `dataSource`, `delayMinutes`, `stale` flags, observation times, worst of
+ * across rows) under what the command declares about them. Nothing to cite, no line.
+ */
+export function rowsFreshness(
+  rows: readonly object[],
+  declared?: HeadlessPaneFreshness,
+  metadata?: Record<string, unknown>,
+  now = Date.now(),
+): ReportFreshness | undefined {
+  if (rows.length === 0 && !metadata && !declared) return undefined;
+  return deriveHeadlessFreshness(
+    { shape: "rows", freshness: declared },
+    { rows: rows as HeadlessPaneRow[], ...(metadata ? { metadata } : {}) },
+    now,
+  );
+}
+
+/** 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 };
+}
+
+/** Worst of across the quotes shown, dated by the newest. 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);
+  return rows.length > 0 ? rowsFreshness(rows, declared, undefined, now) : undefined;
+}
+
+/** The newest reported period end in the statements, the period the trailing figures run through. */
+function latestReportedPeriod(financials: Pick<TickerFinancials, "annualStatements" | "quarterlyStatements">): string | null {
+  const rows: FinancialStatement[] = [...financials.annualStatements, ...financials.quarterlyStatements];
+  return latestFinancialPeriod(rows, (row) => row.date)?.date ?? null;
+}
+
+/**
+ * Fundamentals and valuation: reported figures, not a feed. Dated by when the
+ * statistics block was observed, with the newest statement period they run
+ * through named in the status; stale only when the block says so.
+ */
+export function fundamentalsFreshness(financials: TickerFinancials, now = Date.now()): ReportFreshness {
+  const fundamentals = financials.fundamentals;
+  const period = latestReportedPeriod(financials);
+  return rowsFreshness([], {
+    ...REPORTED_DATA,
+    basis: period ? `reported through ${period}` : REPORTED_DATA.basis,
+    asOf: fundamentals?.fetchedAt ?? null,
+  }, { stale: fundamentals?.stale === true }, now)!;
+}

package/src/cli/help.ts

@@ -95,6 +95,7 @@ export function renderCliHelp(entries: CliHelpEntry[], version: string, descript
       ["gloomberb", "Open the terminal UI"],
       ["gloomberb <command> [args]", "Run a command and print the result"],
       ["gloomberb help <command>", "Show a command's usage, options, and examples"],
+      ["gloomberb ticker SAN:EPA", "Name the listing of a symbol that trades in several places (or --exchange EPA)"],
     ], { width }),
   ];
 

package/src/cli/helpers.ts

@@ -9,6 +9,7 @@ import { cliStyles, colorBySign } from "../utils/cli-output";
 import type { AppConfig } from "../types/config";
 import type { Watchlist, TickerRecord } from "../types/ticker";
 import { isFiniteNumber } from "../utils/guards";
+import { formatUtcTime } from "../utils/utc-time";
 
 export function formatSignedCurrency(value: number, currency: string): string {
   return value > 0 ? `+${formatCurrency(value, currency)}` : formatCurrency(value, currency);
@@ -87,15 +88,10 @@ export function formatPriceRange(
   return `${format(low, { fixedFractionDigits: digits })}${separator}${format(high, { fixedFractionDigits: digits })}`;
 }
 
+/** A timestamp in CLI text: UTC with the zone named, the same on every machine. */
 export function formatTimestamp(timestamp: number | undefined): string {
-  if (!timestamp) return "—";
-  return new Date(timestamp).toLocaleString("en-US", {
-    month: "short",
-    day: "numeric",
-    year: "numeric",
-    hour: "numeric",
-    minute: "2-digit",
-  });
+  if (!timestamp || !Number.isFinite(timestamp)) return "—";
+  return formatUtcTime(new Date(timestamp)) || "—";
 }
 
 export function formatBidAsk(

package/src/cli/index.ts

@@ -23,6 +23,8 @@ import { fail, inferCliErrorOptions, printCliError } from "./errors";
 import { setCliColorEnabledOverride } from "../utils/cli-output";
 import { search, searchCandidatesForCli, buildSearchReport } from "./commands/search";
 import { ticker } from "./commands/ticker";
+import { takeOption } from "./commands/command-utils";
+import { EXCHANGE_OPTION } from "./listing-arg";
 import { apiCliCommand } from "./commands/api";
 import { marketDataCliCommands } from "./commands/market";
 import { overviewCliCommands } from "./commands/overview";
@@ -99,14 +101,18 @@ function createCoreCliCommands(
       help: {
         group: CLI_COMMAND_GROUPS.research,
         usage: ["ticker <symbol>"],
-        examples: ["ticker AAPL", "ticker 7203.T", "ticker AAPL --json"],
+        options: [EXCHANGE_OPTION],
+        examples: ["ticker AAPL", "ticker SAN:EPA", "ticker 7203.T", "ticker AAPL --json"],
       },
-      execute: async (args, ctx) => {
+      execute: async (rawArgs, ctx) => {
+        const args = [...rawArgs];
+        const exchange = takeOption(args, "--exchange");
         const symbol = args[0];
         if (!symbol) {
           ctx.fail("Usage: gloomberb ticker <symbol>");
         }
         await ticker(symbol!, {
+          exchange,
           initMarketData: ctx.initMarketData,
           fail: ctx.fail,
           ...(ctx.cliOptions.format === "text" ? {} : { printResult: ctx.printResult }),
@@ -140,9 +146,11 @@ function createCoreCliCommands(
         options: [
           { flags: "--<option> <value>", description: "A function setting; gloomberb catalog <function> lists them" },
           { flags: "--require-bot-safe", description: "Fail unless the function has a verified, complete report" },
+          EXCHANGE_OPTION,
         ],
         examples: [
           "fn HP AAPL",
+          "fn ANR SAN:EPA",
           "fn CBR --json",
           "fn 13F AAPL --view=ticker-holdings",
           "fn OVME --spot 100 --strike 100 --days 30 --volatility 25",
@@ -168,9 +176,11 @@ function createCoreCliCommands(
           { flags: "--scale <n>", description: "Text scale from 0.5 to 4 (default 1)" },
           { flags: "--watermark <label>", description: "Label drawn in the pane title bar" },
           { flags: "--<option> <value>", description: "A function setting; gloomberb catalog <function> lists them" },
+          EXCHANGE_OPTION,
         ],
         examples: [
           "shot TAS AAPL --output tape.png",
+          "shot HP BHP:ASX",
           "shot DDIS MSFT --tab history",
           "shot HP NVDA --width 1600 --theme green",
         ],

package/src/cli/listing-arg.ts

@@ -0,0 +1,321 @@
+import type { DataProvider } from "../types/data-provider";
+import type { Quote } from "../types/financials";
+import type { CliCommandContext } from "../types/plugin";
+import type { TickerRecord } from "../types/ticker";
+import { AmbiguousContractError, AmbiguousTickerError, listingChoiceQuery, resolveTickerSearch } from "../tickers/search";
+import { cliStyles } from "../utils/cli-output";
+import {
+  canonicalExchange,
+  exchangeLabel,
+  isKnownExchangeCode,
+  parsePublicTickerKey,
+  publicTickerKey,
+} from "../utils/exchanges";
+import { withMarketData } from "./scoped-context";
+
+/** The `--exchange` option of every command that takes a ticker. */
+export const EXCHANGE_OPTION = {
+  flags: "--exchange <code>",
+  description: "Listing exchange, for a symbol that trades in several places (same as SYMBOL:CODE)",
+};
+
+export class ListingArgError extends Error {
+  constructor(message: string, readonly details?: string) {
+    super(message);
+    this.name = "ListingArgError";
+  }
+}
+
+export interface ListingArg {
+  /** The symbol without a venue: SAN. */
+  symbol: string;
+  /** The canonical code of the exchange the user named, or "" when none was. */
+  exchange: string;
+  /** SAN:EPA, or SAN when no exchange was named. */
+  key: string;
+}
+
+/**
+ * `SAN:EPA` and `SAN --exchange EPA` name the same listing. Both spellings of
+ * an exchange go through the app's alias table, so `SAN:XPAR` is `SAN:EPA`.
+ * A symbol's own exchange and `--exchange` that disagree are an error, unless
+ * the command takes several symbols and `--exchange` only fills in the ones
+ * without an exchange of their own.
+ */
+export function parseListingArg(
+  raw: string,
+  exchangeOption?: string | null,
+  { ownExchangeWins = false }: { ownExchangeWins?: boolean } = {},
+): ListingArg {
+  const option = canonicalExchange(exchangeOption ?? "");
+  let typed = raw.trim().replace(/^\$/, "").toUpperCase();
+  // `SAN:` asks which listing; with --exchange it has its answer.
+  if (option && typed.endsWith(":")) typed = typed.slice(0, -1);
+  const parsed = parsePublicTickerKey(typed);
+  if (parsed.exchange && option && parsed.exchange !== option && !ownExchangeWins) {
+    throw new ListingArgError(
+      `${typed} names exchange ${parsed.exchange}, but --exchange names ${option}.`,
+      `Name the exchange once, as ${parsed.symbol}:${parsed.exchange} or ${parsed.symbol} --exchange ${option}.`,
+    );
+  }
+  const exchange = parsed.exchange ?? option;
+  return { symbol: parsed.symbol, exchange, key: exchange ? `${parsed.symbol}:${exchange}` : parsed.symbol };
+}
+
+interface ListingStore {
+  loadTicker(symbol: string): Promise<TickerRecord | null>;
+  loadAllTickers(): Promise<TickerRecord[]>;
+}
+
+export interface ListingDeps {
+  store: ListingStore;
+  dataProvider: DataProvider;
+}
+
+export interface ListingVenue {
+  /** Canonical code. */
+  exchange: string;
+  name: string;
+}
+
+/**
+ * The venues a symbol trades on and the company on each, from the same
+ * listing picker the command bar opens for `SAN:`.
+ */
+export async function listingVenues(symbol: string, { store, dataProvider }: ListingDeps): Promise<ListingVenue[]> {
+  const query = `${symbol}:`;
+  if (!listingChoiceQuery(query)) return [];
+  const tickers = new Map((await store.loadAllTickers()).map((ticker) => [ticker.metadata.ticker.toUpperCase(), ticker] as const));
+  let venues: ListingVenue[];
+  try {
+    const resolved = await resolveTickerSearch({ query, activeTicker: null, tickers, dataProvider });
+    const only = !resolved ? null
+      : resolved.kind === "local" ? { exchange: resolved.ticker.metadata.exchange, name: resolved.ticker.metadata.name }
+      : {
+        exchange: resolved.result.exchange === "SMART" ? resolved.result.primaryExchange ?? "" : resolved.result.exchange || resolved.result.primaryExchange || "",
+        name: resolved.result.name,
+      };
+    venues = only?.exchange ? [{ exchange: canonicalExchange(only.exchange), name: only.name }] : [];
+  } catch (error) {
+    // One listing settles the picker; several are its choices.
+    if (!(error instanceof AmbiguousTickerError) || error instanceof AmbiguousContractError) return [];
+    venues = error.listings.flatMap((listing) => {
+      const exchange = parsePublicTickerKey(listing).exchange;
+      return exchange ? [{ exchange, name: error.listingNames[listing] ?? "" }] : [];
+    });
+  }
+  return venues.filter((venue, index) => venues.findIndex((other) => other.exchange === venue.exchange) === index);
+}
+
+function tradesOn(symbol: string, venues: readonly ListingVenue[]): string {
+  return venues.length > 0 ? ` ${symbol} trades on: ${venues.map((venue) => venue.exchange).join(", ")}.` : "";
+}
+
+/**
+ * An exchange code the app does not know is accepted only when the symbol is
+ * listed there, so a typo never falls back to another venue's line.
+ */
+async function checkListingExchange(listing: ListingArg, deps: ListingDeps): Promise<void> {
+  if (listing.symbol.endsWith(":")) {
+    const symbol = listing.symbol.slice(0, -1);
+    throw new ListingArgError(`Choose an exchange for ${symbol}.${tradesOn(symbol, await listingVenues(symbol, deps))}`);
+  }
+  if (!listing.exchange || isKnownExchangeCode(listing.exchange)) return;
+  const venues = await listingVenues(listing.symbol, deps);
+  if (venues.some((venue) => venue.exchange === listing.exchange)) return;
+  throw new ListingArgError(
+    `Unknown exchange ${listing.exchange} for ${listing.symbol}.${tradesOn(listing.symbol, venues)}`,
+    venues.length > 0 ? undefined : `No listings of ${listing.symbol} were found.`,
+  );
+}
+
+/**
+ * "SAN does not trade on TSX. SAN trades on: NYSE, EPA." for a listing whose
+ * exchange the symbol is not listed on, from the same picker `SAN:` opens.
+ * Null when no exchange was named, when the symbol is listed there, or when its
+ * venues cannot be found, so the request's own failure stands. It searches, so
+ * ask only after a request came back empty.
+ */
+export async function notTradedMessage(
+  listing: Pick<ListingArg, "symbol" | "exchange">,
+  deps: ListingDeps,
+): Promise<string | null> {
+  if (!listing.exchange) return null;
+  const venues = await listingVenues(listing.symbol, deps).catch(() => []);
+  if (venues.length === 0 || venues.some((venue) => venue.exchange === listing.exchange)) return null;
+  return `${listing.symbol} does not trade on ${listing.exchange}.${tradesOn(listing.symbol, venues)}`;
+}
+
+/** Fails the command with `notTradedMessage`; returns when the symbol does trade there. */
+export async function failIfNotTraded(
+  listing: Pick<ListingArg, "symbol" | "exchange">,
+  deps: ListingDeps,
+  ctx: Pick<CliCommandContext, "fail">,
+): Promise<void> {
+  const message = await notTradedMessage(listing, deps);
+  if (message) ctx.fail(message);
+}
+
+/**
+ * A data request for the listings a command named. When it throws, or `isMiss`
+ * calls what it returned empty, and a listing's exchange is one its symbol does
+ * not trade on, the command ends in that message instead of the request's own
+ * "unavailable". A request that succeeds costs no extra lookup.
+ */
+export async function loadForListing<T>(
+  listings: Pick<ListingArg, "symbol" | "exchange"> | readonly Pick<ListingArg, "symbol" | "exchange">[],
+  deps: ListingDeps,
+  ctx: Pick<CliCommandContext, "fail">,
+  load: () => Promise<T>,
+  isMiss?: (value: T) => boolean,
+): Promise<T> {
+  const named = ("symbol" in listings ? [listings] : listings).filter((listing) => listing.exchange);
+  const checkVenues = () => Promise.all(named.map((listing) => failIfNotTraded(listing, deps, ctx)));
+  let value: T;
+  try {
+    value = await load();
+  } catch (error) {
+    await checkVenues();
+    throw error;
+  }
+  if (isMiss?.(value)) await checkVenues();
+  return value;
+}
+
+/** The saved ticker for a listing: under its own key, or a saved symbol whose venue it is. */
+export async function loadSavedListing(store: ListingStore, listing: ListingArg): Promise<TickerRecord | null> {
+  if (!listing.exchange) return store.loadTicker(listing.symbol);
+  for (const key of new Set([listing.key, publicTickerKey(listing.symbol, listing.exchange), listing.symbol])) {
+    const ticker = await store.loadTicker(key);
+    if (ticker && (key === listing.key || canonicalExchange(ticker.metadata.exchange) === listing.exchange)) return ticker;
+  }
+  return null;
+}
+
+export interface CliListing extends ListingArg {
+  saved: TickerRecord | null;
+  /**
+   * What data requests take: a named listing goes by its key (SAN:EPA), never
+   * the bare symbol's cache; a bare symbol goes on its saved venue, as the
+   * command bar opens it.
+   */
+  request: { symbol: string; exchange: string };
+}
+
+export async function resolveCliListing(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  deps: ListingDeps,
+  options: { ownExchangeWins?: boolean } = {},
+): Promise<CliListing> {
+  const listing = parseListingArg(raw, exchangeOption, options);
+  if (!listing.symbol) throw new ListingArgError("Ticker symbol is required.");
+  await checkListingExchange(listing, deps);
+  const saved = await loadSavedListing(deps.store, listing);
+  return {
+    ...listing,
+    saved,
+    request: listing.exchange
+      ? { symbol: listing.key, exchange: listing.exchange }
+      : { symbol: listing.symbol, exchange: saved?.metadata.exchange ?? "" },
+  };
+}
+
+/** `resolveCliListing` for a command: a bad exchange fails the command with its message. */
+export async function requireCliListing(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  deps: ListingDeps,
+  ctx: Pick<CliCommandContext, "fail">,
+  options: { ownExchangeWins?: boolean } = {},
+): Promise<CliListing> {
+  try {
+    return await resolveCliListing(raw, exchangeOption, deps, options);
+  } catch (error) {
+    if (error instanceof ListingArgError) ctx.fail(error.message, error.details);
+    throw error;
+  }
+}
+
+/**
+ * The listing for commands that store things by symbol (notes, alerts). The
+ * data sources are only opened to check an exchange the app does not know.
+ */
+export async function requireListingArg(
+  raw: string,
+  exchangeOption: string | null | undefined,
+  ctx: Pick<CliCommandContext, "fail" | "initMarketData">,
+): Promise<ListingArg> {
+  try {
+    const listing = parseListingArg(raw, exchangeOption);
+    if (listing.symbol.endsWith(":") || (listing.exchange && !isKnownExchangeCode(listing.exchange))) {
+      await withMarketData(ctx, (market) => checkListingExchange(listing, market));
+    }
+    return listing;
+  } catch (error) {
+    if (error instanceof ListingArgError) ctx.fail(error.message, error.details);
+    throw error;
+  }
+}
+
+export interface ListingIdentity {
+  symbol: string;
+  /** Canonical code of the venue the data is for. */
+  exchange: string;
+  /** The listing's company, from its own quote. */
+  name: string | null;
+}
+
+export function listingIdentity(
+  listing: CliListing,
+  quote?: Pick<Quote, "name" | "listingExchangeName" | "exchangeName"> | null,
+): ListingIdentity {
+  const quoteExchange = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);
+  const exchange = listing.exchange || quoteExchange || canonicalExchange(listing.saved?.metadata.exchange);
+  // A quote that prices another venue names another listing's company.
+  const quoteName = !quoteExchange || quoteExchange === exchange ? quote?.name?.trim() : undefined;
+  return { symbol: listing.symbol, exchange, name: quoteName || listing.saved?.metadata.name?.trim() || null };
+}
+
+/** The listing's own quote, for its company name and venue; null when it has none. */
+export async function loadListingQuote(dataProvider: DataProvider, listing: CliListing): Promise<Quote | null> {
+  try {
+    return await dataProvider.getQuote(listing.request.symbol, listing.request.exchange);
+  } catch {
+    return null;
+  }
+}
+
+/** One line above a table naming what it is about: "Sanofi  ·  Euronext Paris (EPA)". */
+export function listingHeading(identity: ListingIdentity): string {
+  const venue = identity.exchange ? cliStyles.muted(`  ·  ${exchangeLabel(identity.exchange)}`) : "";
+  return `${cliStyles.bold(identity.name || identity.symbol)}${venue}`;
+}
+
+/** "Sanofi (EPA)", for sentences. */
+export function listingTitle(identity: ListingIdentity): string {
+  const name = identity.name || identity.symbol;
+  return identity.exchange ? `${name} (${identity.exchange})` : name;
+}
+
+export interface SavedListingName {
+  symbol: string;
+  /** Canonical code of the venue the row is saved for, or "" when it has none. */
+  exchange: string;
+  /** SAN:EPA, whichever way the row is stored (SAN, SAN:XNYS). */
+  key: string;
+  name: string | null;
+  /** "SAN:EPA (Sanofi)", for sentences. */
+  label: string;
+}
+
+/** The listing a saved ticker row is, as a collection command names it after adding or removing it. */
+export function savedListingName(ticker: TickerRecord): SavedListingName {
+  const { symbol } = parsePublicTickerKey(ticker.metadata.ticker);
+  const exchange = canonicalExchange(ticker.metadata.exchange);
+  const key = exchange ? `${symbol}:${exchange}` : symbol;
+  // A row saved without a company carries its symbol as the name.
+  const typed = ticker.metadata.name?.trim();
+  const name = typed && typed !== symbol && typed !== ticker.metadata.ticker ? typed : null;
+  return { symbol, exchange, key, name, label: name ? `${key} (${name})` : key };
+}

package/src/cli/pane-functions/access-gate.ts

@@ -0,0 +1,42 @@
+/**
+ * What keeps a pane from showing everything it has: a Pro lock on part of it,
+ * or a wall that needs an account. Reports and screenshots name it, so a
+ * failure says "locked" instead of a generic incomplete or empty.
+ */
+export type PaneAccessGate = "pro" | "sign-in";
+
+// A Pro-gated loader reports what is locked in its errors ("Full history requires Gloom Pro").
+const SIGN_IN_ERROR = /\bsign(?:ed)?[ -]?in\b|\bsignup\b|\bemail verification\b|\bverify your email\b/i;
+const PRO_ERROR = /\bGloom (?:Cloud )?Pro\b|\b(?:requires?|needs?) Pro\b|\bPro access\b/;
+
+function errorMessages(errors: unknown): string[] {
+  return Array.isArray(errors) ? errors.filter((error): error is string => typeof error === "string") : [];
+}
+
+/** Why the output cannot be used as it is, as a clause: "some values need Gloom Cloud Pro (locked)". */
+function accessGateReason(gate: PaneAccessGate): string {
+  return gate === "pro" ? "some values need Gloom Cloud Pro (locked)" : "it needs a Gloom Cloud sign-in";
+}
+
+/** The reason as a sentence, for a screenshot's "Reason" row. */
+export function accessGateSentence(gate: PaneAccessGate): string {
+  const reason = accessGateReason(gate);
+  return `${reason.charAt(0).toUpperCase()}${reason.slice(1)}.`;
+}
+
+/** The word a screenshot's status line uses in place of "empty" for a gated pane. */
+export function accessGateStatus(gate: PaneAccessGate): string {
+  return gate === "pro" ? "locked" : "needs sign-in";
+}
+
+/**
+ * The failure for an incomplete report whose own errors name a gate, with
+ * those errors saying which values; null when they name none.
+ */
+export function incompleteReportGateMessage(token: string, errors: unknown): string | null {
+  const messages = errorMessages(errors);
+  const gate = messages.some((message) => SIGN_IN_ERROR.test(message)) ? "sign-in"
+    : messages.some((message) => PRO_ERROR.test(message)) ? "pro" : null;
+  const detail = messages.map((message) => message.replace(/\.+$/, "")).join(". ");
+  return gate ? `${token} is not bot-safe: ${accessGateReason(gate)}. ${detail}.` : null;
+}