Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

13.6 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { DEFAULT_SETTINGS } from '@shared/types'
import { matchesShortcut, type ShortcutKeyEvent } from '@shared/shortcut'
import { terminalKeyAction } from '../terminal/terminal-config'
import { useSettings } from '../state/settings'
import {
  activeKeybindingOverrides, effectiveBindings, commandKeys, commandTooltip, chipFor,
  setKeybindingOverride, commandKeysFor, dictationBinding,
  terminalShortcutPolicy, terminalChordBubbles, noteTerminalCapture
} from './keybindingOverrides'

const setKb = (kb: unknown) =>
  useSettings.setState({ settings: { ...DEFAULT_SETTINGS, keybindings: kb as never } })

beforeEach(() => setKb(undefined))

describe('activeKeybindingOverrides', () => {
  it('absent key means no overrides, silently', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    expect(activeKeybindingOverrides()).toEqual({})
    expect(warn).not.toHaveBeenCalled()
    warn.mockRestore()
  })
  it('sanitizes and memoizes by reference, warning once per change', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    setKb({ 'node.newTerminal': ['Cmd+Shift+Y'], 'bogus.command': ['Cmd+X'] })
    const first = activeKeybindingOverrides()
    expect(first).toEqual({ 'node.newTerminal': ['Cmd+Shift+Y'] })
    expect(activeKeybindingOverrides()).toBe(first)
    expect(warn).toHaveBeenCalledTimes(1)
    warn.mockRestore()
  })
})

describe('effectiveBindings / commandKeys / commandTooltip', () => {
  it('defaults flow through when no override exists', () => {
    expect(effectiveBindings('app.commandPalette')).toEqual(['Cmd+K'])
  })
  it('an override replaces the default everywhere', () => {
    setKb({ 'panel.sessions': ['Cmd+Alt+L'] })
    expect(commandKeys('panel.sessions', true)).toEqual(['⌘', '⌥', 'L'])
    expect(commandTooltip('Sessions', 'panel.sessions', true)).toBe('Sessions (⌘⌥L)')
  })
  it('matches the legacy hintLabel formatting on both platforms for the defaults', () => {
    expect(commandTooltip('Sessions', 'panel.sessions', true)).toBe('Sessions (⌘⇧L)')
    expect(commandTooltip('Sessions', 'panel.sessions', false)).toBe('Sessions (Ctrl+Shift+L)')
  })
  it('resolves the defaults with the SAME platform it formats with', () => {
    // terminal.copySelection is the one command whose defaults differ per platform, so it is
    // the only case that can catch a commandKeys that resolves with isMacPlatform() (true in
    // node) while formatting for the caller's platform.
    expect(commandKeys('terminal.copySelection', true)).toEqual(['⌘', 'C'])
    expect(commandKeys('terminal.copySelection', false)).toEqual(['Ctrl', 'Shift', 'C'])
  })
  it('unbound commands render without a chord suffix', () => {
    expect(commandTooltip('Fit all', 'canvas.fitAll', true)).toBe('Fit all')
    expect(commandKeys('canvas.fitAll', true)).toEqual([])
  })
})

// The exact composition SourceControlPanel's commit textarea now runs on keydown. It replaced a
// lax `(e.metaKey || e.ctrlKey) && e.key === 'Enter'`, so the D-strict losses below are pinned
// here rather than asserted in prose: matching is EXACT on all four modifiers.
describe('the commit textarea matcher (scm.commit)', () => {
  const key = (over: Partial<ShortcutKeyEvent> = {}): ShortcutKeyEvent =>
    ({ metaKey: false, ctrlKey: false, shiftKey: false, altKey: false, key: 'Enter', ...over })
  const commits = (e: ShortcutKeyEvent, isMac: boolean) =>
    effectiveBindings('scm.commit').some((s) => matchesShortcut(e, s, isMac))

  it('commits on the platform chord', () => {
    expect(commits(key({ metaKey: true }), true)).toBe(true)
    expect(commits(key({ ctrlKey: true }), false)).toBe(true)
  })
  it('no longer commits on the OTHER platform primary (the named D-strict losses)', () => {
    expect(commits(key({ ctrlKey: true }), true)).toBe(false) // mac Ctrl+Enter
    expect(commits(key({ metaKey: true }), false)).toBe(false) // non-mac Meta+Enter
  })
  it('no longer commits with an extra modifier held on top', () => {
    expect(commits(key({ metaKey: true, shiftKey: true }), true)).toBe(false)
    expect(commits(key({ metaKey: true, altKey: true }), true)).toBe(false)
  })
  it('follows a remap, so the key agrees with the placeholder chip', () => {
    setKb({ 'scm.commit': ['Cmd+Shift+Enter'] })
    expect(commits(key({ metaKey: true }), true)).toBe(false)
    expect(commits(key({ metaKey: true, shiftKey: true }), true)).toBe(true)
    expect(chipFor('scm.commit', true)).toBe('⌘⇧Enter')
  })
  it('is inert when unbound — the placeholder drops its chord for the same reason', () => {
    setKb({ 'scm.commit': [] })
    expect(commits(key({ metaKey: true }), true)).toBe(false)
    expect(chipFor('scm.commit', true)).toBe('')
  })
  it('plain Enter never commits (it types a newline)', () => {
    expect(commits(key(), true)).toBe(false)
  })
})

describe('chipFor', () => {
  it('renders the bare chord the way each platform spells it', () => {
    expect(chipFor('app.commandPalette', true)).toBe('⌘K')
    expect(chipFor('app.commandPalette', false)).toBe('Ctrl+K')
  })
  it('follows a remap', () => {
    setKb({ 'app.commandPalette': ['Cmd+Shift+P'] })
    expect(chipFor('app.commandPalette', true)).toBe('⌘⇧P')
  })
  it('is empty for an unbound command, so callers can fall back', () => {
    expect(chipFor('canvas.fitAll', true)).toBe('')
  })
})

describe('setKeybindingOverride', () => {
  it('set, disable, and reset shape the map correctly', () => {
    setKeybindingOverride('node.newTerminal', ['Cmd+Shift+T'])
    expect(useSettings.getState().settings.keybindings).toEqual({
      'node.newTerminal': ['Cmd+Shift+T']
    })
    setKeybindingOverride('canvas.undo', [])
    expect(useSettings.getState().settings.keybindings?.['canvas.undo']).toEqual([])
    setKeybindingOverride('node.newTerminal', null)
    expect('node.newTerminal' in (useSettings.getState().settings.keybindings ?? {})).toBe(false)
  })
  it('mirrors speech.dictation into speech.shortcut, and reset restores the default mirror', () => {
    setKeybindingOverride('speech.dictation', ['Cmd+Alt+D'])
    expect(useSettings.getState().settings.speech.shortcut).toBe('Cmd+Alt+D')
    setKeybindingOverride('speech.dictation', null)
    expect(useSettings.getState().settings.speech.shortcut).toBe(DEFAULT_SETTINGS.speech.shortcut)
  })
})

// NODE ENV, deliberately: this file runs without jsdom (see the note on noteTerminalCapture), so
// only the SETTINGS side is asserted here — WHETHER a notice is raised (the policy gate, the
// once-ever ledger), never what it looks like.
//
// The other side is `components/ShortcutCaptureBanner.test.tsx` (jsdom): it dispatches
// 'nodeterm:shortcut-captured' ITSELF and asserts what the banner does with it — copy, replacement,
// the 12s clock, dismissal, and the two silent cases (unknown id, unbound command). Be precise
// about the seam: nothing presses `noteTerminalCapture`'s own `window.dispatchEvent` line, which is
// `typeof window` guarded and cannot run here. The two files meet at the event NAME and its
// `detail.commandId` shape, and that agreement is by convention, not by a test.
describe('terminalShortcutPolicy / noteTerminalCapture', () => {
  const seen = () => useSettings.getState().settings.seenShortcutCaptureNotices
  const setSettings = (patch: Record<string, unknown>) =>
    useSettings.setState({ settings: { ...DEFAULT_SETTINGS, ...patch } as never })

  it('normalizes the setting', () => {
    expect(terminalShortcutPolicy()).toBe('app-first')
    setSettings({ terminalShortcutPolicy: 'terminal-first' })
    expect(terminalShortcutPolicy()).toBe('terminal-first')
  })
  it('a hand-edited garbage policy reads as app-first, not as the raw value', () => {
    // settings.json is hand-editable, so the compile-time type is not a runtime guarantee —
    // and the unknown value must degrade to today's behavior, never to terminal-first.
    setSettings({ terminalShortcutPolicy: 'shell-first' })
    expect(terminalShortcutPolicy()).toBe('app-first')
  })
  it('notes a capture once, persists the id, and is silent under terminal-first', () => {
    noteTerminalCapture('app.commandPalette')
    noteTerminalCapture('app.commandPalette')
    expect(seen()).toEqual(['app.commandPalette'])
    setSettings({
      terminalShortcutPolicy: 'terminal-first',
      seenShortcutCaptureNotices: ['app.commandPalette']
    })
    noteTerminalCapture('canvas.undo')
    expect(seen()).toEqual(['app.commandPalette'])
  })
  it('appends to the ids already seen rather than replacing them', () => {
    setSettings({ seenShortcutCaptureNotices: ['app.settings'] })
    noteTerminalCapture('app.commandPalette')
    expect(seen()).toEqual(['app.settings', 'app.commandPalette'])
  })
  it('a hand-edited seenShortcutCaptureNotices of the wrong shape reads as empty', () => {
    // `.includes` on a string would answer TRUE for any substring of it, silently swallowing
    // the first notice; on a non-array it would throw inside a keydown handler.
    setSettings({ seenShortcutCaptureNotices: 'garbage' })
    noteTerminalCapture('app.commandPalette')
    expect(seen()).toEqual(['app.commandPalette'])
  })
  it('drops non-string entries from a hand-edited list instead of carrying them forward', () => {
    setSettings({ seenShortcutCaptureNotices: ['app.settings', 7, null] })
    noteTerminalCapture('app.commandPalette')
    expect(seen()).toEqual(['app.settings', 'app.commandPalette'])
  })
  it('does not throw with no window (the guard node-env dispatch depends on)', () => {
    expect(typeof window).toBe('undefined')
    expect(() => noteTerminalCapture('app.commandPalette')).not.toThrow()
  })
})

describe('commandKeysFor / dictationBinding', () => {
  it('lists every effective binding', () => {
    expect(commandKeysFor('canvas.deleteSelection', true)).toEqual([['Delete'], ['Backspace']])
    expect(commandKeysFor('canvas.fitAll', true)).toEqual([])
  })
  it('dictationBinding follows the override and reports disabled as empty', () => {
    expect(dictationBinding()).toBe('Cmd+Alt')
    setKeybindingOverride('speech.dictation', ['Cmd+Alt+D'])
    expect(dictationBinding()).toBe('Cmd+Alt+D')
    setKeybindingOverride('speech.dictation', [])
    expect(dictationBinding()).toBe('')
  })
})

describe('terminalChordBubbles', () => {
  // Platform-independent by construction: every case pins an explicit literal-Ctrl override, so
  // the assertions do not depend on which platform the test host reports.
  const bubbleEv = (p: Partial<ShortcutKeyEvent>): ShortcutKeyEvent => ({
    metaKey: false,
    ctrlKey: false,
    shiftKey: false,
    altKey: false,
    key: 'ArrowLeft',
    ...p
  })

  it('true for an allowInTerminal canvas command the dispatcher would claim', () => {
    setKb({ 'node.focusLeft': ['Ctrl+Shift+ArrowLeft'] })
    expect(
      terminalChordBubbles(bubbleEv({ ctrlKey: true, shiftKey: true, key: 'ArrowLeft' }), false)
    ).toBe(true)
  })

  it('false under terminal-first — the chord stays with the shell', () => {
    useSettings.setState({
      settings: {
        ...DEFAULT_SETTINGS,
        keybindings: { 'node.focusLeft': ['Ctrl+Shift+ArrowLeft'] } as never,
        terminalShortcutPolicy: 'terminal-first'
      }
    })
    expect(
      terminalChordBubbles(bubbleEv({ ctrlKey: true, shiftKey: true, key: 'ArrowLeft' }), false)
    ).toBe(false)
  })

  it('false over the kanban board for a canvas-scope command', () => {
    setKb({ 'node.focusLeft': ['Ctrl+Shift+ArrowLeft'] })
    expect(
      terminalChordBubbles(bubbleEv({ ctrlKey: true, shiftKey: true, key: 'ArrowLeft' }), true)
    ).toBe(false)
  })

  it('false for a terminal-scope command — its local listener owns the chord', () => {
    setKb({ 'terminal.find': ['Ctrl+Shift+F1'] })
    expect(
      terminalChordBubbles(bubbleEv({ ctrlKey: true, shiftKey: true, key: 'F1' }), false)
    ).toBe(false)
  })

  it('keeps Ctrl+W in xterm when main stands down for a focused terminal', () => {
    setKb({ 'node.close': ['Ctrl+W'] })
    const event = {
      ...bubbleEv({ ctrlKey: true, key: 'w' }),
      type: 'keydown',
      code: 'KeyW'
    }
    const bubbles = terminalChordBubbles(event, false)

    expect(bubbles).toBe(false)
    expect(terminalKeyAction(event, false, false, bubbles)).toBe('pass')
  })

  it('bubbles the markdown toggle out of a focused terminal (its window listener owns it)', () => {
    // The Server Edition's `onMarkdownToggle` is a window keydown listener; if xterm kept the
    // chord it would write \r and cancel the event, and ⌘M would be dead in every focused
    // terminal. On desktop main claims it above the page, so this never runs there under
    // app-first, and under terminal-first the resolver refuses it (next case).
    setKb({ 'node.toggleMarkdown': ['Ctrl+M'] })
    const event = { ...bubbleEv({ ctrlKey: true, key: 'm' }), type: 'keydown', code: 'KeyM' }
    const bubbles = terminalChordBubbles(event, false)
    expect(bubbles).toBe(true)
    expect(terminalKeyAction(event, false, false, bubbles)).toBe('bubble')
    // Over the board too: the card modal's terminal is a markdown-toggle target as well.
    expect(terminalChordBubbles(event, true)).toBe(true)
  })

  it('keeps the markdown toggle in xterm under terminal-first', () => {
    useSettings.setState({
      settings: {
        ...DEFAULT_SETTINGS,
        keybindings: { 'node.toggleMarkdown': ['Ctrl+M'] } as never,
        terminalShortcutPolicy: 'terminal-first'
      }
    })
    expect(terminalChordBubbles(bubbleEv({ ctrlKey: true, key: 'm' }), false)).toBe(false)
  })

  it('false for a chord nothing resolves', () => {
    setKb(undefined)
    expect(
      terminalChordBubbles(bubbleEv({ ctrlKey: true, shiftKey: true, key: 'F12' }), false)
    ).toBe(false)
  })
})