gloomberb 0.14.0 → 0.14.1

package/src/app/keybindings/react.tsx

@@ -0,0 +1,32 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { KeybindingsConfig } from "../../types/config";
+import { resolveKeybindings, type ResolvedKeybindings } from "./resolve";
+
+const KeybindingsContext = createContext<ResolvedKeybindings | null>(null);
+
+let defaultKeybindings: ResolvedKeybindings | null = null;
+
+/** The shipped table, for surfaces rendered outside the app tree such as tests. */
+export function getDefaultKeybindings(): ResolvedKeybindings {
+  if (!defaultKeybindings) defaultKeybindings = resolveKeybindings(undefined);
+  return defaultKeybindings;
+}
+
+/** Resolves the config once per change; the app passes the result down and into its own hooks. */
+export function useResolvedKeybindings(config: KeybindingsConfig | undefined): ResolvedKeybindings {
+  return useMemo(() => resolveKeybindings(config), [config]);
+}
+
+export function KeybindingsProvider({
+  value,
+  children,
+}: {
+  value: ResolvedKeybindings;
+  children: ReactNode;
+}) {
+  return <KeybindingsContext value={value}>{children}</KeybindingsContext>;
+}
+
+export function useKeybindings(): ResolvedKeybindings {
+  return useContext(KeybindingsContext) ?? getDefaultKeybindings();
+}

package/src/app/keybindings/resolve.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { applyActionBinding, removeCommandBinding, setCommandBinding, updateKeybindingsConfig } from "./config";
+import { parseKeyChord, serializeKeyChord } from "./chord";
+import { matchKeybinding, resolveKeybindings, resolvePluginShortcutChords } from "./resolve";
+import { createDefaultConfig } from "../../types/config";
+
+const base = { ctrl: false, shift: false, alt: false, meta: false, super: false };
+
+describe("resolveKeybindings", () => {
+  test("ships every default and reports nothing", () => {
+    const resolved = resolveKeybindings(undefined);
+    expect(resolved.issues).toEqual([]);
+    expect(resolved.actionsById.get("ticker-search")?.chords.map(serializeKeyChord)).toEqual(["`"]);
+    expect(matchKeybinding(resolved, { ...base, name: "`" })).toMatchObject({ kind: "action", id: "ticker-search" });
+    expect(matchKeybinding(resolved, { ...base, name: "t", ctrl: true })).toBeNull();
+    expect(matchKeybinding(resolved, { ...base, name: "2", super: true })).toMatchObject({ kind: "action", id: "switch-layout", digit: 2 });
+    expect(matchKeybinding(resolved, { ...base, name: "w", ctrl: true, alt: true })).toMatchObject({ id: "close-floating-panes" });
+    expect(matchKeybinding(resolved, { ...base, name: "w", ctrl: true })).toMatchObject({ id: "pane-close" });
+    expect(matchKeybinding(resolved, { ...base, name: "x" })).toBeNull();
+  });
+
+  test("overrides replace defaults, null unbinds, and the rest stay put", () => {
+    const resolved = resolveKeybindings({
+      actions: { "ticker-search": "Ctrl+T", "command-bar": "Ctrl+Shift+P", help: null },
+    });
+    expect(resolved.issues).toEqual([]);
+    expect(matchKeybinding(resolved, { ...base, name: "`" })).toBeNull();
+    expect(matchKeybinding(resolved, { ...base, name: "t", ctrl: true })).toMatchObject({ id: "ticker-search" });
+    expect(matchKeybinding(resolved, { ...base, name: "k", ctrl: true })).toBeNull();
+    expect(matchKeybinding(resolved, { ...base, name: "p", ctrl: true, shift: true })).toMatchObject({ id: "command-bar" });
+    expect(matchKeybinding(resolved, { ...base, name: "?", shift: true })).toBeNull();
+    expect(resolved.actionsById.get("help")).toMatchObject({ custom: true, chords: [] });
+    expect(resolved.actionsById.get("quit")).toMatchObject({ custom: false });
+  });
+
+  test("commands run after actions and need a modifier or function key", () => {
+    const resolved = resolveKeybindings({
+      commands: { "Alt+1": "DES AAPL", F5: " NEWS ", "CmdOrCtrl+W": "HN", a: "HN", "": "HN", "Alt+2": "" },
+    });
+    expect(matchKeybinding(resolved, { ...base, name: "1", alt: true })).toMatchObject({ kind: "command", command: { query: "DES AAPL" } });
+    expect(matchKeybinding(resolved, { ...base, name: "f5" })).toMatchObject({ kind: "command", command: { query: "NEWS" } });
+    expect(matchKeybinding(resolved, { ...base, name: "w", ctrl: true })).toMatchObject({ kind: "action", id: "pane-close" });
+    expect(resolved.commands.map((command) => command.text)).toEqual(["Alt+1", "F5", "CmdOrCtrl+W"]);
+    expect(resolved.issues).toEqual([
+      { kind: "typing-chord", target: "commands", text: "a" },
+      { kind: "invalid-chord", target: "commands", text: "" },
+      { kind: "conflict", chord: parseKeyChord("CmdOrCtrl+W"), targets: ["pane-close", "command:CmdOrCtrl+W"] },
+    ]);
+  });
+
+  test("reports unparseable overrides, unknown actions and overlapping chords", () => {
+    const resolved = resolveKeybindings({
+      actions: { "ticker-search": ["Ctrl+K", "Bogus+Q"], "not-a-thing": "F1" },
+    });
+    expect(resolved.issues).toEqual([
+      { kind: "invalid-chord", target: "ticker-search", text: "Bogus+Q" },
+      { kind: "unknown-action", actionId: "not-a-thing" },
+      { kind: "conflict", chord: parseKeyChord("CmdOrCtrl+K"), targets: ["command-bar", "ticker-search"] },
+    ]);
+    // Table order decides, so the earlier action keeps the chord.
+    expect(matchKeybinding(resolved, { ...base, name: "k", ctrl: true })).toMatchObject({ id: "command-bar" });
+  });
+
+  test("folds plugin shortcuts in under their own namespace", () => {
+    const shortcut = { id: "hn-refresh", key: "x", ctrl: true, description: "Refresh", execute: () => {} };
+    const plain = resolveKeybindings(undefined, { pluginShortcuts: [shortcut] });
+    expect(matchKeybinding(plain, { ...base, name: "x", ctrl: true })).toMatchObject({ id: "plugin:hn-refresh" });
+    expect(resolvePluginShortcutChords(undefined, shortcut).map(serializeKeyChord)).toEqual(["Ctrl+X"]);
+
+    const config = { actions: { "plugin:hn-refresh": "Alt+X" } };
+    const custom = resolveKeybindings(config, { pluginShortcuts: [shortcut] });
+    expect(custom.issues).toEqual([]);
+    expect(matchKeybinding(custom, { ...base, name: "x", ctrl: true })).toBeNull();
+    expect(matchKeybinding(custom, { ...base, name: "x", alt: true })).toMatchObject({ id: "plugin:hn-refresh", action: { custom: true } });
+    expect(resolvePluginShortcutChords(config, shortcut).map(serializeKeyChord)).toEqual(["Alt+X"]);
+  });
+});
+
+describe("keybinding config edits", () => {
+  test("applyActionBinding records overrides and drops ones equal to the default", () => {
+    const bound = applyActionBinding(undefined, "ticker-search", [parseKeyChord("Ctrl+T")!]);
+    expect(bound).toEqual({ actions: { "ticker-search": "Ctrl+T" } });
+    const unbound = applyActionBinding(bound, "help", []);
+    expect(unbound).toEqual({ actions: { "ticker-search": "Ctrl+T", help: null } });
+    const restored = applyActionBinding(unbound, "ticker-search", [parseKeyChord("`")!]);
+    expect(restored).toEqual({ actions: { help: null } });
+    expect(applyActionBinding(restored, "help", [parseKeyChord("?")!])).toBeUndefined();
+  });
+
+  test("setCommandBinding replaces a command already on the chord, and removal clears the key", () => {
+    const first = setCommandBinding(undefined, parseKeyChord("Alt+1")!, "DES AAPL");
+    const second = setCommandBinding(first, parseKeyChord("alt+1")!, "HN");
+    expect(second).toEqual({ commands: { "Alt+1": "HN" } });
+    expect(removeCommandBinding(second, "Alt+1")).toBeUndefined();
+  });
+
+  test("updateKeybindingsConfig drops the key once nothing is customised", () => {
+    const config = { ...createDefaultConfig("/tmp/keybindings"), keybindings: { actions: { help: null } } };
+    expect(updateKeybindingsConfig(config, undefined).keybindings).toBeUndefined();
+    expect("keybindings" in updateKeybindingsConfig(config, { actions: {} })).toBe(false);
+    expect(updateKeybindingsConfig(config, { commands: { F5: "NEWS" } }).keybindings).toEqual({ commands: { F5: "NEWS" } });
+  });
+});

package/src/app/keybindings/resolve.ts

@@ -0,0 +1,280 @@
+import type { KeybindingsConfig } from "../../types/config";
+import type { KeyboardShortcut } from "../../types/plugin";
+import {
+  getKeybindingAction,
+  isCoreKeybindingActionId,
+  KEYBINDING_ACTIONS,
+  PANE_ACTION_IDS,
+  PLUGIN_ACTION_PREFIX,
+  pluginShortcutActionId,
+  type KeybindingActionDef,
+} from "./actions";
+import {
+  isTypingChord,
+  keyChordDigit,
+  matchesKeyChord,
+  parseKeyChord,
+  serializeKeyChord,
+  type KeyChord,
+  type KeyChordEventLike,
+} from "./chord";
+
+export interface ResolvedKeybindingAction {
+  id: string;
+  /** Set for built-in actions. */
+  def?: KeybindingActionDef;
+  /** Set for actions a plugin registered. */
+  pluginShortcut?: KeyboardShortcut;
+  chords: KeyChord[];
+  defaults: KeyChord[];
+  /** The user replaced or removed the default chords. */
+  custom: boolean;
+}
+
+export interface KeybindingCommand {
+  chord: KeyChord;
+  /** The chord text as written in the config, which is the map key. */
+  text: string;
+  /** Command bar text submitted when the chord is pressed. */
+  query: string;
+}
+
+export type KeybindingIssue =
+  | { kind: "invalid-chord"; target: string; text: string }
+  | { kind: "unknown-action"; actionId: string }
+  | { kind: "typing-chord"; target: string; text: string }
+  | { kind: "conflict"; chord: KeyChord; targets: string[] };
+
+export interface ResolvedKeybindings {
+  actions: ResolvedKeybindingAction[];
+  actionsById: Map<string, ResolvedKeybindingAction>;
+  commands: KeybindingCommand[];
+  issues: KeybindingIssue[];
+}
+
+export type KeybindingMatch =
+  | { kind: "action"; id: string; action: ResolvedKeybindingAction; digit: number | null }
+  | { kind: "command"; command: KeybindingCommand };
+
+export interface ResolveKeybindingsOptions {
+  /** Plugin shortcuts to fold into the table, for listing and conflict checks. */
+  pluginShortcuts?: Iterable<KeyboardShortcut>;
+}
+
+export function pluginShortcutDefaultChord(shortcut: KeyboardShortcut): KeyChord {
+  return {
+    key: shortcut.key.toLowerCase(),
+    ctrl: shortcut.ctrl === true,
+    cmd: false,
+    primary: false,
+    alt: false,
+    shift: shortcut.shift === true || (shortcut.key.length === 1 && shortcut.key !== shortcut.key.toLowerCase()),
+  };
+}
+
+/**
+ * An override's chords. `null` in the config is a deliberate unbind and gives
+ * an empty list; text that does not parse is reported and dropped, and when
+ * nothing parses the override is ignored so a typo never silently unbinds.
+ */
+function parseChordList(
+  value: string | string[] | null | undefined,
+  target: string,
+  issues: KeybindingIssue[],
+): KeyChord[] | null {
+  if (value === undefined) return null;
+  if (value === null) return [];
+  const texts = Array.isArray(value) ? value : [value];
+  const chords: KeyChord[] = [];
+  let invalid = false;
+  for (const text of texts) {
+    if (typeof text !== "string") continue;
+    const chord = parseKeyChord(text);
+    if (!chord) {
+      issues.push({ kind: "invalid-chord", target, text });
+      invalid = true;
+      continue;
+    }
+    chords.push(chord);
+  }
+  return chords.length === 0 && invalid ? null : chords;
+}
+
+function parseDefaults(texts: readonly string[]): KeyChord[] {
+  return texts.map((text) => {
+    const chord = parseKeyChord(text);
+    if (!chord) throw new Error(`Default keybinding "${text}" does not parse.`);
+    return chord;
+  });
+}
+
+const DEFAULT_CHORDS = new Map(KEYBINDING_ACTIONS.map((action) => [action.id, parseDefaults(action.defaults)]));
+
+/**
+ * Two chords fire on the same keypress somewhere: identical, or one says
+ * `CmdOrCtrl` where the other names Control or Command explicitly.
+ */
+export function keyChordsOverlap(left: KeyChord, right: KeyChord): boolean {
+  if (left.key !== right.key || left.alt !== right.alt || left.shift !== right.shift) return false;
+  if (left.primary && right.primary) return true;
+  if (left.primary) return (right.ctrl || right.cmd) && !(right.ctrl && right.cmd);
+  if (right.primary) return (left.ctrl || left.cmd) && !(left.ctrl && left.cmd);
+  return left.ctrl === right.ctrl && left.cmd === right.cmd;
+}
+
+function resolveAction(
+  def: KeybindingActionDef | undefined,
+  pluginShortcut: KeyboardShortcut | undefined,
+  id: string,
+  defaults: KeyChord[],
+  overrides: NonNullable<KeybindingsConfig["actions"]>,
+  issues: KeybindingIssue[],
+): ResolvedKeybindingAction {
+  const override = parseChordList(overrides[id], id, issues);
+  return {
+    id,
+    def,
+    pluginShortcut,
+    defaults,
+    chords: override ?? defaults,
+    custom: override !== null,
+  };
+}
+
+function collectConflicts(actions: ResolvedKeybindingAction[], commands: KeybindingCommand[]): KeybindingIssue[] {
+  const entries: Array<{ target: string; chord: KeyChord }> = [
+    ...actions.flatMap((action) => action.chords.map((chord) => ({ target: action.id, chord }))),
+    ...commands.map((command) => ({ target: `command:${command.text}`, chord: command.chord })),
+  ];
+  const reported = new Set<string>();
+  const issues: KeybindingIssue[] = [];
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index]!;
+    const targets = [entry.target];
+    for (let other = index + 1; other < entries.length; other += 1) {
+      const candidate = entries[other]!;
+      if (candidate.target !== entry.target && keyChordsOverlap(entry.chord, candidate.chord)) {
+        targets.push(candidate.target);
+      }
+    }
+    if (targets.length < 2) continue;
+    const key = `${serializeKeyChord(entry.chord)}|${[...new Set(targets)].sort().join(",")}`;
+    if (reported.has(key)) continue;
+    reported.add(key);
+    issues.push({ kind: "conflict", chord: entry.chord, targets: [...new Set(targets)] });
+  }
+  return issues;
+}
+
+export function resolveKeybindings(
+  config: KeybindingsConfig | undefined,
+  options: ResolveKeybindingsOptions = {},
+): ResolvedKeybindings {
+  const issues: KeybindingIssue[] = [];
+  const overrides = config?.actions ?? {};
+  const actions: ResolvedKeybindingAction[] = KEYBINDING_ACTIONS.map((def) => resolveAction(
+    def,
+    undefined,
+    def.id,
+    DEFAULT_CHORDS.get(def.id)!,
+    overrides,
+    issues,
+  ));
+  for (const shortcut of options.pluginShortcuts ?? []) {
+    actions.push(resolveAction(
+      undefined,
+      shortcut,
+      pluginShortcutActionId(shortcut.id),
+      [pluginShortcutDefaultChord(shortcut)],
+      overrides,
+      issues,
+    ));
+  }
+  for (const actionId of Object.keys(overrides)) {
+    if (isCoreKeybindingActionId(actionId) || actionId.startsWith(PLUGIN_ACTION_PREFIX)) continue;
+    issues.push({ kind: "unknown-action", actionId });
+  }
+
+  const commands: KeybindingCommand[] = [];
+  for (const [text, query] of Object.entries(config?.commands ?? {})) {
+    if (typeof query !== "string" || !query.trim()) continue;
+    const chord = parseKeyChord(text);
+    if (!chord) {
+      issues.push({ kind: "invalid-chord", target: "commands", text });
+      continue;
+    }
+    if (isTypingChord(chord)) {
+      issues.push({ kind: "typing-chord", target: "commands", text });
+      continue;
+    }
+    commands.push({ chord, text, query: query.trim() });
+  }
+
+  issues.push(...collectConflicts(actions, commands));
+
+  return {
+    actions,
+    actionsById: new Map(actions.map((action) => [action.id, action])),
+    commands,
+    issues,
+  };
+}
+
+/**
+ * The first action or command whose chord the event is, in table order. Actions
+ * win over commands, so a stray command binding never shadows a core key.
+ */
+export function matchKeybinding(resolved: ResolvedKeybindings, event: KeyChordEventLike): KeybindingMatch | null {
+  for (const action of resolved.actions) {
+    for (const chord of action.chords) {
+      if (!matchesKeyChord(chord, event)) continue;
+      return {
+        kind: "action",
+        id: action.id,
+        action,
+        digit: chord.key === "digit" ? keyChordDigit(event) : null,
+      };
+    }
+  }
+  for (const command of resolved.commands) {
+    if (matchesKeyChord(command.chord, event)) return { kind: "command", command };
+  }
+  return null;
+}
+
+export function matchesKeybindingAction(resolved: ResolvedKeybindings, id: string, event: KeyChordEventLike): boolean {
+  const action = resolved.actionsById.get(id);
+  return !!action && action.chords.some((chord) => matchesKeyChord(chord, event));
+}
+
+export function isPaneKeybindingAction(id: string): boolean {
+  return isCoreKeybindingActionId(id) && PANE_ACTION_IDS.has(id);
+}
+
+/**
+ * Chords for one plugin shortcut, honouring an override, for a handler that
+ * reads the live registry instead of a resolved table.
+ */
+export function resolvePluginShortcutChords(config: KeybindingsConfig | undefined, shortcut: KeyboardShortcut): KeyChord[] {
+  const override = parseChordList(config?.actions?.[pluginShortcutActionId(shortcut.id)], shortcut.id, []);
+  return override ?? [pluginShortcutDefaultChord(shortcut)];
+}
+
+export function describeKeybindingIssue(issue: KeybindingIssue): string {
+  switch (issue.kind) {
+    case "invalid-chord":
+      return `"${issue.text}" is not a key chord (${issue.target}).`;
+    case "unknown-action":
+      return `"${issue.actionId}" is not a keybinding action.`;
+    case "typing-chord":
+      return `"${issue.text}" would fire while typing; command bindings need Ctrl, Cmd, Alt or a function key.`;
+    case "conflict":
+      return `${serializeKeyChord(issue.chord)} is bound to ${issue.targets.join(" and ")}.`;
+  }
+}
+
+export function keybindingActionLabel(action: ResolvedKeybindingAction): string {
+  return action.def?.description ?? action.pluginShortcut?.description ?? action.id;
+}
+
+export { getKeybindingAction };

package/src/app.tsx

@@ -39,6 +39,7 @@ import { useBrokerImportRuntime } from "./app/runtime/broker-import";
 import { useDesktopDeepLinkRuntime } from "./app/runtime/desktop-deeplink";
 import { useDesktopApplicationMenuRuntime } from "./app/runtime/desktop-menu";
 import { useAppGlobalShortcuts } from "./app/global-shortcuts";
+import { KeybindingsProvider, useResolvedKeybindings } from "./app/keybindings";
 import { useAppPaneRuntime } from "./app/pane-runtime";
 import { bindPluginRegistryRuntimeAccess } from "./app/runtime/plugin-bindings";
 import { useAppStartupRuntime } from "./app/runtime/startup";
@@ -380,10 +381,12 @@ function AppInner({
     }
   }, [focusedTickerSymbol]);
 
+  const keybindings = useResolvedKeybindings(state.config.keybindings);
   useAppGlobalShortcuts({
     dispatch,
     focusedTickerSymbol,
     isDetachedWindow,
+    keybindings,
     pluginRegistry,
     refreshTicker,
     startUpdate,
@@ -392,27 +395,30 @@ function AppInner({
 
   if (desktopWindowBridge?.kind === "detached" && desktopWindowBridge.paneId) {
     return (
-      <ContextMenuProvider pluginRegistry={pluginRegistry}>
-        <RemoteControlHost
-          adapter={remoteControlAdapter}
-          dispatch={dispatch}
-          getState={getRemoteState}
-          pluginRegistry={pluginRegistry}
-          desktopWindowBridge={desktopWindowBridge}
-        >
-          <ThemedAppRoot>
-            <DetachedPaneShell
-              pluginRegistry={pluginRegistry}
-              desktopWindowBridge={{ ...desktopWindowBridge, kind: "detached", paneId: desktopWindowBridge.paneId }}
-            />
-            <ToastViewport position="bottom-right" />
-          </ThemedAppRoot>
-        </RemoteControlHost>
-      </ContextMenuProvider>
+      <KeybindingsProvider value={keybindings}>
+        <ContextMenuProvider pluginRegistry={pluginRegistry}>
+          <RemoteControlHost
+            adapter={remoteControlAdapter}
+            dispatch={dispatch}
+            getState={getRemoteState}
+            pluginRegistry={pluginRegistry}
+            desktopWindowBridge={desktopWindowBridge}
+          >
+            <ThemedAppRoot>
+              <DetachedPaneShell
+                pluginRegistry={pluginRegistry}
+                desktopWindowBridge={{ ...desktopWindowBridge, kind: "detached", paneId: desktopWindowBridge.paneId }}
+              />
+              <ToastViewport position="bottom-right" />
+            </ThemedAppRoot>
+          </RemoteControlHost>
+        </ContextMenuProvider>
+      </KeybindingsProvider>
     );
   }
 
   return (
+    <KeybindingsProvider value={keybindings}>
     <ContextMenuProvider pluginRegistry={pluginRegistry}>
       <RemoteControlHost
         adapter={remoteControlAdapter}
@@ -460,6 +466,7 @@ function AppInner({
         </ThemedAppRoot>
       </RemoteControlHost>
     </ContextMenuProvider>
+    </KeybindingsProvider>
   );
 }
 
@@ -548,6 +555,7 @@ export function App({
       servicesFactory({
         config,
         plugins,
+        externalPlugins,
       })
     ), {
       externalPluginCount: externalPlugins.length,

package/src/cli/commands/keybindings.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { createDefaultConfig } from "../../types/config";
+import { applyKeybindingCliSet, describeKeybindingsForCli } from "./keybindings";
+
+const config = createDefaultConfig("/tmp/gloomberb-cli-keybindings");
+
+describe("config set keybindings", () => {
+  test("binds, unbinds and restores actions", () => {
+    const bound = applyKeybindingCliSet(config, "keybindings.actions.ticker-search", "Ctrl+T `");
+    if (!bound.ok) throw new Error(bound.message);
+    expect(bound.value).toEqual(["Ctrl+T", "`"]);
+    expect(bound.config.keybindings).toEqual({ actions: { "ticker-search": ["Ctrl+T", "`"] } });
+
+    const unbound = applyKeybindingCliSet(bound.config, "keybindings.actions.help", "null");
+    if (!unbound.ok) throw new Error(unbound.message);
+    expect(unbound.config.keybindings?.actions).toEqual({ "ticker-search": ["Ctrl+T", "`"], help: null });
+
+    const restored = applyKeybindingCliSet(unbound.config, "keybindings.actions.ticker-search", "default");
+    if (!restored.ok) throw new Error(restored.message);
+    expect(restored.config.keybindings).toEqual({ actions: { help: null } });
+    expect(describeKeybindingsForCli(restored.config)).toMatchObject({
+      actions: {
+        help: { keys: [], custom: true, defaults: ["?"] },
+        "ticker-search": { keys: ["`"] },
+      },
+      issues: [],
+    });
+  });
+
+  test("binds and removes commands, refusing chords a text field would eat", () => {
+    const bound = applyKeybindingCliSet(config, "keybindings.commands.alt+1", "DES AAPL");
+    if (!bound.ok) throw new Error(bound.message);
+    expect(bound.config.keybindings).toEqual({ commands: { "Alt+1": "DES AAPL" } });
+
+    const removed = applyKeybindingCliSet(bound.config, "keybindings.commands.Alt+1", "null");
+    if (!removed.ok) throw new Error(removed.message);
+    expect(removed.config.keybindings).toBeUndefined();
+
+    expect(applyKeybindingCliSet(config, "keybindings.commands.a", "HN")).toMatchObject({ ok: false });
+  });
+
+  test("rejects unknown actions, bad chords and bad sections with a usable message", () => {
+    expect(applyKeybindingCliSet(config, "keybindings.actions.nope", "F1")).toMatchObject({ ok: false, message: expect.stringContaining("not a keybinding action") });
+    expect(applyKeybindingCliSet(config, "keybindings.actions.quit", "Hyper+Q")).toMatchObject({ ok: false, message: expect.stringContaining("not a key chord") });
+    expect(applyKeybindingCliSet(config, "keybindings.other.x", "F1")).toMatchObject({ ok: false });
+    expect(applyKeybindingCliSet(config, "keybindings.actions", "F1")).toMatchObject({ ok: false });
+  });
+});

package/src/cli/commands/keybindings.ts

@@ -0,0 +1,102 @@
+import {
+  applyActionBinding,
+  describeKeybindingIssue,
+  isCoreKeybindingActionId,
+  isTypingChord,
+  parseKeyChord,
+  PLUGIN_ACTION_PREFIX,
+  removeCommandBinding,
+  resolveKeybindings,
+  serializeKeyChord,
+  setCommandBinding,
+  updateKeybindingsConfig,
+} from "../../app/keybindings";
+import type { AppConfig } from "../../types/config";
+
+export const KEYBINDINGS_CONFIG_KEY = "keybindings";
+
+const UNBIND_WORDS = new Set(["null", "none", "off", "unbind"]);
+const DEFAULT_WORDS = new Set(["default", "defaults", "reset"]);
+
+/** The effective table with defaults filled in, plus anything that needs fixing. */
+export function describeKeybindingsForCli(config: AppConfig): Record<string, unknown> {
+  const resolved = resolveKeybindings(config.keybindings);
+  return {
+    actions: Object.fromEntries(resolved.actions.map((action) => [
+      action.id,
+      {
+        keys: action.chords.map(serializeKeyChord),
+        ...(action.custom ? { custom: true, defaults: action.defaults.map(serializeKeyChord) } : {}),
+      },
+    ])),
+    commands: Object.fromEntries(resolved.commands.map((command) => [command.text, command.query])),
+    issues: resolved.issues.map(describeKeybindingIssue),
+  };
+}
+
+export type KeybindingCliSetResult =
+  | { ok: true; config: AppConfig; value: unknown }
+  | { ok: false; message: string };
+
+/**
+ * `config set keybindings.actions.<action> <chords>` and
+ * `config set keybindings.commands.<chord> <query>`. Chords are separated by
+ * whitespace, since no chord contains a space; `null` unbinds and `default`
+ * clears an override.
+ */
+export function applyKeybindingCliSet(config: AppConfig, key: string, rawValue: string): KeybindingCliSetResult {
+  const [, section, ...rest] = key.split(".");
+  const target = rest.join(".");
+  const value = rawValue.trim();
+  if (!target) {
+    return { ok: false, message: `Usage: gloomberb config set ${KEYBINDINGS_CONFIG_KEY}.actions.<action> <chord> or ${KEYBINDINGS_CONFIG_KEY}.commands.<chord> <query>` };
+  }
+
+  if (section === "actions") {
+    if (!isCoreKeybindingActionId(target) && !target.startsWith(PLUGIN_ACTION_PREFIX)) {
+      return { ok: false, message: `"${target}" is not a keybinding action. Run "gloomberb config get keybindings" for the list.` };
+    }
+    const lowered = value.toLowerCase();
+    if (DEFAULT_WORDS.has(lowered)) {
+      const actions = { ...(config.keybindings?.actions ?? {}) };
+      delete actions[target];
+      return { ok: true, config: updateKeybindingsConfig(config, { ...config.keybindings, actions }), value: "default" };
+    }
+    if (UNBIND_WORDS.has(lowered) || value === "") {
+      return { ok: true, config: updateKeybindingsConfig(config, applyActionBinding(config.keybindings, target, [])), value: null };
+    }
+    const chords = [];
+    for (const text of value.split(/\s+/)) {
+      const chord = parseKeyChord(text);
+      if (!chord) return { ok: false, message: `"${text}" is not a key chord. Examples: Ctrl+T, CmdOrCtrl+Shift+F, Alt+1, F5, \`` };
+      chords.push(chord);
+    }
+    return {
+      ok: true,
+      config: updateKeybindingsConfig(config, applyActionBinding(config.keybindings, target, chords)),
+      value: chords.map(serializeKeyChord),
+    };
+  }
+
+  if (section === "commands") {
+    const chord = parseKeyChord(target);
+    if (!chord) return { ok: false, message: `"${target}" is not a key chord. Examples: Alt+1, CmdOrCtrl+Shift+N, F5` };
+    if (UNBIND_WORDS.has(value.toLowerCase()) || value === "") {
+      return {
+        ok: true,
+        config: updateKeybindingsConfig(config, removeCommandBinding(config.keybindings, serializeKeyChord(chord))),
+        value: null,
+      };
+    }
+    if (isTypingChord(chord)) {
+      return { ok: false, message: `"${target}" would fire while typing; command bindings need Ctrl, Cmd, Alt or a function key.` };
+    }
+    return {
+      ok: true,
+      config: updateKeybindingsConfig(config, setCommandBinding(config.keybindings, chord, value)),
+      value,
+    };
+  }
+
+  return { ok: false, message: `Unknown keybindings section "${section ?? ""}". Use keybindings.actions or keybindings.commands.` };
+}