keybindings ux improvments

[juliusmarminge]

Note

Medium Risk
Adds filesystem watching and new WS payload fields for keybindings config validation issues; changes affect server startup/config loading and client push handling, with moderate risk of missed updates or noisy notifications across platforms.

Overview
Keybindings config loading is refactored to return a runtime KeybindingsConfigState that includes non-fatal validation issues (malformed JSON vs invalid entries), while still falling back to defaults and not overwriting a bad file.

The server now watches keybindings.json for changes, revalidates, and pushes server.configUpdated events over WebSocket; server.getConfig/server.upsertKeybinding responses and contracts are extended to include an issues array.

The web app subscribes to server.configUpdated, invalidates cached config queries, and shows success/warning toasts (with an action to open keybindings.json in the user’s editor). Tests are expanded to cover malformed/partial configs, issue reporting, and the new push channel + caching behavior.

^{Written by Cursor Bugbot for commit 51dbea2. This will update automatically on new commits. Configure here.}

Note

Rework keybindings UX by adding Effect-based server config and WS schema, exposing Keybindings.upsertKeybindingRule over WebSocket, and wiring Settings UI to open keybindings.json

Refactor server to Effect services and schema-validated WebSocket protocol; add a server.configUpdated push and request/response schemas; implement a Keybindings service with atomic writes, issues reporting, and change stream; route serverGetConfig and serverUpsertKeybinding in apps/server/src/wsServer.ts; update web to acquire the API lazily, render settings showing the keybindings path, open the config via native editor, and validate project script keybindings; migrate terminal PTY selection and Node/Bun layers; replace Zod with Effect Schema across contracts and tests; introduce orchestration engine, projections, and snapshot syncing to drive UI state.

📍Where to Start

Start with the WebSocket server routing and pushes in apps/server/src/wsServer.ts, then review the Keybindings service in apps/server/src/keybindings.ts and the web settings integration in apps/web/src/routes/_chat.settings.tsx.

📊 Macroscope summarized 51dbea2. 5 files reviewed, 4 issues evaluated, 1 issue filtered, 0 comments posted

🗂️ Filtered Issues

apps/server/src/keybindings.ts — 0 comments posted, 2 evaluated, 1 filtered

• line 812: The upsertKeybindingRule operation causes data loss by silently permanently deleting any existing invalid or malformed entries in the configuration file. The loadWritableCustomKeybindingsConfig function (used by upsertKeybindingRule) iterates over the raw configuration and filters out any entries that fail KeybindingRule or ResolvedKeybindingFromConfig validation, returning only the valid subset. upsertKeybindingRule then takes this filtered subset, adds the new rule, and overwrites the configuration file on disk via writeConfigAtomically. Consequently, if a user has a syntax error or an invalid property in one rule, adding a new rule via the application will wipe the invalid rule from the file instead of preserving it. [ Out of scope ]

Summary by CodeRabbit

Release Notes

New Features

• Configuration validation now detects malformed keybindings and invalid entries, reporting issues with detailed messages
• Real-time notifications alert you when keybindings are updated or contain problems
• In-app toast messages display configuration issues with a quick-access button to edit the keybindings file

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 79b8fd7 and 51dbea2.

📒 Files selected for processing (9)

• apps/server/src/keybindings.test.ts
• apps/server/src/keybindings.ts
• apps/server/src/wsServer.test.ts
• apps/server/src/wsServer.ts
• apps/web/src/routes/__root.tsx
• apps/web/src/wsNativeApi.test.ts
• apps/web/src/wsNativeApi.ts
• packages/contracts/src/server.ts
• packages/contracts/src/ws.ts

---

Walkthrough

The changes introduce a keybindings configuration validation and state management system. The keybindings module now exposes loadConfigState, validates configurations at runtime, tracks issues as non-fatal state, emits changes via PubSub, and watches for file modifications. The WebSocket server extends its API to include an issues field and broadcasts config updates. The web client subscribes to these updates, deduplicates payloads, and displays notifications to users.

Changes

Cohort / File(s)	Summary
Keybindings Configuration & Validation apps/server/src/keybindings.ts, apps/server/src/keybindings.test.ts	Introduced keybindings state model (KeybindingsConfigState) with non-fatal issue tracking. Replaced loadResolvedKeybindingsConfig with loadConfigState. Added file watching, runtime validation with issue accumulation, and PubSub-based change notifications. Updated tests to verify malformed configs, invalid entries, and state transitions.
WebSocket Server API apps/server/src/wsServer.ts, apps/server/src/wsServer.test.ts	Extended serverGetConfig and serverUpsertKeybinding responses to include issues field. Introduced broadcastPush helper to centralize push encoding and client transmission. Updated subscription wiring for serverConfigUpdated events. Added comprehensive tests for malformed configs, file watching, and config change notifications.
Web Client Config Handler apps/web/src/routes/__root.tsx	Added onServerConfigUpdated subscription handler with payload deduplication using signature-based tracking. Displays success toast on valid configs and warning toast with keybindings.json editor action on detected issues. Invalidates server config queries on updates.
Web Native API apps/web/src/wsNativeApi.ts, apps/web/src/wsNativeApi.test.ts	Introduced onServerConfigUpdated public API function with listener registration, cached payload replay for late subscribers, and error suppression. Added tests verifying caching, listener notification, and schema validation of incoming payloads.
Type Contracts & Schemas packages/contracts/src/server.ts, packages/contracts/src/ws.ts	Added schemas for KeybindingsMalformedConfigIssue, KeybindingsInvalidEntryIssue, ServerConfigIssue, and ServerConfigUpdatedPayload. Extended ServerConfig and ServerUpsertKeybindingResult with issues field. Added serverConfigUpdated channel to WS_CHANNELS.

Sequence Diagram

sequenceDiagram
    participant FileSystem
    participant Server as Keybindings Module
    participant PubSub
    participant WSServer as WebSocket Server
    participant Client as Web Client
    participant UI as Toast Manager

    FileSystem->>Server: File change detected
    activate Server
    Server->>Server: Validate config<br/>(decode entries,<br/>accumulate issues)
    Server->>Server: Update cache<br/>(KeybindingsConfigState)
    Server->>PubSub: Emit change event<br/>(issues)
    deactivate Server

    PubSub->>WSServer: Notify subscribers
    activate WSServer
    WSServer->>WSServer: Create serverConfigUpdated<br/>push (issues payload)
    WSServer->>Client: Broadcast to all clients
    deactivate WSServer

    activate Client
    Client->>Client: Receive update
    Client->>Client: Compute signature<br/>from issues
    Client->>Client: Deduplicate<br/>(compare with last)
    alt Issues detected
        Client->>UI: Show warning toast<br/>(issue message +<br/>editor action)
    else No issues
        Client->>UI: Show success toast<br/>(config reloaded)
    end
    Client->>Client: Invalidate queries
    deactivate Client

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codething/orchestration-engine

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Too many files changed for review. (265 files found, 100 file limit)

[macroscopeapp]

🟢 Low src/wsServer.ts:113

When a multi-byte UTF-8 character is split across array chunks, decoding each chunk individually corrupts the data. Consider concatenating all buffers first with Buffer.concat(), then decoding to UTF-8 once.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file apps/server/src/wsServer.ts around line 113:

When a multi-byte UTF-8 character is split across array chunks, decoding each chunk individually corrupts the data. Consider concatenating all buffers first with `Buffer.concat()`, then decoding to UTF-8 once.

Evidence trail:
apps/server/src/wsServer.ts lines 113-131 (commit REVIEWED_COMMIT): The `websocketRawToString` function handles `Array.isArray(raw)` by iterating over chunks and calling `Buffer.from(chunk).toString('utf8')` on each Uint8Array/ArrayBuffer individually (lines 121-127), then joining with `chunks.join('')` (line 130). This decodes each chunk separately before concatenation, which corrupts multi-byte UTF-8 characters split across chunk boundaries.