gloomberb 0.17.2 → 0.17.3

package/src/cli/pane-functions/dom.ts

@@ -1,5 +1,5 @@
 import type { DesktopPaneShotRenderedRow } from "../desktop-pane-shot";
-import { cliStyles, renderSection, renderTable } from "../../utils/cli-output";
+import { cliStyles, cliTerminalWidth, renderSection, renderTable, wrapText } from "../../utils/cli-output";
 import { formatUtcTime } from "../../utils/utc-time";
 import type { MarketContext } from "../types";
 import type { PaneFunctionReport } from "./report";
@@ -14,10 +14,14 @@ import { renderedReportFailure, renderedReportFreshness, renderedReportNotices,
 
 const DOM_REPORT_WIDTH = 1280;
 const DOM_REPORT_HEIGHT = 720;
+/** A pane whose reader has a page open grows to show all of it, up to about 18,000 px: a report saves no image to bound it. */
+const DOM_REPORT_MAX_HEIGHT_CELLS = 1000;
 const DOM_LIMITATION =
   "Only values visible in the rendered pane are returned; clipped or off-screen data may be omitted.";
 const DOM_EVERY_ROW =
   "Every row of the pane's table is returned, including rows scrolled out of view.";
+const DOM_WHOLE_PANE =
+  "The pane was grown to fit the page it has open, so all of its text is returned.";
 
 /** The sign-in wall's buttons, which a rendered view reads as words: `Log in ↵ Sign up free`. */
 const SIGN_IN_WALL_BUTTONS = /\s*\b(?:Log in|Sign up free|Resend Verification Email)(?:\s*\u21B5)?(?=\s|$)/g;
@@ -39,6 +43,28 @@ function signInWallText(visibleText: string): string {
   return headline ? `${headline} ${needs}` : needs;
 }
 
+const LIST_MARKER = /^\s*[\u2022\u25E6\u25AA\u00B7\u2013-]\s*$/;
+
+/**
+ * The words of a pane that is prose, not a table, a line to each block it draws
+ * and wrapped to the terminal's width (100 where it has none): the pane's own title,
+ * which the report's heading says already, is left off its top.
+ */
+function proseLines(render: PaneScreenshotResult["render"], title: string): string[] {
+  const lines = render.visibleLines?.length ? render.visibleLines : [render.visibleText];
+  const width = Math.min(cliTerminalWidth() ?? 100, 100);
+  const titled = lines[0]?.trim() === title ? lines.slice(1) : lines;
+  const body: string[] = [];
+  // A stack's detail opens under its Back button, a control and not part of the page.
+  for (const line of titled[0] === "Back" ? titled.slice(1) : titled) {
+    // A list marker is drawn as a block of its own, ahead of the item's words.
+    const marker = body.at(-1);
+    if (marker !== undefined && LIST_MARKER.test(marker)) body[body.length - 1] = `${marker.trim()} ${line}`;
+    else body.push(line);
+  }
+  return body.flatMap((line) => wrapText(line, width));
+}
+
 function rowsContainEllipsis(rows: DesktopPaneShotRenderedRow[]): boolean {
   return rows.some((row) => row.cells.some((cell) => /\u2026|\.\.\./.test(cell.text)));
 }
@@ -215,7 +241,7 @@ export function buildDomPaneReportFromRender(
   } else if (lockNote) {
     textLines.push(...lockNoteLines(lockNote));
   } else if (result.render.visibleText) {
-    textLines.push(gate === "sign-in" ? signInWallText(result.render.visibleText) : result.render.visibleText);
+    textLines.push(...(gate === "sign-in" ? [signInWallText(result.render.visibleText)] : proseLines(result.render, resolved.label)));
   } else {
     textLines.push(failureReason ?? "No rendered values were available.");
   }
@@ -231,6 +257,8 @@ export function buildDomPaneReportFromRender(
   const complete = failureReason === null && !truncated;
   // Each table published its rows and nothing else was cut: the report is the whole view.
   const everyRow = complete && result.render.reportRows !== undefined;
+  // A reader grown to fit its page (a docs page) and not cut once grown is read whole.
+  const wholePane = complete && !everyRow && resolved.pane.shotFitsReader === true;
   return {
     data: {
       kind: "rendered-view",
@@ -247,7 +275,8 @@ export function buildDomPaneReportFromRender(
       truncated,
       truncationReasons,
       ...(everyRow ? { everyRow } : {}),
-      limitation: everyRow ? DOM_EVERY_ROW : DOM_LIMITATION,
+      ...(wholePane ? { wholePane } : {}),
+      limitation: everyRow ? DOM_EVERY_ROW : wholePane ? DOM_WHOLE_PANE : DOM_LIMITATION,
       ...(lockReason ?? failureReason ? { reason: lockReason ?? failureReason } : {}),
       ...(notices.length > 0 ? { metadata: { ...rendered.facts, notices } } : {}),
       ...(locked ? { locked } : { freshness }),
@@ -278,12 +307,12 @@ export function appendDomReportFooter(
   ].join("\n");
 }
 
-/** How much of the pane a rendered-view report holds: none behind a wall, cut, every row its tables publish, or what the viewport shows. */
-export type DomReportView = "locked" | "clipped" | "every-row" | "visible";
+/** How much of the pane a rendered-view report holds: none behind a wall, cut, every row its tables publish, all of a pane grown to fit, or what the viewport shows. */
+export type DomReportView = "locked" | "clipped" | "every-row" | "whole" | "visible";
 
 export function domReportView(data: Readonly<Record<string, unknown>>): DomReportView {
   if (data.locked) return "locked";
-  return data.truncated === true ? "clipped" : data.everyRow === true ? "every-row" : "visible";
+  return data.truncated === true ? "clipped" : data.everyRow === true ? "every-row" : data.wholePane === true ? "whole" : "visible";
 }
 
 /** What a rendered-view report says about where its values come from. */
@@ -292,6 +321,8 @@ export function domReportNote(elapsedMs: number, view: DomReportView): string {
     ? "Rendered view: the pane is locked, so no values were read."
     : view === "every-row"
     ? "Rendered view: every row of the pane's table, including rows scrolled out of view."
+    : view === "whole"
+    ? "Rendered view: the pane grown to fit the whole page."
     : `Rendered view: values come from the visible pane. ${view === "clipped" ? "The rendered view is clipped." : "The rendered view may be clipped."}`;
   return `${source} Render time: ${elapsedMs} ms.`;
 }
@@ -356,6 +387,8 @@ export async function buildDomFunctionReport(
       theme: null,
       scale: 1,
       watermark: null,
+      fitReader: true,
+      maxHeightCells: DOM_REPORT_MAX_HEIGHT_CELLS,
       options: {},
       captureImage: false,
     });

package/src/cli/pane-functions/freshness.ts

@@ -10,8 +10,8 @@ import type {
 } from "../../types/plugin";
 import { localTimeSuffix, parseReportTime, type ReportTime } from "../../utils/utc-time";
 import { isRecord } from "../../utils/guards";
-import { latestRegularSessionClose } from "../../market-data/market/freshness";
-import { reportMarketSession, type ReportMarket, type SessionObservation } from "./market-session";
+import { latestRegularSessionClose, readIndexSession } from "../../market-data/market/freshness";
+import { reportMarketSession, reportVenueSessionDates, type ReportMarket, type SessionObservation, type VenueSessionDate } from "./market-session";
 
 /**
  * The four states of docs/usage.md#how-current-a-report-is, plus `unreported`
@@ -53,6 +53,12 @@ export interface ReportFreshness {
   tradingDayMarket?: string;
   /** Where the venues of a quote report stand now, from their session calendars. */
   market?: ReportMarket;
+  /**
+   * With a declared `datesEachVenue`, when the rows trade on more than one
+   * market: each market's session date, which the status line gives in place
+   * of the newest row's alone.
+   */
+  venueSessions?: VenueSessionDate[];
   /**
    * For a dataset (declared `dataset`, with no quote among its rows): whole UTC
    * days from the last day its newest observation covers to when this report
@@ -76,6 +82,8 @@ export interface ReportFreshness {
   oldestAgeMinutes?: number;
   /** What the figures are, said after the status: `funding = current estimate, pays 08:00 UTC`. */
   note?: string;
+  /** When the figures reach readers and when the next are due, said right after the as-of date. */
+  schedule?: string;
   /** Who published the figures, when the data names them. */
   publisher?: string;
   /** When the publisher released the data, an ISO instant in UTC or an ISO date, when the data states it. */
@@ -145,10 +153,12 @@ function readFeedSignals(record: Record<string, unknown>, signals: FeedSignals):
 function readSession(record: Record<string, unknown>, time: ReportTime | null, signals: FeedSignals): void {
   const exchange = record.sessionExchange;
   if (typeof exchange !== "string" || !exchange.trim()) return;
+  const calendar = readIndexSession(record.sessionCalendar);
   signals.sessions.push({
     exchange,
     ...(typeof record.marketState === "string" ? { marketState: record.marketState } : {}),
     time,
+    ...(calendar ? { calendar } : {}),
   });
 }
 
@@ -404,6 +414,7 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
     }
   }
   const { market, closeDate, closeMarket } = reportMarketSession(signals.sessions, now);
+  const venueSessions = declared.datesEachVenue && !declaredAsOf ? reportVenueSessionDates(signals.sessions, now) : [];
   // The close wording dates the newest observation, so only when that is what `asOf` is.
   const asOfClose = closeDate && asOf && !declaredAsOf ? closeDate : null;
   const tradingDayMarket = asOfClose ? closeMarket
@@ -417,6 +428,7 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
   const observation = lagDays != null ? declared.observation?.trim() : undefined;
 
   const note = declared.note?.trim();
+  const schedule = declared.schedule?.trim();
   const publisher = declared.publisher?.trim();
   const publishedAt = parseReportTime(declared.publishedAt);
   return {
@@ -434,11 +446,13 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
     ...(asOfClose ? { asOfClose } : {}),
     ...(tradingDayMarket ? { tradingDayMarket } : {}),
     ...(market ? { market } : {}),
+    ...(venueSessions.length > 0 ? { venueSessions } : {}),
     ...(lagDays != null ? { lagDays } : {}),
     ...(observation ? { observation } : {}),
     ...(sources.length ? { sources: sources.map(({ source, time }) => ({ source, asOf: isoTime(time) })) } : {}),
     ...(oldestAgeMinutes != null ? { oldestAgeMinutes } : {}),
     ...(note ? { note } : {}),
+    ...(schedule ? { schedule } : {}),
     ...(publisher ? { publisher } : {}),
     ...(publishedAt ? { publishedAt: isoTime(publishedAt) } : {}),
     retrievedAt: new Date(now).toISOString(),
@@ -628,6 +642,26 @@ function onRetrievalDay(iso: string, retrievedAt: string): boolean {
   return iso.slice(0, 10) === retrievedAt.slice(0, 10);
 }
 
+/** `US and XETRA`, `US, XETRA and EPA`. */
+function listText(items: readonly string[]): string {
+  return items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+
+/**
+ * Each market's session date, markets on the same day and state said once:
+ * `US, XETRA and EPA Tue 13 Oct 2026 close`, or `US Tue 13 Oct 2026 close,
+ * XETRA Wed 14 Oct 2026 session` while Xetra trades.
+ */
+function venueSessionsText(sessions: readonly VenueSessionDate[]): string {
+  const groups: Array<{ markets: string[]; date: string; close: boolean }> = [];
+  for (const { market, date, close } of sessions) {
+    const group = groups.find((entry) => entry.date === date && entry.close === close);
+    if (group) group.markets.push(market);
+    else groups.push({ markets: [market], date, close });
+  }
+  return groups.map(({ markets, date, close }) => `${listText(markets)} ${dayText(date)} ${close ? "close" : "session"}`).join(", ");
+}
+
 /**
  * The dated as-of: a session close, a UTC time, a date, or when the report was
  * retrieved; with the oldest observation unless `short`, or when the line says
@@ -636,6 +670,7 @@ function onRetrievalDay(iso: string, retrievedAt: string): boolean {
  */
 function asOfText(freshness: ReportFreshness, short: boolean, local: boolean, undated = false): string {
   if (!freshness.asOf) return `retrieved ${timeText(freshness.retrievedAt, local)}`;
+  if (freshness.venueSessions?.length) return venueSessionsText(freshness.venueSessions);
   const market = freshness.tradingDayMarket;
   const period = freshness.periodicity;
   const time = parseReportTime(freshness.asOf);
@@ -713,6 +748,8 @@ interface StatusLineDetail {
   date?: "none";
   /** Leave out what the figures are (`funding = current estimate`). */
   note?: "none";
+  /** Leave out when the figures are published and the next are due. */
+  schedule?: "none";
 }
 
 /**
@@ -728,6 +765,7 @@ function statusLineParts(freshness: ReportFreshness, detail: StatusLineDetail =
   return [
     ...(freshness.sources?.length ? sourcesAsOfParts(freshness, freshness.sources, undated)
       : [asOfText(freshness, detail.asOf === "short", local, undated)]),
+    ...(freshness.schedule && detail.schedule !== "none" ? [freshness.schedule] : []),
     ...(freshness.oldestAgeMinutes != null ? [`oldest ${ageText(freshness.oldestAgeMinutes)}`] : []),
     statusText(freshness, detail.status === "short"),
     ...(freshness.market && detail.market !== "none" ? [marketText(freshness.market, now, detail.market === "short", local)] : []),
@@ -812,13 +850,13 @@ export function paneStatusLine(freshness: ReportFreshness): string {
 /**
  * `paneStatusLine` from longest to shortest, for a footer to show the first
  * that fits beside its keys: the market part shortens, the stale total goes,
- * then what the figures are.
+ * then what the figures are, then when they are published.
  */
 export function paneStatusLineVariants(freshness: ReportFreshness): string[] {
   // A dataset's line has no market or local time to leave out: it reads as its report and capture do.
   if (datesObservation(freshness)) return statusLineVariants(freshness);
   const pane: StatusLineDetail = { local: "none", date: "none" };
-  const details: StatusLineDetail[] = [pane, { ...pane, market: "short" }, { ...pane, market: "short", status: "short" }, { ...pane, market: "short", status: "short", note: "none" }];
+  const details: StatusLineDetail[] = [pane, { ...pane, market: "short" }, { ...pane, market: "short", status: "short" }, { ...pane, market: "short", status: "short", note: "none" }, { ...pane, market: "short", status: "short", note: "none", schedule: "none" }];
   return [...new Set(details.map((detail) => capitalize(statusLineParts(freshness, detail).join(" · "))))];
 }
 
@@ -855,9 +893,14 @@ export function statusLineVariants(freshness: ReportFreshness, { source = false
   // A line that dates each source keeps every source's time and their age to
   // the last: its day goes first, then what the figures are.
   const shortest = details.at(-1)!;
+  // What the figures are goes before when they are published.
+  const trailing: StatusLineDetail[] = [
+    ...(freshness.note ? [{ ...shortest, note: "none" as const }] : []),
+    ...(freshness.schedule ? [{ ...shortest, note: "none" as const, schedule: "none" as const }] : []),
+  ];
   const variants: StatusLineDetail[] = freshness.sources?.length
     ? [{}, ...details.map((detail) => ({ ...detail, date: "none" as const })), { ...shortest, date: "none", note: "none" }]
-    : freshness.note ? [...details, { ...shortest, note: "none" }] : details;
+    : [...details, ...trailing];
   const lines = [...new Set(variants.map((detail) => capitalize(statusLineParts(freshness, detail).join(" · "))))];
   // A line that dates each source names them already.
   if (!source || freshness.sources?.length) return lines;

package/src/cli/pane-functions/function-help.ts

@@ -749,7 +749,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   FUT: {
-    summary: "Front-month futures across equity index, rates, energy, metals, agriculture, livestock and FX with last price and session change, grouped by sector.",
+    summary: "Each root's most active futures contract across equity index, rates, energy, metals, agriculture, livestock and FX with last price, unit and session change, grouped by sector.",
     usage: ["FUT"],
     keys: [SEARCH, OPEN],
     data: same(DELAYED),

package/src/cli/pane-functions/headless.ts

@@ -5,6 +5,7 @@ import { findNamedCollection } from "../../portfolio/collection-name";
 import { apiClient } from "../../api-client";
 import type { MarketContext } from "../types";
 import type {
+  HeadlessArgumentExpansion,
   HeadlessBundleResult,
   HeadlessBundleSection,
   HeadlessPaneColumn,
@@ -37,6 +38,7 @@ import type { ResolvedSeries } from "../../time-series/types";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 import { isRecord } from "../../utils/guards";
+import { splitSymbolArgs } from "../symbol-args";
 import { formatUtcTime, localTimeSuffix } from "../../utils/utc-time";
 import { deriveHeadlessFreshness, formatFreshnessLine, staleRowsText, type ReportFreshness } from "./freshness";
 import { accessGateStatus, errorsAccessGate, isProLock } from "./access-gate";
@@ -74,7 +76,7 @@ function normalizeSymbol(value: string): string {
 function normalizeSymbolList(value: string): string[] {
   const symbols: string[] = [];
   const seen = new Set<string>();
-  for (const part of value.split(/[,\s]+/)) {
+  for (const part of splitSymbolArgs([value])) {
     const symbol = normalizeSymbol(part);
     if (!symbol || seen.has(symbol)) continue;
     seen.add(symbol);
@@ -162,22 +164,17 @@ async function loadHeadlessPaneModel(
   return result;
 }
 
-/**
- * Loads the same renderer-neutral model used by `fn`.
- * Both reports and screenshot payloads execute this loader.
- */
-export async function loadResolvedHeadlessPaneModel(
+type HeadlessMarketContext = Pick<MarketContext, "config" | "store" | "refresh"> & Partial<Pick<MarketContext, "persistence" | "seriesCapabilities">> & {
+  dataProvider: HeadlessPaneContext["marketData"];
+};
+
+/** What a headless loader reads the market, the account and the saved collections through. */
+function createHeadlessPaneContext(
   resolved: ResolvedPaneFunction,
-  context: Pick<MarketContext, "config" | "store" | "refresh"> & Partial<Pick<MarketContext, "persistence" | "seriesCapabilities">> & {
-    dataProvider: HeadlessPaneContext["marketData"];
-  },
-  rawArgument: string,
-  signal: AbortSignal = new AbortController().signal,
-): Promise<LoadedHeadlessPaneModel> {
-  const definition = resolved.headless;
-  if (!definition) throw new Error(`${resolved.token} has no headless pane model.`);
-  const args = buildHeadlessPaneLoadArgs(definition, resolved.token, rawArgument, resolved.options);
-  const headlessContext: HeadlessPaneContext = {
+  context: HeadlessMarketContext,
+  signal: AbortSignal,
+): HeadlessPaneContext {
+  return {
     marketData: context.dataProvider,
     apiClient,
     config: context.config,
@@ -203,7 +200,40 @@ export async function loadResolvedHeadlessPaneModel(
       return { symbol: parsed.symbol, exchange: parsed.exchange ?? ticker?.metadata.exchange };
     },
   };
-  const result = await loadHeadlessPaneModel(definition, args, headlessContext);
+}
+
+/**
+ * The argument a function widens before it runs (`expandArgument`, RV's
+ * `--peers`), with the settings that say how; null when it runs as typed.
+ */
+export async function expandResolvedArgument(
+  resolved: ResolvedPaneFunction,
+  context: HeadlessMarketContext,
+  rawArgument: string,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<HeadlessArgumentExpansion | null> {
+  const definition = resolved.headless;
+  if (!definition?.expandArgument) return null;
+  const args = buildHeadlessPaneLoadArgs(definition, resolved.token, rawArgument, resolved.options);
+  const expansion = await definition.expandArgument(args, createHeadlessPaneContext(resolved, context, signal));
+  throwIfAborted(signal);
+  return expansion;
+}
+
+/**
+ * Loads the same renderer-neutral model used by `fn`.
+ * Both reports and screenshot payloads execute this loader.
+ */
+export async function loadResolvedHeadlessPaneModel(
+  resolved: ResolvedPaneFunction,
+  context: HeadlessMarketContext,
+  rawArgument: string,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<LoadedHeadlessPaneModel> {
+  const definition = resolved.headless;
+  if (!definition) throw new Error(`${resolved.token} has no headless pane model.`);
+  const args = buildHeadlessPaneLoadArgs(definition, resolved.token, rawArgument, resolved.options);
+  const result = await loadHeadlessPaneModel(definition, args, createHeadlessPaneContext(resolved, context, signal));
   return { definition, args, result };
 }
 
@@ -527,6 +557,36 @@ function splitErrors(result: HeadlessPaneResult): { locked: string[]; failed: st
   return { locked: errors.filter(isProLock), failed: errors.filter((error) => !isProLock(error)) };
 }
 
+/**
+ * Why a report with nothing in it is empty, when its pane gave no reason of
+ * its own: the free view left it empty (the report carries a Pro line), or the
+ * symbols asked for are not covered by the function (or hold nothing for the
+ * options chosen). Null when something has
+ * rows, a table states its own reason, an error explains it, or no symbol was
+ * asked for (a board that is empty says nothing about coverage).
+ */
+function emptyReportReason(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessPaneResult,
+  args: HeadlessPaneLoadArgs,
+  token: string | undefined,
+): string | null {
+  if (resultRowCount(definition, result) > 0) return null;
+  const ownReason = definition.shape === "rows" ? !!(result as HeadlessRowsResult).empty
+    : definition.shape === "bundle" && (result as HeadlessBundleResult).sections.some((section) => "empty" in section && !!section.empty);
+  const { locked, failed } = splitErrors(result);
+  if (ownReason || failed.length) return null;
+  if (locked.length) return "Locked: Gloom Pro";
+  const symbols = result.symbols ?? args.symbols;
+  if (!symbols.length) return null;
+  // An option the reader chose (a range, a tab) can leave a covered symbol empty, so coverage is not claimed then.
+  const narrowed = definition.options.some((option) => {
+    const value = args.options[option.key];
+    return value !== undefined && value !== "" && String(value) !== String(option.defaultValue ?? "");
+  });
+  return narrowed ? `No data for ${symbols.join(", ")} with these options.` : `No data for ${symbols.join(", ")}: not covered${token ? ` by ${token}` : ""}.`;
+}
+
 function textNotices(result: HeadlessPaneResult): string[] {
   const notices = result.metadata?.notices;
   if (!Array.isArray(notices)) return [];
@@ -634,15 +694,20 @@ export function renderHeadlessPaneText(
   args: HeadlessPaneLoadArgs,
   fallbackTitle: string,
   freshness: ReportFreshness = deriveHeadlessFreshness(definition, result),
+  /** The function's token, which an empty report names as the one that does not cover the symbol. */
+  token?: string,
 ): string {
   // A long title wraps to a narrow --width like the text under a table; each line stays bold.
   const lines = [...wrapToTerminal(reportTitle(definition, args, result, fallbackTitle)).split("\n").map(cliStyles.bold), ""];
   const notices = textNotices(result);
   if (notices.length) lines.push(...notices, "");
-  switch (definition.shape) {
+  const reason = emptyReportReason(definition, result, args, token);
+  // Said once, not under the heading of each empty table.
+  if (reason) lines.push(reason);
+  else switch (definition.shape) {
     case "rows": {
       const rowsResult = result as HeadlessRowsResult;
-      lines.push(renderRows(rowsResult.rows, rowsResult.columns, definition.columns, rowsResult.empty));
+      lines.push(renderRows(rowsResult.rows, rowsResult.textColumns ?? rowsResult.columns, definition.columns, rowsResult.empty));
       break;
     }
     case "bundle":
@@ -756,6 +821,7 @@ export async function buildHeadlessFunctionReport(
       loaded.args,
       resolved.label,
       freshness,
+      resolved.token,
     ),
     tables: headlessReportTables(
       loaded.definition,

package/src/cli/pane-functions/index.ts

@@ -1,5 +1,5 @@
 import { extname, isAbsolute, relative, resolve } from "path";
-import type { CliCommandContext } from "../../types/plugin";
+import type { CliCommandContext, HeadlessArgumentExpansion } from "../../types/plugin";
 import type { MarketContext } from "../types";
 import { withMarketData } from "../context";
 import { cliStyles, renderStats, type CliStatEntry } from "../../utils/cli-output";
@@ -8,6 +8,7 @@ import {
   findFunctionCode,
   renderPaneCatalogReport,
   selectPaneCatalogMatches,
+  suggestPaneFunctions,
   type PaneFunctionCatalog,
 } from "./catalog";
 import { createPaneCatalog } from "./discovery";
@@ -19,6 +20,7 @@ import {
 } from "./options";
 import { applyListingArgument, resolvePaneFunction, UnknownPaneFunctionError, type ResolvedPaneFunction } from "./resolver";
 import { buildFunctionReport } from "./report";
+import { expandResolvedArgument } from "./headless";
 import { defaultScreenshotPath, renderDesktopShot, shotSizeWarnings, shotStatusIssues } from "./screenshot";
 import {
   buildPaneCatalogEntries,
@@ -29,6 +31,7 @@ import { ListingArgError, listingReadNotes, loadForListing, quotedListingChoiceN
 import { knownGapMessage, settingsPointer, topicPointer } from "../known-gaps";
 import { selectReportTables } from "../report-tables";
 import { cliOutputWritten } from "../result";
+import type { CatalogCommandHit } from "../unknown-command";
 import { CLI_EXIT_CODES } from "../exit-codes";
 import {
   GLOSSARY,
@@ -55,8 +58,14 @@ async function withPaneRuntime<T>(
     const context: MarketContext = ctx.cliOptions.refresh ? { ...market, refresh: true } : market;
     const registry = await createPaneCatalog(context, ctx.plugins);
     try {
-      const parsed = await applyListingArgument(registry, context, parsePaneFunctionArgs(args, ctx.cliOptions), settings.command);
-      const resolved = await resolvePaneFunction(registry, context, parsed, settings);
+      let parsed = await applyListingArgument(registry, context, parsePaneFunctionArgs(args, ctx.cliOptions), settings.command);
+      let resolved = await resolvePaneFunction(registry, context, parsed, settings);
+      // A function that widens its argument (RV's --peers) runs, reports and captures the widened one.
+      const expansion = await withPersistedCloudSession(context, () => expandResolvedArgument(resolved, context, parsed.arg));
+      if (expansion) {
+        parsed = { ...parsed, arg: expansion.argument };
+        resolved = withExpansion(await resolvePaneFunction(registry, context, parsed, settings), expansion);
+      }
       return await run({ parsed, context, registry, resolved });
     } finally {
       registry.destroy();
@@ -64,6 +73,15 @@ async function withPaneRuntime<T>(
   });
 }
 
+/** The resolved function with what its expansion adds to the pane: settings, and a title that says how. */
+function withExpansion(resolved: ResolvedPaneFunction, { settings = {}, title }: HeadlessArgumentExpansion): ResolvedPaneFunction {
+  return {
+    ...resolved,
+    optionSettings: { ...resolved.optionSettings, ...settings },
+    instance: { ...resolved.instance, ...(title ? { title } : {}), settings: { ...resolved.instance.settings, ...settings } },
+  };
+}
+
 /** A word that can be a function code: letters and digits, with the dots and dashes some codes carry. */
 const FUNCTION_CODE_WORD = /^[\w.$-]{1,24}$/;
 
@@ -102,6 +120,42 @@ export async function functionCodeCommand(
   }
 }
 
+/** How many functions an unknown command word is answered with. */
+const COMMAND_HIT_LIMIT = 3;
+
+/**
+ * The functions the catalog finds for a word typed as a command (`gloomberb
+ * comps`): what `catalog <word>` would list first, as many as are close.
+ * Empty when the word finds none or the catalog cannot be read.
+ */
+export async function catalogCommandHits(ctx: CliCommandContext, token: string): Promise<CatalogCommandHit[]> {
+  const word = token.trim();
+  if (!/^[a-z][\w-]{1,30}$/i.test(word)) return [];
+  try {
+    return await withMarketData(ctx, async (market) => {
+      const registry = await createPaneCatalog(market, ctx.plugins);
+      try {
+        return (await suggestPaneFunctions(registry, market, word)).slice(0, COMMAND_HIT_LIMIT).map((entry) => ({
+          code: entry.token,
+          label: entry.label,
+          argKind: entry.argKind ?? null,
+          argPlaceholder: entry.argPlaceholder ?? null,
+          peers: entry.capability.options.some((option) => option.key === "peers" && option.type === "boolean"),
+        }));
+      } finally {
+        registry.destroy();
+      }
+    });
+  } catch {
+    return [];
+  }
+}
+
+/** Whether a list report has no row with data: it is empty, or every row is a name without any. */
+function foundNothing(data: { rowCount: number; unavailableSymbols: readonly string[] }): boolean {
+  return data.rowCount === 0 || data.unavailableSymbols.length >= data.rowCount;
+}
+
 export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
   await runPaneCliCommand(ctx, async () => {
     await withPaneRuntime(ctx, args, async ({ parsed, context, resolved }) => {
@@ -161,6 +215,8 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
         text: () => glossary ? `${report.text}\n\n${renderReportGlossary(resolved.token, glossary)}` : report.text,
         ...(tabular ? { tables: selectReportTables(report.tables, resolved.tableSection) } : {}),
       });
+      // The report is printed as it is; a list that found data for none of its names says so in the exit status too.
+      if (resolved.headless?.failsWithoutData && foundNothing(report.data)) process.exitCode = CLI_EXIT_CODES.error;
     }, { strictHeadlessOptions: true, tableSection: true });
   });
 }
@@ -283,7 +339,7 @@ function runGlossary(term: string, ctx: CliCommandContext): void {
   const { exact, partial } = lookupGlossary(term);
   const entries = [...exact, ...partial];
   if (entries.length === 0) {
-    ctx.fail(`No glossary entry for "${term}".`, "gloomberb catalog glossary lists every term.");
+    ctx.fail(`No glossary entry for "${term}".`, knownGapMessage(term) ?? "gloomberb catalog glossary lists every term.");
   }
   ctx.printResult({ data: entries.map(glossaryRecord) }, { text: () => renderGlossaryEntries(entries).join("\n") });
 }