gloomberb 0.16.4 → 0.16.6

package/src/data/config/store/portfolio-as-of-column.ts

@@ -0,0 +1,57 @@
+import { isRecord } from "../../../utils/guards";
+
+const PORTFOLIO_PANE_ID = "portfolio-list";
+
+/**
+ * The portfolio pane's default columns before AS OF UTC took AGE's place
+ * (GLO-575). Frozen here: the current default may change again, and only a
+ * list still equal to this one was never chosen by the user.
+ */
+const PREVIOUS_DEFAULT_COLUMN_IDS: readonly string[] = [
+  "ticker", "price", "change_pct", "market_cap", "pe", "forward_pe", "latency",
+  "sparkline", "shares", "avg_cost", "cost_basis", "mkt_value", "day_pnl", "pnl", "pnl_pct",
+];
+
+function isPreviousDefault(value: unknown): value is string[] {
+  return Array.isArray(value)
+    && value.length === PREVIOUS_DEFAULT_COLUMN_IDS.length
+    && value.every((columnId, index) => columnId === PREVIOUS_DEFAULT_COLUMN_IDS[index]);
+}
+
+/**
+ * A layout whose portfolio panes still show the old default columns, with AS
+ * OF UTC where AGE was, so they date each row by the price its value uses as
+ * new panes do. A list the user changed in any way keeps every column, and a
+ * list already moved over is left as it is. Returns the layout itself when
+ * nothing changes.
+ */
+export function swapDefaultPortfolioAgeColumn<T>(layout: T): T {
+  if (!isRecord(layout) || !Array.isArray(layout.instances)) return layout;
+  let changed = false;
+  const instances = layout.instances.map((instance: unknown) => {
+    if (!isRecord(instance) || instance.paneId !== PORTFOLIO_PANE_ID || !isRecord(instance.settings)) return instance;
+    const columnIds = instance.settings.columnIds;
+    if (!isPreviousDefault(columnIds)) return instance;
+    changed = true;
+    return {
+      ...instance,
+      settings: { ...instance.settings, columnIds: columnIds.map((columnId) => columnId === "latency" ? "as_of" : columnId) },
+    };
+  });
+  return changed ? { ...layout, instances } as T : layout;
+}
+
+/** The open layout and every saved tab. */
+export function migratePortfolioAsOfColumn(saved: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...saved,
+    ...("layout" in saved ? { layout: swapDefaultPortfolioAgeColumn(saved.layout) } : {}),
+    ...(Array.isArray(saved.layouts)
+      ? {
+        layouts: saved.layouts.map((entry: unknown) => (
+          isRecord(entry) && "layout" in entry ? { ...entry, layout: swapDefaultPortfolioAgeColumn(entry.layout) } : entry
+        )),
+      }
+      : {}),
+  };
+}

package/src/data/ticker-repository.ts

@@ -33,6 +33,11 @@ export class TickerRepository {
     this.tickers.save(ticker.metadata.ticker, ticker.metadata);
   }
 
+  /** Saves several tickers in one write. */
+  async saveTickers(tickers: readonly TickerRecord[]): Promise<void> {
+    this.tickers.saveMany(tickers.map((ticker) => ({ symbol: ticker.metadata.ticker, metadata: ticker.metadata })));
+  }
+
   async createTicker(metadata: TickerMetadata): Promise<TickerRecord> {
     const ticker: TickerRecord = { metadata };
     await this.saveTicker(ticker);

package/src/data/ticker-store.ts

@@ -42,6 +42,21 @@ export class TickerStore {
     });
   }
 
+  /** Saves every record in one transaction: one write for a whole import, not one per ticker. */
+  saveMany(records: ReadonlyArray<{ symbol: string; metadata: unknown }>): void {
+    if (records.length === 0) return;
+    withSqliteBusyRetry("save tickers", () => {
+      const statement = this.db.query(
+        `INSERT OR REPLACE INTO tickers (symbol, metadata, updated_at)
+         VALUES (?, ?, ?)`,
+      );
+      const now = Date.now();
+      this.db.transaction(() => {
+        for (const record of records) statement.run(record.symbol, serializeJson(record.metadata), now);
+      })();
+    });
+  }
+
   delete(symbol: string): void {
     withSqliteBusyRetry("delete ticker", () => {
       this.db.query("DELETE FROM tickers WHERE symbol = ?").run(symbol);

package/src/docs/content.ts

@@ -0,0 +1,215 @@
+/**
+ * The docs and the Academy as gloom.sh publishes them for the app: one
+ * source, read in the DOCS pane instead of a browser. The site serves the
+ * index (every function, every docs page, the Academy outline) at
+ * `/api/app-docs` and one lesson at `/api/app-docs/academy/<lesson>`, as JSON
+ * blocks of markdown text. Nothing here is HTML and nothing is executed:
+ * blocks are drawn with the app's own components, and an unknown block or
+ * field is dropped rather than shown.
+ */
+
+export const DOCS_SITE = "https://gloom.sh";
+export const DOCS_FEED_URL = `${DOCS_SITE}/api/app-docs`;
+/** The feed shape this app reads; a newer major shape falls back to the saved copy. */
+const DOCS_FEED_FORMAT = 1;
+/** The DOCS pane's template, for the chrome and the help card to open it by id. */
+export const DOCS_PANE_TEMPLATE_ID = "docs-pane";
+
+export type DocsBlock =
+  | { type: "paragraph"; text: string }
+  | { type: "heading"; level: 2 | 3; text: string }
+  | { type: "list"; ordered?: boolean; start?: number; items: string[] }
+  | { type: "table"; headers: string[]; rows: string[][] }
+  | { type: "code"; code: string }
+  | { type: "image"; src: string; alt: string; caption?: string }
+  | { type: "diagram"; alt: string; light: string; dark: string; steps?: string[] }
+  | { type: "callout"; kind?: string; blocks: DocsBlock[] }
+  | { type: "details"; summary: string; blocks: DocsBlock[] };
+
+export interface DocsFunction {
+  code: string;
+  name: string;
+  description: string;
+  detail: string;
+  category: string;
+  arg?: string;
+  access?: "pro" | "cloud";
+  plugin?: { id: string; name: string };
+  /** Screenshot URL on gloom.sh. */
+  shot?: string;
+  /** The Academy lesson that teaches it, as a site path. */
+  lesson?: string;
+}
+
+export interface DocsPage {
+  slug: string;
+  title: string;
+  lead: string;
+  category: string;
+  tags: string[];
+  updatedAt?: string;
+  blocks: DocsBlock[];
+}
+
+export interface DocsLessonSummary {
+  /** `/academy/<chapter>/<section>/<lesson>` */
+  url: string;
+  title: string;
+  summary: string;
+  chapter: string;
+  minutes: number;
+}
+
+export interface DocsLesson extends DocsLessonSummary {
+  blocks: DocsBlock[];
+}
+
+export interface DocsFeed {
+  /** The newest page date, `YYYY-MM-DD`. */
+  updatedAt: string;
+  categories: Array<{ id: string; title: string }>;
+  functions: DocsFunction[];
+  pages: DocsPage[];
+  lessons: DocsLessonSummary[];
+}
+
+type Json = Record<string, unknown>;
+
+const isRecord = (value: unknown): value is Json => !!value && typeof value === "object" && !Array.isArray(value);
+const text = (value: unknown): value is string => typeof value === "string";
+const texts = (value: unknown): value is string[] => Array.isArray(value) && value.every(text);
+/** An image only ever comes from the site itself, over https. */
+const siteImage = (value: unknown): value is string => text(value) && value.startsWith(`${DOCS_SITE}/`);
+
+function parseBlock(raw: unknown): DocsBlock | null {
+  if (!isRecord(raw)) return null;
+  switch (raw.type) {
+    case "paragraph":
+      return text(raw.text) ? { type: "paragraph", text: raw.text } : null;
+    case "heading":
+      return text(raw.text) ? { type: "heading", level: raw.level === 3 ? 3 : 2, text: raw.text } : null;
+    case "list":
+      if (!texts(raw.items)) return null;
+      return {
+        type: "list",
+        items: raw.items,
+        ...(raw.ordered === true ? { ordered: true } : {}),
+        ...(typeof raw.start === "number" && Number.isInteger(raw.start) ? { start: raw.start } : {}),
+      };
+    case "table":
+      if (!texts(raw.headers) || !Array.isArray(raw.rows) || !raw.rows.every(texts)) return null;
+      return { type: "table", headers: raw.headers, rows: raw.rows as string[][] };
+    case "code":
+      return text(raw.code) ? { type: "code", code: raw.code } : null;
+    case "image":
+      if (!siteImage(raw.src)) return null;
+      return {
+        type: "image",
+        src: raw.src,
+        alt: text(raw.alt) ? raw.alt : "",
+        ...(text(raw.caption) ? { caption: raw.caption } : {}),
+      };
+    case "diagram":
+      if (!siteImage(raw.light) || !siteImage(raw.dark)) return null;
+      return {
+        type: "diagram",
+        alt: text(raw.alt) ? raw.alt : "",
+        light: raw.light,
+        dark: raw.dark,
+        ...(texts(raw.steps) ? { steps: raw.steps } : {}),
+      };
+    case "callout":
+      return {
+        type: "callout",
+        ...(text(raw.kind) ? { kind: raw.kind } : {}),
+        blocks: parseBlocks(raw.blocks),
+      };
+    case "details":
+      return text(raw.summary) ? { type: "details", summary: raw.summary, blocks: parseBlocks(raw.blocks) } : null;
+    default:
+      return null;
+  }
+}
+
+function parseBlocks(raw: unknown): DocsBlock[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(parseBlock).filter((block): block is DocsBlock => block !== null);
+}
+
+function parseFunction(raw: unknown): DocsFunction | null {
+  if (!isRecord(raw) || !text(raw.code) || !text(raw.name) || !text(raw.description) || !text(raw.detail)) return null;
+  const plugin = isRecord(raw.plugin) && text(raw.plugin.id) && text(raw.plugin.name)
+    ? { id: raw.plugin.id, name: raw.plugin.name }
+    : undefined;
+  return {
+    code: raw.code.toUpperCase(),
+    name: raw.name,
+    description: raw.description,
+    detail: raw.detail,
+    category: text(raw.category) ? raw.category : "",
+    ...(text(raw.arg) ? { arg: raw.arg } : {}),
+    ...(raw.access === "pro" || raw.access === "cloud" ? { access: raw.access } : {}),
+    ...(plugin ? { plugin } : {}),
+    ...(siteImage(raw.shot) ? { shot: raw.shot } : {}),
+    ...(text(raw.lesson) && raw.lesson.startsWith("/academy/") ? { lesson: raw.lesson } : {}),
+  };
+}
+
+function parsePage(raw: unknown): DocsPage | null {
+  if (!isRecord(raw) || !text(raw.slug) || !text(raw.title)) return null;
+  return {
+    slug: raw.slug,
+    title: raw.title,
+    lead: text(raw.lead) ? raw.lead : "",
+    category: text(raw.category) ? raw.category : "",
+    tags: texts(raw.tags) ? raw.tags : [],
+    ...(text(raw.updatedAt) ? { updatedAt: raw.updatedAt } : {}),
+    blocks: parseBlocks(raw.blocks),
+  };
+}
+
+function parseLessonSummary(raw: unknown): DocsLessonSummary | null {
+  if (!isRecord(raw) || !text(raw.url) || !raw.url.startsWith("/academy/") || !text(raw.title)) return null;
+  return {
+    url: raw.url,
+    title: raw.title,
+    summary: text(raw.summary) ? raw.summary : "",
+    chapter: text(raw.chapter) ? raw.chapter : "",
+    minutes: typeof raw.minutes === "number" && Number.isFinite(raw.minutes) ? raw.minutes : 0,
+  };
+}
+
+function compact<T>(values: unknown, parse: (raw: unknown) => T | null): T[] {
+  return Array.isArray(values) ? values.map(parse).filter((value): value is T => value !== null) : [];
+}
+
+/** The index as the site sent it, or null when it is not a feed this app can read. */
+export function parseDocsFeed(raw: unknown): DocsFeed | null {
+  if (!isRecord(raw) || raw.format !== DOCS_FEED_FORMAT) return null;
+  const functions = compact(raw.functions, parseFunction);
+  const pages = compact(raw.pages, parsePage);
+  // A feed with nothing to read is a broken response, not an empty manual.
+  if (functions.length === 0 || pages.length === 0) return null;
+  return {
+    updatedAt: text(raw.updatedAt) ? raw.updatedAt : "",
+    categories: compact(raw.categories, (category) => (
+      isRecord(category) && text(category.id) && text(category.title) ? { id: category.id, title: category.title } : null
+    )),
+    functions,
+    pages,
+    lessons: compact(raw.lessons, parseLessonSummary),
+  };
+}
+
+export function parseDocsLesson(raw: unknown): DocsLesson | null {
+  if (!isRecord(raw) || raw.format !== DOCS_FEED_FORMAT) return null;
+  const summary = parseLessonSummary(raw);
+  if (!summary) return null;
+  const blocks = parseBlocks(raw.blocks);
+  return blocks.length > 0 ? { ...summary, blocks } : null;
+}
+
+/** Where the site serves one lesson's blocks. */
+export function docsLessonFeedUrl(url: string): string {
+  return `${DOCS_SITE}/api/app-docs${url}`;
+}

package/src/docs/load.ts

@@ -0,0 +1,139 @@
+/**
+ * Where the DOCS pane gets its text. The index comes from gloom.sh, read at
+ * most every few hours and kept; the copy that ships with the app covers a
+ * first start and a machine that is offline. A lesson is read when it is
+ * opened and kept the same way, so a lesson read once stays readable.
+ */
+import { createPluginCache } from "../data/plugin-cache";
+import type { PluginPersistence } from "../types/plugin";
+import { createThrottledFetch } from "../utils/throttled-fetch";
+import {
+  DOCS_FEED_URL,
+  docsLessonFeedUrl,
+  parseDocsFeed,
+  parseDocsLesson,
+  type DocsFeed,
+  type DocsLesson,
+} from "./content";
+
+const HOUR_MS = 60 * 60_000;
+const YEAR_MS = 365 * 24 * HOUR_MS;
+const FEED_KEY = "index";
+
+const docsFetch = createThrottledFetch({
+  requestsPerMinute: 20,
+  maxRetries: 1,
+  timeoutMs: 10_000,
+  backoffBaseMs: 500,
+  dedupeGetRequests: true,
+  defaultHeaders: { Accept: "application/json" },
+});
+
+const feedCache = createPluginCache<DocsFeed>({
+  kind: "docs-index",
+  source: "gloom-site",
+  policy: { staleMs: 6 * HOUR_MS, expireMs: YEAR_MS },
+  decode: (value) => {
+    const feed = parseDocsFeed({ format: 1, ...(value as object) });
+    if (!feed) throw new Error("Unreadable saved docs");
+    return feed;
+  },
+});
+
+const lessonCache = createPluginCache<DocsLesson>({
+  kind: "docs-lesson",
+  source: "gloom-site",
+  policy: { staleMs: 24 * HOUR_MS, expireMs: YEAR_MS },
+  decode: (value) => {
+    const lesson = parseDocsLesson({ format: 1, ...(value as object) });
+    if (!lesson) throw new Error("Unreadable saved lesson");
+    return lesson;
+  },
+});
+
+export function attachDocsPersistence(persistence: PluginPersistence): void {
+  feedCache.attach(persistence);
+  lessonCache.attach(persistence);
+}
+
+export function resetDocsPersistence(): void {
+  feedCache.reset();
+  lessonCache.reset();
+}
+
+type FetchJson = (url: string) => Promise<unknown>;
+
+const siteFetchJson: FetchJson = async (url) => {
+  const response = await docsFetch.fetch(url);
+  if (!response.ok) throw new Error(`gloom.sh returned ${response.status}`);
+  return response.json();
+};
+
+let fetchJson = siteFetchJson;
+
+/** Tests read a fixed site, or none; null restores the real one. */
+export function setDocsFetchForTests(next: FetchJson | null): void {
+  fetchJson = next ?? siteFetchJson;
+}
+
+let snapshot: Promise<DocsFeed> | null = null;
+
+/** The copy that ships with the app. Loaded on first use: the web build keeps it out of the startup bundle. */
+function loadDocsSnapshot(): Promise<DocsFeed> {
+  snapshot ??= import("./snapshot.chunk.js").then(({ DOCS_SNAPSHOT }) => {
+    const feed = parseDocsFeed(DOCS_SNAPSHOT);
+    if (!feed) throw new Error("The docs that ship with the app are unreadable.");
+    return feed;
+  });
+  return snapshot;
+}
+
+export interface DocsFeedResult {
+  feed: DocsFeed;
+  /** The site could not be read; this is the saved or shipped copy. */
+  offline: boolean;
+}
+
+/** A saved copy older than the one the app shipped with loses to it. */
+function newer(saved: DocsFeed | null, shipped: DocsFeed): DocsFeed {
+  return saved && saved.updatedAt >= shipped.updatedAt ? saved : shipped;
+}
+
+/** The index as last read, without waiting on the network; null before the first read. */
+export function savedDocsFeed(): DocsFeed | null {
+  return feedCache.get(FEED_KEY, { allowExpired: true })?.data ?? null;
+}
+
+/**
+ * The freshest index this machine can have: the saved one while it is
+ * recent, otherwise the site's, otherwise the saved or shipped copy marked
+ * offline. Never rejects.
+ */
+export async function loadDocsFeed({ force = false }: { force?: boolean } = {}): Promise<DocsFeedResult> {
+  const shipped = await loadDocsSnapshot();
+  try {
+    const result = await feedCache.load(FEED_KEY, async () => {
+      const feed = parseDocsFeed(await fetchJson(DOCS_FEED_URL));
+      if (!feed) throw new Error("gloom.sh sent docs this version cannot read");
+      return feed;
+    }, { force });
+    return { feed: newer(result.data, shipped), offline: result.source === "stale-fallback" };
+  } catch {
+    return { feed: newer(savedDocsFeed(), shipped), offline: true };
+  }
+}
+
+/** A lesson, from the site or as last read. Rejects when it was never read and the site cannot be reached. */
+export async function loadDocsLesson(url: string, { force = false }: { force?: boolean } = {}): Promise<{ lesson: DocsLesson; offline: boolean }> {
+  const result = await lessonCache.load(url, async () => {
+    const lesson = parseDocsLesson(await fetchJson(docsLessonFeedUrl(url)));
+    if (!lesson) throw new Error("gloom.sh sent a lesson this version cannot read");
+    return lesson;
+  }, { force });
+  return { lesson: result.data, offline: result.source === "stale-fallback" };
+}
+
+/** A lesson already read, for a first frame that does not flash a loading state. */
+export function savedDocsLesson(url: string): DocsLesson | null {
+  return lessonCache.get(url, { allowExpired: true })?.data ?? null;
+}

package/src/docs/requests.ts

@@ -0,0 +1,39 @@
+/**
+ * The `?` on a pane, and the pane menu's Docs item, ask for that pane's docs
+ * here. The window's global shortcuts answer: the main window opens the
+ * pane's entry in DOCS; a popped-out window, which cannot open a pane, shows
+ * the pane's help card with its docs link.
+ */
+type PaneDocsHandler = (paneId: string) => void;
+
+const handlers = new Set<PaneDocsHandler>();
+
+/**
+ * One press reaches the terminal header twice, through its button and the
+ * shell's hit test, the same as the menu button; the second ask is dropped so
+ * one press never opens two readers.
+ */
+const REPEAT_MS = 300;
+let last: { paneId: string; at: number } | null = null;
+
+/**
+ * Asks this window for the pane's docs. Without an answer from the app (a
+ * shell mounted on its own) `fallback` opens them, through the plugin registry.
+ */
+export function requestPaneDocs(paneId: string, fallback?: PaneDocsHandler): void {
+  const now = Date.now();
+  if (last?.paneId === paneId && now - last.at < REPEAT_MS) return;
+  last = { paneId, at: now };
+  if (handlers.size === 0) {
+    fallback?.(paneId);
+    return;
+  }
+  for (const handler of handlers) handler(paneId);
+}
+
+export function registerPaneDocsHandler(handler: PaneDocsHandler): () => void {
+  handlers.add(handler);
+  return () => {
+    handlers.delete(handler);
+  };
+}

package/src/docs/snapshot.chunk.ts

@@ -0,0 +1,8 @@
+/**
+ * The docs index as gloom.sh served it when this version was built
+ * (`bun run docs:snapshot`). A lazy chunk: the web build fetches it only when
+ * the DOCS pane first opens.
+ */
+import snapshot from "./snapshot.json";
+
+export const DOCS_SNAPSHOT: unknown = snapshot;