Normalize minus key sequences and return 400 for invalid keys

[masnwilliams]

summary

• normalize literal hyphens in key combinations to the X11 minus keysym
• classify xdotool key-conversion failures as client validation errors
• document punctuation key syntax

why

Agents commonly express zoom-out as Ctrl+-. xdotool requires Ctrl+minus, and treating that mismatch as an internal error causes SDKs to retry a deterministic invalid request.

testing

• go vet ./...
• go test -race $(go list ./... | grep -v /e2e$)

---

Note

Low Risk
Localized to press-key input normalization and error mapping; behavior change is more correct client errors and accepting Ctrl+- aliases.

Overview
Press key handling now accepts common shorthand like Ctrl+- by normalizing hyphen segments to xdotool’s minus keysym (with whitespace trimmed around +), for both keys and hold_keys.

When xdotool rejects a key sequence (Invalid key sequence / Failure converting key sequence), the API returns a 400 validation error instead of 500, so clients won’t retry deterministic bad input. OpenAPI docs describe punctuation keys (Ctrl+minus, Ctrl+- alias). Unit tests cover normalization and error classification.

^{Reviewed by Cursor Bugbot for commit 15d375f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[rgarcia]

reviewed — the change itself is safe for existing callers (everything the normalizer rewrites was already a hard xdotool error, and both matched error strings only come from xdotool's forbidden-character check, so they're input-deterministic). requesting changes for the generated spec drift; the rest is optional.

suggestions

• server/openapi.yaml:6616 — openapi-3.0.yaml and the embedded spec in lib/oapi/oapi.go weren't regenerated; GetSwagger() on this branch still serves the old keys description. run make oapi-generate and commit
• server/cmd/api/api/computer.go:40 — Ctrl++ (zoom in) isn't handled. xdotool drops empty tokens, so it exits 0 and silently presses only Ctrl. consider mapping a trailing empty segment to plus for symmetry with Ctrl+-

questions

• server/cmd/api/api/computer.go:52 — unknown keysyms (ctrl+wat) still return 200 since xdotool prints No such key name ... Ignoring it. and exits 0. fine, just noting the 400 only covers forbidden punctuation, not all invalid keys

nits

• server/cmd/api/api/computer.go:178,287 — hold_keys on click_mouse / move_mouse aren't normalized; optional consistency
• server/cmd/api/api/computer_test.go:173 — add "-": "minus" and "Ctrl++": "Ctrl++" cases to pin the split/join edges
• server/cmd/api/api/computer_test.go:195 — fixtures use ctrl+wat, which xdotool wouldn't actually reject; ctrl+- is the realistic example

[masnwilliams]

addressed the required generated-spec drift in b4e3911: regenerated the downconverted spec and committed the updated lib/oapi/oapi.go, then confirmed GetSwagger() serves the new key description. (openapi-3.0.yaml remains untracked because it is intentionally gitignored as an intermediate.)

also added the bare-minus and unchanged Ctrl++ edge cases and switched the classification fixtures to realistic ctrl+- output. keeping plus normalization and click/move hold_keys normalization out of this PR so the runtime alias remains minus-only; unknown keysyms remain unchanged as noted.

[rgarcia]

approving — verified on b4e3911:

• lib/oapi/oapi.go regenerated; GetSwagger() now serves the new keys description (checked by loading the embedded spec in a test)
• openapi-3.0.yaml is gitignored as an intermediate, so no drift there — my earlier note was wrong on that file
• go test ./cmd/api/api/ and go vet pass locally; Bugbot and CI green on the new commit
• minus-only scope is fine; Ctrl++ can be a follow-up if agents hit it

[masnwilliams]

rebased onto main at 3469a2d. the WebMCP PRs that landed since (#365, #367) regenerated the same embedded spec, so server/lib/oapi/oapi.go conflicted; I regenerated it on top of current main rather than hand-merging. the only non-blob delta versus main is the two new keys description lines, and GetSwagger() still serves the new description.

go vet ./... and the cmd/api/api + lib/oapi tests pass with -race. no behavior change from your approved commit — re-requesting since the force-push dismissed the approval.

[rgarcia]

re-approving on 41a73e8 — confirmed the rebase is clean:

• git diff origin/main...HEAD outside oapi.go is byte-identical to the commit I approved
• oapi.go non-blob delta vs main is only the two keys comment lines; GetSwagger() serves the new description
• go test -race ./cmd/api/api/, go vet, Bugbot and CI green on the new head