@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/keybindings/__tests__/node-keybindings-source.test.ts

@@ -0,0 +1,111 @@
+import { mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createNodeKeybindingsSource,
+} from '../node-keybindings-source.js';
+
+const roots: string[] = [];
+
+async function temporaryRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'robota-keybindings-'));
+  roots.push(root);
+  return root;
+}
+
+async function eventually(assertion: () => void, timeout = 2_000): Promise<void> {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    try {
+      assertion();
+      return;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+  assertion();
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe('Node keybindings source', () => {
+  it('uses only the host-selected file and schema when creating the sparse document', async () => {
+    const root = await temporaryRoot();
+    const filePath = join(root, 'host-config', 'keys.json');
+    const schemaUrl = 'https://example.invalid/schemas/keys.json';
+    const source = createNodeKeybindingsSource({ filePath, schemaUrl });
+    const firstPath = await source.ensureFile();
+    expect(firstPath).toBe(filePath);
+    expect(JSON.parse(await readFile(firstPath, 'utf8'))).toEqual({
+      $schema: schemaUrl,
+      version: 1,
+      bindings: {},
+    });
+
+    await writeFile(firstPath, '{"owned":true}\n', 'utf8');
+    expect(await source.ensureFile()).toBe(firstPath);
+    expect(await readFile(firstPath, 'utf8')).toBe('{"owned":true}\n');
+    source.dispose();
+  });
+
+  it('loads atomic replacements, retains last-valid bindings on invalid input, and disposes', async () => {
+    const root = await temporaryRoot();
+    const path = join(root, 'custom', 'keybindings.json');
+    const log = vi.fn();
+    const source = createNodeKeybindingsSource({
+      filePath: path,
+      schemaUrl: 'https://example.invalid/keys.json',
+      onDiagnostic: log,
+    });
+    await source.start();
+    expect(await source.ensureFile()).toBe(path);
+    const snapshots = [source.getSnapshot()];
+    const unsubscribe = source.subscribe((snapshot) => snapshots.push(snapshot));
+
+    const replacement = join(root, 'custom', 'keybindings.next.json');
+    await writeFile(
+      replacement,
+      JSON.stringify({ version: 1, bindings: { 'chat-input': { submit: 'ctrl+k' } } }),
+      'utf8',
+    );
+    await rename(replacement, path);
+    await eventually(() => {
+      expect(source.getSnapshot().bindings['chat-input'].submit).toEqual(['ctrl+k']);
+    });
+    const valid = source.getSnapshot();
+
+    await writeFile(replacement, '{"version":1,"bindings":{"missing":{}}}', 'utf8');
+    await rename(replacement, path);
+    await eventually(() => {
+      expect(source.getSnapshot().diagnostic?.path).toBe('$.bindings.missing');
+    });
+    expect(source.getSnapshot().bindings).toBe(valid.bindings);
+    expect(source.getSnapshot().generation).toBeGreaterThan(valid.generation);
+    expect(log).toHaveBeenCalledWith(expect.objectContaining({ file: path }));
+
+    unsubscribe();
+    source.dispose();
+    const count = snapshots.length;
+    await writeFile(path, JSON.stringify({ version: 1, bindings: {} }), 'utf8');
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    expect(snapshots).toHaveLength(count);
+  });
+
+  it('shares one start, and a failed start leaves no half-started source', async () => {
+    const root = await temporaryRoot();
+    const source = createNodeKeybindingsSource({
+      filePath: join(root, 'custom', 'keybindings.json'),
+      schemaUrl: 'https://example.invalid/keys.json',
+    });
+    await Promise.all([source.start(), source.start()]);
+    expect(source.isStarted()).toBe(true);
+    source.dispose();
+    expect(source.isStarted()).toBe(false);
+    await expect(source.start()).rejects.toThrow(/disposed/i);
+  });
+});

package/src/keybindings/keybinding-catalogue.ts

@@ -0,0 +1,171 @@
+export const KEYBINDING_ACTIONS = {
+  app: ['open-workspace-switcher'],
+  thinking: ['abort'],
+  'background-detail': ['return-to-main'],
+  recovery: ['retry'],
+  'chat-input': [
+    'submit',
+    'history-previous',
+    'history-next',
+    'history-search',
+    'cursor-left',
+    'cursor-right',
+    'delete-backward',
+    'delete-word',
+    'delete-line',
+  ],
+  'text-input': [
+    'submit',
+    'cursor-left',
+    'cursor-right',
+    'cursor-up',
+    'cursor-down',
+    'delete-backward',
+    'delete-word',
+    'delete-line',
+  ],
+  'autocomplete-menu': ['previous', 'next', 'close', 'accept', 'execute'],
+  'queued-prompt': ['cancel'],
+  'confirm-prompt': ['previous', 'next', 'confirm', 'choose-yes', 'choose-no'],
+  'permission-prompt': [
+    'previous',
+    'next',
+    'confirm',
+    'allow-once',
+    'allow-session',
+    'allow-project',
+    'deny',
+  ],
+  'text-prompt': ['submit', 'cancel', 'delete-backward'],
+  'list-picker': ['previous', 'next', 'select', 'cancel'],
+  'menu-select': ['previous', 'next', 'select', 'back'],
+  'multi-select': ['previous', 'next', 'toggle', 'confirm', 'cancel'],
+  'workspace-switcher': ['previous', 'next', 'select', 'close', 'attach'],
+  'background-list': ['previous', 'next', 'open', 'close'],
+  'transport-settings': ['previous', 'next', 'toggle', 'close'],
+  /** SCREEN-1993: the reverse prompt-history search overlay. */
+  'history-search': ['previous', 'next', 'cycle-scope', 'insert', 'execute', 'cancel'],
+  /**
+   * SCREEN-2002: the theme picker. Navigation PREVIEWS; only `select` applies. Printable keys are
+   * fine here because the picker takes no text.
+   */
+  'theme-picker': ['previous', 'next', 'select', 'toggle-syntax', 'toggle-motion', 'cancel'],
+} as const;
+
+export type TKeybindingContext = keyof typeof KEYBINDING_ACTIONS;
+export type TKeybindingAction<TContext extends TKeybindingContext = TKeybindingContext> =
+  (typeof KEYBINDING_ACTIONS)[TContext][number];
+
+type TDefaultKeybindings = {
+  readonly [TContext in TKeybindingContext]: Readonly<
+    Record<TKeybindingAction<TContext>, readonly string[]>
+  >;
+};
+
+export const DEFAULT_KEYBINDINGS = {
+  app: { 'open-workspace-switcher': ['ctrl+b'] },
+  thinking: { abort: ['escape'] },
+  'background-detail': { 'return-to-main': ['escape'] },
+  recovery: { retry: ['enter'] },
+  'chat-input': {
+    submit: ['enter'],
+    'history-previous': ['up'],
+    'history-next': ['down'],
+    'history-search': ['ctrl+r'],
+    'cursor-left': ['left'],
+    'cursor-right': ['right'],
+    'delete-backward': ['backspace', 'delete'],
+    'delete-word': ['ctrl+w'],
+    'delete-line': ['ctrl+u'],
+  },
+  'text-input': {
+    submit: ['enter'],
+    'cursor-left': ['left'],
+    'cursor-right': ['right'],
+    'cursor-up': ['up'],
+    'cursor-down': ['down'],
+    'delete-backward': ['backspace', 'delete'],
+    'delete-word': ['ctrl+w'],
+    'delete-line': ['ctrl+u'],
+  },
+  'autocomplete-menu': {
+    previous: ['up'],
+    next: ['down'],
+    close: ['escape'],
+    accept: ['tab'],
+    execute: ['enter'],
+  },
+  'queued-prompt': { cancel: ['backspace', 'delete'] },
+  'confirm-prompt': {
+    previous: ['left', 'up'],
+    next: ['right', 'down'],
+    confirm: ['enter'],
+    'choose-yes': ['y'],
+    'choose-no': ['n'],
+  },
+  'permission-prompt': {
+    previous: ['left', 'up'],
+    next: ['right', 'down'],
+    confirm: ['enter'],
+    'allow-once': ['y'],
+    'allow-session': ['s', 'a'],
+    'allow-project': ['p'],
+    deny: ['n', 'd'],
+  },
+  'text-prompt': {
+    submit: ['enter'],
+    cancel: ['escape'],
+    'delete-backward': ['backspace', 'delete'],
+  },
+  'list-picker': { previous: ['up'], next: ['down'], select: ['enter'], cancel: ['escape'] },
+  'menu-select': { previous: ['up'], next: ['down'], select: ['enter'], back: ['escape'] },
+  'multi-select': {
+    previous: ['up'],
+    next: ['down'],
+    toggle: ['space'],
+    confirm: ['enter'],
+    cancel: ['escape'],
+  },
+  'workspace-switcher': {
+    previous: ['up'],
+    next: ['down'],
+    select: ['enter'],
+    close: ['ctrl+b', 'escape'],
+    attach: ['a'],
+  },
+  'background-list': {
+    previous: ['up'],
+    next: ['down'],
+    open: ['enter'],
+    close: ['escape'],
+  },
+  'transport-settings': {
+    previous: ['up'],
+    next: ['down'],
+    toggle: ['space'],
+    close: ['enter', 'escape'],
+  },
+  'history-search': {
+    previous: ['up'],
+    next: ['down', 'ctrl+r'],
+    'cycle-scope': ['ctrl+s'],
+    insert: ['enter', 'tab'],
+    execute: ['ctrl+e'],
+    cancel: ['escape'],
+  },
+  'theme-picker': {
+    previous: ['up'],
+    next: ['down'],
+    select: ['enter'],
+    'toggle-syntax': ['s'],
+    'toggle-motion': ['m'],
+    cancel: ['escape'],
+  },
+} as const satisfies TDefaultKeybindings;
+
+export const TEXT_ENTRY_CONTEXTS: ReadonlySet<TKeybindingContext> = new Set([
+  'chat-input',
+  'text-input',
+  'text-prompt',
+  'history-search',
+]);

package/src/keybindings/keybinding-registry.ts

@@ -0,0 +1,303 @@
+import { isJsonRecord } from '../json-value.js';
+import {
+  DEFAULT_KEYBINDINGS,
+  KEYBINDING_ACTIONS,
+  TEXT_ENTRY_CONTEXTS,
+  type TKeybindingAction,
+  type TKeybindingContext,
+} from './keybinding-catalogue.js';
+import {
+  displayBinding,
+  keybindingDeliverySignature,
+  keyStrokesFromInput,
+  normalizeBinding,
+  type IKeyInput,
+} from './keybinding-syntax.js';
+
+import type { TJsonValue } from '../json-value.js';
+
+export { DEFAULT_KEYBINDINGS } from './keybinding-catalogue.js';
+export type { IKeyInput } from './keybinding-syntax.js';
+export type { TKeybindingAction, TKeybindingContext } from './keybinding-catalogue.js';
+
+export interface IKeybindingWarning {
+  readonly code: 'multiplexer-conflict' | 'modifier-delivery';
+  readonly path: string;
+  readonly message: string;
+}
+
+export interface IKeybindingDiagnostic {
+  readonly file: string;
+  readonly path: string;
+  readonly message: string;
+}
+
+export interface IKeybindingSnapshot {
+  readonly generation: number;
+  readonly sourcePath: string;
+  readonly bindings: Readonly<
+    Record<TKeybindingContext, Readonly<Record<string, readonly string[]>>>
+  >;
+  readonly warnings: readonly IKeybindingWarning[];
+  readonly diagnostic?: IKeybindingDiagnostic;
+}
+
+export type TParseKeybindingsResult =
+  | { readonly ok: true; readonly snapshot: IKeybindingSnapshot }
+  | { readonly ok: false; readonly diagnostic: IKeybindingDiagnostic };
+
+const CHORD_TIMEOUT_MS = 1_000;
+
+function diagnostic(file: string, path: string, message: string): TParseKeybindingsResult {
+  return { ok: false, diagnostic: { file, path, message } };
+}
+
+function cloneDefaults(): Record<TKeybindingContext, Record<string, string[]>> {
+  return Object.fromEntries(
+    Object.entries(DEFAULT_KEYBINDINGS).map(([context, actions]) => [
+      context,
+      Object.fromEntries(
+        Object.entries(actions).map(([action, bindings]) => [action, [...bindings]]),
+      ),
+    ]),
+  ) as Record<TKeybindingContext, Record<string, string[]>>;
+}
+
+function bindingValues(value: TJsonValue): readonly string[] | null | undefined {
+  if (value === null) return null;
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string')) {
+    return value;
+  }
+  return undefined;
+}
+
+function validateContextBindings(
+  context: TKeybindingContext,
+  bindings: Record<string, string[]>,
+  file: string,
+): TParseKeybindingsResult | undefined {
+  const owners = new Map<string, string>();
+  const prefixes = new Map<string, string>();
+  for (const [action, values] of Object.entries(bindings)) {
+    for (const binding of values) {
+      const deliveryBinding = keybindingDeliverySignature(binding);
+      const owner = owners.get(deliveryBinding);
+      const actionPath = `$.bindings.${context}.${action}`;
+      if (owner !== undefined && owner !== action) {
+        return diagnostic(file, actionPath, `Binding duplicates action ${owner}.`);
+      }
+      const strokes = deliveryBinding.split(' ');
+      if (strokes.length > 1 && TEXT_ENTRY_CONTEXTS.has(context) && isPrintable(strokes[0] ?? '')) {
+        return diagnostic(
+          file,
+          actionPath,
+          'Printable text cannot begin a chord in a text context.',
+        );
+      }
+      owners.set(deliveryBinding, action);
+      if (strokes.length > 1) prefixes.set(strokes[0] ?? '', action);
+    }
+  }
+  for (const [binding, action] of owners) {
+    const prefixOwner = prefixes.get(binding);
+    if (prefixOwner !== undefined) {
+      return diagnostic(
+        file,
+        `$.bindings.${context}.${prefixOwner}`,
+        `Chord prefix collides with action ${action}.`,
+      );
+    }
+  }
+  return undefined;
+}
+
+function isPrintable(stroke: string): boolean {
+  return !stroke.includes('+') && [...stroke].length === 1;
+}
+
+function warningFor(binding: string, path: string): IKeybindingWarning[] {
+  const warnings: IKeybindingWarning[] = [];
+  if (binding.split(' ').includes('ctrl+b')) {
+    warnings.push({
+      code: 'multiplexer-conflict',
+      path,
+      message: 'Ctrl+B may be captured by a terminal multiplexer.',
+    });
+  }
+  if (/ctrl\+shift\+[a-z]/u.test(binding)) {
+    warnings.push({
+      code: 'modifier-delivery',
+      path,
+      message: 'This terminal may not distinguish Ctrl+Shift from Ctrl.',
+    });
+  }
+  return warnings;
+}
+
+export function parseKeybindingsDocument(text: string, file: string): TParseKeybindingsResult {
+  let value: TJsonValue;
+  try {
+    value = JSON.parse(text) as TJsonValue;
+  } catch (cause) {
+    return diagnostic(file, '$', cause instanceof Error ? cause.message : 'Invalid JSON.');
+  }
+  if (!isJsonRecord(value)) return diagnostic(file, '$', 'Expected an object.');
+  if (value.version !== 1) return diagnostic(file, '$.version', 'Expected version 1.');
+  if (!isJsonRecord(value.bindings)) return diagnostic(file, '$.bindings', 'Expected an object.');
+
+  const effective = cloneDefaults();
+  const warnings: IKeybindingWarning[] = [];
+  for (const [rawContext, rawActions] of Object.entries(value.bindings)) {
+    if (!(rawContext in KEYBINDING_ACTIONS)) {
+      return diagnostic(file, `$.bindings.${rawContext}`, 'Unknown keybinding context.');
+    }
+    const context = rawContext as TKeybindingContext;
+    if (!isJsonRecord(rawActions)) {
+      return diagnostic(file, `$.bindings.${context}`, 'Expected an action object.');
+    }
+    for (const [action, rawBindings] of Object.entries(rawActions)) {
+      if (!(KEYBINDING_ACTIONS[context] as readonly string[]).includes(action)) {
+        return diagnostic(file, `$.bindings.${context}.${action}`, 'Unknown action.');
+      }
+      const values = bindingValues(rawBindings);
+      const actionPath = `$.bindings.${context}.${action}`;
+      if (values === undefined) {
+        return diagnostic(file, actionPath, 'Expected a binding, binding list, or null.');
+      }
+      if (values === null) {
+        effective[context][action] = [];
+        continue;
+      }
+      const normalized: string[] = [];
+      for (const rawBinding of values) {
+        const binding = normalizeBinding(rawBinding);
+        if (binding === undefined) return diagnostic(file, actionPath, 'Invalid binding syntax.');
+        if (binding.split(' ').includes('ctrl+c')) {
+          return diagnostic(file, actionPath, 'Ctrl+C is reserved for two-stage shutdown.');
+        }
+        normalized.push(binding);
+        warnings.push(...warningFor(binding, actionPath));
+      }
+      effective[context][action] = normalized;
+    }
+  }
+  for (const context of Object.keys(effective) as TKeybindingContext[]) {
+    const invalid = validateContextBindings(context, effective[context], file);
+    if (invalid !== undefined) return invalid;
+  }
+  const bindings = Object.freeze(
+    Object.fromEntries(
+      Object.entries(effective).map(([context, actions]) => [
+        context,
+        Object.freeze(
+          Object.fromEntries(
+            Object.entries(actions).map(([action, bindings]) => [action, Object.freeze(bindings)]),
+          ),
+        ),
+      ]),
+    ),
+  ) as IKeybindingSnapshot['bindings'];
+  return {
+    ok: true,
+    snapshot: Object.freeze({
+      generation: 0,
+      sourcePath: file,
+      bindings,
+      warnings: Object.freeze(warnings),
+    }),
+  };
+}
+
+export interface IChordState {
+  readonly context?: TKeybindingContext;
+  readonly generation?: number;
+  readonly strokes: readonly string[];
+  readonly deadline?: number;
+}
+
+export function createEmptyChordState(): IChordState {
+  return { strokes: [] };
+}
+
+function actionBindings(
+  snapshot: IKeybindingSnapshot,
+  context: TKeybindingContext,
+): [TKeybindingAction, readonly string[]][] {
+  return Object.entries(snapshot.bindings[context]) as [TKeybindingAction, readonly string[]][];
+}
+
+export function resolveKeybindingInput(options: {
+  readonly snapshot: IKeybindingSnapshot;
+  readonly state: IChordState;
+  readonly context: TKeybindingContext;
+  readonly input: string;
+  readonly key: IKeyInput;
+  readonly now: number;
+}): {
+  readonly state: IChordState;
+  readonly actions: readonly TKeybindingAction[];
+  readonly consumed: boolean;
+} {
+  const strokes = keyStrokesFromInput(options.input, options.key);
+  if (strokes.length === 0) {
+    return { state: createEmptyChordState(), actions: [], consumed: false };
+  }
+  const stateValid =
+    options.state.context === options.context &&
+    options.state.generation === options.snapshot.generation &&
+    (options.state.deadline === undefined || options.now <= options.state.deadline) &&
+    !options.key.escape;
+  const prior = stateValid ? options.state.strokes : [];
+  const entries = actionBindings(options.snapshot, options.context);
+  for (const stroke of strokes) {
+    const sequence = [...prior, stroke].join(' ');
+    const exact = entries
+      .filter(([, bindings]) => bindings.includes(sequence))
+      .map(([action]) => action);
+    if (exact.length > 0) {
+      return { state: createEmptyChordState(), actions: exact, consumed: true };
+    }
+    if (
+      entries.some(([, bindings]) => bindings.some((binding) => binding.startsWith(`${sequence} `)))
+    ) {
+      return {
+        state: {
+          context: options.context,
+          generation: options.snapshot.generation,
+          strokes: [...prior, stroke],
+          deadline: options.now + CHORD_TIMEOUT_MS,
+        },
+        actions: [],
+        consumed: true,
+      };
+    }
+  }
+  if (prior.length > 0) {
+    return resolveKeybindingInput({ ...options, state: createEmptyChordState() });
+  }
+  return { state: createEmptyChordState(), actions: [], consumed: false };
+}
+
+export function keybindingHints<TContext extends TKeybindingContext>(
+  snapshot: IKeybindingSnapshot,
+  context: TContext,
+  actions: readonly (readonly [
+    TKeybindingAction<TContext> | readonly TKeybindingAction<TContext>[],
+    string,
+  ])[],
+): { keys: string; label: string }[] {
+  return actions.flatMap(([actionOrActions, label]) => {
+    const grouped = Array.isArray(actionOrActions);
+    const actionList = grouped ? actionOrActions : [actionOrActions];
+    const bindings = actionList.flatMap((action) => {
+      const values = snapshot.bindings[context][action] ?? [];
+      return grouped ? values.slice(0, 1) : values;
+    });
+    const displayed = bindings.map(displayBinding);
+    const keys = displayed.every((binding) => /^[↑↓←→]$/u.test(binding))
+      ? displayed.join('')
+      : displayed.join('/');
+    return bindings.length === 0 ? [] : [{ keys, label }];
+  });
+}