gloomberb 0.16.2 → 0.16.4

package/src/cli/commands/overview.ts

@@ -1,4 +1,5 @@
 import { apiClient } from "../../api-client";
+import { ApiRequestError } from "../../api-client/errors";
 import type { CliCommandDef } from "../../types/plugin";
 import { withCliServices } from "../context";
 import { formatCompact } from "../../utils/format";
@@ -10,8 +11,18 @@ import {
   type ScreenerCategory,
 } from "../../plugins/builtin/market-movers/screener";
 import { formatMoverPrice, moverReferencePrice } from "../../plugins/builtin/market-movers/model";
-import { loadCalendar, matchesCountry, matchesImpact, type CountryFilter, type ImpactFilter } from "../../plugins/builtin/econ/calendar-model";
-import { isoDate, requireArg, takeOption } from "./command-utils";
+import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, type ExtendedSession } from "../../market-data/market/status";
+import {
+  COUNTRY_CYCLE,
+  FILTER_CYCLE,
+  loadCalendar,
+  matchesCountry,
+  matchesImpact,
+  shortCalendarEnd,
+  type CountryFilter,
+  type ImpactFilter,
+} from "../../plugins/builtin/econ/calendar-model";
+import { isoDate, rejectExtraArgs, requireArg, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix/model";
 import { alignDailyCloses, correlateDailyCloses } from "../../plugins/builtin/correlation/compute";
 import { mixedSessionCloseNote } from "../../market-data/market/session-close-note";
@@ -31,39 +42,89 @@ const BASKET_NAMES = new Map<string, string>([
   ...SECTOR_COLLECTIONS.flatMap((collection) => collection.items.map((item) => [item.etf, item.name] as const)),
 ]);
 // Priced like the MOST pane. Index and yield levels (^GSPC, ^TNX) carry no currency sign.
-const PRICE_COLUMN = { key: "price", header: "Last", align: "right" as const,
-  format: (value: unknown, row: Record<string, unknown>) => typeof value === "number"
+function formatRowPrice(value: unknown, row: Record<string, unknown>): string {
+  return typeof value === "number"
     ? formatMoverPrice(
       value,
       typeof row.currency === "string" && !String(row.symbol ?? "").startsWith("^") ? row.currency : "",
       moverReferencePrice(row as Parameters<typeof moverReferencePrice>[0]),
-    ) : "" };
+    ) : "";
+}
+const PRICE_COLUMN = { key: "price", header: "Last", align: "right" as const, format: formatRowPrice };
+
+/**
+ * A pre-market or after-hours print and its move from the regular close, as
+ * `quote` gives it, in its own column beside Last and Chg%. Text drops a
+ * column no row fills, so a table without an extended print stays as before.
+ */
+function extendedColumn(session: ExtendedSession) {
+  return {
+    key: session === "PRE" ? "preMarket" : "afterHours",
+    header: EXTENDED_SESSION_LABELS[session],
+    align: "right" as const,
+    value: (row: Record<string, unknown>) => row.extendedSession === session ? row.extendedPrice : null,
+    format: (value: unknown, row: Record<string, unknown>) => typeof value === "number"
+      ? [formatRowPrice(value, row), formatChangePercentCell(row.extendedChangePercent)].join(" ").trim()
+      : "",
+  };
+}
+const EXTENDED_COLUMNS = [extendedColumn("PRE"), extendedColumn("POST")];
+// A narrow terminal drops these before it cuts the names short.
+const MARKET_CAP_CELL = { key: "marketCap", header: "Mkt Cap", align: "right" as const, optional: true, dropPriority: 1 };
 const MOVER_COLUMNS = [
   { key: "symbol", header: "Symbol" },
   { key: "name", header: "Name" },
   PRICE_COLUMN,
   { key: "changePercent", header: "Chg%", align: "right" as const, format: formatChangePercentCell },
+  ...EXTENDED_COLUMNS,
   { key: "volume", header: "Volume", align: "right" as const, format: formatCompactCell },
-  { key: "marketCap", header: "Mkt Cap", align: "right" as const, format: formatCompactCell },
+  { ...MARKET_CAP_CELL, format: formatCompactCell },
 ];
 const START_OPTION = { flags: "--start <yyyy-mm-dd>", description: "First observation date (default 2021-01-01)" };
 
-function screenerCategory(value: string | undefined): ScreenerCategory | "trending" {
-  if (value === "losers") return "day_losers";
-  if (value === "active" || value === "most-active") return "most_actives";
-  if (value === "trending") return "trending";
-  return "day_gainers";
+const MOVER_LISTS: Record<string, ScreenerCategory | "trending"> = {
+  gainers: "day_gainers",
+  losers: "day_losers",
+  active: "most_actives",
+  "most-active": "most_actives",
+  trending: "trending",
+};
+const MOVERS_USAGE = "movers [gainers|losers|active|trending]";
+
+function screenerCategory(args: readonly string[], ctx: Parameters<CliCommandDef["execute"]>[1]): ScreenerCategory | "trending" {
+  rejectExtraArgs(args, 1, { usage: MOVERS_USAGE, takes: "one list" }, ctx);
+  const list = args[0]?.toLowerCase() ?? "gainers";
+  const category = MOVER_LISTS[list];
+  if (!category) ctx.fail(`Unknown list "${args[0]}".`, "Use gainers, losers, active or trending.");
+  return category;
+}
+
+/** A command that takes no arguments fails on one, rather than answering as if it were not there. */
+function rejectArgs(args: readonly string[], usage: string, ctx: Parameters<CliCommandDef["execute"]>[1], advice?: string): void {
+  rejectExtraArgs(args, 0, { usage, takes: "no arguments", advice }, ctx);
+}
+
+/** A percent to two decimals, as the table prints it. */
+function roundedPercent(value: number | null): number | null {
+  return value == null ? null : Number(value.toFixed(2));
 }
 
 function quoteRows(results: Awaited<ReturnType<NonNullable<import("../../types/data-provider").AssetDataProvider["getQuotesBatch"]>>>) {
   return results.map((result) => {
     const quote = result.quote;
+    // Last and Chg% are the regular session, as `ticker` reads it; a pre-market or
+    // after-hours print is its own column, measured from that session's close.
+    const session = getQuoteSessionFields(quote);
     return {
       symbol: result.target.symbol,
       name: quote?.name || BASKET_NAMES.get(result.target.symbol) || "",
-      price: quote?.price ?? null,
-      change: quote?.change ?? null,
-      changePercent: quote?.changePercent == null ? null : Number(quote.changePercent.toFixed(2)),
+      price: session.price,
+      change: session.change,
+      changePercent: roundedPercent(session.changePercent),
+      extendedSession: session.extendedSession,
+      extendedPrice: session.extendedPrice,
+      extendedChange: session.extendedChange,
+      extendedChangePercent: roundedPercent(session.extendedChangePercent),
       currency: quote?.currency ?? "",
       providerId: quote?.providerId ?? "",
       marketCap: quote?.marketCap ?? null,
@@ -72,7 +133,7 @@ function quoteRows(results: Awaited<ReturnType<NonNullable<import("../../types/d
 }
 
 async function runMoverCommand(args: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
-  const category = screenerCategory(args[0]);
+  const category = screenerCategory(args, ctx);
   const limit = ctx.cliOptions.limit ?? 25;
   if (category === "trending") {
     await withCliServices(ctx, async (services) => {
@@ -112,7 +173,8 @@ async function runQuoteBasket(symbols: string[], ctx: Parameters<CliCommandDef["
         { key: "name", header: "Name" },
         PRICE_COLUMN,
         { key: "changePercent", header: "Chg%", align: "right", format: formatChangePercentCell },
-        { key: "marketCap", header: "Mkt Cap", align: "right", value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
+        ...EXTENDED_COLUMNS,
+        { ...MARKET_CAP_CELL, value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
       ],
     });
   });
@@ -126,16 +188,61 @@ function utcDateTimePart(value: unknown, part: "date" | "time"): string {
   return part === "date" ? iso.slice(0, 10) : `${iso.slice(11, 16)} UTC`;
 }
 
+const ECON_USAGE = "econ [--country <region>] [--impact <level>] [--from <yyyy-mm-dd>]";
+const DAY_MS = 86_400_000;
+
+/**
+ * What an empty calendar says. A window that starts after the last day listed
+ * says where the listing stops, whatever the filters, rather than nothing.
+ */
+function econEmptyMessage(from: string | null, listedThrough: string | null, stopsShort: boolean): string {
+  if (!listedThrough) return "No events listed.";
+  if (from != null && from > listedThrough) return `No events listed after ${listedThrough}.`;
+  const range = from ? ` from ${from}` : "";
+  return stopsShort
+    ? `No matching events${range}; none listed after ${listedThrough}.`
+    : `No matching events${range} through ${listedThrough}.`;
+}
+
+/** A `yyyy-mm-dd` option, checked here; null when it was not given. */
+function parseDateOption(value: string | undefined, flag: string, ctx: Parameters<CliCommandDef["execute"]>[1]): string | null {
+  if (value == null) return null;
+  const date = value.trim();
+  const time = /^\d{4}-\d{2}-\d{2}$/.test(date) ? Date.parse(`${date}T00:00:00Z`) : Number.NaN;
+  if (!Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== date) {
+    ctx.fail(`${flag} takes a date as yyyy-mm-dd, got "${value}".`);
+  }
+  return date;
+}
+
+/** One of a filter's values, matched without regard to case; anything else fails with the list. */
+function parseFilter<T extends string>(value: string | undefined, values: readonly T[], label: string, ctx: Parameters<CliCommandDef["execute"]>[1]): T {
+  if (value == null) return values[0]!;
+  const match = values.find((candidate) => candidate.toLowerCase() === value.trim().toLowerCase());
+  if (!match) ctx.fail(`Unknown ${label} "${value}".`, `Use ${values.join(", ")}.`);
+  return match;
+}
+
 async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const rawArgs = [...args];
-  const country = (takeOption(rawArgs, "--country") ?? "all") as CountryFilter;
-  const impact = (takeOption(rawArgs, "--impact") ?? "all") as ImpactFilter;
-  await withCliServices(ctx, async (services) => {
-    const { data: events } = await loadCalendar(ctx.cliOptions.refresh);
+  const country: CountryFilter = parseFilter(takeOption(rawArgs, "--country"), COUNTRY_CYCLE, "country", ctx);
+  const impact: ImpactFilter = parseFilter(takeOption(rawArgs, "--impact"), FILTER_CYCLE, "impact", ctx);
+  const fromOption = parseDateOption(takeOption(rawArgs, "--from"), "--from", ctx);
+  rejectArgs(rawArgs, ECON_USAGE, ctx, "Filter with --country and --impact.");
+  await withCliServices(ctx, async () => {
+    const { data: events, fetchedAt, stale } = await loadCalendar(ctx.cliOptions.refresh);
+    const todayStart = Math.floor(Date.now() / DAY_MS) * DAY_MS;
+    // The calendar lists from today (UTC). --from moves the first day; --tail
+    // alone keeps the newest events of the whole calendar, the past week's too.
+    const from = fromOption ?? (ctx.cliOptions.tail != null ? null : new Date(todayStart).toISOString().slice(0, 10));
+    const fromTime = from == null ? Number.NEGATIVE_INFINITY : Date.parse(`${from}T00:00:00Z`);
+    const lastEvent = events.reduce<Date | null>((last, event) => (!last || event.date > last ? event.date : last), null);
+    const listedThrough = lastEvent ? lastEvent.toISOString().slice(0, 10) : null;
+    // A calendar that stops short of a week ahead says so under the table.
+    const listedAfter = shortCalendarEnd(events, Math.max(todayStart, fromTime)) ? `No events listed after ${listedThrough}` : null;
     const rows = events
-      .filter((event) => matchesCountry(event, country) && matchesImpact(event, impact))
+      .filter((event) => event.date.getTime() >= fromTime && matchesCountry(event, country) && matchesImpact(event, impact))
       .sort((left, right) => left.date.getTime() - right.date.getTime())
-      .slice(0, ctx.cliOptions.limit ?? 50)
       .map((event) => ({
         date: isoDate(event.date),
         time: event.time,
@@ -148,9 +255,14 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
       }));
     ctx.printResult({
       data: rows,
-      metadata: { country, impact },
-      freshness: rowsFreshness(rows, { status: "not-a-feed", basis: "calendar", observedKey: "date", oldest: null }),
+      metadata: { country, impact, from, listedThrough },
+      // The calendar as read, not its rows: those are scheduled, mostly ahead.
+      freshness: rowsFreshness([], { status: "not-a-feed", basis: "calendar", asOf: fetchedAt }, { stale }),
     }, {
+      dateKey: "date",
+      defaultLimit: 50,
+      empty: econEmptyMessage(from, listedThrough, listedAfter != null),
+      ...(listedAfter ? { footnote: listedAfter } : {}),
       columns: [
         // Text shows both halves of the event timestamp in UTC, never the host's zone; exports keep the source values.
         { key: "date", header: "Date", format: (value) => utcDateTimePart(value, "date") },
@@ -166,18 +278,70 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
   });
 }
 
+const FRED_USAGE = "fred <series-id> [--start <yyyy-mm-dd>] [--sort desc|asc]";
+const FRED_LIST_USAGE = "fred --list [filter]";
+
+/** `--start`, checked here: Gloom Cloud cannot read anything but yyyy-mm-dd. */
+function parseStartDate(value: string | undefined, ctx: Parameters<CliCommandDef["execute"]>[1]): string {
+  return parseDateOption(value, "--start", ctx) ?? "2021-01-01";
+}
+
+/** Gloom Cloud serves a curated set of FRED series and answers 400 for any other id. */
+function isUnsupportedSeries(error: unknown): boolean {
+  if (!(error instanceof ApiRequestError) || error.status !== 400) return false;
+  const message = typeof error.details?.message === "string" ? error.details.message : error.message;
+  return error.details?.code === "unsupported_series" || /^Unsupported FRED series\b/i.test(message);
+}
+
+async function runFredList(filter: string, ctx: Parameters<CliCommandDef["execute"]>[1]) {
+  let catalog;
+  try {
+    catalog = await apiClient.getCloudFredSeriesCatalog();
+  } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) ctx.fail("The list of supported FRED series is not available yet.");
+    throw error;
+  }
+  const terms = filter.toLowerCase().split(/\s+/).filter(Boolean);
+  const rows = catalog.series
+    .map((series) => ({ id: series.id, title: series.title?.trim() ?? "", group: series.group?.trim() ?? "" }))
+    .filter((series) => {
+      const text = `${series.id} ${series.title} ${series.group}`.toLowerCase();
+      return terms.every((term) => text.includes(term));
+    });
+  ctx.printResult({ data: rows, metadata: { filter: filter || null, total: catalog.series.length } }, {
+    columns: [
+      { key: "id", header: "ID", shrink: false },
+      { key: "title", header: "Title" },
+      { key: "group", header: "Group" },
+    ],
+    empty: filter ? `No supported FRED series match "${filter}". Run gloomberb fred --list to see them all.` : "No FRED series are listed.",
+  });
+}
+
 async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
-  const startDate = takeOption(args, "--start") ?? "2021-01-01";
-  const sortOrder = (takeOption(args, "--sort") ?? "desc") as "asc" | "desc";
-  const seriesId = requireArg(args[0]?.toUpperCase(), "Usage: gloomberb fred <series-id> [--start <yyyy-mm-dd>]", ctx);
-  const data = await apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder });
-  const rows = data.observations.slice(0, ctx.cliOptions.limit ?? data.observations.length);
+  const list = takeFlag(args, "--list");
+  const start = takeOption(args, "--start");
+  const sort = takeOption(args, "--sort");
+  if (list) {
+    if (start != null || sort != null) ctx.fail("--list takes a filter, not --start or --sort.", `Usage: gloomberb ${FRED_LIST_USAGE}`);
+    return runFredList(args.join(" ").trim(), ctx);
+  }
+  const startDate = parseStartDate(start, ctx);
+  const sortOrder = (sort ?? "desc").trim().toLowerCase();
+  if (sortOrder !== "asc" && sortOrder !== "desc") ctx.fail(`Unknown sort order "${sort}".`, "Use desc (newest first) or asc.");
+  const seriesId = requireOneArg(args, FRED_USAGE, "series", ctx).toUpperCase();
+  const data = await apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder }).catch((error: unknown) => {
+    if (isUnsupportedSeries(error)) ctx.fail(`Unsupported FRED series ${seriesId}. List supported series with: gloomberb fred --list`);
+    throw error;
+  });
+  const rows = data.observations;
   ctx.printResult({
     data: rows,
     metadata: { info: data.info, seriesId, startDate, sortOrder },
     freshness: rowsFreshness(rows, { source: "FRED", status: "not-a-feed", basis: "published statistics", observedKey: "date", oldest: null }),
   }, {
+    dateKey: "date",
     textColumns: [
       { key: "date", header: "Date" },
       { key: "value", header: data.info?.units ? `Value (${data.info.units})` : "Value", align: "right" },
@@ -187,8 +351,10 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
 
 const YIELD_TENORS: Record<string, string> = { DGS3MO: "3M", DGS2: "2Y", DGS10: "10Y", DGS30: "30Y" };
 
-async function runYieldCurve(args: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
-  const startDate = takeOption(args, "--start") ?? "2021-01-01";
+async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
+  const args = [...rawArgs];
+  const startDate = parseStartDate(takeOption(args, "--start"), ctx);
+  rejectArgs(args, "yield-curve [--start <yyyy-mm-dd>]", ctx);
   const series = Object.keys(YIELD_TENORS);
   const results = await Promise.all(series.map(async (seriesId) => {
     const data = await apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder: "desc" });
@@ -217,9 +383,10 @@ async function runYieldCurve(args: string[], ctx: Parameters<CliCommandDef["exec
 async function runCorrelation(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const exchange = takeOption(args, "--exchange");
-  const usage = "Usage: gloomberb correlation <symbol-a> <symbol-b>";
-  requireArg(args[0], usage, ctx);
-  requireArg(args[1], usage, ctx);
+  const usage = "correlation <symbol-a> <symbol-b>";
+  requireArg(args[0], `Usage: gloomberb ${usage}`, ctx);
+  requireArg(args[1], `Usage: gloomberb ${usage}`, ctx);
+  rejectExtraArgs(args, 2, { usage, takes: "two symbols", advice: "Run it once per pair." }, ctx);
   await withCliServices(ctx, async (services) => {
     // --exchange is for a symbol that names no exchange of its own.
     const [leftListing, rightListing] = await Promise.all([args[0]!, args[1]!].map((raw) => (
@@ -274,7 +441,7 @@ export const overviewCliCommands: CliCommandDef[] = [
     description: "Show gainers, losers, most active, or trending stocks",
     help: {
       group: CLI_COMMAND_GROUPS.markets,
-      usage: ["movers [gainers|losers|active|trending]"],
+      usage: [MOVERS_USAGE],
       examples: ["movers", "movers losers --limit 10", "movers trending"],
     },
     execute: runMoverCommand,
@@ -283,39 +450,53 @@ export const overviewCliCommands: CliCommandDef[] = [
     name: "indices",
     description: "Show the major US stock indices",
     help: { group: CLI_COMMAND_GROUPS.markets, usage: ["indices"] },
-    execute: (_args, ctx) => runQuoteBasket([...MARKET_SUMMARY_SYMBOLS], ctx, { group: "indices" }),
+    execute: (args, ctx) => {
+      rejectArgs(args, "indices", ctx);
+      return runQuoteBasket([...MARKET_SUMMARY_SYMBOLS], ctx, { group: "indices" });
+    },
   },
   {
     name: "sectors",
     description: "Show the SPDR sector ETFs",
     help: { group: CLI_COMMAND_GROUPS.markets, usage: ["sectors"] },
-    execute: (_args, ctx) => runQuoteBasket(getSectorCollection("sectors").items.map((item) => item.etf), ctx, { group: "sectors" }),
+    execute: (args, ctx) => {
+      rejectArgs(args, "sectors", ctx);
+      return runQuoteBasket(getSectorCollection("sectors").items.map((item) => item.etf), ctx, { group: "sectors" });
+    },
   },
   {
     name: "econ",
     description: "List upcoming economic calendar events",
     help: {
       group: CLI_COMMAND_GROUPS.markets,
-      usage: ["econ [--country <region>] [--impact <level>]"],
+      usage: [ECON_USAGE],
       options: [
         { flags: "--country <region>", description: "US, G7, EU, or all (default all)" },
         { flags: "--impact <level>", description: "high, medium, low, or all (default all)" },
+        { flags: "--from <yyyy-mm-dd>", description: "First day listed (default today, UTC); an earlier day reaches past events" },
       ],
-      examples: ["econ", "econ --country US --impact high"],
+      examples: ["econ", "econ --country US --impact high", "econ --tail 20"],
     },
     execute: runEcon,
   },
   {
     name: "fred",
-    description: "Fetch a FRED economic series (needs a Gloom Cloud sign-in)",
+    description: "Fetch a FRED economic series, or list the ones served",
     help: {
       group: CLI_COMMAND_GROUPS.markets,
-      usage: ["fred <series-id> [--start <yyyy-mm-dd>]"],
+      usage: [FRED_USAGE, FRED_LIST_USAGE],
       options: [
         START_OPTION,
         { flags: "--sort <order>", description: "desc for newest first (default) or asc" },
+        { flags: "--list", description: "List the series Gloom Cloud serves (ID, title, group); words after it filter the list" },
       ],
-      examples: ["fred CPIAUCSL", "fred UNRATE --start 2020-01-01 --csv"],
+      sections: [{
+        title: "Series",
+        lines: [
+          "Gloom Cloud serves a curated set of FRED series and needs no sign-in for them. gloomberb fred --list prints them; any other ID fails with that pointer.",
+        ],
+      }],
+      examples: ["fred CPIAUCSL", "fred DGS10 --tail 5", "fred UNRATE --start 2020-01-01 --csv", "fred --list", "fred --list fx"],
     },
     execute: runFred,
   },

package/src/cli/commands/search.ts

@@ -13,6 +13,7 @@ import { initMarketData, withMarketData } from "../context";
 import { fail } from "../errors";
 import type { MarketContext } from "../types";
 import type { CliCommandContext } from "../../types/plugin";
+import { indexRootFor, indexRootTryLine } from "../index-roots";
 
 interface SearchCommandDependencies {
   initMarketData?: () => Promise<MarketContext>;
@@ -52,6 +53,11 @@ export async function searchCandidatesForCli({
   }
 }
 
+/** "Saved", or the broker a row came from; never the data service's internal id. */
+function searchSourceLabel(candidate: TickerSearchCandidate): string {
+  return candidate.kind === "ticker" ? "Saved" : candidate.result?.brokerLabel || "";
+}
+
 function resolveSearchName(candidate: TickerSearchCandidate): string {
   return candidate.detail.split(" | ")[0] || candidate.detail || "—";
 }
@@ -70,14 +76,22 @@ function searchCandidateRows(candidates: TickerSearchCandidate[]) {
       || candidate.result?.brokerContract?.secType
       || candidate.ticker?.metadata.assetCategory
       || "",
-    source: candidate.kind === "ticker"
-      ? "Saved"
-      : candidate.result?.brokerLabel || candidate.result?.providerId || "Provider",
+    source: searchSourceLabel(candidate),
     providerId: candidate.result?.providerId ?? "",
     saved: candidate.kind === "ticker",
   }));
 }
 
+/**
+ * "^VIX  Cboe Volatility Index (try: gloomberb quote ^VIX)" for a bare index root, whose
+ * search finds funds named after the index but not the index, unless it does list it.
+ */
+function indexRootNote(query: string, candidates: TickerSearchCandidate[]): string | null {
+  const root = indexRootFor(query);
+  if (!root || candidates.some((candidate) => candidate.label.toUpperCase() === root.symbol)) return null;
+  return indexRootTryLine(root);
+}
+
 export function buildSearchReport({
   query,
   candidates,
@@ -86,6 +100,8 @@ export function buildSearchReport({
   candidates: TickerSearchCandidate[];
 }): string {
   const lines = [renderSection(`Search: ${query}`)];
+  const indexNote = indexRootNote(query, candidates);
+  if (indexNote) lines.push("", indexNote);
 
   if (candidates.length === 0) {
     lines.push(cliStyles.muted("No matches found."));
@@ -93,6 +109,8 @@ export function buildSearchReport({
   }
 
   const categories = Array.from(new Set(candidates.map((candidate) => candidate.category)));
+  // Where a row came from, only when one is saved or from a broker.
+  const showSource = candidates.some((candidate) => searchSourceLabel(candidate));
   for (const category of categories) {
     const categoryRows = candidates.filter((candidate) => candidate.category === category);
     lines.push("");
@@ -103,7 +121,7 @@ export function buildSearchReport({
         { header: "Name" },
         { header: "Exchange" },
         { header: "Type" },
-        { header: "Source" },
+        ...(showSource ? [{ header: "Source" }] : []),
       ],
       categoryRows.map((candidate) => [
         candidate.label,
@@ -117,9 +135,7 @@ export function buildSearchReport({
           || candidate.result?.brokerContract?.secType
           || candidate.ticker?.metadata.assetCategory
           || "—",
-        candidate.kind === "ticker"
-          ? "Saved"
-          : candidate.result?.brokerLabel || candidate.result?.providerId || "Provider",
+        ...(showSource ? [searchSourceLabel(candidate) || "—"] : []),
       ]),
     ));
   }
@@ -144,7 +160,12 @@ export async function search(query: string, dependencies: SearchCommandDependenc
     });
 
     if (dependencies.printResult) {
-      dependencies.printResult({ data: searchCandidateRows(candidates), metadata: { query: trimmedQuery } }, {
+      const indexNote = indexRootNote(trimmedQuery, candidates);
+      dependencies.printResult({
+        data: searchCandidateRows(candidates),
+        metadata: { query: trimmedQuery },
+        warnings: indexNote ? [indexNote] : undefined,
+      }, {
         columns: [
           { key: "category", header: "Category" },
           { key: "symbol", header: "Symbol" },