gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/yield-curve/swaps-model.ts

@@ -0,0 +1,93 @@
+import { SWAP_TENORS, type SwapCurvePayload, type SwapPoint, type SwapTenor } from "../../../api-client/swap-curve";
+import type { CurveSeries } from "../../../components/chart/curve";
+import { staticSeries } from "../../../components/chart/static/series";
+
+const finite = (value: unknown) => value === null || typeof value === "number" && Number.isFinite(value);
+const count = (value: number) => Number.isInteger(value) && value >= 0;
+const date = (value: unknown) => value === null || typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)
+  && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+const quality = (value: unknown) => value === "ok" || value === "thin" || value === "missing";
+
+/** Reject incompatible observations before they replace the last usable cache. */
+export function validateSwapCurve(payload: SwapCurvePayload): SwapCurvePayload {
+  const invalid = () => { throw new Error("The server returned invalid SOFR swap observations"); };
+  if (!payload || payload.currency !== "USD" || payload.benchmark !== "SOFR" || typeof payload.stale !== "boolean"
+    || !date(payload.asOf) || !date(payload.previousDate) || !date(payload.treasuryDate)
+    || !payload.comparisons?.week || !payload.comparisons.month || !payload.history
+    || !SWAP_TENORS.includes(payload.history.tenor) || !Array.isArray(payload.history.points)) return invalid();
+  for (const snapshot of [{ date: payload.asOf, points: payload.points }, payload.comparisons.week, payload.comparisons.month]) {
+    if (!date(snapshot.date) || !Array.isArray(snapshot.points)
+      || new Set(snapshot.points.map((point) => point.tenor)).size !== snapshot.points.length) return invalid();
+    for (const point of snapshot.points) {
+      if (!SWAP_TENORS.includes(point.tenor) || point.years !== Number.parseInt(point.tenor)
+        || !finite(point.rate) || !finite(point.changeBp) || !finite(point.spreadBp) || !finite(point.treasuryRate)
+        || !count(point.tradeCount) || !count(point.candidateCount) || !count(point.excludedCount)
+        || !Number.isFinite(point.notionalUsd) || point.notionalUsd < 0 || !quality(point.quality)
+        || point.rate != null && (snapshot.date == null || point.tradeCount < 3 || point.quality === "missing" || point.quality === "ok" && point.tradeCount < 5)
+        || point.rate == null && (point.changeBp != null || point.spreadBp != null)
+        || point.tenor === "15Y" && point.spreadBp != null) return invalid();
+    }
+  }
+  if (payload.points.length !== SWAP_TENORS.length) return invalid();
+  let previous = "";
+  for (const point of payload.history.points) {
+    if (point.date == null || !date(point.date) || point.date <= previous || !finite(point.rate) || !finite(point.spreadBp)
+      || !count(point.tradeCount) || !quality(point.quality)
+      || point.rate != null && (point.tradeCount < 3 || point.quality === "missing" || point.quality === "ok" && point.tradeCount < 5)
+      || point.rate == null && point.spreadBp != null
+      || payload.history.tenor === "15Y" && point.spreadBp != null) return invalid();
+    previous = point.date;
+  }
+  return payload;
+}
+
+export function selectedSwapTenor(value: unknown): SwapTenor {
+  return SWAP_TENORS.includes(value as SwapTenor) ? value as SwapTenor : "10Y";
+}
+
+const curvePoints = (points: readonly SwapPoint[]) => points.map((point) => ({
+  id: point.tenor, label: point.tenor, x: point.years, value: point.rate,
+}));
+
+/** Missing tenors remain null nodes, which break the line instead of bridging the gap. */
+export function swapCurveSeries(payload: SwapCurvePayload,
+  colors: { current: string; thin: string; ghosts: Readonly<Record<string, string>> }): CurveSeries[] {
+  const series: CurveSeries[] = [
+    { id: "sofr", label: "SOFR", role: "primary", color: colors.current, points: curvePoints(payload.points) },
+    ...(["week", "month"] as const).flatMap((key): CurveSeries[] => {
+      const snapshot = payload.comparisons[key];
+      const id = key === "week" ? "1W" : "1M";
+      return snapshot.date == null ? [] : [{ id, label: id, role: "ghost", asOf: snapshot.date,
+        color: colors.ghosts[id], points: curvePoints(snapshot.points) }];
+    }),
+  ];
+  // The shared marker layer identifies thin observations on every dated curve.
+  // Keep their values in the main series so selection/readouts still show them.
+  const snapshots = [payload.points, ...(["week", "month"] as const)
+    .filter((key) => payload.comparisons[key].date != null).map((key) => payload.comparisons[key].points)];
+  return [...series, ...series.flatMap((entry, index): CurveSeries[] => {
+    const points = curvePoints(snapshots[index]!.filter((point) => point.quality === "thin" && point.rate != null));
+    return points.length ? [{ id: `${entry.id}-thin`, label: "Thin", role: "marker", color: colors.thin, points }] : [];
+  })];
+}
+
+/** Preserve missing sessions and their null values on the calendar axis. */
+export function swapHistorySeries(history: SwapCurvePayload["history"], color: string, thinColor: string) {
+  const observation = (point: SwapCurvePayload["history"]["points"][number], thin: boolean) => ({
+    date: new Date(point.date), observedAt: new Date(point.date),
+    value: (point.quality === "thin") === thin ? point.rate : null,
+  });
+  return [
+    staticSeries(history.points.map((point) => observation(point, false)),
+      { id: `sofr-${history.tenor}`, label: `${history.tenor} SOFR`, color, calendarSpaced: true }),
+    ...(history.points.some((point) => point.quality === "thin" && point.rate != null)
+      ? [staticSeries(history.points.map((point) => observation(point, true)),
+        { id: `sofr-${history.tenor}-thin`, label: "Thin", color: thinColor, style: "points", calendarSpaced: true })] : []),
+  ];
+}
+
+/** Already in basis points: never multiply a swap change or spread by 100 again. */
+export function formatSwapBp(value: number): string {
+  const rounded = Math.round(value * 10) / 10;
+  return `${rounded > 0 ? "+" : ""}${rounded.toFixed(1)}bp`;
+}

package/src/plugins/builtin/yield-curve/swaps.tsx

@@ -0,0 +1,99 @@
+import { useCallback, useMemo } from "react";
+import type { SwapPoint } from "../../../api-client/swap-curve";
+import {
+  ChartTableHeader, CurveSurface, curveGhostColors, DataTableView, formatPercentAxis, QueryBar,
+  useChartTableSelection, usePaneNoticeFooter, type ChartTableChart, type DataTableColumn,
+} from "../../../components";
+import { curveStrip, curveSurfaceMinRows } from "../../../components/chart/curve";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { usePaneStatusFooter } from "../../../components/layout/pane/status-footer";
+import { FILL_REST } from "../../../components/ui/fill";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePluginPaneState } from "../../../public/react";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAutoRefresh } from "../../../react/auto-refresh";
+import { priceColor } from "../../../theme/colors";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box } from "../../../ui";
+import { getCachedSwapCurve, loadSwapCurve } from "./client";
+import { formatYield, formatYieldChange } from "./chart";
+import { formatSwapBp, selectedSwapTenor, swapCurveSeries, swapHistorySeries } from "./swaps-model";
+
+const COLUMNS: DataTableColumn[] = [
+  { id: "tenor", label: "Tenor", width: 7, align: "left" },
+  { id: "rate", label: "Rate %", width: 9, align: "right" },
+  { id: "changeBp", label: "1D bp", width: 9, align: "right" },
+  { id: "spreadBp", label: "Spread bp", width: 10, align: "right" },
+  { id: "tradeCount", label: "Trades", width: 10, align: "right" },
+];
+const EMPTY_ROWS: SwapPoint[] = [];
+const tenorKey = (row: SwapPoint) => row.tenor;
+const tenorPosition = (row: SwapPoint) => new Date(row.years * 86_400_000);
+
+export function SwapsTab({ focused, width, height }: { focused: boolean; width: number; height: number }) {
+  const colors = useThemeColors();
+  const [selected, setSelected] = usePluginPaneState<string>("yield-curve:swap-tenor", "10Y");
+  const [view, setView] = usePluginPaneState<"curve" | "history">("yield-curve:swap-view", "curve");
+  const tenor = selectedSwapTenor(selected);
+  const loader = useCallback((force: boolean) => loadSwapCurve(tenor, force), [tenor]);
+  const resource = useAsyncResource(loader, {
+    initialData: () => getCachedSwapCurve(tenor), keepPreviousData: true, clearOnError: isAccessDenied,
+  });
+  const payload = resource.data?.payload;
+  const rows = payload?.asOf ? payload.points : EMPTY_ROWS;
+  // A new tenor keeps the curve/table in place, but never relabels the old tenor's history.
+  const history = payload?.history.tenor === tenor ? payload.history : null;
+  const stale = !!payload?.asOf && (payload.stale || resource.data?.stale || false);
+  const error = resource.error || resource.data?.refreshError || null;
+  useAutoRefresh(stale ? null : resource.updatedAt, resource.load);
+  usePaneRefreshKey(resource.reload, { focused });
+  usePaneStatusFooter({ registrationId: "yield-curve:swaps", loading: resource.loading, error, stale });
+  usePaneNoticeFooter({
+    registrationId: "yield-curve:swaps:notices", focused,
+    notices: payload?.asOf ? [
+      ...(!payload.comparisons.week.date ? ["The one-week comparison is unavailable."] : []),
+      ...(!payload.comparisons.month.date ? ["The one-month comparison is unavailable."] : []),
+      ...(!payload.treasuryDate ? ["Same-session Treasury yields are unavailable; swap spreads are blank."] : []),
+    ] : [],
+  });
+
+  useChartTableSelection({ rows, getId: tenorKey, getDate: tenorPosition, selectedId: tenor, onSelect: setSelected, focused });
+  const curve = useMemo(() => payload ? swapCurveSeries(payload, { current: colors.positive, thin: colors.text, ghosts: curveGhostColors(colors) }) : [],
+    [payload, colors]);
+  const historySeries = useMemo(() => history ? swapHistorySeries(history, colors.positive, colors.text) : [], [history, colors.positive, colors.text]);
+  const strip = curveStrip(curve, formatYield, { caption: "SOFR %", selectedPointId: tenor });
+  const chart: ChartTableChart | null = !payload?.asOf ? null : view === "history" ? {
+    series: historySeries, formatValue: formatYield, formatAxisValue: formatPercentAxis,
+    loading: resource.loading && !history, empty: `No history for ${tenor}`,
+  } : strip ? {
+    render: (size) => <CurveSurface series={curve} width={size.width} height={size.height} display="chart"
+      caption="USD SOFR % by maturity" xScale="log" formatValue={formatYield} formatChange={formatYieldChange}
+      formatAxisValue={formatPercentAxis} selectedPointId={tenor} onSelectedPointChange={setSelected} />,
+    minRows: curveSurfaceMinRows({ series: curve, width, caption: "USD SOFR % by maturity" }), strip,
+  } : null;
+  const renderCell = useCallback((row: SwapPoint, column: DataTableColumn) => {
+    if (column.id === "tenor") return { text: row.tenor };
+    if (column.id === "tradeCount") return { text: `${row.tradeCount}${row.quality === "thin" ? " Thin" : ""}`, value: row.tradeCount,
+      color: row.quality === "ok" ? undefined : colors.warning };
+    const value = row[column.id as "rate" | "changeBp" | "spreadBp"];
+    if (value == null) return { text: "--", color: colors.textMuted };
+    if (column.id === "rate") return { text: formatYield(value), value };
+    return { text: formatSwapBp(value), value,
+      color: column.id === "changeBp" ? priceColor(Math.round(value * 10), colors) : undefined };
+  }, [colors]);
+
+  return <Box flexDirection="column" width={width} height={height} {...FILL_REST}>
+    <DataTableView<SwapPoint> focused={focused} rootWidth={width} rootHeight={height}
+      columns={COLUMNS} items={rows} getItemKey={tenorKey} renderCell={renderCell} selectedTextOverridesCellColor
+      selection={{ kind: "id", selectedId: tenor, getId: tenorKey, onChange: setSelected }}
+      onActivate={(row) => { setSelected(row.tenor); setView("history"); }} sortColumnId={null} sortDirection="asc"
+      emptyStateTitle="No swap rates yet."
+      status={{ loading: resource.loading && !payload, error: !payload ? error : null,
+        loadingLabel: "Loading swap rates...", subject: "swap rates", retry: { onRetry: resource.reload, pending: resource.loading } }}
+      rootBefore={payload && !payload.asOf ? null : <ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={COLUMNS}
+        query={<QueryBar width={width}
+          view={{ value: view, options: [{ value: "curve", label: "Curve" }, { value: "history", label: "History" }], onChange: setView }}
+          asOf={payload?.asOf ? `as of ${payload.asOf}` : undefined} />}
+        chart={chart} />} />
+  </Box>;
+}

package/src/plugins/bundle.ts

@@ -32,7 +32,7 @@ import { PLUGIN_HOST_GLOBAL, SHARED_SPECIFIERS, importPluginHostModule } from ".
 export function buildSharedModuleSource(specifier: string, exportNames: readonly string[]): string {
   const lines = [
     `const mod = globalThis[${JSON.stringify(PLUGIN_HOST_GLOBAL)}]?.[${JSON.stringify(specifier)}];`,
-    `if (!mod) throw new Error(${JSON.stringify(`Gloomberb host module "${specifier}" is unavailable. The plugin host was not installed before this plugin loaded.`)});`,
+    `if (!mod) throw new Error(${JSON.stringify(`Gloom host module "${specifier}" is unavailable. The plugin host was not installed before this plugin loaded.`)});`,
     "export default mod;",
   ];
   for (const name of exportNames) {

package/src/plugins/catalog-browser.ts

@@ -16,6 +16,7 @@ import { treasuryDailyModule } from "./builtin/treasury-daily";
 import { revenueBreakdownModule } from "./builtin/revenue-breakdown";
 import { mnaModule } from "./builtin/mna";
 import { cryptoBoardModule } from "./builtin/crypto-board";
+import { cryptoEtfFlowsModule } from "./builtin/crypto-etf-flows";
 import { shortInterestModule } from "./builtin/short-interest";
 import { shortVolumeModule } from "./builtin/short-volume";
 import { socialMentionsModule } from "./builtin/social-mentions";
@@ -216,7 +217,7 @@ const browserFuturesCommoditiesPlugin = composeBuiltinPlugin({
 
 const browserCryptoPlugin = composeBuiltinPlugin({
   ...cryptoPluginMeta,
-  modules: [cryptoBoardModule, perpsModule],
+  modules: [cryptoBoardModule, cryptoEtfFlowsModule, perpsModule],
 });
 
 const browserAltDataPlugin = composeBuiltinPlugin({

package/src/plugins/compat.ts

@@ -128,7 +128,7 @@ export interface PluginIncompatibility {
 export function checkPluginCompatibility(pluginDir: string, hostVersion: string = VERSION): PluginIncompatibility | null {
   const manifest = readPluginManifest(pluginDir);
   const needs = requiredGloomberb(manifest.minGloomberb, hostVersion);
-  if (needs) return { error: `Needs Gloomberb ${needs}, this is ${hostVersion}.`, needsGloomberb: needs };
+  if (needs) return { error: `Needs Gloom ${needs}, this is ${hostVersion}.`, needsGloomberb: needs };
   const peer = missingPeerPlugins(pluginDir)[0];
   if (peer) return { error: `Needs the ${peer} plugin. Install it from the Plugins pane.`, needsPlugin: peer };
   const broken = manifest.id ? KNOWN_BROKEN_PLUGINS[manifest.id] : undefined;
@@ -191,8 +191,8 @@ export function explainPluginLoadError(message: string, hostVersion: string = VE
   if (!missing) return message;
   const { specifier, name } = missing;
   const removed = REMOVED_HOST_EXPORTS[specifier]?.[name];
-  if (removed) return `Uses ${name} from ${specifier}, removed in Gloomberb ${removed.removedIn}. Update the plugin.`;
-  return `Uses ${name} from ${specifier}, which Gloomberb ${hostVersion} does not have. Update the plugin, or Gloomberb if the plugin is newer.`;
+  if (removed) return `Uses ${name} from ${specifier}, removed in Gloom ${removed.removedIn}. Update the plugin.`;
+  return `Uses ${name} from ${specifier}, which Gloom ${hostVersion} does not have. Update the plugin, or Gloom if the plugin is newer.`;
 }
 
 /** The plugin's own source files, without tests, dependencies or build output. */

package/src/plugins/dependencies.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { basename, join } from "path";
 import { logFailure } from "../utils/log-failure";
 import { linkHostPackages } from "./host-link";
 
@@ -55,6 +55,66 @@ export function missingPluginDependencies(pluginDir: string): string[] {
   return [...new Set(missing)];
 }
 
+interface DependencyInstall {
+  directory: string;
+  startedAt: number;
+  endedAt?: number;
+  code?: number | null;
+  done: Promise<unknown>;
+}
+
+/**
+ * Every `bun install` this process ran in a plugin folder. It prunes the
+ * links to the host and to sibling plugins until they are made again, so an
+ * import that fails on a sibling waits for one still running, and its crash
+ * report says which ran.
+ */
+const installs = new Map<string, DependencyInstall>();
+
+/** Runs `install`, a `bun install` in `pluginDir`, on the record. */
+export async function recordDependencyInstall<T extends { code?: number | null } | number | null>(
+  pluginDir: string,
+  install: () => Promise<T>,
+): Promise<T> {
+  const done = install();
+  const settled = done.catch(() => {
+    // Intentional ignore: the caller awaits this same promise and handles its failure.
+  });
+  const entry: DependencyInstall = { directory: basename(pluginDir), startedAt: Date.now(), done: settled };
+  installs.set(pluginDir, entry);
+  try {
+    const result = await done;
+    entry.code = typeof result === "number" || result === null ? result : result.code ?? null;
+    return result;
+  } catch (error) {
+    entry.code = null;
+    throw error;
+  } finally {
+    entry.endedAt = Date.now();
+  }
+}
+
+/** Waits, at most `timeoutMs`, for installs still running in any of `pluginDirs`. */
+export async function settleDependencyInstalls(pluginDirs: readonly string[], timeoutMs: number): Promise<void> {
+  const running = pluginDirs.map((dir) => installs.get(dir)).filter((entry) => entry && entry.endedAt === undefined);
+  if (running.length === 0) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  await Promise.race([
+    Promise.all(running.map((entry) => entry!.done)),
+    new Promise((resolve) => { timer = setTimeout(resolve, timeoutMs); }),
+  ]);
+  clearTimeout(timer);
+}
+
+/** `gloom-ibkr-gateway:0@12s`, one per install this process ran, newest first; `running` while it runs. */
+export function describeDependencyInstalls(now: number = Date.now()): string[] {
+  return [...installs.values()]
+    .sort((a, b) => b.startedAt - a.startedAt)
+    .map((entry) => entry.endedAt === undefined
+      ? `${entry.directory}:running`
+      : `${entry.directory}:${entry.code ?? "?"}@${Math.round((now - entry.endedAt) / 1000)}s`);
+}
+
 /**
  * Installs the dependencies of a plugin that was installed without them, and
  * relinks `gloomberb` and `react`, which `bun install` prunes. Runs through
@@ -64,19 +124,20 @@ export function missingPluginDependencies(pluginDir: string): string[] {
 export async function installPluginDependencies(pluginDir: string): Promise<boolean> {
   const bun = bunCommand();
   if (!bun) return false;
-  let code: number | null = null;
-  try {
-    const child = Bun.spawn([bun.command, "install", "--production"], {
-      cwd: pluginDir,
-      env: bun.env ?? process.env,
-      stdout: "ignore",
-      stderr: "ignore",
-    });
-    code = await child.exited;
-  } catch (error) {
-    logFailure("plugin-dependencies", "Dependency installer launch failed")(error);
-    code = null;
-  }
+  const code = await recordDependencyInstall(pluginDir, async () => {
+    try {
+      const child = Bun.spawn([bun.command, "install", "--production"], {
+        cwd: pluginDir,
+        env: bun.env ?? process.env,
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      return await child.exited;
+    } catch (error) {
+      logFailure("plugin-dependencies", "Dependency installer launch failed")(error);
+      return null;
+    }
+  });
   linkHostPackages(pluginDir);
   return code === 0;
 }

package/src/plugins/extracted-plugins.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "fs";
 import { join } from "path";
 
-import type { AppConfig } from "../types/config";
+import type { AppConfig, PluginSeedFailure } from "../types/config";
 import { debugLog } from "../utils/debug-log";
 import { getPluginsDir } from "./loader";
 import { encodeBuiltinDisabledPluginIds } from "./ownership";
@@ -21,20 +21,22 @@ export const EXTRACTED_PLUGINS = [
   // TV was a module inside Macro, so a user who turned Macro off was turning
   // it off with it. `previousOwnerIds` keeps that choice: the seeder does not
   // restore what someone disabled.
-  { id: "tv", repo: "gloom-sh/gloom-tv", directory: "gloom-tv", previousOwnerIds: ["macro", "macro-tv"] },
-  { id: "substack", repo: "gloom-sh/gloom-substack", directory: "gloom-substack" },
-  { id: "ibkr", repo: "gloom-sh/gloom-ibkr", directory: "gloom-ibkr" },
-  { id: "ibkr-gateway", repo: "gloom-sh/gloom-ibkr-gateway", directory: "gloom-ibkr-gateway" },
-  { id: "public", repo: "gloom-sh/gloom-public", directory: "gloom-public" },
-  { id: "robinhood", repo: "gloom-sh/gloom-robinhood", directory: "gloom-robinhood" },
-  { id: "simplefin", repo: "gloom-sh/gloom-simplefin", directory: "gloom-simplefin" },
-  { id: "polls", repo: "gloom-sh/gloom-polls", directory: "gloom-polls" },
-  { id: "prediction-markets", repo: "gloom-sh/gloom-prediction-markets", directory: "gloom-prediction-markets" },
+  { id: "tv", name: "TV", repo: "gloom-sh/gloom-tv", directory: "gloom-tv", previousOwnerIds: ["macro", "macro-tv"] },
+  { id: "substack", name: "Substack", repo: "gloom-sh/gloom-substack", directory: "gloom-substack" },
+  { id: "ibkr", name: "Interactive Brokers", repo: "gloom-sh/gloom-ibkr", directory: "gloom-ibkr" },
+  { id: "ibkr-gateway", name: "IBKR Gateway", repo: "gloom-sh/gloom-ibkr-gateway", directory: "gloom-ibkr-gateway" },
+  { id: "public", name: "Public", repo: "gloom-sh/gloom-public", directory: "gloom-public" },
+  { id: "robinhood", name: "Robinhood", repo: "gloom-sh/gloom-robinhood", directory: "gloom-robinhood" },
+  { id: "simplefin", name: "SimpleFIN", repo: "gloom-sh/gloom-simplefin", directory: "gloom-simplefin" },
+  { id: "polls", name: "Polls", repo: "gloom-sh/gloom-polls", directory: "gloom-polls" },
+  { id: "prediction-markets", name: "Prediction Markets", repo: "gloom-sh/gloom-prediction-markets", directory: "gloom-prediction-markets" },
   // Bring-your-own-key AI left under a new id, so the choice to switch the old
   // one off is recorded against `ai` rather than against this entry.
-  { id: "byok-ai", repo: "gloom-sh/gloom-byok-ai", directory: "gloom-byok-ai", previousOwnerIds: ["ai"] },
+  { id: "byok-ai", name: "BYOK AI", repo: "gloom-sh/gloom-byok-ai", directory: "gloom-byok-ai", previousOwnerIds: ["ai"] },
 ] as const;
 
+type ExtractedPlugin = (typeof EXTRACTED_PLUGINS)[number];
+
 export interface SeedResult {
   installed: string[];
   failed: string[];
@@ -52,17 +54,12 @@ function isInstalled(directory: string, pluginsDir: string): boolean {
 }
 
 /**
- * Installs any extracted plugin the user has not seen yet.
- *
- * Best effort by design: a failure is logged and retried on the next launch
- * rather than recorded, because the common cause is being offline at startup and
- * marking it seeded would silently drop the plugin forever.
+ * The plugins left to install, each neither recorded as seeded, installed
+ * already, nor switched off before the move, and the ids to record as seeded
+ * without installing them. After a launch's seed, `pending` is what it could
+ * not install.
  */
-export async function seedExtractedPlugins(
-  config: AppConfig,
-  installPlugin: (ref: string) => Promise<unknown>,
-  pluginsDir: string = getPluginsDir(),
-): Promise<SeedResult> {
+function classifyExtractedPlugins(config: AppConfig, pluginsDir: string): { pending: ExtractedPlugin[]; settled: string[] } {
   const alreadySeeded = new Set(config.seededPlugins ?? []);
   // A previous owner that is now a group of built-ins counts as off only while
   // all of them are, which is when its id is saved.
@@ -70,25 +67,39 @@ export async function seedExtractedPlugins(
     ...config.disabledPlugins ?? [],
     ...encodeBuiltinDisabledPluginIds(config.disabledPlugins ?? []),
   ]);
-
-  const result: SeedResult = { installed: [], failed: [], seeded: [...alreadySeeded] };
-
+  const pending: ExtractedPlugin[] = [];
+  const settled: string[] = [];
   for (const entry of EXTRACTED_PLUGINS) {
     if (alreadySeeded.has(entry.id)) continue;
-
-    // Present already: either installed by hand or seeded before this record
-    // existed. Mark it so we stop looking.
-    if (isInstalled(entry.directory, pluginsDir)) {
-      result.seeded.push(entry.id);
+    // Present already (installed by hand, or seeded before this record
+    // existed), or turned off before the move, which restoring it would
+    // override: recorded so we stop looking.
+    if (isInstalled(entry.directory, pluginsDir)
+      || disabled.has(entry.id) || ("previousOwnerIds" in entry && entry.previousOwnerIds.some((id) => disabled.has(id)))) {
+      settled.push(entry.id);
       continue;
     }
+    pending.push(entry);
+  }
+  return { pending, settled };
+}
 
-    // Turned off before the move: restoring it would override that choice.
-    if (disabled.has(entry.id) || ("previousOwnerIds" in entry && entry.previousOwnerIds.some((id) => disabled.has(id)))) {
-      result.seeded.push(entry.id);
-      continue;
-    }
+/**
+ * Installs any extracted plugin the user has not seen yet.
+ *
+ * Best effort by design: a failure is logged and retried on the next launch
+ * rather than recorded, because the common cause is being offline at startup and
+ * marking it seeded would silently drop the plugin forever.
+ */
+export async function seedExtractedPlugins(
+  config: AppConfig,
+  installPlugin: (ref: string) => Promise<unknown>,
+  pluginsDir: string = getPluginsDir(),
+): Promise<SeedResult> {
+  const { pending, settled } = classifyExtractedPlugins(config, pluginsDir);
+  const result: SeedResult = { installed: [], failed: [], seeded: [...config.seededPlugins ?? [], ...settled] };
 
+  for (const entry of pending) {
     try {
       log.info(`Restoring ${entry.id} from ${entry.repo}`);
       await installPlugin(entry.repo);
@@ -102,3 +113,90 @@ export async function seedExtractedPlugins(
 
   return result;
 }
+
+/** `TV, Polls and Substack`. */
+function nameList(names: readonly string[]): string {
+  return names.length <= 1 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+
+/** Where to get git: Git for Windows on Windows, with its download page when there is room for it. */
+export function gitInstallAdvice(platform: string = process.platform, link = false): string {
+  if (platform !== "win32") return "install git";
+  return link ? "install Git for Windows (https://git-scm.com/download/win)" : "install Git for Windows";
+}
+
+function capitalize(text: string): string {
+  return `${text[0]?.toUpperCase() ?? ""}${text.slice(1)}`;
+}
+
+/** What a seed's result leaves to record: the plugins it could not install, sorted, or nothing. */
+export function pluginSeedFailure(failedIds: readonly string[], gitMissing: boolean): PluginSeedFailure | undefined {
+  return failedIds.length > 0 ? { plugins: [...new Set(failedIds)].sort(), gitMissing } : undefined;
+}
+
+/** Whether two recorded seed failures are the same: the same plugins, for the same reason. */
+export function samePluginSeedFailure(a: PluginSeedFailure | undefined, b: PluginSeedFailure | undefined): boolean {
+  return a?.gitMissing === b?.gitMissing && (a?.plugins ?? []).join() === (b?.plugins ?? []).join();
+}
+
+export interface PluginSeedNotice {
+  body: string;
+  type: "error" | "info";
+}
+
+/**
+ * The one notice a launch shows when its seed left official plugins
+ * uninstalled. A missing git, the usual cause on Windows, is an error said at
+ * every launch until git is there, since nothing else installs them. Anything
+ * else (offline, the registry unreadable) the next launch retries on its own,
+ * so it is information, said once and not again while the same plugins keep
+ * failing (`previous` is the failure the last launch recorded).
+ */
+export function pluginSeedNotice(
+  failure: PluginSeedFailure | undefined,
+  previous: PluginSeedFailure | undefined,
+  platform: string = process.platform,
+): PluginSeedNotice | null {
+  const names = EXTRACTED_PLUGINS.filter((entry) => failure?.plugins.includes(entry.id)).map((entry) => entry.name);
+  if (!failure || names.length === 0) return null;
+  const what = names.length <= 2 ? nameList(names) : `${names.length} official plugins`;
+  const one = names.length === 1;
+  if (failure.gitMissing) {
+    return { type: "error", body: `${what} ${one ? "needs" : "need"} Git and ${one ? "is" : "are"} not installed. ${capitalize(gitInstallAdvice(platform))}, then restart Gloom.` };
+  }
+  if (samePluginSeedFailure(failure, previous)) return null;
+  return { type: "info", body: `${what} could not be installed. Gloom tries again at the next launch.` };
+}
+
+/**
+ * `doctor`'s check of the official plugins the seed has not installed: which,
+ * and what to do. A failure only once a launch tried and could not install
+ * them; before any launch has (a terminal-only setup, a container, CI) a
+ * warning, git missing or not. Null when none is missing.
+ */
+export function officialPluginsCheck(
+  config: AppConfig,
+  { gitMissing, pluginsDir = getPluginsDir(), platform = process.platform }: { gitMissing: () => boolean; pluginsDir?: string; platform?: string },
+): { check: string; status: "error" | "warn"; detail: string } | null {
+  const { pending } = classifyExtractedPlugins(config, pluginsDir);
+  if (pending.length === 0) return null;
+  const names = nameList(pending.map((entry) => entry.name));
+  const git = gitMissing() ? gitInstallAdvice(platform, true) : null;
+  const attempted = pending.some((entry) => config.pluginSeedFailure?.plugins.includes(entry.id));
+  if (attempted) {
+    return {
+      check: "official plugins",
+      status: "error",
+      detail: git
+        ? `Not installed: ${names}. They need Git: ${git}, then restart Gloom.`
+        : `Not installed: ${names}. The last launch could not install them; the next one tries again.`,
+    };
+  }
+  return {
+    check: "official plugins",
+    status: "warn",
+    detail: git
+      ? `Not installed yet: ${names}. Gloom installs them when the app starts, which needs Git: ${git}.`
+      : `Not installed yet: ${names}. Gloom installs them when the app next starts.`,
+  };
+}