gloomberb 0.16.2 → 0.16.4

package/src/brokers/signed-in/sign-in-dialog.tsx

@@ -21,6 +21,7 @@ import type { SignedInBroker } from "./client";
 import {
   BrokerSignInController,
   runBrokerSignIn,
+  type BrokerSignInOptions,
   type BrokerSignInOutcome,
   type BrokerSignInSnapshot,
 } from "./sign-in";
@@ -59,9 +60,10 @@ export function useBrokerSignInAttempt(
   broker: SignedInBroker,
   write: boolean,
   onOutcome: (outcome: "connected" | "signed-out") => void,
+  options: BrokerSignInOptions = {},
 ): { snapshot: BrokerSignInSnapshot; restart(): void; finish(): void } {
   const controllerRef = useRef<BrokerSignInController | null>(null);
-  if (!controllerRef.current) controllerRef.current = new BrokerSignInController(broker, write);
+  if (!controllerRef.current) controllerRef.current = new BrokerSignInController(broker, write, {}, options);
   const controller = controllerRef.current;
   const [snapshot, setSnapshot] = useState(controller.getSnapshot());
   const onOutcomeRef = useRef(onOutcome);
@@ -110,12 +112,13 @@ function BrokerSignInDialog({
   dismiss,
   broker,
   write,
-}: PromptContext<BrokerSignInOutcome> & { broker: SignedInBroker; write: boolean }) {
+  renew,
+}: PromptContext<BrokerSignInOutcome> & { broker: SignedInBroker; write: boolean; renew: boolean }) {
   useAppLanguage();
   const { height: termHeight } = useViewport();
   // Close after a beat so "Connected" is visible; enter skips the wait. Signed
   // out closes at once, for the host to sign in to Gloom.
-  const { snapshot, restart, finish } = useBrokerSignInAttempt(broker, write, resolve);
+  const { snapshot, restart, finish } = useBrokerSignInAttempt(broker, write, resolve, { renew });
 
   useDialogKeyboard((event) => {
     event.stopPropagation();
@@ -170,6 +173,8 @@ export interface BrokerSignInRequest {
   broker: SignedInBroker;
   /** Ask for trading as well as reading. Defaults to whether the broker takes orders. */
   write?: boolean;
+  /** Sign in again although the broker is connected. */
+  renew?: boolean;
   resolve: (connected: boolean) => void;
 }
 
@@ -178,13 +183,17 @@ const requestListeners = new Set<(request: BrokerSignInRequest) => void>();
 /**
  * Connects a signed-in broker, signing in to Gloom first when needed.
  * Resolves true once the broker is connected, false when the user cancels or
- * no dialog host is mounted.
+ * no dialog host is mounted. A broker that is already connected is done at
+ * once unless `renew` asks for a new sign-in.
  */
-export function requestBrokerSignIn(broker: SignedInBroker, options: { write?: boolean } = {}): Promise<boolean> {
+export function requestBrokerSignIn(
+  broker: SignedInBroker,
+  options: { write?: boolean; renew?: boolean } = {},
+): Promise<boolean> {
   if (requestListeners.size === 0) return Promise.resolve(false);
   return new Promise((resolve) => {
     const write = options.write ?? Boolean(broker.capabilities.orders);
-    for (const listener of requestListeners) listener({ broker, write, resolve });
+    for (const listener of requestListeners) listener({ broker, write, renew: options.renew, resolve });
   });
 }
 
@@ -203,13 +212,18 @@ export function BrokerSignInDialogHost() {
       void runBrokerSignIn(request.broker, request.write, {
         isSignedIn: () => apiClient.isSignedIn(),
         signInToGloom: () => promptGloomSignIn(dialog),
-        connectBroker: async (broker, write) => await dialog.prompt<BrokerSignInOutcome>({
+        connectBroker: async (broker, write, renew) => await dialog.prompt<BrokerSignInOutcome>({
           size: "full",
           content: (context: unknown) => (
-            <BrokerSignInDialog {...(context as PromptContext<BrokerSignInOutcome>)} broker={broker} write={write} />
+            <BrokerSignInDialog
+              {...(context as PromptContext<BrokerSignInOutcome>)}
+              broker={broker}
+              write={write}
+              renew={renew}
+            />
           ),
         }) ?? "cancelled",
-      })
+      }, { renew: request.renew })
         .then(request.resolve, () => request.resolve(false))
         .finally(() => {
           openRef.current = false;

package/src/brokers/signed-in/sign-in.ts

@@ -24,9 +24,21 @@ export interface BrokerSignInSnapshot {
   error: string | null;
 }
 
+/** What a read of the account's connection tells the flow. */
+export type BrokerConnectionRead = Pick<SignedInBrokerConnection, "status"> & { connectedAt?: string | null };
+
+export interface BrokerSignInOptions {
+  /**
+   * Sign in again although the broker is connected, to start a new sign-in
+   * before the broker ends the old one. Without it a connected broker is done
+   * at once, as when a device adds a connection the account already holds.
+   */
+  renew?: boolean;
+}
+
 export interface BrokerSignInIo {
   start(brokerId: string, write: boolean): Promise<{ connectUrl: string; code: string; expiresAt: string }>;
-  fetchConnection(brokerId: string): Promise<Pick<SignedInBrokerConnection, "status">>;
+  fetchConnection(brokerId: string): Promise<BrokerConnectionRead>;
   now(): number;
   delay(ms: number): Promise<void>;
 }
@@ -58,10 +70,37 @@ function codeDeadline(expiresAt: string, now: number): number {
   return Number.isFinite(parsed) && parsed > now ? parsed : now + DEFAULT_CODE_TTL_MS;
 }
 
+function stamp(value: string | null | undefined): number | null {
+  const parsed = value ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * Whether `now` shows a sign-in made after `before` was read. Renewing a
+ * connection takes more than connected: a broker that was connected when the
+ * flow began stays connected while the user signs in again, until Gloom stamps
+ * the new sign-in. Both reads are Gloom's, so a device clock that runs fast or
+ * slow cannot matter.
+ */
+function signedInSince(before: BrokerConnectionRead, now: BrokerConnectionRead): boolean {
+  if (now.status !== "connected") return false;
+  if (before.status !== "connected") return true;
+  const at = stamp(now.connectedAt);
+  const was = stamp(before.connectedAt);
+  return at !== null && (was === null || at > was);
+}
+
 export class BrokerSignInController {
   private readonly io: BrokerSignInIo;
   private readonly listeners = new Set<(snapshot: BrokerSignInSnapshot) => void>();
   private generation = 0;
+  /**
+   * Renewing only: the account's connection as first seen. It outlives a
+   * restarted code, so a sign-in finished while "r" asked for a new one still
+   * counts.
+   */
+  private before: BrokerConnectionRead | null = null;
+  private readonly renew: boolean;
   private snapshot: BrokerSignInSnapshot = { phase: "starting", connectUrl: null, code: null, error: null };
 
   constructor(
@@ -69,8 +108,10 @@ export class BrokerSignInController {
     /** Ask for trading as well as reading when the broker offers it. */
     private readonly write: boolean,
     io: Partial<BrokerSignInIo> = {},
+    options: BrokerSignInOptions = {},
   ) {
     this.io = { ...defaultIo, ...io };
+    this.renew = options.renew === true;
   }
 
   getSnapshot(): BrokerSignInSnapshot {
@@ -102,6 +143,14 @@ export class BrokerSignInController {
   private async run(generation: number): Promise<void> {
     const stale = () => this.generation !== generation;
     let retryMs = POLL_INTERVAL_MS;
+    // Renewing: read before a code exists, so nothing the user does can come
+    // first. A failed read leaves the first poll to stand in for it: no
+    // sign-in finishes within a poll interval.
+    if (this.renew && !this.before) {
+      const read = await this.io.fetchConnection(this.broker.id).catch(() => null);
+      if (stale()) return;
+      this.before ??= read;
+    }
     // Each iteration is one code: start, poll until connected, and loop again
     // when the code expired so the link refreshes instead of dead-ending.
     while (!stale()) {
@@ -132,8 +181,14 @@ export class BrokerSignInController {
         await this.io.delay(POLL_INTERVAL_MS);
         if (stale()) return;
         try {
+          const connection = await this.io.fetchConnection(this.broker.id);
           // Connected is enough: a user who declined trading still gets a read-only connection.
-          if ((await this.io.fetchConnection(this.broker.id)).status === "connected") {
+          let done = connection.status === "connected";
+          if (this.renew) {
+            this.before ??= connection;
+            done = signedInSince(this.before, connection);
+          }
+          if (done) {
             if (!stale()) this.update({ phase: "connected", error: null });
             this.generation += 1;
             return;
@@ -154,7 +209,7 @@ export interface BrokerSignInSteps {
   isSignedIn(): boolean;
   /** The Gloom device sign-in; true once signed in. */
   signInToGloom(): Promise<boolean>;
-  connectBroker(broker: SignedInBroker, write: boolean): Promise<BrokerSignInOutcome>;
+  connectBroker(broker: SignedInBroker, write: boolean, renew: boolean): Promise<BrokerSignInOutcome>;
 }
 
 /**
@@ -166,13 +221,15 @@ export async function runBrokerSignIn(
   broker: SignedInBroker,
   write: boolean | undefined,
   steps: BrokerSignInSteps,
+  options: BrokerSignInOptions = {},
 ): Promise<boolean> {
   if (!steps.isSignedIn() && !await steps.signInToGloom()) return false;
   // Trading is asked for only where the broker takes orders from Gloom.
   const scope = write ?? Boolean(broker.capabilities.orders);
-  let outcome = await steps.connectBroker(broker, scope);
+  const renew = options.renew === true;
+  let outcome = await steps.connectBroker(broker, scope, renew);
   if (outcome === "signed-out" && await steps.signInToGloom()) {
-    outcome = await steps.connectBroker(broker, scope);
+    outcome = await steps.connectBroker(broker, scope, renew);
   }
   return outcome === "connected";
 }

package/src/capabilities/registry.ts

@@ -159,7 +159,14 @@ export class CapabilityRegistry {
 
   private resolveOperation(capabilityId: string, operationId: string, options: { renderer?: boolean }) {
     const entry = this.capabilities.get(capabilityId);
-    if (!entry || !this.isEnabled(entry)) throw new Error(`Capability "${capabilityId}" is not available.`);
+    if (!entry || !this.isEnabled(entry)) {
+      const pluginName = entry && this.options.isPluginEnabled?.(entry.pluginId) === false
+        ? this.options.pluginName?.(entry.pluginId)
+        : undefined;
+      throw new Error(pluginName
+        ? `Turn on ${pluginName} to use ${entry!.capability.name}.`
+        : `Capability "${capabilityId}" is not available.`);
+    }
     const operation = entry.capability.operations[operationId];
     if (!operation) throw new Error(`Capability operation "${capabilityId}.${operationId}" is not available.`);
     if (options.renderer && operation.rendererSafe !== true) {

package/src/capabilities/types.ts

@@ -132,6 +132,8 @@ export interface CapabilityManifest {
 
 export interface CapabilityRegistryOptions {
   isPluginEnabled?(pluginId: string): boolean;
+  /** Names the plugin a switched-off capability belongs to, so the error can say what to turn on. */
+  pluginName?(pluginId: string): string | undefined;
   isCapabilityEnabled?(capability: PluginCapability, pluginId: string): boolean;
   connectionHealth?: ConnectionHealthRegistry;
 }

package/src/cli/command-options.ts

@@ -0,0 +1,74 @@
+import type { CliCommandDef } from "../types/plugin";
+import { fail } from "./errors";
+import { suggestCliOption } from "./help";
+
+/** A built-in command, which may say more about an option it does not take than the list of those it does. */
+export interface BuiltinCliCommandDef extends CliCommandDef {
+  /** A sentence for an unknown option people reach for, such as `--from` on `history`; null for the rest. */
+  unknownOptionHint?(flag: string): string | null;
+}
+
+interface DeclaredOption {
+  flag: string;
+  takesValue: boolean;
+}
+
+/** `--range`, `--range=5Y`: an option. `-5`, `---`, `--` and plain words are not. */
+const OPTION_TOKEN = /^--[a-z]/i;
+
+/**
+ * The options a command's help declares, from each spelling such as
+ * `--range <range>` (takes a value) or `--all` (a switch). Null when it takes
+ * any option: `--<option> <value>` on `fn` and `shot`.
+ */
+function declaredOptions(command: CliCommandDef): Map<string, DeclaredOption> | null {
+  const declared = new Map<string, DeclaredOption>();
+  for (const option of command.help?.options ?? []) {
+    for (const spelling of option.flags.split(",")) {
+      const trimmed = spelling.trim();
+      if (trimmed.startsWith("--<")) return null;
+      const match = /^(--?[a-z][\w-]*)(?:[ =](.+))?$/i.exec(trimmed);
+      if (match) declared.set(match[1]!, { flag: match[1]!, takesValue: match[2] != null });
+    }
+  }
+  return declared;
+}
+
+function failUnknownOption(command: BuiltinCliCommandDef, flag: string, declared: Map<string, DeclaredOption>): never {
+  const flags = [...declared.keys()];
+  const suggestion = suggestCliOption(flag, flags);
+  const help = `See gloomberb help ${command.name}.`;
+  fail(`Unknown option ${flag} for ${command.name}.`, [
+    command.unknownOptionHint?.(flag) ?? "",
+    suggestion ? `Did you mean ${suggestion}?` : "",
+    flags.length > 0 ? `Options: ${flags.join(", ")}. ${help}` : `${command.name} takes no options. ${help}`,
+  ].filter(Boolean).join("\n"));
+}
+
+/**
+ * Fails on the first `--option` a built-in command does not declare, which it
+ * would otherwise ignore and answer as if it had not been given: `history
+ * --from 1995-01-01` printing the default year. Global flags are already out
+ * of `args`; a declared option's value is skipped whatever it looks like, and
+ * nothing from `literalStart` on (after a bare `--`) is read as an option.
+ */
+export function checkCliCommandOptions(
+  command: BuiltinCliCommandDef,
+  args: readonly string[],
+  literalStart = args.length,
+): void {
+  const declared = declaredOptions(command);
+  if (!declared) return;
+  for (let index = 0; index < Math.min(literalStart, args.length); index += 1) {
+    const arg = args[index]!;
+    if (!OPTION_TOKEN.test(arg)) continue;
+    const equals = arg.indexOf("=");
+    const flag = equals >= 0 ? arg.slice(0, equals) : arg;
+    const option = declared.get(flag);
+    if (!option) failUnknownOption(command, flag, declared);
+    if (!option.takesValue && equals >= 0) {
+      fail(`${flag} takes no value.`, `Write it alone, as ${flag}. See gloomberb help ${command.name}.`);
+    }
+    if (option.takesValue && equals < 0) index += 1;
+  }
+}

package/src/cli/commands/command-utils.ts

@@ -46,6 +46,35 @@ export function requireArg(value: string | undefined, usage: string, ctx: CliCom
   return value;
 }
 
+/**
+ * Fails on arguments past the `max` a command takes rather than dropping them:
+ * `fx NGN ZAR` printing NGN alone reads as an answer for both. `usage` is the
+ * command's usage line without `gloomberb`, `takes` what it takes ("one
+ * currency", "no arguments").
+ */
+export function rejectExtraArgs(
+  args: readonly string[],
+  max: number,
+  { usage, takes, advice }: { usage: string; takes: string; advice?: string },
+  ctx: Pick<CliCommandContext, "fail">,
+): void {
+  if (args.length <= max) return;
+  const command = usage.split(" ")[0];
+  ctx.fail(`${command} takes ${takes}; got ${args.join(" ")}.`, [advice, `Usage: gloomberb ${usage}`].filter(Boolean).join("\n"));
+}
+
+/** The one argument a command takes, such as a symbol: missing fails with the usage line, extras are not dropped. */
+export function requireOneArg(
+  args: readonly string[],
+  usage: string,
+  noun: string,
+  ctx: CliCommandContext,
+): string {
+  const value = requireArg(args[0], `Usage: gloomberb ${usage}`, ctx);
+  rejectExtraArgs(args, 1, { usage, takes: `one ${noun}`, advice: `Run it once per ${noun}.` }, ctx);
+  return value;
+}
+
 export function isoDate(value: unknown): string {
   if (value instanceof Date) return value.toISOString();
   if (typeof value === "number") return new Date(value).toISOString();

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

@@ -1,6 +1,7 @@
 import { isCryptoInstrumentType } from "../../tickers/search/ranking";
 import type { Quote } from "../../types/financials";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
+import { isNotATickerMessage } from "../not-a-ticker";
 
 /** Where a crypto pair that will not load can still be read. `fn CRYP` takes no argument. */
 export const CRYPTO_BOARD_HINT = "Crypto prices may be briefly unavailable; the CRYP function (gloomberb fn CRYP) shows the crypto board.";
@@ -42,11 +43,15 @@ interface QuoteNoteResult {
   error: string | null;
 }
 
-/** The router words a failure as "<reason> for <symbol>"; drop the symbol so equal reasons group. */
+/**
+ * The router words a failure as "<reason> for <symbol>"; drop the symbol so equal reasons group.
+ * Any other line, such as a sentence the data service wrote, is kept as it reads.
+ */
 function failureReason(message: string, symbol: string): string {
-  const line = (message.split("\n")[0] ?? "").trim().replace(/\.+$/, "");
+  const line = (message.split("\n")[0] ?? "").trim();
+  const bare = line.replace(/\.+$/, "");
   const suffix = ` for ${symbol}`;
-  return line.toLowerCase().endsWith(suffix.toLowerCase()) ? line.slice(0, -suffix.length) : line;
+  return bare.toLowerCase().endsWith(suffix.toLowerCase()) ? bare.slice(0, -suffix.length) : line;
 }
 
 /**
@@ -63,7 +68,10 @@ export function quoteNotes(results: QuoteNoteResult[], options: { exchange?: str
     if (!symbols.includes(result.target.symbol)) failures.set(reason, [...symbols, result.target.symbol]);
   }
   const notes = [...failures].map(([reason, symbols]) => (
-    `${symbols.join(", ")}: ${reason}${symbols.some(isCryptoPairSymbol) ? `. ${CRYPTO_BOARD_HINT}` : ""}`
+    // "Not a ticker: APPLE." already names its symbol.
+    isNotATickerMessage(reason)
+      ? reason
+      : `${symbols.join(", ")}: ${reason}${symbols.some(isCryptoPairSymbol) ? `${/[.!?]$/.test(reason) ? "" : "."} ${CRYPTO_BOARD_HINT}` : ""}`
   ));
   if (!options.exchange) {
     for (const result of results) {