feat(generators): add curated macOS preferences generator

CONTRIBUTING.md

@@ -26,19 +26,21 @@ This project follows [Conventional Commits](https://www.conventionalcommits.org/
 
 ### Scopes
 
-| Scope        | Description                        |
-|--------------|------------------------------------|
-| `cli`        | CLI commands and options           |
-| `scanners`   | macOS system scanners              |
-| `generators` | Nix configuration generators       |
-| `mappings`   | macOS-to-nix mapping tables        |
-| `models`     | Data models                        |
-| `reports`    | Scan reports and diffs             |
-| `templates`  | Jinja2 nix templates               |
-| `vm`         | Tart VM integration                |
-| `drift`      | Configuration drift detection      |
-| `deps`       | Dependency updates                 |
-| `ci`         | CI/CD pipeline                     |
+| Scope          | Description                         |
+|----------------|--------------------------------------|
+| `cli`          | CLI commands and options             |
+| `scanners`     | macOS system scanners                |
+| `generators`   | Nix configuration generators         |
+| `mappings`     | macOS-to-nix mapping tables          |
+| `models`       | Data models                          |
+| `reports`      | Scan reports and diffs               |
+| `templates`    | Jinja2 nix templates                 |
+| `vm`           | Tart VM integration                  |
+| `drift`        | Configuration drift detection        |
+| `deps`         | Dependency updates                   |
+| `ci`           | CI/CD pipeline                       |
+| `tests`        | Test-only infrastructure/helpers     |
+| `contributing` | Contributing guide and conventions   |
 
 ### Examples
 

README.md

@@ -8,12 +8,49 @@ Generate nix-darwin configurations from macOS system scans.
 uv sync
 ```
 
+mac2nix also ships a minimal `flake.nix`, so it can be run via Nix without a
+local `uv` install (used internally to re-scan a VM during `mac2nix validate`):
+
+```sh
+nix run github:gordon-code/mac2nix -- --help
+```
+
 ## Usage
 
 ```sh
 uv run mac2nix --help
 ```
 
+### Migrating a Mac
+
+Scaffold a reusable, host-less nix-darwin + home-manager + sops-nix framework,
+register a machine, scan it, and generate that host's configuration:
+
+```sh
+uv run mac2nix init ~/my-nix-config
+uv run mac2nix add-host ~/my-nix-config --hostname my-mac --username myuser
+uv run mac2nix generate ~/my-nix-config --hostname my-mac
+```
+
+`init` runs once per framework (it scaffolds `flake.nix`, shared `modules/`,
+and sops-nix wiring with zero hosts registered). `add-host` registers one
+machine at a time — including the first — generating that host's own
+sops-nix age key behind a mandatory backup-confirmation prompt. `generate`
+scans the current machine (or replays a `mac2nix scan` JSON file via
+`--scan-file`) and writes that host's curated `preferences.nix` — bundling a
+personal desktop wallpaper image under that host's `assets/` directory when
+one is set — updating `configuration.nix`'s generated-imports section. It's
+safely re-runnable and supports `--domains` to select which domains to
+generate (currently just `preferences`; more are added incrementally).
+
+Anything `generate` can't apply automatically shows up as a `# not automated:`
+comment in the generated file, prefixed with why: `[sensitive]` (a value
+that's deliberately never captured), `[coverage gap]` (no nix-darwin option
+exists yet), `[hardware-dependent]` (the target machine's support for the
+setting can't be known until activation time), or `[out of scope]` (outside
+this generator's current scope). Review these and apply them manually where
+needed.
+
 ## License
 
 MIT

flake.nix

@@ -0,0 +1,52 @@
+{
+  description = "mac2nix -- scan macOS system state and generate nix-darwin configuration";
+
+  # Minimal packaging for `nix run` -- delegates to `uv` for the actual Python
+  # dependency resolution/venv management (this project's own established
+  # convention, per CLAUDE.md's "use uv for all Python work"), rather than
+  # reimplementing that as a native Nix Python closure (uv2nix, etc.). This
+  # exists specifically so `Validator._scan_vm()` (src/mac2nix/vm/validator.py)
+  # can `nix run <this-repo-or-a-copy-of-it> -- scan` from inside a VM that
+  # only has Nix bootstrapped, not `uv` itself -- `uv` is fetched from
+  # nixpkgs as part of this flake's own closure.
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      systems = [
+        "aarch64-darwin"
+        "x86_64-darwin"
+      ];
+      forEachSystem = nixpkgs.lib.genAttrs systems;
+    in
+    {
+      apps = forEachSystem (
+        system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+        in
+        {
+          default = {
+            type = "app";
+            # `--project ${self}` points uv at a read-only Nix store path for
+            # source/dependency resolution -- uv must never try to create its
+            # venv there (its own default, and any ambient
+            # $UV_PROJECT_ENVIRONMENT override, both assume a writable
+            # project root). Force the venv into a stable, writable cache
+            # location instead of a fresh `mktemp -d` per invocation -- `uv`
+            # creates any missing parent directories itself, and reusing the
+            # same venv makes repeat invocations a fast no-op sync instead of
+            # a full dependency install, and never leaves orphaned venv
+            # directories behind in $TMPDIR.
+            program = toString (
+              pkgs.writeShellScript "mac2nix" ''
+                export UV_PROJECT_ENVIRONMENT="''${XDG_CACHE_HOME:-$HOME/.cache}/mac2nix/nix-run-venv"
+                exec ${pkgs.uv}/bin/uv run --project ${self} mac2nix "$@"
+              ''
+            );
+          };
+        }
+      );
+    };
+}

pyproject.toml

@@ -63,7 +63,7 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"**/tests/**/*.py" = ["S101", "S105", "S106", "S107", "S108", "S314", "SLF001", "ARG001"]  # assert + test data + credentials + XML parsing + private access + unused mock args OK in tests
+"**/tests/**/*.py" = ["S101", "S105", "S106", "S107", "S108", "S314", "SLF001", "ARG001", "ARG002"]  # assert + test data + credentials + XML parsing + private access + unused mock/fixture args (functions and methods) OK in tests
 
 [tool.ruff.lint.isort]
 known-first-party = ["mac2nix"]

src/mac2nix/cli.py

@@ -21,7 +21,8 @@
 from rich.text import Text
 
 from mac2nix import onepassword
-from mac2nix.generators.scaffold import add_host, age_key_path, init_framework
+from mac2nix.generators import generate_all
+from mac2nix.generators.scaffold import add_host, age_key_path, has_hosts_sentinels, init_framework
 from mac2nix.models.system_state import SystemState
 from mac2nix.orchestrator import run_scan
 from mac2nix.scan_report import ScannerOutcome, ScannerStatus, capture_scanner_logs, get_remediation_hint
@@ -384,10 +385,99 @@ def _register_one(current_hostname: str, current_username: str, current_system:
     )
 
 
+# Extend this tuple (never restructure) as each domain generator lands --
+# Task 7 (shell) adds "shell", then Task 6 (homebrew) adds "homebrew".
+_ALLOWED_DOMAINS = ("preferences",)
+
+
+def _check_scaffolded_framework(output_dir: Path) -> None:
+    """Matches add_host()'s own scaffolded-framework check in scaffold.py
+    (shared `has_hosts_sentinels()` predicate) -- kept as a second,
+    independent check (not a shared function) since this one must raise
+    click.ClickException while add_host() raises ScaffoldError, but reusing
+    the shared predicate avoids the two checks silently drifting apart.
+    """
+    flake_path = output_dir / "flake.nix"
+    try:
+        flake_content = flake_path.read_text() if flake_path.is_file() else ""
+    except OSError as exc:
+        raise click.ClickException(f"Failed to read {flake_path}: {exc}") from exc
+    if not has_hosts_sentinels(flake_content):
+        raise click.ClickException(f"{output_dir} is not a mac2nix-scaffolded framework — run `mac2nix init` first")
+
+
+def _check_host_registered(output_dir: Path, hostname: str) -> None:
+    host_dir = output_dir / "hosts" / "darwin" / hostname
+    try:
+        host_registered = host_dir.exists()
+    except OSError as exc:
+        raise click.ClickException(f"Failed to check {host_dir}: {exc}") from exc
+    if not host_registered:
+        msg = f"host {hostname!r} is not registered under {output_dir} — run `mac2nix add-host` first"
+        raise click.ClickException(msg)
+
+
 @main.command()
-def generate() -> None:
-    """Generate nix-darwin configuration from a scan snapshot."""
-    click.echo("generate: not yet implemented")
+@click.argument("output_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option(
+    "--hostname",
+    required=True,
+    callback=_validate_hostname,
+    help="Host to populate (must already be registered via add-host).",
+)
+@click.option(
+    "--scan-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Source SystemState JSON produced by 'mac2nix scan'. Omit to scan the current machine inline.",
+)
+@click.option(
+    "--domains",
+    default="preferences",
+    show_default=True,
+    help=f"Comma-separated domains to generate. Allowed: {', '.join(_ALLOWED_DOMAINS)}.",
+)
+def generate(output_dir: Path, hostname: str, scan_file: Path | None, domains: str) -> None:
+    """Generate nix-darwin configuration for one host from a scan.
+
+    Never invokes `nix flake lock`, `nix build`, `darwin-rebuild`, or `git`
+    -- it only writes files and (for an inline scan) runs the existing
+    read-only scanners.
+    """
+    _check_scaffolded_framework(output_dir)
+
+    requested_domains = {token.strip() for token in domains.split(",") if token.strip()}
+    unknown = requested_domains - set(_ALLOWED_DOMAINS)
+    if unknown:
+        msg = f"unknown domain(s): {', '.join(sorted(unknown))}. Allowed: {', '.join(_ALLOWED_DOMAINS)}"
+        raise click.BadParameter(msg, param_hint="--domains")
+
+    _check_host_registered(output_dir, hostname)
+
+    if scan_file is not None:
+        try:
+            system_state = SystemState.from_json(scan_file)
+        except Exception as exc:
+            raise click.ClickException(f"Failed to load scan file: {exc}") from exc
+    else:
+        try:
+            system_state = asyncio.run(run_scan())
+        except RuntimeError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    try:
+        result = generate_all(system_state, output_dir, hostname, requested_domains)
+    except click.ClickException:
+        raise
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if result.ran:
+        click.echo(f"Generated: {', '.join(sorted(result.ran))}")
+    for domain, reason in sorted(result.skipped.items()):
+        click.echo(f"Skipped {domain}: {reason}")
+    if result.unrecognized:
+        click.echo(f"Unrecognized (not generated): {', '.join(sorted(result.unrecognized))}")
 
 
 @main.command()