Skip to content

feat: first-run permission setup wizard (0.6.3) - #21

Merged
chaodu-agent merged 1 commit into
mainfrom
feat/permission-setup-wizard
Sep 27, 2026
Merged

chaodu-agent merged 1 commit into
mainfrom
feat/permission-setup-wizard

Conversation

@chaodu-agent

Copy link
Copy Markdown
Contributor

Summary

First install still requires the human to grant macOS TCC permissions — that cannot and should not be bypassed. 0.6.3 makes the one-time process explicit and usable instead of leaving it in README text.

  • First launch with anything missing: auto-show once. Not Now is respected across launches and versions; fully-granted upgrades mark setup complete without a window.
  • Three capability cards: Screen & System Audio Recording (Screens/screenshot), Accessibility (mouse/key), Full Disk Access (protected Mail/Messages/Safari via exec/osascript). Each opens the exact System Settings pane.
  • Test Again; automatic one-shot refresh when returning from Settings. No timer, no screenshot, no prompting APIs — avoids the permission-popup storm recorded in oablab/oab-pty-mac#62.
  • Explicit browser-only copy: browser_* works without any of these grants.
  • Menu bar: permanent Set Up Permissions… plus live ✓/✗/? for all three.

Measurement

PermissionProbe is in Core and testable. Screen/AX use Apple's non-prompting preflight APIs. macOS has no FDA preflight API, so FDA is measured by actual open(O_RDONLY|O_CLOEXEC) + immediate close of an existing protected DB (user TCC.db, Safari History, Messages chat) — no bytes are read. Result is tri-state: granted / denied / unknown (no candidate exists). sys_info now exposes full_disk_access + state.

Verification

  • macmini: 97 tests, 0 failures; packaging smoke OK.
  • 9 new tests: FDA success stops at first open, all-denied, no-file unknown, exact protected paths, snapshot summary; first-run missing, Not Now, fully granted, unknown FDA policy.
  • Real GUI smoke via a separate test bundle/port on the logged-in desktop. It caught two bugs unit tests cannot (constraint activated before shared hierarchy; NSBox cards collapsed to zero height); both fixed. Final screenshot shows aligned 3-row mixed-state window.
  • Independent audit: no blocker; confirmed non-prompting APIs only, no polling, privacy-safe FDA probe, one callback per dismiss path, correct actor/lifecycle behavior.

Version

0.6.3. After merge, tag release uses the signed/notarized universal pkg pipeline proven by v0.6.2.

Add a one-time AppKit wizard for Screen Recording, Accessibility and Full Disk Access. It opens the exact System Settings pane, re-tests only on explicit Test Again or app activation, and explains that browser-only use needs none — no automated grant, screenshot, prompt, or polling loop. Not Now is respected across launches/versions; the menu bar keeps Set Up Permissions permanently available and shows live ✓/✗/? rows including FDA.

PermissionProbe lives in Core with tri-state results: Apple preflight APIs for screen/AX and an actual O_RDONLY|O_CLOEXEC open+immediate close of protected TCC/Safari/Messages databases for FDA (no content read), with injected seams. Sys_info and startup logs now include FDA.

9 new tests cover FDA granted/denied/unknown/path logic and every auto-show policy branch (97 total). Real GUI smoke on macmini caught and fixed two AppKit layout faults; final screenshot verifies aligned mixed-state rows. Packaging smoke passes. Version 0.6.3.
@chaodu-agent
chaodu-agent merged commit a27cf64 into main Sep 27, 2026
4 checks passed
@chaodu-agent
chaodu-agent deleted the feat/permission-setup-wizard branch September 27, 2026 14:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant