@xortex/xcode 3.0.0 → 3.0.2

package/keybindings/parser.ts

@@ -0,0 +1,203 @@
+import type {
+  Chord,
+  KeybindingBlock,
+  ParsedBinding,
+  ParsedKeystroke,
+} from './types.js'
+
+/**
+ * Parse a keystroke string like "ctrl+shift+k" into a ParsedKeystroke.
+ * Supports various modifier aliases (ctrl/control, alt/opt/option/meta,
+ * cmd/command/super/win).
+ */
+export function parseKeystroke(input: string): ParsedKeystroke {
+  const parts = input.split('+')
+  const keystroke: ParsedKeystroke = {
+    key: '',
+    ctrl: false,
+    alt: false,
+    shift: false,
+    meta: false,
+    super: false,
+  }
+  for (const part of parts) {
+    const lower = part.toLowerCase()
+    switch (lower) {
+      case 'ctrl':
+      case 'control':
+        keystroke.ctrl = true
+        break
+      case 'alt':
+      case 'opt':
+      case 'option':
+        keystroke.alt = true
+        break
+      case 'shift':
+        keystroke.shift = true
+        break
+      case 'meta':
+        keystroke.meta = true
+        break
+      case 'cmd':
+      case 'command':
+      case 'super':
+      case 'win':
+        keystroke.super = true
+        break
+      case 'esc':
+        keystroke.key = 'escape'
+        break
+      case 'return':
+        keystroke.key = 'enter'
+        break
+      case 'space':
+        keystroke.key = ' '
+        break
+      case '↑':
+        keystroke.key = 'up'
+        break
+      case '↓':
+        keystroke.key = 'down'
+        break
+      case '←':
+        keystroke.key = 'left'
+        break
+      case '→':
+        keystroke.key = 'right'
+        break
+      default:
+        keystroke.key = lower
+        break
+    }
+  }
+
+  return keystroke
+}
+
+/**
+ * Parse a chord string like "ctrl+k ctrl+s" into an array of ParsedKeystrokes.
+ */
+export function parseChord(input: string): Chord {
+  // A lone space character IS the space key binding, not a separator
+  if (input === ' ') return [parseKeystroke('space')]
+  return input.trim().split(/\s+/).map(parseKeystroke)
+}
+
+/**
+ * Convert a ParsedKeystroke to its canonical string representation for display.
+ */
+export function keystrokeToString(ks: ParsedKeystroke): string {
+  const parts: string[] = []
+  if (ks.ctrl) parts.push('ctrl')
+  if (ks.alt) parts.push('alt')
+  if (ks.shift) parts.push('shift')
+  if (ks.meta) parts.push('meta')
+  if (ks.super) parts.push('cmd')
+  // Use readable names for display
+  const displayKey = keyToDisplayName(ks.key)
+  parts.push(displayKey)
+  return parts.join('+')
+}
+
+/**
+ * Map internal key names to human-readable display names.
+ */
+function keyToDisplayName(key: string): string {
+  switch (key) {
+    case 'escape':
+      return 'Esc'
+    case ' ':
+      return 'Space'
+    case 'tab':
+      return 'tab'
+    case 'enter':
+      return 'Enter'
+    case 'backspace':
+      return 'Backspace'
+    case 'delete':
+      return 'Delete'
+    case 'up':
+      return '↑'
+    case 'down':
+      return '↓'
+    case 'left':
+      return '←'
+    case 'right':
+      return '→'
+    case 'pageup':
+      return 'PageUp'
+    case 'pagedown':
+      return 'PageDown'
+    case 'home':
+      return 'Home'
+    case 'end':
+      return 'End'
+    default:
+      return key
+  }
+}
+
+/**
+ * Convert a Chord to its canonical string representation for display.
+ */
+export function chordToString(chord: Chord): string {
+  return chord.map(keystrokeToString).join(' ')
+}
+
+/**
+ * Display platform type - a subset of Platform that we care about for display.
+ * WSL and unknown are treated as linux for display purposes.
+ */
+type DisplayPlatform = 'macos' | 'windows' | 'linux' | 'wsl' | 'unknown'
+
+/**
+ * Convert a ParsedKeystroke to a platform-appropriate display string.
+ * Uses "opt" for alt on macOS, "alt" elsewhere.
+ */
+export function keystrokeToDisplayString(
+  ks: ParsedKeystroke,
+  platform: DisplayPlatform = 'linux',
+): string {
+  const parts: string[] = []
+  if (ks.ctrl) parts.push('ctrl')
+  // Alt/meta are equivalent in terminals, show platform-appropriate name
+  if (ks.alt || ks.meta) {
+    // Only macOS uses "opt", all other platforms use "alt"
+    parts.push(platform === 'macos' ? 'opt' : 'alt')
+  }
+  if (ks.shift) parts.push('shift')
+  if (ks.super) {
+    parts.push(platform === 'macos' ? 'cmd' : 'super')
+  }
+  // Use readable names for display
+  const displayKey = keyToDisplayName(ks.key)
+  parts.push(displayKey)
+  return parts.join('+')
+}
+
+/**
+ * Convert a Chord to a platform-appropriate display string.
+ */
+export function chordToDisplayString(
+  chord: Chord,
+  platform: DisplayPlatform = 'linux',
+): string {
+  return chord.map(ks => keystrokeToDisplayString(ks, platform)).join(' ')
+}
+
+/**
+ * Parse keybinding blocks (from JSON config) into a flat list of ParsedBindings.
+ */
+export function parseBindings(blocks: KeybindingBlock[]): ParsedBinding[] {
+  const bindings: ParsedBinding[] = []
+  for (const block of blocks) {
+    for (const [key, action] of Object.entries(block.bindings)) {
+      bindings.push({
+        chord: parseChord(key),
+        action,
+        context: block.context,
+      })
+    }
+  }
+  return bindings
+}

package/keybindings/reservedShortcuts.ts

@@ -0,0 +1,127 @@
+import { getPlatform } from '../utils/platform.js'
+
+/**
+ * Shortcuts that are typically intercepted by the OS, terminal, or shell
+ * and will likely never reach the application.
+ */
+export type ReservedShortcut = {
+  key: string
+  reason: string
+  severity: 'error' | 'warning'
+}
+
+/**
+ * Shortcuts that cannot be rebound - they are hardcoded in Claude Code.
+ */
+export const NON_REBINDABLE: ReservedShortcut[] = [
+  {
+    key: 'ctrl+c',
+    reason: 'Cannot be rebound - used for interrupt/exit (hardcoded)',
+    severity: 'error',
+  },
+  {
+    key: 'ctrl+d',
+    reason: 'Cannot be rebound - used for exit (hardcoded)',
+    severity: 'error',
+  },
+  {
+    key: 'ctrl+m',
+    reason:
+      'Cannot be rebound - identical to Enter in terminals (both send CR)',
+    severity: 'error',
+  },
+]
+
+/**
+ * Terminal control shortcuts that are intercepted by the terminal/OS.
+ * These will likely never reach the application.
+ *
+ * Note: ctrl+s (XOFF) and ctrl+q (XON) are NOT included here because:
+ * - Most modern terminals disable flow control by default
+ * - We use ctrl+s for the stash feature
+ */
+export const TERMINAL_RESERVED: ReservedShortcut[] = [
+  {
+    key: 'ctrl+z',
+    reason: 'Unix process suspend (SIGTSTP)',
+    severity: 'warning',
+  },
+  {
+    key: 'ctrl+\\',
+    reason: 'Terminal quit signal (SIGQUIT)',
+    severity: 'error',
+  },
+]
+
+/**
+ * macOS-specific shortcuts that the OS intercepts.
+ */
+export const MACOS_RESERVED: ReservedShortcut[] = [
+  { key: 'cmd+c', reason: 'macOS system copy', severity: 'error' },
+  { key: 'cmd+v', reason: 'macOS system paste', severity: 'error' },
+  { key: 'cmd+x', reason: 'macOS system cut', severity: 'error' },
+  { key: 'cmd+q', reason: 'macOS quit application', severity: 'error' },
+  { key: 'cmd+w', reason: 'macOS close window/tab', severity: 'error' },
+  { key: 'cmd+tab', reason: 'macOS app switcher', severity: 'error' },
+  { key: 'cmd+space', reason: 'macOS Spotlight', severity: 'error' },
+]
+
+/**
+ * Get all reserved shortcuts for the current platform.
+ * Includes non-rebindable shortcuts and terminal-reserved shortcuts.
+ */
+export function getReservedShortcuts(): ReservedShortcut[] {
+  const platform = getPlatform()
+  // Non-rebindable shortcuts first (highest priority)
+  const reserved = [...NON_REBINDABLE, ...TERMINAL_RESERVED]
+
+  if (platform === 'macos') {
+    reserved.push(...MACOS_RESERVED)
+  }
+
+  return reserved
+}
+
+/**
+ * Normalize a key string for comparison (lowercase, sorted modifiers).
+ * Chords (space-separated steps like "ctrl+x ctrl+b") are normalized
+ * per-step — splitting on '+' first would mangle "x ctrl" into a mainKey
+ * overwritten by the next step, collapsing the chord into its last key.
+ */
+export function normalizeKeyForComparison(key: string): string {
+  return key.trim().split(/\s+/).map(normalizeStep).join(' ')
+}
+
+function normalizeStep(step: string): string {
+  const parts = step.split('+')
+  const modifiers: string[] = []
+  let mainKey = ''
+
+  for (const part of parts) {
+    const lower = part.trim().toLowerCase()
+    if (
+      [
+        'ctrl',
+        'control',
+        'alt',
+        'opt',
+        'option',
+        'meta',
+        'cmd',
+        'command',
+        'shift',
+      ].includes(lower)
+    ) {
+      // Normalize modifier names
+      if (lower === 'control') modifiers.push('ctrl')
+      else if (lower === 'option' || lower === 'opt') modifiers.push('alt')
+      else if (lower === 'command' || lower === 'cmd') modifiers.push('cmd')
+      else modifiers.push(lower)
+    } else {
+      mainKey = lower
+    }
+  }
+
+  modifiers.sort()
+  return [...modifiers, mainKey].join('+')
+}

package/keybindings/resolver.ts

@@ -0,0 +1,244 @@
+import type { Key } from '../ink.js'
+import { getKeyName, matchesBinding } from './match.js'
+import { chordToString } from './parser.js'
+import type {
+  KeybindingContextName,
+  ParsedBinding,
+  ParsedKeystroke,
+} from './types.js'
+
+export type ResolveResult =
+  | { type: 'match'; action: string }
+  | { type: 'none' }
+  | { type: 'unbound' }
+
+export type ChordResolveResult =
+  | { type: 'match'; action: string }
+  | { type: 'none' }
+  | { type: 'unbound' }
+  | { type: 'chord_started'; pending: ParsedKeystroke[] }
+  | { type: 'chord_cancelled' }
+
+/**
+ * Resolve a key input to an action.
+ * Pure function - no state, no side effects, just matching logic.
+ *
+ * @param input - The character input from Ink
+ * @param key - The Key object from Ink with modifier flags
+ * @param activeContexts - Array of currently active contexts (e.g., ['Chat', 'Global'])
+ * @param bindings - All parsed bindings to search through
+ * @returns The resolution result
+ */
+export function resolveKey(
+  input: string,
+  key: Key,
+  activeContexts: KeybindingContextName[],
+  bindings: ParsedBinding[],
+): ResolveResult {
+  // Find matching bindings (last one wins for user overrides)
+  let match: ParsedBinding | undefined
+  const ctxSet = new Set(activeContexts)
+
+  for (const binding of bindings) {
+    // Phase 1: Only single-keystroke bindings
+    if (binding.chord.length !== 1) continue
+    if (!ctxSet.has(binding.context)) continue
+
+    if (matchesBinding(input, key, binding)) {
+      match = binding
+    }
+  }
+
+  if (!match) {
+    return { type: 'none' }
+  }
+
+  if (match.action === null) {
+    return { type: 'unbound' }
+  }
+
+  return { type: 'match', action: match.action }
+}
+
+/**
+ * Get display text for an action from bindings (e.g., "ctrl+t" for "app:toggleTodos").
+ * Searches in reverse order so user overrides take precedence.
+ */
+export function getBindingDisplayText(
+  action: string,
+  context: KeybindingContextName,
+  bindings: ParsedBinding[],
+): string | undefined {
+  // Find the last binding for this action in this context
+  const binding = bindings.findLast(
+    b => b.action === action && b.context === context,
+  )
+  return binding ? chordToString(binding.chord) : undefined
+}
+
+/**
+ * Build a ParsedKeystroke from Ink's input/key.
+ */
+function buildKeystroke(input: string, key: Key): ParsedKeystroke | null {
+  const keyName = getKeyName(input, key)
+  if (!keyName) return null
+
+  // QUIRK: Ink sets key.meta=true when escape is pressed (see input-event.ts).
+  // This is legacy terminal behavior - we should NOT record this as a modifier
+  // for the escape key itself, otherwise chord matching will fail.
+  const effectiveMeta = key.escape ? false : key.meta
+
+  return {
+    key: keyName,
+    ctrl: key.ctrl,
+    alt: effectiveMeta,
+    shift: key.shift,
+    meta: effectiveMeta,
+    super: key.super,
+  }
+}
+
+/**
+ * Compare two ParsedKeystrokes for equality. Collapses alt/meta into
+ * one logical modifier — legacy terminals can't distinguish them (see
+ * match.ts modifiersMatch), so "alt+k" and "meta+k" are the same key.
+ * Super (cmd/win) is distinct — only arrives via kitty keyboard protocol.
+ */
+export function keystrokesEqual(
+  a: ParsedKeystroke,
+  b: ParsedKeystroke,
+): boolean {
+  return (
+    a.key === b.key &&
+    a.ctrl === b.ctrl &&
+    a.shift === b.shift &&
+    (a.alt || a.meta) === (b.alt || b.meta) &&
+    a.super === b.super
+  )
+}
+
+/**
+ * Check if a chord prefix matches the beginning of a binding's chord.
+ */
+function chordPrefixMatches(
+  prefix: ParsedKeystroke[],
+  binding: ParsedBinding,
+): boolean {
+  if (prefix.length >= binding.chord.length) return false
+  for (let i = 0; i < prefix.length; i++) {
+    const prefixKey = prefix[i]
+    const bindingKey = binding.chord[i]
+    if (!prefixKey || !bindingKey) return false
+    if (!keystrokesEqual(prefixKey, bindingKey)) return false
+  }
+  return true
+}
+
+/**
+ * Check if a full chord matches a binding's chord.
+ */
+function chordExactlyMatches(
+  chord: ParsedKeystroke[],
+  binding: ParsedBinding,
+): boolean {
+  if (chord.length !== binding.chord.length) return false
+  for (let i = 0; i < chord.length; i++) {
+    const chordKey = chord[i]
+    const bindingKey = binding.chord[i]
+    if (!chordKey || !bindingKey) return false
+    if (!keystrokesEqual(chordKey, bindingKey)) return false
+  }
+  return true
+}
+
+/**
+ * Resolve a key with chord state support.
+ *
+ * This function handles multi-keystroke chord bindings like "ctrl+k ctrl+s".
+ *
+ * @param input - The character input from Ink
+ * @param key - The Key object from Ink with modifier flags
+ * @param activeContexts - Array of currently active contexts
+ * @param bindings - All parsed bindings
+ * @param pending - Current chord state (null if not in a chord)
+ * @returns Resolution result with chord state
+ */
+export function resolveKeyWithChordState(
+  input: string,
+  key: Key,
+  activeContexts: KeybindingContextName[],
+  bindings: ParsedBinding[],
+  pending: ParsedKeystroke[] | null,
+): ChordResolveResult {
+  // Cancel chord on escape
+  if (key.escape && pending !== null) {
+    return { type: 'chord_cancelled' }
+  }
+
+  // Build current keystroke
+  const currentKeystroke = buildKeystroke(input, key)
+  if (!currentKeystroke) {
+    if (pending !== null) {
+      return { type: 'chord_cancelled' }
+    }
+    return { type: 'none' }
+  }
+
+  // Build the full chord sequence to test
+  const testChord = pending
+    ? [...pending, currentKeystroke]
+    : [currentKeystroke]
+
+  // Filter bindings by active contexts (Set lookup: O(n) instead of O(n·m))
+  const ctxSet = new Set(activeContexts)
+  const contextBindings = bindings.filter(b => ctxSet.has(b.context))
+
+  // Check if this could be a prefix for longer chords. Group by chord
+  // string so a later null-override shadows the default it unbinds —
+  // otherwise null-unbinding `ctrl+x ctrl+k` still makes `ctrl+x` enter
+  // chord-wait and the single-key binding on the prefix never fires.
+  const chordWinners = new Map<string, string | null>()
+  for (const binding of contextBindings) {
+    if (
+      binding.chord.length > testChord.length &&
+      chordPrefixMatches(testChord, binding)
+    ) {
+      chordWinners.set(chordToString(binding.chord), binding.action)
+    }
+  }
+  let hasLongerChords = false
+  for (const action of chordWinners.values()) {
+    if (action !== null) {
+      hasLongerChords = true
+      break
+    }
+  }
+
+  // If this keystroke could start a longer chord, prefer that
+  // (even if there's an exact single-key match)
+  if (hasLongerChords) {
+    return { type: 'chord_started', pending: testChord }
+  }
+
+  // Check for exact matches (last one wins)
+  let exactMatch: ParsedBinding | undefined
+  for (const binding of contextBindings) {
+    if (chordExactlyMatches(testChord, binding)) {
+      exactMatch = binding
+    }
+  }
+
+  if (exactMatch) {
+    if (exactMatch.action === null) {
+      return { type: 'unbound' }
+    }
+    return { type: 'match', action: exactMatch.action }
+  }
+
+  // No match and no potential longer chords
+  if (pending !== null) {
+    return { type: 'chord_cancelled' }
+  }
+
+  return { type: 'none' }
+}