feat(generators): add curated macOS preferences generator

[wgordon17]

Summary

• Curated 7-domain preferences generator (dock, Finder, screensaver, trackpad, keyboard shortcuts/text replacements, battery/power, wallpaper) rendering all four classification tiers, plus the generate_all()/mac2nix generate CLI foundation scoped to the preferences domain
• Fixes a real, previously-undiscovered gap found while building this PR's own VM test: mac2nix has never shipped its own flake.nix, so Validator's VM-based re-scan mechanism (used by both mac2nix validate and this PR's nix_vm test) could never actually run nix run ... -- scan inside a VM
• Verified with a real nix build against the assembled flake and a real Tart-VM apply-and-verify run (nix run nix-darwin -- switch, confirmed the generated dock.tilesize setting survives), not just unit tests

[wgordon17]

UAT — Curated macOS Preferences Generator

Real commands, run against a scaffolded framework. The scan data is synthetic (fake dock settings, a fake API key, a fake wallpaper image) rather than a real Mac's personal data — chosen to exercise every output type in one pass, not to represent anyone's actual settings.

1. Generate a host's preferences from a scan

A host was already registered via mac2nix add-host (unrelated to this PR — not re-demonstrated here). From there:

$ mac2nix init ~/my-nix-config
Framework scaffolded at ~/my-nix-config
Next: mac2nix add-host --hostname <name> [--username <name>] to register a machine.

$ mac2nix generate ~/my-nix-config --hostname uat-host --scan-file scan.json --domains preferences
Generated: preferences

2. Generated preferences.nix

$ cat ~/my-nix-config/hosts/darwin/uat-host/preferences.nix
{ config, lib, pkgs, ... }:

{
  power.sleep.computer = lib.mkDefault "never";
  power.sleep.display = lib.mkDefault 10;
  system.defaults.dock.tilesize = lib.mkDefault 48;
  system.defaults.CustomUserPreferences = lib.mkDefault { "com.apple.symbolichotkeys" = { AppleSymbolicHotKeys = { "32" = { enabled = 0; }; }; }; };
  system.activationScripts.postActivation.text = (
  lib.concatStringsSep "\n" [
    (let
      settingValue = toString 3;
    in
    ''
      pmset -a hibernatemode ${lib.escapeShellArg settingValue}
    '')
    (let
      settingValue = "off";
    in
    ''
      if systemsetup -getRestartPowerFailure | grep -q "Not supported"; then
        echo "mac2nix: restart-after-power-failure not supported on this hardware, skipped" >&2
      else
        systemsetup -setRestartPowerFailure ${lib.escapeShellArg settingValue}
      fi
    '')
    (let
      settingValue = "on";
    in
    ''
      if systemsetup -getwakeonnetworkaccess | grep -q "Not supported"; then
        echo "mac2nix: wake-on-LAN not supported on this hardware, skipped" >&2
      else
        systemsetup -setwakeonnetworkaccess ${lib.escapeShellArg settingValue}
      fi
    '')
    (let
      wallpaperPath = toString ./assets/wallpaper.jpg;
    in
    ''
      sudo -u ${config.system.primaryUser} osascript \
        -e 'on run argv' \
        -e '  tell application "System Events" to tell every desktop to set picture to POSIX file (item 1 of argv)' \
        -e 'end run' \
        ${lib.escapeShellArg wallpaperPath} \
        || echo "mac2nix: could not set desktop wallpaper (no GUI session for ${config.system.primaryUser}?)" >&2
    '')
  ]
);
  # not automated: [sensitive] manual report: key '***REDACTED***' in domain 'com.apple.dock' matches a sensitive pattern
  # not automated: [out of scope] activationScripts: defaults write for com.apple.dock some-binary-pref (binary data)
  # not automated: [coverage gap] manual report: no nix-darwin option for system setting 'gpuswitch'
}

Every output type is exercised: plain settings, custom preferences, activation scripts (a bundled wallpaper, two hardware-probing power settings, and one plain pmset setting), and three tagged notes for what wasn't automated and why:

• [sensitive] — the key name looked like a credential, so its name and value are both withheld.
• [out of scope] — the value was binary data this tool doesn't know how to reproduce.
• [coverage gap] — no nix-darwin equivalent exists yet for this setting.

3. Wallpaper file bundling

$ ls ~/my-nix-config/hosts/darwin/uat-host/assets/
wallpaper.jpg

The wallpaper image itself is copied alongside preferences.nix, byte-for-byte identical to the source file, so the generated config is self-contained.

4. Generated config is valid Nix, and re-running is a no-op

$ nix-instantiate --parse ~/my-nix-config/hosts/darwin/uat-host/preferences.nix
exit code: 0

$ mac2nix generate ~/my-nix-config --hostname uat-host --scan-file scan.json --domains preferences   # run again
Generated: preferences

preferences.nix is byte-for-byte identical before and after the second run.

5. Full config builds for real

$ uv run pytest tests/generators/test_generate_integration.py -m nix_build -v
tests/generators/test_generate_integration.py::test_generate_with_hardware_dependent_settings_builds_for_real PASSED
1 passed in 607.84s (0:10:07)

Builds the complete flake (home-manager, homebrew, sops-nix, and all) with the generated preferences.nix wired in — not just a syntax check.

6. Real Mac, real apply: hardware-probing settings don't break the switch

$ uv run pytest tests/vm/test_generate_vm.py -m nix_vm -v
tests/vm/test_generate_vm.py::test_generate_switches_and_matches_scan PASSED
1 passed in 814.61s (0:13:34)

Clones a real macOS VM, applies the generated config with darwin-rebuild switch, and re-scans the VM to confirm the settings actually took effect. The two power settings that need to probe the target machine's hardware support both ran their probe and skipped cleanly on hardware that doesn't support them — captured from the real switch output:

mac2nix: restart-after-power-failure not supported on this hardware, skipped
mac2nix: wake-on-LAN not supported on this hardware, skipped

The switch completed successfully. Neither setting can abort the apply anymore.

7. Wallpaper database assumption, verified on a real Mac

$ sqlite3 ~/Library/Application\ Support/Dock/desktoppicture.db .schema
CREATE TABLE pictures (space_id INTEGER, display_id INTEGER);
CREATE TABLE preferences (key INTEGER, data_id INTEGER, picture_id INTEGER);
CREATE TABLE data (value);
...

Matches the schema this tool's wallpaper lookup assumes.

Full test suite

$ uv run pytest -q
1 failed, 1808 passed, 2 skipped
$ uv run ruff check src/ tests/
All checks passed!
$ uv run ruff format --check src/ tests/
130 files already formatted
$ uv run pyright
0 errors, 0 warnings, 0 informations

The one failure is tests/vm/test_integration.py::TestSharedVM::test_snapshot_and_diff_detects_new_file, an SSH permission error against the shared test VM. It's unrelated to this PR — that file has no changes on this branch — and reproduces intermittently on its own, independent of this work.