catsona/macoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
macoc/docs/reviews/2026-10-25-code-review.md

2.8 KiB
Raw Blame History

Capswitch code review — 2026-10-25

Scope

Review of the already-working Caps->F19 HID remapping, Quartz event tap, TIS input source switching, menu bar lifecycle, installer and login setup.

Findings and changes

  1. High: no stable installation path. Launching a bundle in build/ makes privacy permissions and login registration fragile. Added a user-scoped installer to ~/Applications with staged copying, identity validation and safeguards against replacing a different or running application.
  2. High: unsafe restart could strand a remapped Caps. Restart restores the physical key first, refuses to exit if restoration fails, launches a new copy of the same executable and waits for the previous PID to disappear before creating AppKit, the event tap or HID manager.
  3. Medium: no native login management. SMAppService.mainApp now provides a user-toggleable Launch at Login status with approval guidance in Settings.
  4. Medium: InputSourceManager and HID event-tap concerns were co-located. Extracted the input source adapter without changing the proven event path.
  5. Medium: startup argument parsing embedded in main. Added an independent LaunchArguments core type and tests for doctor, install and wait-for-PID.
  6. Medium: distribution required manual copying. Taskfile now provides an install task that packages and starts the installed copy without sudo.

Protected behavior

The existing HID IOHIDServiceClientSetProperty and CoreGraphics CGEventTap approach is hardware-verified on macOS 14.8.9. The normal Caps->F19 event path and Option+Caps gesture state machine are deliberately unchanged.

Remaining verification

  • SMAppService status/registration for ad-hoc signed apps and user Applications on this particular macOS Sonoma machine.
  • Restart of a copy launched via its signed bundle executable must be checked for macOS privacy identity continuity.
  • Staged app replacement rolls back ordinary filesystem errors but a power interruption between filesystem moves can leave a backup copy.
  • HID ownership persistence failure handling needs independent runtime tests.
  • Enabled input source ordering uses HIToolbox preferences. Preserve the current working behavior unless a future acceptance test demonstrates a bug.

On-Mac acceptance

  1. Quit the old app and run task test, task install.
  2. Confirm the launched bundle resides in ~/Applications.
  3. Verify the rapid Caps typing test still passes.
  4. Restart via menu; only one status item and running process remains.
  5. Verify Caps+Option and Pause/Quit restore normal Caps.
  6. Toggle Launch at Login on, approve when required, log out/in to verify.
  7. Toggle Launch at Login off, log out/in to verify it stays off.
  8. Reinstall an updated development build after closing the installed app.
  9. Confirm other pre-existing HID mappings survive every path.