Add configurable keybindings via ~/.t3/keybindings.json

KEYBINDINGS.md

@@ -0,0 +1,95 @@
+# Keybindings
+
+T3 Code reads keybindings from:
+
+- `~/.t3/keybindings.json`
+
+The file must be a JSON array of rules:
+
+```json
+[
+  { "key": "mod+g", "command": "terminal.toggle" },
+  { "key": "mod+shift+g", "command": "terminal.new", "when": "terminalFocus" }
+]
+```
+
+See the full schema for more details: [`packages/contracts/src/keybindings.ts`](packages/contracts/src/keybindings.ts)
+
+## Defaults
+
+```json
+[
+  { "key": "mod+j", "command": "terminal.toggle" },
+  { "key": "mod+d", "command": "terminal.split", "when": "terminalFocus" },
+  { "key": "mod+n", "command": "terminal.new", "when": "terminalFocus" },
+  { "key": "mod+shift+o", "command": "chat.new" },
+  { "key": "mod+o", "command": "editor.openFavorite" }
+]
+```
+
+For most up to date defaults, see [`DEFAULT_KEYBINDINGS` in `apps/server/src/keybindings.ts`](apps/server/src/keybindings.ts)
+
+## Configuration
+
+### Rule Shape
+
+Each entry supports:
+
+- `key` (required): shortcut string, like `mod+j`, `ctrl+k`, `cmd+shift+d`
+- `command` (required): action ID
+- `when` (optional): boolean expression controlling when the shortcut is active
+
+Invalid rules are ignored. Invalid config files are ignored. Warnings are logged by the server.
+
+### Available Commands
+
+- `terminal.toggle`: open/close terminal drawer
+- `terminal.split`: split terminal (in focused terminal context by default)
+- `terminal.new`: create new terminal (in focused terminal context by default)
+- `chat.new`: create a new chat thread for the active project
+- `editor.openFavorite`: open current project/worktree in the last-used editor
+
+### Key Syntax
+
+Supported modifiers:
+
+- `mod` (`cmd` on macOS, `ctrl` on non-macOS)
+- `cmd` / `meta`
+- `ctrl` / `control`
+- `shift`
+- `alt` / `option`
+
+Examples:
+
+- `mod+j`
+- `mod+shift+d`
+- `ctrl+l`
+- `cmd+k`
+
+### `when` Conditions
+
+Currently available context keys:
+
+- `terminalFocus`
+- `terminalOpen`
+
+Supported operators:
+
+- `!` (not)
+- `&&` (and)
+- `||` (or)
+- parentheses: `(` `)`
+
+Examples:
+
+- `"when": "terminalFocus"`
+- `"when": "terminalOpen && !terminalFocus"`
+- `"when": "terminalFocus || terminalOpen"`
+
+Unknown condition keys evaluate to `false`.
+
+### Precedence
+
+- Rules are evaluated in array order.
+- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.
+- That means precedence is across commands, not only within the same command.

apps/server/src/keybindings.test.ts

@@ -0,0 +1,69 @@
+import { assert, describe, it } from "vitest";
+
+import { compileResolvedKeybindingRule, parseKeybindingShortcut } from "./keybindings";
+
+describe("server keybindings", () => {
+  it("parses shortcuts including plus key", () => {
+    assert.deepEqual(parseKeybindingShortcut("mod+j"), {
+      key: "j",
+      metaKey: false,
+      ctrlKey: false,
+      shiftKey: false,
+      altKey: false,
+      modKey: true,
+    });
+    assert.deepEqual(parseKeybindingShortcut("mod++"), {
+      key: "+",
+      metaKey: false,
+      ctrlKey: false,
+      shiftKey: false,
+      altKey: false,
+      modKey: true,
+    });
+  });
+
+  it("compiles valid rule with parsed when AST", () => {
+    const compiled = compileResolvedKeybindingRule({
+      key: "mod+d",
+      command: "terminal.split",
+      when: "terminalOpen && !terminalFocus",
+    });
+
+    assert.deepEqual(compiled, {
+      command: "terminal.split",
+      shortcut: {
+        key: "d",
+        metaKey: false,
+        ctrlKey: false,
+        shiftKey: false,
+        altKey: false,
+        modKey: true,
+      },
+      whenAst: {
+        type: "and",
+        left: { type: "identifier", name: "terminalOpen" },
+        right: {
+          type: "not",
+          node: { type: "identifier", name: "terminalFocus" },
+        },
+      },
+    });
+  });
+
+  it("rejects invalid rules", () => {
+    assert.isNull(
+      compileResolvedKeybindingRule({
+        key: "mod+shift+d+o",
+        command: "terminal.new",
+      }),
+    );
+
+    assert.isNull(
+      compileResolvedKeybindingRule({
+        key: "mod+d",
+        command: "terminal.split",
+        when: "terminalFocus && (",
+      }),
+    );
+  });
+});