gloomberb 0.11.2 → 0.12.0

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

@@ -1,31 +1,22 @@
-import type { PaneDef, PaneTemplateDef } from "../../types/plugin";
+import { CHART_RESOLUTIONS } from "../../time-series/range";
+import type {
+  HeadlessPaneArgumentDef,
+  HeadlessPaneDefinition,
+  HeadlessPaneOptionDef,
+  HeadlessPaneOptionType,
+  HeadlessPaneOptionValue,
+  PaneDef,
+  PaneTemplateDef,
+} from "../../types/plugin";
 
 export type PaneFunctionReadiness = "ready" | "partial" | "unsupported";
+export type PaneFunctionScreenshotReadiness = PaneFunctionReadiness | "live-dom";
 export type PaneFunctionTickerCardinality = "none" | "one" | "one-or-more" | "two-or-more" | "one-or-two";
-export type PaneFunctionOptionType = "enum" | "integer" | "string" | "boolean";
+export type PaneFunctionOptionType = HeadlessPaneOptionType;
+export type PaneFunctionOptionValue = HeadlessPaneOptionValue;
+export type PaneFunctionOptionDef = HeadlessPaneOptionDef;
 export type NormalizedPaneFunctionOptions = Record<string, string | number | boolean>;
 
-export interface PaneFunctionOptionValue {
-  value: string;
-  aliases?: string[];
-}
-
-export interface PaneFunctionOptionDef {
-  key: string;
-  description: string;
-  type: PaneFunctionOptionType;
-  aliases?: string[];
-  values?: PaneFunctionOptionValue[];
-  defaultValue?: string | number | boolean;
-  minimum?: number;
-  maximum?: number;
-  settingKey?: string;
-  pluginState?: {
-    pluginId: string;
-    key?: string;
-  };
-}
-
 export interface PaneFunctionCapability {
   id: string;
   botSafe: boolean;
@@ -34,7 +25,7 @@ export interface PaneFunctionCapability {
   intents: string[];
   outputKind: string;
   reportReadiness: PaneFunctionReadiness;
-  screenshotReadiness: PaneFunctionReadiness;
+  screenshotReadiness: PaneFunctionScreenshotReadiness;
   dataRequirements: string[];
   limitations: string[];
   options: PaneFunctionOptionDef[];
@@ -128,8 +119,7 @@ const CAPABILITIES: Record<string, PaneFunctionCapability> = {
         description: "Market-price sampling resolution.",
         type: "enum",
         aliases: ["resolution"],
-        values: ["auto", "1m", "5m", "15m", "30m", "45m", "1h", "1d", "1wk", "1mo"]
-          .map((value) => ({ value })),
+        values: CHART_RESOLUTIONS.map((value) => ({ value })),
       },
     ],
   },
@@ -251,7 +241,7 @@ const CAPABILITIES: Record<string, PaneFunctionCapability> = {
         description: "Price sampling resolution.",
         type: "enum",
         aliases: ["resolution"],
-        values: ["1m", "5m", "15m", "30m", "45m", "1h", "1d", "1wk", "1mo"].map((value) => ({ value })),
+        values: CHART_RESOLUTIONS.filter((value) => value !== "auto").map((value) => ({ value })),
         defaultValue: "1d",
       },
     ],
@@ -401,9 +391,11 @@ const UNSUPPORTED_CAPABILITY: PaneFunctionCapability = {
   intents: [],
   outputKind: "pane",
   reportReadiness: "unsupported",
-  screenshotReadiness: "unsupported",
+  screenshotReadiness: "live-dom",
   dataRequirements: [],
-  limitations: ["This UI pane has not been verified as a deterministic CLI or bot capability."],
+  limitations: [
+    "Reports are not verified for automation. Screenshots render live and derive evidence from visible DOM rows.",
+  ],
   options: [],
 };
 
@@ -411,11 +403,49 @@ function optionToken(value: string): string {
   return value.trim().toLowerCase().replace(/[\s_.-]+/g, "");
 }
 
+function headlessTickerCardinality(argument: HeadlessPaneArgumentDef): PaneFunctionTickerCardinality {
+  switch (argument.kind) {
+    case "ticker":
+      return "one";
+    case "tickers":
+    case "symbol-list":
+      return (argument.minimum ?? 1) >= 2 ? "two-or-more" : "one-or-more";
+    case "none":
+    case "free-text":
+      return "none";
+    default: {
+      const _exhaustive: never = argument.kind;
+      return _exhaustive;
+    }
+  }
+}
+
+export function getHeadlessPaneDefinition(
+  template: PaneTemplateDef | undefined,
+  pane: PaneDef,
+): HeadlessPaneDefinition | undefined {
+  return template?.headless ?? pane.headless;
+}
+
 export function getPaneFunctionCapability(
   template: PaneTemplateDef | undefined,
-  _pane: PaneDef,
+  pane: PaneDef,
 ): PaneFunctionCapability {
-  return template ? CAPABILITIES[template.id] ?? UNSUPPORTED_CAPABILITY : UNSUPPORTED_CAPABILITY;
+  const existing = template ? CAPABILITIES[template.id] ?? UNSUPPORTED_CAPABILITY : UNSUPPORTED_CAPABILITY;
+  const headless = getHeadlessPaneDefinition(template, pane);
+  if (!headless) return existing;
+
+  const hasExistingCapability = existing !== UNSUPPORTED_CAPABILITY;
+  return {
+    ...(hasExistingCapability ? existing : UNSUPPORTED_CAPABILITY),
+    id: hasExistingCapability ? existing.id : template?.id ?? pane.id,
+    botSafe: true,
+    tickerCardinality: headlessTickerCardinality(headless.argument),
+    outputKind: headless.shape,
+    reportReadiness: "ready",
+    options: [...headless.options],
+    ...(hasExistingCapability ? {} : { limitations: [] }),
+  };
 }
 
 function resolveOptionDef(

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

@@ -7,6 +7,7 @@ import {
 } from "./options";
 import {
   capabilityOptionSummary,
+  getHeadlessPaneDefinition,
   getPaneFunctionCapability,
   type PaneFunctionCapability,
 } from "./capabilities";
@@ -120,6 +121,7 @@ async function buildTemplateCatalogEntry(
     }
   }
 
+  const headless = getHeadlessPaneDefinition(template, pane);
   return {
     token: template.shortcut?.prefix ?? template.id,
     label: template.label,
@@ -128,8 +130,8 @@ async function buildTemplateCatalogEntry(
     paneName: pane.name,
     templateId: template.id,
     shortcut: template.shortcut?.prefix,
-    argKind: template.shortcut?.argKind,
-    argPlaceholder: template.shortcut?.argPlaceholder,
+    argKind: headless?.argument.kind ?? template.shortcut?.argKind,
+    argPlaceholder: headless?.argument.placeholder ?? template.shortcut?.argPlaceholder,
     keywords: template.keywords ?? [],
     defaultSettings,
     capability: getPaneFunctionCapability(template, pane),
@@ -158,6 +160,8 @@ export async function buildPaneCatalogEntries(
       description: `Open the ${pane.name} pane.`,
       paneId: pane.id,
       paneName: pane.name,
+      argKind: pane.headless?.argument.kind,
+      argPlaceholder: pane.headless?.argument.placeholder,
       keywords: [],
       defaultSettings: {},
       capability: getPaneFunctionCapability(undefined, pane),
@@ -251,7 +255,13 @@ export function renderPaneCatalogReport(entries: PaneCatalogEntry[], args: Parse
   }
 
   for (const entry of shown) {
-    const arg = entry.argPlaceholder ? `<${entry.argPlaceholder}>` : entry.argKind ? `<${entry.argKind}>` : "[argument]";
+    const arg = entry.argKind === "none"
+      ? ""
+      : entry.argPlaceholder
+        ? `<${entry.argPlaceholder}>`
+        : entry.argKind
+          ? `<${entry.argKind}>`
+          : "[argument]";
     lines.push(`${entry.token} | ${entry.label}`);
     lines.push(`  Description: ${entry.description}`);
     lines.push(`  Pane: ${entry.paneId} (${entry.paneName})`);
@@ -273,7 +283,9 @@ export function renderPaneCatalogReport(entries: PaneCatalogEntry[], args: Parse
       lines.push(`  Limitations: ${entry.capability.limitations.join(" ")}`);
     }
     lines.push(`  Defaults: ${formatCatalogSettings(entry.defaultSettings)}`);
-    lines.push(`  Examples: gloomberb fn ${entry.token} ${arg} | gloomberb shot ${entry.token} ${arg} --output /tmp/${entry.token.toLowerCase()}.png`);
+    const fnExample = `gloomberb fn ${entry.token}${arg ? ` ${arg}` : ""}`;
+    const shotExample = `gloomberb shot ${entry.token}${arg ? ` ${arg}` : ""} --output /tmp/${entry.token.toLowerCase()}.png`;
+    lines.push(`  Examples: ${fnExample} | ${shotExample}`);
     lines.push("");
   }
 

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

@@ -76,6 +76,7 @@ function buildDiscoveryContext({
     registerPane: (pane: PaneDef) => panes.set(pane.id, pane),
     registerPaneTemplate: (template: PaneTemplateDef) => paneTemplates.set(template.id, template),
     registerCommand: () => {},
+    registerCommandBarSearchProvider: () => () => {},
     registerColumn: () => {},
     registerBroker: () => {},
     registerCapability: () => {},

package/src/cli/pane-functions/headless.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_CLI_OPTIONS } from "../options";
+import { serializeCliResult } from "../result";
+import type {
+  HeadlessBundleResult,
+  HeadlessPaneDefinition,
+  HeadlessPaneLoadArgs,
+  HeadlessRowsResult,
+  HeadlessSeriesResult,
+  HeadlessSnapshotResult,
+  PaneDef,
+  PaneTemplateDef,
+} from "../../types/plugin";
+import { getPaneFunctionCapability, normalizeCapabilityOptions } from "./capabilities";
+import {
+  buildHeadlessPaneLoadArgs,
+  renderHeadlessPaneText,
+  serializeHeadlessPaneResult,
+} from "./headless";
+
+const args: HeadlessPaneLoadArgs = {
+  rawArgument: "",
+  argument: null,
+  symbols: [],
+  options: {},
+};
+
+function jsonData(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessRowsResult | HeadlessBundleResult | HeadlessSeriesResult | HeadlessSnapshotResult,
+): Record<string, unknown> {
+  const output = serializeCliResult(
+    { data: serializeHeadlessPaneResult(definition, result) },
+    { ...DEFAULT_CLI_OPTIONS, format: "json" },
+  );
+  return JSON.parse(output) as Record<string, unknown>;
+}
+
+describe("headless pane printer", () => {
+  test("renders rows as aligned text and preserves raw values in JSON", () => {
+    const definition: HeadlessPaneDefinition<"rows"> = {
+      shape: "rows",
+      argument: { kind: "none" },
+      options: [],
+      columns: [
+        { key: "name", header: "Name" },
+        {
+          key: "value",
+          header: "Value",
+          align: "right",
+          format: (value) => `${Number(value).toFixed(1)}%`,
+        },
+      ],
+      load: () => ({ rows: [] }),
+    };
+    const result: HeadlessRowsResult = { rows: [{ name: "CPI", value: 2.45 }] };
+
+    const text = renderHeadlessPaneText(definition, result, args, "Statistics");
+    expect(text).toContain("NAME");
+    expect(text).toContain("2.5%");
+    expect(jsonData(definition, result)).toMatchObject({
+      ok: true,
+      data: {
+        columns: [{ key: "name", header: "Name" }, { key: "value", header: "Value" }],
+        rows: [{ name: "CPI", value: 2.45 }],
+      },
+    });
+  });
+
+  test("renders bundle row and entry sections", () => {
+    const definition: HeadlessPaneDefinition<"bundle"> = {
+      shape: "bundle",
+      argument: { kind: "none" },
+      options: [],
+      load: () => ({ sections: [] }),
+    };
+    const result: HeadlessBundleResult = {
+      sections: [
+        {
+          title: "Inflation",
+          columns: [{ key: "name", header: "Indicator" }],
+          rows: [{ name: "CPI" }],
+        },
+        {
+          title: "CPI detail",
+          entries: [{ label: "Latest", value: 2.45, formatted: "2.5%" }],
+        },
+      ],
+    };
+
+    const text = renderHeadlessPaneText(definition, result, args, "Statistics");
+    expect(text).toContain("Inflation");
+    expect(text).toContain("CPI detail");
+    expect(text).toContain("2.5%");
+    expect(jsonData(definition, result)).toMatchObject({
+      ok: true,
+      data: {
+        sections: [
+          { title: "Inflation", rows: [{ name: "CPI" }] },
+          { title: "CPI detail", entries: [{ label: "Latest", value: 2.45 }] },
+        ],
+      },
+    });
+  });
+
+  test("renders series summaries and structured stats", () => {
+    const definition: HeadlessPaneDefinition<"series"> = {
+      shape: "series",
+      argument: { kind: "ticker" },
+      options: [],
+      load: () => ({ series: [] }),
+    };
+    const result: HeadlessSeriesResult = {
+      series: [{
+        id: "price",
+        label: "Price",
+        points: [
+          { date: "2026-09-01", value: 100 },
+          { date: "2026-09-02", value: 102 },
+        ],
+      }],
+      stats: { return: 0.02 },
+    };
+
+    const text = renderHeadlessPaneText(definition, result, args, "Price");
+    expect(text).toContain("2026-09-02");
+    expect(text).toContain("Statistics");
+    expect(jsonData(definition, result)).toMatchObject({
+      ok: true,
+      data: {
+        series: [{ id: "price", points: [{ value: 100 }, { value: 102 }] }],
+        stats: { return: 0.02 },
+      },
+    });
+  });
+
+  test("renders snapshot time and items", () => {
+    const definition: HeadlessPaneDefinition<"snapshot"> = {
+      shape: "snapshot",
+      argument: { kind: "none" },
+      options: [],
+      columns: [{ key: "headline", header: "Headline" }],
+      load: () => ({ asOf: "", items: [] }),
+    };
+    const result: HeadlessSnapshotResult = {
+      asOf: "2026-09-03T12:00:00Z",
+      items: [{ headline: "Markets open" }],
+    };
+
+    const text = renderHeadlessPaneText(definition, result, args, "News");
+    expect(text).toContain("As of: 2026-09-03T12:00:00Z");
+    expect(text).toContain("Markets open");
+    expect(jsonData(definition, result)).toMatchObject({
+      ok: true,
+      data: {
+        asOf: "2026-09-03T12:00:00Z",
+        items: [{ headline: "Markets open" }],
+      },
+    });
+  });
+});
+
+describe("headless pane arguments and options", () => {
+  test("normalizes symbol lists and enforces their declared minimum", () => {
+    const definition: HeadlessPaneDefinition<"rows"> = {
+      shape: "rows",
+      argument: { kind: "tickers", placeholder: "tickers", minimum: 2 },
+      options: [],
+      load: () => ({ rows: [] }),
+    };
+
+    expect(buildHeadlessPaneLoadArgs(definition, "CMP", "$aapl, msft, AAPL", {})).toMatchObject({
+      argument: ["AAPL", "MSFT"],
+      symbols: ["AAPL", "MSFT"],
+    });
+    expect(() => buildHeadlessPaneLoadArgs(definition, "CMP", "AAPL", {}))
+      .toThrow("CMP requires at least 2 symbols");
+  });
+
+  test("derives ready catalog capability and validates enum values", () => {
+    const definition: HeadlessPaneDefinition<"rows"> = {
+      shape: "rows",
+      argument: { kind: "none" },
+      options: [{
+        key: "mode",
+        description: "Display mode.",
+        type: "enum",
+        values: [{ value: "summary" }, { value: "detail" }],
+        defaultValue: "summary",
+      }],
+      load: () => ({ rows: [] }),
+    };
+    const pane: PaneDef = {
+      id: "example",
+      name: "Example",
+      component: () => null,
+      defaultPosition: "right",
+      headless: definition,
+    };
+    const capability = getPaneFunctionCapability(undefined, pane);
+
+    expect(capability).toMatchObject({
+      id: "example",
+      botSafe: true,
+      reportReadiness: "ready",
+      outputKind: "rows",
+    });
+    expect(normalizeCapabilityOptions(capability, {})).toEqual({ mode: "summary" });
+    expect(() => normalizeCapabilityOptions(capability, { mode: "wide" }))
+      .toThrow('Invalid --mode value "wide". Use one of: summary, detail.');
+  });
+
+  test("prefers a template model when one pane exposes multiple contracts", () => {
+    const paneModel: HeadlessPaneDefinition<"rows"> = {
+      shape: "rows",
+      argument: { kind: "none" },
+      options: [],
+      load: () => ({ rows: [] }),
+    };
+    const templateModel: HeadlessPaneDefinition<"series"> = {
+      shape: "series",
+      argument: { kind: "ticker" },
+      options: [],
+      load: () => ({ series: [] }),
+    };
+    const pane: PaneDef = {
+      id: "chart",
+      name: "Chart",
+      component: () => null,
+      defaultPosition: "right",
+      headless: paneModel,
+    };
+    const template: PaneTemplateDef = {
+      id: "price-chart",
+      paneId: pane.id,
+      label: "Price",
+      description: "Price chart.",
+      headless: templateModel,
+    };
+
+    expect(getPaneFunctionCapability(template, pane)).toMatchObject({
+      outputKind: "series",
+      tickerCardinality: "one",
+      reportReadiness: "ready",
+    });
+  });
+});