gloomberb 0.16.2 → 0.16.4

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

@@ -25,6 +25,7 @@ import {
   type ParsedPaneFunctionArgs,
 } from "./options";
 import {
+  capabilityHasOption,
   capabilityPaneSettings,
   getHeadlessPaneDefinition,
   getPaneFunctionCapability,
@@ -46,6 +47,8 @@ export interface ResolvedPaneFunction {
   optionSettings: Record<string, unknown>;
   capability: PaneFunctionCapability;
   options: NormalizedPaneFunctionOptions;
+  /** `--section` of a report: the table `--csv` and `--ndjson` write, when the function has no `section` option of its own. */
+  tableSection?: string | true;
 }
 
 async function buildPaneInstance(
@@ -126,12 +129,28 @@ export async function applyListingArgument(
   return { ...args, arg: listing.key, options, listing };
 }
 
+/**
+ * `--section` picks one table of a report's `--csv` or `--ndjson` output. A
+ * function that has a `section` option of its own (CALLS: which part of a
+ * transcript) keeps the flag; its report is one table, so there is nothing to
+ * pick there.
+ */
+function takeTableSection(
+  capability: PaneFunctionCapability,
+  options: ParsedPaneFunctionArgs["options"],
+): { options: ParsedPaneFunctionArgs["options"]; tableSection?: string | true } {
+  if (!("section" in options) || capabilityHasOption(capability, "section")) return { options };
+  const { section, ...rest } = options;
+  return { options: rest, tableSection: section };
+}
+
 export async function resolvePaneFunction(
   registry: PaneFunctionCatalog,
   context: MarketContext,
-  args: ParsedPaneFunctionArgs,
-  resolutionSettings: { strictHeadlessOptions?: boolean } = {},
+  parsedArgs: ParsedPaneFunctionArgs,
+  resolutionSettings: { strictHeadlessOptions?: boolean; tableSection?: boolean } = {},
 ): Promise<ResolvedPaneFunction> {
+  let args = parsedArgs;
   if (!args.target) {
     throw new Error("Usage: gloomberb fn <function-or-pane> [argument] [--key value]");
   }
@@ -152,15 +171,19 @@ export async function resolvePaneFunction(
   const createOptions = buildCreateOptions(template, args.arg);
   const headless = getHeadlessPaneDefinition(template, pane);
   const capability = getPaneFunctionCapability(template, pane);
+  let tableSection: string | true | undefined;
+  if (resolutionSettings.tableSection) {
+    const taken = takeTableSection(capability, args.options);
+    args = { ...args, options: taken.options };
+    tableSection = taken.tableSection;
+  }
   const normalizedOptions = normalizeCapabilityOptions(capability, args.options, {
     strict: args.requireBotSafe || (!!headless && resolutionSettings.strictHeadlessOptions === true),
   });
-  const settings = capability.botSafe
-    ? {
-      ...optionSettings(args.options),
-      ...capabilityPaneSettings(capability, normalizedOptions),
-    }
-    : optionSettings(args.options);
+  const settings = {
+    ...optionSettings(args.options),
+    ...capabilityPaneSettings(capability, normalizedOptions),
+  };
   if (args.requireBotSafe) {
     validateTickerCardinality(capability, createOptions);
   }
@@ -177,6 +200,7 @@ export async function resolvePaneFunction(
     optionSettings: settings,
     capability,
     options: normalizedOptions,
+    ...(tableSection !== undefined ? { tableSection } : {}),
   };
   resolved.instance = await buildPaneInstance(resolved, context, args.arg);
   return resolved;

package/src/cli/pane-functions/screenshot-evidence.ts

@@ -18,6 +18,7 @@ import { scenarioScreenshotEvidence } from "../../plugins/builtin/options-scenar
 import { realizedVolScreenshotEvidence } from "../../plugins/builtin/realized-vol/evidence";
 import { volSurfaceScreenshotEvidence } from "../../plugins/builtin/vol-surface/evidence";
 import { volatilityScreenshotEvidence } from "../../plugins/builtin/volatility/evidence";
+import { marketHeatmapScreenshotEvidence } from "../../plugins/builtin/market-heatmap/evidence";
 import { worldMapScreenshotEvidence } from "../../plugins/builtin/world-venue-map/evidence";
 
 /** The envelope every pane's rendered chart-data evidence carries. */
@@ -95,6 +96,7 @@ const PANE_SCREENSHOT_EVIDENCE: readonly PaneScreenshotEvidenceHook[] = [
   volSurfaceScreenshotEvidence,
   volatilityScreenshotEvidence,
   worldMapScreenshotEvidence,
+  marketHeatmapScreenshotEvidence,
 ];
 
 export function paneScreenshotEvidenceHook(resolved: ResolvedPaneFunction): PaneScreenshotEvidenceHook | null {

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

@@ -1,4 +1,5 @@
 import { fetchTape } from "../../plugins/builtin/time-sales/client";
+import { isOptionsUnavailableError } from "../../market-data/options-alternatives";
 import type { TapeCapture } from "../../plugins/builtin/time-sales/snapshot-client";
 import { apiClient } from "../../api-client";
 import { snapshotInstrumentKey, type SnapshotMarketData } from "../../market-data/snapshot-provider";
@@ -9,7 +10,7 @@ import { dirname, resolve } from "path";
 import { mkdir } from "fs/promises";
 import type { PaneRuntimeState } from "../../core/state/app/state";
 import { CHART_COMPOSER_PANE_ID, type AppConfig } from "../../types/config";
-import type { OptionsChain, PricePoint, TickerFinancials } from "../../types/financials";
+import type { OptionsChain, PricePoint, Quote, TickerFinancials } from "../../types/financials";
 import type { TickerRecord } from "../../types/ticker";
 import { slugifyName } from "../../utils/slugify";
 import {
@@ -18,7 +19,7 @@ import {
   type HttpProxyRequestEnvelope,
   type HttpProxyResponseEnvelope,
 } from "../../utils/http-proxy-response";
-import { getTheme, getThemeIds } from "../../theme/themes";
+import { requireThemeId } from "../commands/themes";
 import { isRecord } from "../../utils/guards";
 
 const DEFAULT_SHOT_DEVICE_SCALE_FACTOR = 2;
@@ -74,6 +75,7 @@ import type { ResolvedSeries } from "../../time-series/types";
 import { getQuoteMonitorPaneSettings } from "../../plugins/builtin/ticker-detail/settings";
 import { accessGateSentence } from "./access-gate";
 import { findCollection } from "../../plugins/builtin/portfolio-list/cli/render";
+import { peekCachedBrokerAccounts } from "../../plugins/builtin/portfolio-list/cached-account";
 import {
   paneEvidenceMismatches,
   paneScreenshotEvidenceHook,
@@ -85,6 +87,7 @@ import {
   clipPriceHistoryToRange,
   createFallbackTicker,
   fetchTickerFinancials,
+  loadBrokerMarkedHolding,
   isFinancialAnalysisFunction,
   readsDailyReturns,
   withShotDailyReturns,
@@ -92,6 +95,9 @@ import {
   withShotPriceHistory,
   withShotSeasonalityHistory,
 } from "./data";
+import { renderedReportFreshness, renderedReportNotices, renderedReportObservations } from "./report-notices";
+import { deriveRenderedFreshness, statusLineVariants, type ReportFreshness } from "./freshness";
+import { quotesFreshness } from "../freshness";
 import {
   financialRatioRenderMismatches,
   financialRatioShotEvidence,
@@ -425,6 +431,10 @@ export interface PaneScreenshotResult {
   usable: boolean;
   unusableReason: string | null;
   dataEvidence: PaneScreenshotDataEvidence | null;
+  /** What the pane says its view leaves out, such as OMON's "21 of 145 strikes". */
+  notices?: string[];
+  /** How current the captured data is, as the capture's status line says it; absent with `--no-status`. */
+  freshness?: ReportFreshness;
   outputPath: string;
   render: DesktopPaneShotRenderResult & {
     expectedText: string[];
@@ -492,7 +502,7 @@ export async function buildDesktopShotPayload(
   };
   const config = stripDesktopShotCredentials<AppConfig>({
     ...context.config,
-    ...(theme ? { theme: resolveShotTheme(theme) } : {}),
+    ...(theme ? { theme: requireThemeId(theme) } : {}),
     layout,
     layouts: [{
       name: "CLI Shot",
@@ -524,7 +534,7 @@ export async function buildDesktopShotPayload(
     shotInstance = { ...shotInstance, settings: { ...shotInstance.settings, ...prepared.settings } };
     for (const [symbol, data] of prepared.financials ?? []) {
       financials.push([symbol, data]);
-      tickers.push(createFallbackTicker(symbol, data, context));
+      tickers.push(await createFallbackTicker(symbol, data, context));
     }
   } else if (resolved.pane.id === "analytics") {
     const loaded = await loadResolvedHeadlessPaneModel(resolved, context, rawArg);
@@ -550,13 +560,23 @@ export async function buildDesktopShotPayload(
       if (!target.instrument) financials.push([label, data]);
       const { symbol } = parsePublicTickerKey(key);
       const ticker = await context.store.loadTicker(key) ?? await context.store.loadTicker(symbol);
-      tickers.push(ticker ?? createFallbackTicker(key, data, context));
+      tickers.push(ticker ?? await createFallbackTicker(key, data, context));
     }
     intradayHistories.push(...chartModel.snapshot.intradayHistories.map((history) => ({
       ...history, start: history.start?.toISOString() ?? null, end: history.end?.toISOString() ?? null,
     })));
   } else for (const symbol of await collectShotSymbolsWithCollections(resolved, context, rawArg)) {
-    const entry = await fetchTickerFinancials(context, symbol);
+    let entry: Awaited<ReturnType<typeof fetchTickerFinancials>>;
+    try {
+      entry = await fetchTickerFinancials(context, symbol);
+    } catch (error) {
+      // The pane values a holding no quote covers, such as an option contract,
+      // at the broker's mark. It has no financials to capture.
+      const holding = COLLECTION_PANE_IDS.has(resolved.pane.id) ? await loadBrokerMarkedHolding(context, symbol) : null;
+      if (!holding) throw error;
+      tickers.push(holding);
+      continue;
+    }
     const requestedRange = shotPriceHistoryRange(resolved);
     let data = entry.financials;
     const exchange = entry.instrument.exchange
@@ -564,7 +584,9 @@ export async function buildDesktopShotPayload(
       ?? data.quote?.listingExchangeName
       ?? data.quote?.exchangeName
       ?? "";
-    const fiveYearsDaily = resolved.pane.id === "realized-vol" || resolved.pane.id === "iv-history" || resolved.pane.id === "macro-day";
+    const fiveYearsDaily = resolved.pane.id === "realized-vol" || resolved.pane.id === "iv-history" || resolved.pane.id === "macro-day"
+      // KELLY's History tab reads monthly returns off five years of daily closes.
+      || resolved.pane.id === "kelly-sizer";
     if (fiveYearsDaily || resolved.pane.id === "iv-screen" || resolved.pane.id === "short-watch"
       || resolved.pane.id === "backtest" || resolved.pane.id === OPTIONS_PANE_ID) {
       // Generic 5Y snapshots can contain weekly bars. The snapshot provider
@@ -599,15 +621,19 @@ export async function buildDesktopShotPayload(
       // letting the pane fetch them.
       data = await withShotPriceHistory(context, symbol, entry.tickerFile, data);
     }
-    tickers.push(entry.tickerFile ?? createFallbackTicker(symbol, data, context));
+    tickers.push(entry.tickerFile ?? await createFallbackTicker(symbol, data, context));
     financials.push([symbol, data]);
     if (resolved.pane.id === "time-sales") {
       tapeSnapshots.push([entry.instrument.symbol, exchange, await fetchTape(entry.instrument.symbol, exchange)]);
     }
     if (includeOptionsChains && context.dataProvider.getOptionsChain) {
+      // A future with no chain of its own is the pane's to explain (the listed alternative), not a failed shot.
       const chain = await context.dataProvider.getOptionsChain(entry.instrument.symbol, exchange, undefined,
-        context.refresh ? { cacheMode: "refresh" } : undefined);
-      optionsChains.push([symbol, chain]);
+        context.refresh ? { cacheMode: "refresh" } : undefined).catch((error: unknown) => {
+        if (isOptionsUnavailableError(error)) return null;
+        throw error;
+      });
+      if (chain) optionsChains.push([symbol, chain]);
     }
   }
   layout.instances[0] = shotInstance;
@@ -625,6 +651,9 @@ export async function buildDesktopShotPayload(
     deviceScaleFactor,
     watermark,
     tickers,
+    ...(COLLECTION_PANE_IDS.has(resolved.pane.id)
+      ? { brokerAccounts: peekCachedBrokerAccounts(context.config, context.persistence?.resources) }
+      : {}),
     financials,
     ...(instrumentFinancials?.length ? { instrumentFinancials } : {}),
     ...(historyVariants?.length ? { historyVariants } : {}),
@@ -662,17 +691,6 @@ async function collectShotSymbolsWithCollections(
   return [...new Set([...symbols, ...members])];
 }
 
-function resolveShotTheme(requested: string): string {
-  const normalized = requested.trim().toLowerCase().replace(/[\s_]+/g, "-");
-  const ids = getThemeIds();
-  const match = ids.find((id) => id.toLowerCase() === normalized)
-    ?? ids.find((id) => getTheme(id).name.toLowerCase().replace(/[\s_]+/g, "-") === normalized);
-  if (!match) {
-    throw new Error(`Unknown theme "${requested}". Available themes: ${ids.join(", ")}`);
-  }
-  return match;
-}
-
 function shotPriceHistoryRange(resolved: ResolvedPaneFunction): TimeRange | null {
   // Captured history is authoritative, and the generic 5Y capture is weekly.
   if (resolved.pane.id === "quote-monitor") return getQuoteMonitorPaneSettings(resolved.instance.settings).chartPeriod;
@@ -687,6 +705,60 @@ function shotPriceHistoryRange(resolved: ResolvedPaneFunction): TimeRange | null
   }
 }
 
+/** The bridge, keeping every quote it serves the page: what a pane that loads its own quotes (WEI) shows. */
+function recordBridgedQuotes(bridge: DesktopPaneShotBridge): { bridge: DesktopPaneShotBridge; quotes: Quote[] } {
+  const quotes: Quote[] = [];
+  const keep = (value: unknown) => {
+    if (isRecord(value) && typeof value.symbol === "string" && typeof value.price === "number") quotes.push(value as unknown as Quote);
+  };
+  return {
+    quotes,
+    bridge: {
+      ...bridge,
+      async marketData(operation, args) {
+        const result = await bridge.marketData(operation, args);
+        if (operation === "getQuote") keep(result);
+        if (operation === "getQuotesBatch" && Array.isArray(result)) {
+          for (const entry of result) keep(isRecord(entry) ? entry.quote : null);
+        }
+        return result;
+      },
+    },
+  };
+}
+
+/**
+ * How current a capture's data is. A pane that says what its data is (its
+ * declared status, or a feed it publishes, such as OMON's chain or the news
+ * wire's delay) is taken at its word; otherwise the quotes it shows date it,
+ * with their delay and where their markets stand; otherwise what the
+ * rendered view carries, which may be nothing.
+ */
+function shotFreshness(
+  resolved: Pick<ResolvedPaneFunction, "pane">,
+  payload: Pick<DesktopPaneShotPayload, "financials" | "instrumentFinancials">,
+  render: Pick<DesktopPaneShotRenderResult, "semanticUi" | "footerText" | "rows">,
+  bridgedQuotes: readonly Quote[],
+  now = Date.now(),
+): ReportFreshness {
+  const declared = { ...resolved.pane.reportFreshness, ...renderedReportFreshness(render.semanticUi ?? []) };
+  const quotes = [
+    ...payload.financials.map(([, financials]) => financials.quote),
+    ...(payload.instrumentFinancials ?? []).map(({ financials }) => financials.quote),
+    ...bridgedQuotes,
+  ];
+  // A pane that publishes the observations behind its figures (FXC's rates) dates itself.
+  const observed = renderedReportObservations(render.semanticUi ?? []);
+  const quoted = declared.status || observed.length > 0
+    ? undefined
+    : quotesFreshness(quotes, declared.source ? { source: declared.source } : undefined, now);
+  return quoted ?? deriveRenderedFreshness(declared, {
+    footerText: render.footerText ?? "",
+    cellTimes: render.rows.flatMap((row) => row.cells.flatMap((cell) => (cell.instant ? [cell.instant] : []))),
+    observed,
+  }, now);
+}
+
 export async function renderDesktopShot({
   resolved,
   context,
@@ -697,6 +769,7 @@ export async function renderDesktopShot({
   theme,
   scale,
   watermark,
+  statusLine = false,
   options,
   captureImage = true,
 }: {
@@ -709,6 +782,8 @@ export async function renderDesktopShot({
   theme?: string | null;
   scale?: number;
   watermark?: string | null;
+  /** Draw the dated status line in the capture's footer. Reports and `--no-status` leave it out. */
+  statusLine?: boolean;
   options: Record<string, string | true>;
   captureImage?: boolean;
 }): Promise<PaneScreenshotResult> {
@@ -717,6 +792,7 @@ export async function renderDesktopShot({
   const previousSessionToken = apiClient.getSessionToken();
   let payload: DesktopPaneShotPayload;
   let render: DesktopPaneShotRenderResult;
+  let freshness: ReportFreshness | undefined;
   apiClient.setSessionToken(apiProxy.sessionToken);
   try {
     payload = await buildDesktopShotPayload(
@@ -730,16 +806,24 @@ export async function renderDesktopShot({
       scale ?? 1,
       watermark ?? null,
     );
+    if (statusLine && captureImage) payload.statusLine = true;
+    const recorded = recordBridgedQuotes(createDesktopShotBridge(context));
+    const shotPayload = payload;
     render = await renderDesktopPaneScreenshot(payload, outputPath, apiProxy, {
       captureImage,
-      bridge: createDesktopShotBridge(context),
+      bridge: recorded.bridge,
+      statusLine: (rendered) => {
+        freshness = shotFreshness(resolved, shotPayload, rendered, recorded.quotes);
+        return statusLineVariants(freshness);
+      },
     });
   } finally {
     apiClient.setSessionToken(previousSessionToken);
   }
   const renderedInstance = payload.config.layout.instances.find(({ instanceId }) => instanceId === payload.paneId);
   if (renderedInstance) resolved = { ...resolved, instance: renderedInstance };
-  return assessPaneScreenshot(resolved, payload, render, rawArg, outputPath);
+  const assessed = assessPaneScreenshot(resolved, payload, render, rawArg, outputPath);
+  return freshness ? { ...assessed, freshness } : assessed;
 }
 
 /** What a rendered capture shows, and whether it is fit to use. */
@@ -803,6 +887,7 @@ export function assessPaneScreenshot(
   const unusableReason = usable
     ? null
     : shotUnusableReasonFor(resolved, payload, render, unavailableSymbols, semanticMismatch);
+  const { notices } = renderedReportNotices(render.semanticUi ?? []);
   return {
     kind: "pane-screenshot",
     target: resolved.token,
@@ -823,6 +908,7 @@ export function assessPaneScreenshot(
     usable,
     unusableReason,
     dataEvidence,
+    ...(notices.length > 0 ? { notices } : {}),
     outputPath,
     render: {
       ...stripDesktopShotCredentials(render),

package/src/cli/registry.ts

@@ -27,6 +27,8 @@ interface RegisteredCliCommand {
   command: CliCommandDef;
   ownerId: string;
   source: "core" | "plugin";
+  /** Core or a built-in plugin: its declared options are the only ones it takes. External plugins are not held to theirs. */
+  builtin: boolean;
 }
 
 export interface CliCommandRegistry {
@@ -80,6 +82,7 @@ export function buildCliCommandRegistry({
     command: CliCommandDef,
     ownerId: string,
     source: "core" | "plugin",
+    builtin: boolean,
   ) => {
     const tokens = new Set([
       validateCommandToken(command.name, ownerId, source),
@@ -95,7 +98,7 @@ export function buildCliCommandRegistry({
       );
     }
 
-    const entry: RegisteredCliCommand = { command, ownerId, source };
+    const entry: RegisteredCliCommand = { command, ownerId, source, builtin };
     allCommands.push(entry);
     for (const token of tokens) {
       allTokens.set(token, entry);
@@ -103,7 +106,7 @@ export function buildCliCommandRegistry({
   };
 
   for (const command of coreCommands) {
-    registerCommand(command, "core", "core");
+    registerCommand(command, "core", "core", true);
   }
 
   const loadablePlugins: GloomPlugin[] = [];
@@ -117,7 +120,7 @@ export function buildCliCommandRegistry({
     }
     loadablePlugins.push(entry.plugin);
     for (const command of entry.plugin.cliCommands ?? []) {
-      registerCommand(command, entry.plugin.id, "plugin");
+      registerCommand(command, entry.plugin.id, "plugin", entry.source === "builtin");
     }
   }
 
@@ -146,6 +149,7 @@ export function createCliCommandContext(
   ownerId: string,
   registryOrPlugins: Pick<CliCommandRegistry, "plugins" | "externalPlugins"> | GloomPlugin[],
   cliOptions: CliGlobalOptions = DEFAULT_CLI_OPTIONS,
+  args: readonly string[] = [],
 ): CliCommandContext {
   const registry = Array.isArray(registryOrPlugins)
     ? { plugins: registryOrPlugins, externalPlugins: [] }
@@ -166,7 +170,7 @@ export function createCliCommandContext(
       renderStats,
       renderTable,
     },
-    printResult: (result, options) => printCliResult(result, cliOptions, options),
+    printResult: (result, options) => printCliResult(result, cliOptions, options, args),
     log: debugLog.createLogger(ownerId === "core" ? "cli" : ownerId),
   };
 }