gloomberb 0.16.4 → 0.16.6

package/src/cli/commands/news-hints.ts

@@ -0,0 +1,62 @@
+import { futuresBoardContract, type FuturesContract, type FuturesSector } from "../../market-data/futures-board";
+import { isFuturesInstrument } from "../../market-data/futures-contract";
+import type { Quote } from "../../types/financials";
+
+/**
+ * A company whose news follows a futures market, for the hint `news` gives a
+ * futures code: news is filed under company tickers, and funds such as UNG
+ * rarely carry stories of their own. Index, rates and currency futures have
+ * none; market headlines fit them better.
+ */
+const CONTRACT_COMPANIES: Readonly<Record<string, string>> = {
+  NG: "EQT", TTF: "LNG", CL: "XOM", BZ: "XOM", RB: "XOM", HO: "XOM",
+  GC: "NEM", SI: "NEM", PL: "NEM", PA: "NEM", HG: "FCX", ALI: "AA",
+};
+const SECTOR_COMPANIES: Partial<Record<FuturesSector, string>> = {
+  energy: "XOM",
+  metals: "NEM",
+  agriculture: "DE",
+  livestock: "TSN",
+};
+
+/** "try news LNG", or market headlines where no company follows the contract. */
+function contractSuggestion(contract: FuturesContract): string {
+  const company = CONTRACT_COMPANIES[contract.code] ?? SECTOR_COMPANIES[contract.sector];
+  return company ? `try news ${company}` : "for market headlines run news with no symbol";
+}
+
+/**
+ * What `news <symbol>` says when it finds no stories: news is filed under
+ * company tickers, so a futures board code (TTF), a futures contract (CL=F)
+ * or a symbol no listing answers to gets told so, with something to try.
+ * `searched` says a text search for the word found no story either.
+ */
+export function newsEmptyMessage(
+  symbol: string,
+  title: string,
+  quote: Pick<Quote, "instrumentType"> | null,
+  resolved: boolean,
+  searched = false,
+): string {
+  const contract = futuresBoardContract(symbol);
+  const typed = symbol.trim().toUpperCase();
+  if (!resolved) {
+    if (searched) {
+      return contract
+        ? `No stories match ${typed}, the futures board's code for ${contract.name}. It is not a ticker: ${contractSuggestion(contract)}.`
+        : `No listing answers to ${typed} and no stories match it. Try \`gloomberb search ${typed}\`.`;
+    }
+    return contract
+      ? `${typed} is the futures board's code for ${contract.name}, not a ticker. news takes a company ticker: ${contractSuggestion(contract)}.`
+      : `No listing answers to ${typed}. news takes a company ticker, such as news AAPL. Try \`gloomberb search ${typed}\`.`;
+  }
+  if (isFuturesInstrument(symbol, quote?.instrumentType)) {
+    if (searched) {
+      return `No stories match ${typed}, and news is filed under company tickers, not futures${contract ? `; ${contractSuggestion(contract)}` : ""}.`;
+    }
+    return `No news for ${title}: news is filed under company tickers, not futures${contract ? `; ${contractSuggestion(contract)}` : ""}.`;
+  }
+  return contract
+    ? `No news for ${title}. ${typed} is also the futures board's code for ${contract.name}: ${contractSuggestion(contract)}.`
+    : `No news for ${title}.`;
+}

package/src/cli/commands/news-search.ts

@@ -0,0 +1,53 @@
+import { apiClient } from "../../api-client";
+import type { NewsArticle } from "../../news/types";
+import { mapCloudNewsArticle } from "../../sources/gloomberb-cloud/news";
+import { cliStyles } from "../../utils/cli-output";
+
+/** What the service accepts of a search: two characters to two hundred, with a letter or a number in them. */
+const MIN_TEXT_LENGTH = 2;
+const MAX_TEXT_LENGTH = 200;
+const MIN_FALLBACK_LENGTH = 3;
+
+/**
+ * The text `news` was asked to search for rather than a symbol: several words,
+ * quoted or not (`news "european gas"`, `news european gas`). A single word
+ * is a symbol until nothing answers to it (`newsFallbackText`).
+ */
+export function newsSearchText(args: readonly string[]): string | null {
+  const text = args.join(" ").trim().replace(/\s+/g, " ");
+  return args.length > 1 || /\s/.test(text) ? text : null;
+}
+
+/** Why the service would refuse the text, or null when it can search it. */
+export function newsSearchTextProblem(text: string): string | null {
+  if (text.length < MIN_TEXT_LENGTH || !/[\p{L}\p{N}]/u.test(text)) return "Search text needs at least two characters, with a letter or a number.";
+  if (text.length > MAX_TEXT_LENGTH) return `Search text is limited to ${MAX_TEXT_LENGTH} characters.`;
+  return null;
+}
+
+/**
+ * The word a symbol lookup found no stories for, as text to search stories for.
+ * Null under three characters, where the fuzzy match finds names that merely
+ * contain it (ZN, Telomir-Zn) and the lookup's own answer is the better one.
+ */
+export function newsFallbackText(symbol: string): string | null {
+  const text = symbol.trim().replace(/^\$/, "");
+  return text.length < MIN_FALLBACK_LENGTH || newsSearchTextProblem(text) ? null : text;
+}
+
+/**
+ * The stories matching the text, newest first. The service answers best match
+ * first and holds stories back from an account without real-time access, as
+ * every other news request.
+ */
+export async function searchNewsStories(text: string, limit: number): Promise<NewsArticle[]> {
+  const response = await apiClient.searchCloudNews(text, limit);
+  return response.items
+    .map((item) => mapCloudNewsArticle(item))
+    .sort((a, b) => b.publishedAt.getTime() - a.publishedAt.getTime());
+}
+
+/** The line above the stories: "Stories matching "european gas"", with why a word typed as a symbol is searched. */
+export function newsSearchHeading(text: string, reason?: string): string {
+  return `${cliStyles.bold(`Stories matching "${text}"`)}${reason ? cliStyles.muted(`  ·  ${reason}`) : ""}`;
+}

package/src/cli/commands/options-leaps.ts

@@ -2,7 +2,7 @@ import type { OptionContract, OptionsChain } from "../../types/financials";
 import type { CliCommandContext } from "../../types/plugin";
 import type { MarketContext } from "../types";
 import type { CliResultColumn } from "../result";
-import { requireCliListing, loadListingQuote, type CliListing } from "../listing-arg";
+import { listingReadNotes, requireCliListing, loadListingQuote, type CliListing } from "../listing-arg";
 import { rowsFreshness } from "../freshness";
 import { formatCountCell } from "../helpers";
 import { cliStyles } from "../../utils/cli-output";
@@ -388,7 +388,10 @@ export async function runLeapsScreen(
     ctx.fail(screened.map((entry) => entry.warning).filter(Boolean).join("\n"));
   }
   const rows = sortLeapsRows(screened.flatMap((entry) => entry.rows), criteria.sort);
-  const warnings = screened.map((entry) => entry.warning).filter((warning): warning is string => warning != null);
+  const warnings = [
+    ...listings.flatMap(listingReadNotes),
+    ...screened.map((entry) => entry.warning).filter((warning): warning is string => warning != null),
+  ];
   const { format, limit: rowLimit, tail } = ctx.cliOptions;
   const capped = format === "text" && rowLimit == null && tail == null && rows.length > LEAPS_TEXT_ROWS;
   const describe = (data: readonly LeapsRow[]) => {

package/src/cli/commands/overview.ts

@@ -10,7 +10,7 @@ import {
   rankScreenerQuotes,
   type ScreenerCategory,
 } from "../../plugins/builtin/market-movers/screener";
-import { formatMoverPrice, moverReferencePrice } from "../../plugins/builtin/market-movers/model";
+import { formatMoverPrice, moverReferencePrice, moverRegularSession } from "../../plugins/builtin/market-movers/model";
 import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, type ExtendedSession } from "../../market-data/market/status";
 import {
   COUNTRY_CYCLE,
@@ -27,14 +27,29 @@ import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix
 import { alignDailyCloses, correlateDailyCloses } from "../../plugins/builtin/correlation/compute";
 import { mixedSessionCloseNote } from "../../market-data/market/session-close-note";
 import { CORRELATION_RETURN_BASIS, loadCorrelationHistory } from "../../plugins/builtin/correlation/history";
-import { EXCHANGE_OPTION, listingIdentity, loadForListing, loadListingQuote, requireCliListing, type CliListing } from "../listing-arg";
+import { EXCHANGE_OPTION, listingIdentity, listingReadNotes, loadForListing, loadListingQuote, requireCliListing, type CliListing } from "../listing-arg";
 import { CLI_COMMAND_GROUPS } from "../help";
 import { formatChangePercentCell, formatCompactCell } from "../helpers";
 import { WORLD_INDICES } from "../../plugins/builtin/world-indices/indices";
 import { getSectorCollection, SECTOR_COLLECTIONS } from "../../plugins/builtin/sectors/sector-data";
 import { DAILY_CLOSES } from "../../plugins/builtin/shared/report-freshness";
-import { newestReportTime, oldestReportTime } from "../../utils/utc-time";
+import { localTimeSuffix, newestReportTime, oldestReportTime } from "../../utils/utc-time";
 import { quotesFreshness, rowsFreshness } from "../freshness";
+import { periodicityOf } from "../pane-functions/freshness";
+import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
+import {
+  basisPointsCell,
+  DEFAULT_FRED_START,
+  fredEmptyMessage,
+  fredExportValue,
+  fredHistoryNotes,
+  fredProvenance,
+  fredPublicationTime,
+  fredValueHeader,
+  fredValueKey,
+  isSpreadSeries,
+  laggingSeriesNote,
+} from "./fred-series";
 
 // Batch quotes often omit names for indices and ETFs; these baskets are fixed, so name them here.
 const BASKET_NAMES = new Map<string, string>([
@@ -80,7 +95,10 @@ const MOVER_COLUMNS = [
   { key: "volume", header: "Volume", 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)" };
+const START_OPTION = {
+  flags: "--start <yyyy-mm-dd>",
+  description: `First observation date; yyyy or yyyy-mm start at the first of that year or month (default ${DEFAULT_FRED_START})`,
+};
 
 const MOVER_LISTS: Record<string, ScreenerCategory | "trending"> = {
   gainers: "day_gainers",
@@ -150,13 +168,25 @@ async function runMoverCommand(args: string[], ctx: Parameters<CliCommandDef["ex
   }
 
   const screener = await fetchScreenerResult(category, limit, undefined, { forceRefresh: ctx.cliOptions.refresh });
-  const rows = rankScreenerQuotes(category, screener.data);
+  // Ranked by the live print, as the list is; then Last and Chg% are the regular
+  // session, as `ticker` reads it, and a pre-market or after-hours print is its own column.
+  const rows = rankScreenerQuotes(category, screener.data).map((quote) => {
+    const { extended, ...row } = moverRegularSession(quote);
+    return {
+      ...row,
+      extendedSession: extended?.session ?? null,
+      extendedPrice: extended?.price ?? null,
+      extendedChange: extended?.change ?? null,
+      extendedChangePercent: extended?.changePercent ?? null,
+    };
+  });
   // A screener snapshot, as the MOST report reads it: delayed, each row dated by its own last price.
   ctx.printResult({ data: rows, freshness: rowsFreshness(rows, { status: "delayed" }, { stale: screener.stale === true }) }, {
     columns: [
       ...MOVER_COLUMNS.slice(0, 4),
+      ...EXTENDED_COLUMNS,
       { key: "volume", header: "Volume", align: "right", value: (row) => formatCompact(Number(row.volume)) },
-      { key: "marketCap", header: "Mkt Cap", align: "right", value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
+      { ...MARKET_CAP_CELL, value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
     ],
   });
 }
@@ -180,12 +210,12 @@ async function runQuoteBasket(symbols: string[], ctx: Parameters<CliCommandDef["
   });
 }
 
-/** The UTC date, or the UTC time with its zone named, of an event's timestamp. */
+/** The UTC date, or the UTC time with its zone named (and the reader's own beside it), of an event's timestamp. */
 function utcDateTimePart(value: unknown, part: "date" | "time"): string {
   const date = new Date(String(value));
   if (Number.isNaN(date.getTime())) return "";
   const iso = date.toISOString();
-  return part === "date" ? iso.slice(0, 10) : `${iso.slice(11, 16)} UTC`;
+  return part === "date" ? iso.slice(0, 10) : `${iso.slice(11, 16)} UTC${localTimeSuffix(date.getTime())}`;
 }
 
 const ECON_USAGE = "econ [--country <region>] [--impact <level>] [--from <yyyy-mm-dd>]";
@@ -204,13 +234,22 @@ function econEmptyMessage(from: string | null, listedThrough: string | null, sto
     : `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 {
+/**
+ * A `yyyy-mm-dd` option, checked here; null when it was not given. `expand`
+ * reads a shorthand as a full date first, and `form` is how the message names
+ * what the option takes.
+ */
+function parseDateOption(
+  value: string | undefined,
+  flag: string,
+  ctx: Parameters<CliCommandDef["execute"]>[1],
+  { expand = (text: string) => text, form = "yyyy-mm-dd" }: { expand?: (text: string) => string; form?: string } = {},
+): string | null {
   if (value == null) return null;
-  const date = value.trim();
+  const date = expand(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}".`);
+    ctx.fail(`${flag} takes a date as ${form}, got "${value}".`);
   }
   return date;
 }
@@ -281,9 +320,15 @@ 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. */
+/** A year or a month stands for the first day of it. */
+function startOfPeriod(text: string): string {
+  if (/^\d{4}$/.test(text)) return `${text}-01-01`;
+  return /^\d{4}-\d{2}$/.test(text) ? `${text}-01` : text;
+}
+
+/** `--start`, checked here: Gloom Cloud cannot read anything but yyyy-mm-dd, so yyyy and yyyy-mm are spelled out. */
 function parseStartDate(value: string | undefined, ctx: Parameters<CliCommandDef["execute"]>[1]): string {
-  return parseDateOption(value, "--start", ctx) ?? "2021-01-01";
+  return parseDateOption(value, "--start", ctx, { expand: startOfPeriod, form: "yyyy-mm-dd, yyyy-mm or yyyy" }) ?? DEFAULT_FRED_START;
 }
 
 /** Gloom Cloud serves a curated set of FRED series and answers 400 for any other id. */
@@ -311,8 +356,9 @@ async function runFredList(filter: string, ctx: Parameters<CliCommandDef["execut
   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" },
+      // A title too narrow to tell series apart goes on a line under its ID.
+      { key: "title", header: "Title", minWidth: 30, stackPriority: 1 },
+      { key: "group", header: "Group", shrink: false },
     ],
     empty: filter ? `No supported FRED series match "${filter}". Run gloomberb fred --list to see them all.` : "No FRED series are listed.",
   });
@@ -335,16 +381,53 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     if (isUnsupportedSeries(error)) ctx.fail(`Unsupported FRED series ${seriesId}. List supported series with: gloomberb fred --list`);
     throw error;
   });
-  const rows = data.observations;
+  // Each observation exports under its unit (`value_bp`, `value_pct`), a spread in basis points.
+  const valueKey = fredValueKey(seriesId, data.info?.units);
+  // A value FRED does not list yet carries its publisher and when it published, in every export.
+  const exportRow = (observation: { date: string; value: number | null; publisher?: string; publishedAt?: string }) => ({
+    date: observation.date,
+    [valueKey]: fredExportValue(seriesId, observation.value),
+    ...(observation.publisher?.trim() ? { publisher: observation.publisher.trim(), ...(observation.publishedAt ? { publishedAt: observation.publishedAt } : {}) } : {}),
+  });
+  const rows = data.observations.map(exportRow);
+  // The default start hides older history and a start before the series begins is moved up silently: say where it really starts.
+  const notes = [
+    ...fredHistoryNotes({ startDate, startGiven: start != null, seriesStart: data.info?.observationStart }),
+    laggingSeriesNote(seriesId),
+  ].filter((note): note is string => note != null);
+  // Nothing on or after the start: name where the series ends, so an empty answer is not a dead end.
+  const latest = rows.length > 0 ? null : await apiClient.getCloudFredSeries(seriesId, { limit: 1, sortOrder: "desc" })
+    .then((payload) => payload.observations[0] ?? null).catch(() => null);
+  const periodicity = periodicityOf(data.info?.frequency);
+  const newestDate = rows.reduce<string | null>((newest, row) => (!newest || row.date > newest ? row.date : newest), null);
+  // A newest value FRED does not list yet names its publisher, Treasury for a yield; FRED's own stay "FRED".
+  const ahead = fredProvenance(data.observations.filter((observation) => observation.date === newestDate));
+  // FRED names the series' publisher when Gloom Cloud passes it on, and when it last updated the series.
+  const publisher = ahead?.publisher ?? data.info?.source?.trim();
+  const publishedAt = ahead ? ahead.publishedAt : fredPublicationTime(data.info, newestDate);
   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 }),
+    metadata: {
+      info: data.info, seriesId, startDate, sortOrder,
+      ...(notes.length ? { notes } : {}),
+      ...(latest ? { latestObservation: exportRow(latest) } : {}),
+    },
+    freshness: rowsFreshness(rows, {
+      source: ahead?.source ?? "FRED", status: "not-a-feed", basis: "published statistics", observedKey: "date", oldest: null,
+      // A monthly or quarterly observation is dated the first of its period, not a day it was seen.
+      ...(periodicity ? { periodicity } : {}),
+      ...(publisher ? { publisher } : {}),
+      ...(publishedAt ? { publishedAt } : {}),
+    }),
   }, {
     dateKey: "date",
+    empty: fredEmptyMessage(startDate, latest),
+    ...(notes.length ? { footnote: notes.join("\n") } : {}),
     textColumns: [
       { key: "date", header: "Date" },
-      { key: "value", header: data.info?.units ? `Value (${data.info.units})` : "Value", align: "right" },
+      isSpreadSeries(seriesId)
+        ? { key: valueKey, header: "Value (bp)", align: "right", format: basisPointsCell }
+        : { key: valueKey, header: fredValueHeader(data.info), align: "right" },
     ],
   });
 }
@@ -358,22 +441,44 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   const series = Object.keys(YIELD_TENORS);
   const results = await Promise.all(series.map(async (seriesId) => {
     const data = await apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder: "desc" });
-    const latest = data.observations[0];
+    const [latest, previous] = data.observations;
     return {
       seriesId,
       date: latest?.date ?? "",
-      value: latest?.value ?? null,
+      // Yields in percent, named so in every export, as `fred` names a percent series.
+      value_pct: latest?.value ?? null,
       title: data.info?.title ?? "",
+      // The move since the previous observation FRED has, not calendar yesterday: a Monday reads against Friday.
+      previousDate: previous?.date ?? null,
+      previousValue_pct: previous?.value ?? null,
+      changeBasisPoints: latest?.value != null && previous?.value != null ? toBasisPoints(latest.value - previous.value, 1) : null,
+      latest,
+      publishedAt: latest?.publisher ? null : fredPublicationTime(data.info, latest?.date),
     };
   }));
+  // Tenors whose latest yield FRED does not list yet name the Treasury and when it published them.
+  const ahead = fredProvenance(results.flatMap((row) => row.latest ? [row.latest] : []));
+  // The curve shown was published with its last tenor: the newest of their FRED updates, when each has one.
+  const published = results.map((row) => row.publishedAt);
+  const publishedAt = ahead ? ahead.publishedAt : published.every((time) => time != null) ? published.sort().at(-1) : null;
   ctx.printResult({
-    data: results,
+    data: results.map(({ publishedAt: _publishedAt, latest: _latest, ...row }) => row),
     metadata: { startDate },
-    freshness: rowsFreshness(results, { source: "FRED", status: "not-a-feed", basis: "daily Treasury yields", observedKey: "date" }),
+    freshness: rowsFreshness(results, {
+      source: ahead?.source ?? "FRED", status: "not-a-feed", basis: "daily Treasury yields", observedKey: "date",
+      ...(ahead?.publisher ? { publisher: ahead.publisher } : {}),
+      ...(publishedAt ? { publishedAt } : {}),
+    }),
   }, {
     textColumns: [
       { key: "tenor", header: "Tenor", value: (row) => YIELD_TENORS[String(row.seriesId)] ?? row.seriesId },
-      { key: "value", header: "Yield %", align: "right" },
+      { key: "value_pct", header: "Yield %", align: "right", format: (value) => typeof value === "number" ? value.toFixed(2) : "-" },
+      {
+        key: "changeBasisPoints",
+        header: "1D bp",
+        align: "right",
+        format: (value) => typeof value === "number" ? formatBasisPoints(value / 100) : "-",
+      },
       { key: "date", header: "Date" },
       { key: "seriesId", header: "Series" },
     ],
@@ -419,9 +524,10 @@ async function runCorrelation(rawArgs: string[], ctx: Parameters<CliCommandDef["
       asOf: newestReportTime(lastBars),
       oldest: oldestReportTime(lastBars),
     });
+    const warnings = [...listingReadNotes(leftListing!), ...listingReadNotes(rightListing!), ...sessionNote ? [sessionNote] : []];
     ctx.printResult({
       data: [{ left, right, samples: sampleSize, correlation }],
-      ...(sessionNote ? { warnings: [sessionNote] } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
       metadata: { range: "1Y", basis: CORRELATION_RETURN_BASIS },
       freshness,
     }, {

package/src/cli/commands/remote.ts

@@ -41,9 +41,10 @@ export const remoteCliCommand: CliCommandDef = {
       return;
     }
 
+    // No data folder means this profile never opened the app, so none is running to drive.
     const dataDir = await getDataDir();
     if (!dataDir) {
-      ctx.fail("No data directory configured.", "Run gloomberb once before using remote control.");
+      ctx.fail("No running Gloomberb app found.", "Open the desktop app or run gloomberb, then try again.");
       return;
     }