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

package/src/keybindings/keybinding-syntax.ts

@@ -0,0 +1,155 @@
+export interface IKeyInput {
+  readonly ctrl?: boolean;
+  readonly shift?: boolean;
+  readonly meta?: boolean;
+  readonly return?: boolean;
+  readonly escape?: boolean;
+  readonly tab?: boolean;
+  readonly upArrow?: boolean;
+  readonly downArrow?: boolean;
+  readonly leftArrow?: boolean;
+  readonly rightArrow?: boolean;
+  readonly backspace?: boolean;
+  readonly delete?: boolean;
+}
+
+const MODIFIER_ALIASES: Readonly<Record<string, 'ctrl' | 'alt' | 'meta' | 'shift'>> = {
+  ctrl: 'ctrl',
+  control: 'ctrl',
+  alt: 'alt',
+  option: 'alt',
+  meta: 'meta',
+  cmd: 'meta',
+  command: 'meta',
+  shift: 'shift',
+};
+const MODIFIER_ORDER = ['ctrl', 'alt', 'meta', 'shift'] as const;
+const KEY_ALIASES: Readonly<Record<string, string>> = {
+  return: 'enter',
+  enter: 'enter',
+  esc: 'escape',
+  escape: 'escape',
+  tab: 'tab',
+  space: 'space',
+  spacebar: 'space',
+  up: 'up',
+  down: 'down',
+  left: 'left',
+  right: 'right',
+  backspace: 'backspace',
+  delete: 'delete',
+};
+
+export function normalizeBinding(raw: string): string | undefined {
+  const strokes = raw.trim().split(/\s+/u);
+  if (strokes.length < 1 || strokes.length > 2) return undefined;
+  const normalized = strokes.map(normalizeStroke);
+  return normalized.every((stroke): stroke is string => stroke !== undefined)
+    ? normalized.join(' ')
+    : undefined;
+}
+
+function normalizeStroke(raw: string): string | undefined {
+  if (!raw || raw.includes(' ')) return undefined;
+  const parts = raw.split('+');
+  if (parts.some((part) => part.length === 0)) return undefined;
+  const rawKey = parts.at(-1);
+  if (rawKey === undefined) return undefined;
+  const modifiers = new Set<'ctrl' | 'alt' | 'meta' | 'shift'>();
+  for (const rawModifier of parts.slice(0, -1)) {
+    const modifier = MODIFIER_ALIASES[rawModifier.toLowerCase()];
+    if (modifier === undefined || modifiers.has(modifier)) return undefined;
+    modifiers.add(modifier);
+  }
+  let key = KEY_ALIASES[rawKey.toLowerCase()];
+  if (key === undefined) {
+    if ([...rawKey].length !== 1 || /\s/u.test(rawKey)) return undefined;
+    key = rawKey.toLowerCase();
+    if (parts.length === 1 && rawKey !== key) modifiers.add('shift');
+  }
+  return [...MODIFIER_ORDER.filter((modifier) => modifiers.has(modifier)), key].join('+');
+}
+
+function keyStrokeFromInput(input: string, key: IKeyInput): string | undefined {
+  // Ink preserves LF as a one-character input string instead of setting `key.return`. In terminal
+  // raw mode that byte is Ctrl+J; normalize it before printable-text handling can treat it as paste.
+  if (/^[\r\n]*\n[\r\n]*$/u.test(input)) return 'ctrl+j';
+  const special = key.return
+    ? 'enter'
+    : key.escape
+      ? 'escape'
+      : key.tab
+        ? 'tab'
+        : key.upArrow
+          ? 'up'
+          : key.downArrow
+            ? 'down'
+            : key.leftArrow
+              ? 'left'
+              : key.rightArrow
+                ? 'right'
+                : key.backspace
+                  ? 'backspace'
+                  : key.delete
+                    ? 'delete'
+                    : input === ' '
+                      ? 'space'
+                      : [...input].length === 1
+                        ? input.toLowerCase()
+                        : undefined;
+  if (special === undefined) return undefined;
+  const modifiers = [
+    ...(key.ctrl ? ['ctrl'] : []),
+    ...(key.meta ? ['meta'] : []),
+    ...(key.shift ? ['shift'] : []),
+  ];
+  return [...modifiers, special].join('+');
+}
+
+/**
+ * Terminal protocols collapse several control characters onto named keys. Keep the configured
+ * spelling for hints, but offer every spelling that the same received byte can represent.
+ */
+export function keyStrokesFromInput(input: string, key: IKeyInput): readonly string[] {
+  const primary = keyStrokeFromInput(input, key);
+  if (primary === undefined) return [];
+  if (primary === 'enter') return ['enter', 'ctrl+m'];
+  if (primary === 'tab') return ['tab', 'ctrl+i'];
+  if (primary === 'escape') return ['escape', 'ctrl+['];
+  return [primary];
+}
+
+export function keybindingDeliverySignature(binding: string): string {
+  return binding
+    .split(' ')
+    .map((stroke) => {
+      if (stroke === 'ctrl+m') return 'enter';
+      if (stroke === 'ctrl+i') return 'tab';
+      if (stroke === 'ctrl+[') return 'escape';
+      return stroke;
+    })
+    .join(' ');
+}
+
+export function displayBinding(binding: string): string {
+  const displayStroke = (stroke: string): string =>
+    stroke
+      .split('+')
+      .map(
+        (part) =>
+          ({
+            ctrl: 'Ctrl',
+            alt: 'Alt',
+            meta: 'Meta',
+            shift: 'Shift',
+            escape: 'Esc',
+            up: '↑',
+            down: '↓',
+            left: '←',
+            right: '→',
+          })[part] ??
+          (part.length === 1 ? part.toUpperCase() : `${part[0]?.toUpperCase()}${part.slice(1)}`),
+      )
+      .join('+');
+  return binding.split(' ').map(displayStroke).join(' ');
+}

package/src/keybindings/keybindings-context.tsx

@@ -0,0 +1,124 @@
+import { useInput } from 'ink';
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
+
+import {
+  createEmptyChordState,
+  keybindingHints,
+  parseKeybindingsDocument,
+  resolveKeybindingInput,
+  type IChordState,
+  type IKeybindingSnapshot,
+  type IKeyInput,
+  type TKeybindingAction,
+  type TKeybindingContext,
+} from './keybinding-registry.js';
+
+import type { IKeybindingsSource } from './node-keybindings-source.js';
+
+const parsedDefault = parseKeybindingsDocument('{"version":1,"bindings":{}}', '<defaults>');
+if (!parsedDefault.ok) throw new Error(parsedDefault.diagnostic.message);
+const DEFAULT_SNAPSHOT = parsedDefault.snapshot;
+
+const KeybindingsContext = createContext<IKeybindingSnapshot>(DEFAULT_SNAPSHOT);
+
+export function KeybindingsProvider({
+  source,
+  children,
+}: {
+  source?: IKeybindingsSource;
+  children: React.ReactNode;
+}): React.ReactElement {
+  const [snapshot, setSnapshot] = useState(() => source?.getSnapshot() ?? DEFAULT_SNAPSHOT);
+  useEffect(() => {
+    if (source === undefined) return;
+    setSnapshot(source.getSnapshot());
+    return source.subscribe(setSnapshot);
+  }, [source]);
+  return <KeybindingsContext.Provider value={snapshot}>{children}</KeybindingsContext.Provider>;
+}
+
+export function useKeybindings(): IKeybindingSnapshot {
+  return useContext(KeybindingsContext);
+}
+
+export function useKeybindingHints<TContext extends TKeybindingContext>(
+  context: TContext,
+  actions: readonly (readonly [
+    TKeybindingAction<TContext> | readonly TKeybindingAction<TContext>[],
+    string,
+  ])[],
+): { keys: string; label: string }[] {
+  return keybindingHints(useKeybindings(), context, actions);
+}
+
+export function useKeybindingActions<
+  TContext extends TKeybindingContext,
+  TFallback extends TKeybindingContext = TContext,
+>(
+  context: TContext,
+  handler: (
+    actions: readonly (TKeybindingAction<TContext> | TKeybindingAction<TFallback>)[],
+    input: string,
+    key: IKeyInput,
+    consumed: boolean,
+    resolvedContext: TContext | TFallback,
+  ) => void,
+  options: {
+    readonly isActive?: boolean;
+    /**
+     * A key `context` does not bind is resolved again here, so a surface layered over an editor (the
+     * autocomplete menu over the chat input) leaves every key it does not use to the editor's bindings.
+     */
+    readonly fallbackContext?: TFallback;
+  } = {},
+): void {
+  const snapshot = useKeybindings();
+  const stateRef = useRef<IChordState>(createEmptyChordState());
+  const fallbackStateRef = useRef<IChordState>(createEmptyChordState());
+  const { fallbackContext } = options;
+  useEffect(() => {
+    stateRef.current = createEmptyChordState();
+    fallbackStateRef.current = createEmptyChordState();
+  }, [context, fallbackContext, snapshot.generation]);
+  useInput(
+    (input, key) => {
+      const result = resolveKeybindingInput({
+        snapshot,
+        state: stateRef.current,
+        context,
+        input,
+        key,
+        now: Date.now(),
+      });
+      stateRef.current = result.state;
+      if (fallbackContext === undefined || result.consumed) {
+        fallbackStateRef.current = createEmptyChordState();
+        handler(
+          result.actions as readonly TKeybindingAction<TContext>[],
+          input,
+          key,
+          result.consumed,
+          context,
+        );
+        return;
+      }
+      const fallback = resolveKeybindingInput({
+        snapshot,
+        state: fallbackStateRef.current,
+        context: fallbackContext,
+        input,
+        key,
+        now: Date.now(),
+      });
+      fallbackStateRef.current = fallback.state;
+      handler(
+        fallback.actions as readonly TKeybindingAction<TFallback>[],
+        input,
+        key,
+        fallback.consumed,
+        fallbackContext,
+      );
+    },
+    { isActive: options.isActive ?? true },
+  );
+}

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

@@ -0,0 +1,189 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+
+import {
+  parseKeybindingsDocument,
+  type IKeybindingDiagnostic,
+  type IKeybindingSnapshot,
+} from './keybinding-registry.js';
+
+const RELOAD_DEBOUNCE_MS = 10;
+
+export interface IKeybindingsFilePort {
+  ensureFile(): Promise<string>;
+}
+
+export interface IKeybindingsSource extends IKeybindingsFilePort {
+  readonly filePath: string;
+  start(): Promise<void>;
+  isStarted(): boolean;
+  getSnapshot(): IKeybindingSnapshot;
+  subscribe(listener: (snapshot: IKeybindingSnapshot) => void): () => void;
+  dispose(): void;
+}
+
+export interface INodeKeybindingsSourceOptions {
+  readonly filePath: string;
+  readonly schemaUrl: string;
+  readonly onDiagnostic?: (diagnostic: IKeybindingDiagnostic) => void;
+}
+
+function defaultDocument(schemaUrl: string) {
+  return { $schema: schemaUrl, version: 1 as const, bindings: {} };
+}
+
+function defaultSnapshot(filePath: string, schemaUrl: string): IKeybindingSnapshot {
+  const parsed = parseKeybindingsDocument(JSON.stringify(defaultDocument(schemaUrl)), filePath);
+  if (!parsed.ok) throw new Error(parsed.diagnostic.message);
+  return parsed.snapshot;
+}
+
+class NodeKeybindingsSource implements IKeybindingsSource {
+  readonly filePath: string;
+  readonly #schemaUrl: string;
+  readonly #onDiagnostic: ((diagnostic: IKeybindingDiagnostic) => void) | undefined;
+  readonly #listeners = new Set<(snapshot: IKeybindingSnapshot) => void>();
+  #snapshot: IKeybindingSnapshot;
+  #watcher: FSWatcher | undefined;
+  #reloadTimer: ReturnType<typeof setTimeout> | undefined;
+  #startPromise: Promise<void> | undefined;
+  #disposed = false;
+
+  constructor(options: INodeKeybindingsSourceOptions) {
+    if (options.filePath.trim() === '') throw new Error('Keybindings file path must not be empty.');
+    if (options.schemaUrl.trim() === '') throw new Error('Keybindings schema URL must not be empty.');
+    this.filePath = options.filePath;
+    this.#schemaUrl = options.schemaUrl;
+    this.#onDiagnostic = options.onDiagnostic;
+    this.#snapshot = defaultSnapshot(this.filePath, this.#schemaUrl);
+  }
+
+  start(): Promise<void> {
+    if (this.#disposed) return Promise.reject(new Error('Keybindings source is disposed.'));
+    if (this.#startPromise !== undefined) return this.#startPromise;
+    this.#startPromise = this.#start().catch((cause) => {
+      this.#watcher?.close();
+      this.#watcher = undefined;
+      this.#startPromise = undefined;
+      throw cause;
+    });
+    return this.#startPromise;
+  }
+
+  async #start(): Promise<void> {
+    const directory = dirname(this.filePath);
+    await mkdir(directory, { recursive: true });
+    await this.#load();
+    if (this.#disposed) throw new Error('Keybindings source is disposed.');
+    this.#watcher = watch(directory, { persistent: false }, (_event, filename) => {
+      if (filename !== null && filename.toString() !== basename(this.filePath)) return;
+      this.#scheduleReload();
+    });
+  }
+
+  isStarted(): boolean {
+    return this.#watcher !== undefined && !this.#disposed;
+  }
+
+  getSnapshot(): IKeybindingSnapshot {
+    return this.#snapshot;
+  }
+
+  subscribe(listener: (snapshot: IKeybindingSnapshot) => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  async ensureFile(): Promise<string> {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    try {
+      await writeFile(this.filePath, `${JSON.stringify(defaultDocument(this.#schemaUrl), null, 2)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+      });
+    } catch (cause) {
+      if (!isAlreadyExists(cause as object)) throw cause;
+    }
+    return this.filePath;
+  }
+
+  dispose(): void {
+    this.#disposed = true;
+    if (this.#reloadTimer !== undefined) clearTimeout(this.#reloadTimer);
+    this.#reloadTimer = undefined;
+    this.#watcher?.close();
+    this.#watcher = undefined;
+    this.#listeners.clear();
+  }
+
+  #scheduleReload(): void {
+    if (this.#disposed) return;
+    if (this.#reloadTimer !== undefined) clearTimeout(this.#reloadTimer);
+    this.#reloadTimer = setTimeout(() => {
+      this.#reloadTimer = undefined;
+      void this.#load();
+    }, RELOAD_DEBOUNCE_MS);
+  }
+
+  async #load(): Promise<void> {
+    let text: string;
+    try {
+      text = await readFile(this.filePath, 'utf8');
+    } catch (cause) {
+      if (isNotFound(cause as object)) return;
+      this.#publishInvalid({
+        file: this.filePath,
+        path: '$',
+        message: errorMessage(cause as object),
+      });
+      return;
+    }
+    const parsed = parseKeybindingsDocument(text, this.filePath);
+    if (!parsed.ok) {
+      this.#publishInvalid(parsed.diagnostic);
+      return;
+    }
+    this.#publish(Object.freeze({ ...parsed.snapshot, generation: this.#snapshot.generation + 1 }));
+  }
+
+  #publishInvalid(diagnostic: IKeybindingDiagnostic): void {
+    this.#onDiagnostic?.(diagnostic);
+    this.#publish(
+      Object.freeze({
+        ...this.#snapshot,
+        generation: this.#snapshot.generation + 1,
+        diagnostic,
+      }),
+    );
+  }
+
+  #publish(snapshot: IKeybindingSnapshot): void {
+    if (this.#disposed) return;
+    this.#snapshot = snapshot;
+    for (const listener of this.#listeners) listener(snapshot);
+  }
+}
+
+function isNotFound(cause: object): boolean {
+  return isNodeError(cause) && cause.code === 'ENOENT';
+}
+
+function isAlreadyExists(cause: object): boolean {
+  return isNodeError(cause) && cause.code === 'EEXIST';
+}
+
+function isNodeError(cause: object): cause is NodeJS.ErrnoException {
+  return cause instanceof Error && 'code' in cause;
+}
+
+function errorMessage(cause: object): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+export function createNodeKeybindingsSource(
+  options: INodeKeybindingsSourceOptions,
+): IKeybindingsSource {
+  return new NodeKeybindingsSource(options);
+}

package/src/numbered-list.tsx

@@ -0,0 +1,113 @@
+/**
+ * CLI-2004 — the numbered-list menu (SSOT for its grammar).
+ *
+ * Every arrow-key menu becomes this in screen-reader mode: `N. <option>` lines followed by one
+ * prompt naming the valid range. Arrow navigation and the `> ` cursor are position cues a reader
+ * cannot follow — a spoken "3" is unambiguous, and the range in the prompt is the affordance.
+ *
+ * The prompt LITERAL is authored here, not copied from any reference: the surveyed documentation
+ * publishes the prompt's NAME and the cancel suffix, never the composed string. This module is the
+ * one place it exists, so the menus cannot drift into per-component dialects — the same reason
+ * `key-hint-footer.tsx` owns the footer grammar.
+ *
+ * No colour props: the mode drops colour rather than substituting values, so the palette floor stays
+ * green and nothing here depends on a cue a reader cannot hear.
+ */
+
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+
+/** Appended to the prompt when Escape actually cancels the menu. */
+export const NUMBERED_LIST_CANCEL_SUFFIX = ' or Escape to cancel';
+
+/** The prompt literal. `Enter selection (1-3)`, plus the cancel suffix where it applies. */
+export function formatNumberedSelectionPrompt(itemCount: number, cancellable: boolean): string {
+  const base = `Enter selection (1-${itemCount})`;
+  return cancellable ? `${base}${NUMBERED_LIST_CANCEL_SUFFIX}` : base;
+}
+
+/** One row's number prefix: `1. `, `2. `, … */
+export function numberedRowPrefix(index: number): string {
+  return `${index + 1}. `;
+}
+
+export interface INumberedSelectionPromptProps {
+  /** How many rows the prompt names. Zero ⇒ nothing is rendered: `(1-0)` names no answer. */
+  itemCount: number;
+  cancellable?: boolean;
+  /** Digits typed so far, echoed after the prompt. */
+  buffer?: string;
+  /** The last entry was out of range ⇒ the same literal is re-printed. */
+  invalid?: boolean;
+}
+
+/**
+ * The prompt line, separated from `NumberedList` so a menu that renders its own rows — the
+ * checklist, whose rows carry a checkbox — asks its question in the same words rather than
+ * inventing a dialect.
+ */
+export function NumberedSelectionPrompt({
+  itemCount,
+  cancellable = false,
+  buffer = '',
+  invalid = false,
+}: INumberedSelectionPromptProps): React.ReactElement | null {
+  if (itemCount === 0) return null;
+  const prompt = formatNumberedSelectionPrompt(itemCount, cancellable);
+  return (
+    <>
+      <Text>
+        {prompt}
+        {buffer.length > 0 ? ` ${buffer}` : ''}
+      </Text>
+      {/* An out-of-range answer re-prints the SAME literal: the range is the correction. */}
+      {invalid && <Text>{prompt}</Text>}
+    </>
+  );
+}
+
+export interface INumberedListProps {
+  /** Heading line, e.g. the menu title or the permission question. */
+  title?: string;
+  /** Extra context line under the title. */
+  description?: string;
+  /** The selectable options, in order. */
+  options: readonly string[];
+  /** Escape cancels ⇒ the prompt says so. */
+  cancellable?: boolean;
+  /** Digits typed so far, echoed after the prompt. */
+  buffer?: string;
+  /** The last entry was out of range ⇒ the same literal is re-printed. */
+  invalid?: boolean;
+}
+
+/** Render the numbered list and its prompt. */
+export function NumberedList({
+  title,
+  description,
+  options,
+  cancellable = false,
+  buffer = '',
+  invalid = false,
+}: INumberedListProps): React.ReactElement {
+  return (
+    <Box flexDirection="column">
+      {title !== undefined && title.length > 0 && <Text>{title}</Text>}
+      {description !== undefined && description.length > 0 && <Text>{description}</Text>}
+      {options.map((option, index) => (
+        <Text key={`${index}-${option}`}>
+          {numberedRowPrefix(index)}
+          {option}
+        </Text>
+      ))}
+      <NumberedSelectionPrompt
+        itemCount={options.length}
+        cancellable={cancellable}
+        buffer={buffer}
+        invalid={invalid}
+      />
+    </Box>
+  );
+}