james.maesandClaude Opus 4.7
508cf924d0
Adds README.md to each of the 13 SPM packages (AgentCore, Bus, Config, DevOverlay, Harness, Keychain, Logging, MCP, Memory, Replay, Shell, Vision, Voice). Each covers purpose, key public types, deps, consumers, invariants (pulled from CLAUDE.md + grep-gates + audit findings), test stack, and notable files. Memory README explicitly marks the package functionally OFF until vec0.dylib + Ollama models land. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
44 lines
2.0 KiB
Markdown
44 lines
2.0 KiB
Markdown
# Shell
|
|
|
|
OS-touch primitives: global hotkeys, Input Monitoring TCC handling, launch-at-login, the SwiftUI shortcut recorder.
|
|
|
|
## Key public types
|
|
|
|
| Type | Purpose |
|
|
|------|---------|
|
|
| `HotkeyBinder` | Wraps `NSEvent.addGlobalMonitorForEvents` (preferred over Carbon `RegisterEventHotKey`) |
|
|
| `KeyboardShortcut` | Typed shortcut model (modifiers + keyCode) |
|
|
| `InputMonitoringProbe` | Calls `IOHIDRequestAccess(kIOHIDRequestTypeListenEvent)` to detect silent-no-op denial |
|
|
| `HIDAccessProbe` (protocol) | Test seam |
|
|
| `TCCAlertService` | HUD banner + System Settings deep-link on Input Monitoring denial |
|
|
| `LaunchAtLoginController` | Wraps `SMAppService.mainApp` |
|
|
| `ShortcutRecorder` (SwiftUI) | First-launch shortcut binder |
|
|
| `CollisionDetector` | Detects shortcuts that collide with Chrome/Slack/VSCode/Alfred/Raycast |
|
|
|
|
## Depends on
|
|
|
|
`Config`, `Logging`. External: `swift-log`.
|
|
|
|
## Used by
|
|
|
|
`App/AppDelegate`, `App/Wizard/` (first-launch shortcut binding flow).
|
|
|
|
## Key invariants / contracts
|
|
|
|
- **`NSEvent.addGlobalMonitorForEvents` over Carbon `RegisterEventHotKey`.** Fewer TCC surfaces; no full-process key-read risk.
|
|
- **Global monitor silently no-ops on Input Monitoring denial.** `InputMonitoringProbe` detects this and surfaces a banner; degraded mode falls back to local-monitor-only.
|
|
- **Hotkey ships unset.** First launch routes through `ShortcutRecorder`. Cmd+Shift+J / Option+Space collide with common apps; `CollisionDetector` warns.
|
|
- **`HIDAccessProbe` test seam protocol.** Production = `RealHIDAccessProbe`; tests = `MockHIDAccessProbe`.
|
|
|
|
## Tests
|
|
|
|
XCTest + swift-testing. Hotkey binding fixtures, Input Monitoring denial paths (`InputMonitoringDenialTests`), shortcut collision detection.
|
|
|
|
## Notable files
|
|
|
|
- `Sources/Shell/HotkeyBinder.swift` — global hotkey wrapper
|
|
- `Sources/Shell/InputMonitoringProbe.swift` — TCC denial probe
|
|
- `Sources/Shell/TCCAlertService.swift` — banner + deep-link
|
|
- `Sources/Shell/ShortcutRecorder/` — SwiftUI shortcut binder
|
|
- `Sources/Shell/LaunchAtLoginController.swift` — `SMAppService` wrapper
|