refactor(modules): replace mkModuleV2 with per-user mkFeature compiler

.agents/AGENTS.md

@@ -15,7 +15,7 @@ dot/
 │       ├── nix-oldstar/      # NixOS host
 │       └── mac-brightstar/   # Darwin host
 ├── lib/
-│   ├── default.nix           # Core helpers: mkModuleV2, mkSystemModuleV2, mkDotfilesSymlink, etc.
+│   ├── default.nix           # Core helpers: mkFeature, mkSystemModuleV2, mkDotfilesSymlink, etc.
 │   ├── flakeHelpers.nix      # mkDarwinConfiguration, mkNixosConfiguration
 │   ├── moduleRegistry.nix    # Module discovery/registry
 │   └── themes/               # Theme system (rose-pine-moon, etc.)
@@ -80,13 +80,13 @@ Use `lib.recursiveUpdate` (not `//`) to merge nested attrsets without clobbering
 
 ### Module dependency requires
 
-Modules can declare `requires = [ "home.other.module" ]` in `mkModuleV2`. Enabling a module auto-enables its full transitive dependency tree — if A requires B and B requires C, enabling A auto-enables B and C. Inspect the registry: `nix eval '.#moduleRegistry.modules' --json`.
+Modules can declare `requires = [ "home.other.module" ]` in `mkFeature`. Enabling a module auto-enables its full transitive dependency tree — if A requires B and B requires C, enabling A auto-enables B and C. Inspect the registry: `nix eval '.#moduleRegistry.modules' --json`.
 
 ### Two module types
 
 | Type | Location | Created with | Enabled via | Auto-discovered |
 |------|----------|-------------|-------------|-----------------|
-| User | `modules/home/` | `mkModuleV2` | `hostUsers.<user>.modules.<path>.enable` | Yes |
+| User | `modules/home/` | `mkFeature` | `hostUsers.<user>.modules.<path>.enable` | Yes |
 | System | `modules/systems/` | `mkSystemModuleV2` | `modules.system.all.*` / `modules.system.linux.*` / `modules.system.darwin.*` | Yes |
 
 ### Hierarchical enables — home modules
@@ -112,34 +112,42 @@ Individual module enables still work as before (and take precedence for opt-outs
 
 Path follows directory structure: `modules/systems/<platform>/<module>` → `modules.system.<platform>.<module>`
 
-### Platform sections in modules
+### Feature structure (mkFeature)
 
 ```nix
-module = {
-  allSystems.home.packages = [ ... ];      # Both platforms
-  nixosSystems.home.packages = [ ... ];    # Linux only
-  darwinSystems.homebrew.casks = [ ... ];  # macOS only
-};
+lib.my.mkFeature {
+  description = "Feature description";
+  platforms = [ "linux" "darwin" ];  # Supported platforms
+  requires = [ "home.shell.zsh" ];   # Dependencies auto-enabled per user
+  extraOptions = { ... };            # Per-user typed extra options
+
+  dotfiles = {                       # Optional dotfiles symlinking
+    path = "app";
+    source = "modules/home/.../dotfiles";
+  };
 
-systemModule = {
-  nixosSystems = { programs.hyprland.enable = true; };
-  darwinSystems = { ... };
-  allSystems = { ... };
+  homeModule = { config, osConfig, pkgs, lib, featureCfg, userName, ... }: {
+    # Home Manager configuration scoped exclusively to this user
+  };
+  homeModuleLinux = { ... }: { ... };   # Linux-only HM config
+  homeModuleDarwin = { ... }: { ... };  # Darwin-only HM config
+  nixosModule = { config, pkgs, lib, featureCfg, selectedUsers, ... }: { ... };   # System-level NixOS activation
+  darwinModule = { config, pkgs, lib, featureCfg, selectedUsers, ... }: { ... };  # System-level Darwin activation
 };
 ```
 
-Home-manager attrs (`home`, `programs`, `xdg`, `services`, etc.) are automatically routed to all enabled `hostUsers`.
+Home-manager configuration is scoped strictly per-user to users who enable the feature.
 
 ## Key Helpers (lib/default.nix)
 
-- `lib.my.mkModuleV2 args { module, systemModule?, dotfiles?, imports?, extraOptions?, ... }` — User modules
+- `lib.my.mkFeature { description?, platforms?, requires?, extraOptions?, dotfiles?, homeModule?, homeModuleLinux?, homeModuleDarwin?, nixosModule?, darwinModule? }` — User feature descriptors
 - `lib.my.mkSystemModuleV2 args { namespace, module, moduleLinux?, moduleDarwin?, ... }` — System modules
 - `lib.my.shouldEnableModule { config, modulePath }` — Check hierarchical enable
+- `lib.my.isFeatureEnabledForUser { config, userName, modulePath }` — Check per-user feature enable
 - `lib.my.getUsersWithModule { config, modulePath }` — Users with module enabled
 - `lib.my.getUsersWithModuleNames { config, _modulePath }` — Usernames list
 - `lib.my.mkDotfilesSymlink { config, self, path, source, target? }` — Live-editable dotfile symlinks
 - `lib.my.mkUsersAttrs usernames fn` — Creates `users.users` attrset
-- `lib.my.mkModule system config cfg` — Low-level platform-aware config builder
 - `lib.my.getTheme config` — Get active theme (set via `config.theme.name`)
 
 ## Live-Editable Dotfiles

.agents/skills/nix-module-creation/SKILL.md

@@ -1,42 +1,42 @@
 ---
 name: nix-module-creation
-description: Creating new NixOS user and system modules using mkModuleV2/mkSystemModuleV2
+description: Creating new NixOS user features and system modules using mkFeature/mkSystemModuleV2
 ---
 
-# Creating NixOS Modules
+# Creating NixOS Modules and Features
 
-## User Module (mkModuleV2)
+## User Feature (mkFeature)
 
-### Simple module
+### Simple feature
 
 ```nix
 # modules/home/<category>/<name>.nix
-{ lib, pkgs, ... }@args:
+{ lib, pkgs, ... }:
 
-lib.my.mkModuleV2 args {
-  description = "Description of the module";
+lib.my.mkFeature {
+  description = "Description of the feature";
   platforms = [ "linux" "darwin" ];  # optional, defaults to both
 
-  module = {
-    allSystems.home.packages = [ pkgs.my-tool ];
-    # Or platform-specific:
-    # nixosSystems.home.packages = [ pkgs.linux-tool ];
-    # darwinSystems.homebrew.casks = [ "mac-tool" ];
+  homeModule = { pkgs, ... }: {
+    home.packages = [ pkgs.my-tool ];
   };
+  # Or platform-specific:
+  # homeModuleLinux = { pkgs, ... }: { home.packages = [ pkgs.linux-tool ]; };
+  # darwinModule = { homebrew.casks = [ "mac-tool" ]; };
 }
 ```
 
 ### With dotfiles (live-editable symlinks)
 
 ```nix
 # modules/home/<category>/<name>/<name>.nix
-{ lib, pkgs, ... }@args:
+{ lib, pkgs, ... }:
 
-lib.my.mkModuleV2 args {
+lib.my.mkFeature {
   description = "Tool with live-editable config";
 
-  module = {
-    allSystems.home.packages = [ pkgs.my-tool ];
+  homeModule = { pkgs, ... }: {
+    home.packages = [ pkgs.my-tool ];
   };
 
   dotfiles = {
@@ -57,20 +57,18 @@ modules/home/<category>/<name>/
 ### With system-level config
 
 ```nix
-{ lib, pkgs, config, ... }@args:
+{ lib, pkgs, ... }:
 
-lib.my.mkModuleV2 args {
-  description = "Module with system-level configuration";
+lib.my.mkFeature {
+  description = "Feature with system-level configuration";
 
-  systemModule = {
-    nixosSystems = {
-      programs.hyprland.enable = true;
-      services.greetd.enable = true;
-    };
+  nixosModule = { ... }: {
+    programs.hyprland.enable = true;
+    services.greetd.enable = true;
   };
 
-  module = {
-    nixosSystems.home.packages = [ pkgs.hyprland ];
+  homeModuleLinux = { pkgs, ... }: {
+    home.packages = [ pkgs.hyprland ];
   };
 
   dotfiles = {
@@ -83,10 +81,10 @@ lib.my.mkModuleV2 args {
 ### With custom options
 
 ```nix
-{ lib, pkgs, ... }@args:
+{ lib, pkgs, ... }:
 
-lib.my.mkModuleV2 args {
-  description = "Module with custom options";
+lib.my.mkFeature {
+  description = "Feature with custom options";
 
   extraOptions = {
     showHostname = lib.mkOption {
@@ -96,49 +94,46 @@ lib.my.mkModuleV2 args {
     };
   };
 
-  # When using extraOptions, module becomes a function receiving cfg
-  module = cfg: {
-    allSystems.home.packages = [ pkgs.my-tool ];
-    # Access option: cfg.showHostname
+  homeModule = { pkgs, featureCfg, ... }: {
+    home.packages = [ pkgs.my-tool ];
+    # Access option: featureCfg.showHostname
   };
 }
 ```
 
-### With imports (sub-modules)
+### With dependencies (requires)
 
 ```nix
-{ lib, pkgs, ... }@args:
+{ lib, pkgs, ... }:
 
-lib.my.mkModuleV2 args {
-  description = "Module with sub-module imports";
+lib.my.mkFeature {
+  description = "Feature with dependencies";
 
-  imports = [
-    ./dotfiles/general.nix
-    ./dotfiles/plugins/airline.nix
+  requires = [
+    "home.shell.zsh"
+    "home.desktop.services.audio"
   ];
 
-  systemModule = {
-    allSystems.programs.nixvim.enable = true;
-  };
-
-  module = {
-    allSystems.home.packages = [ pkgs.ripgrep pkgs.fzf ];
+  homeModule = { pkgs, ... }: {
+    home.packages = [ pkgs.my-tool ];
   };
 }
 ```
 
-## mkModuleV2 Parameters
+## mkFeature Parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `description` | string | No | Module description |
+| `description` | string | No | Feature description |
 | `platforms` | list | No | `["linux" "darwin"]` (default: both) |
-| `requires` | list | No | Module path dependencies |
-| `module` | attrset or `cfg -> attrset` | No | Platform config with `allSystems`/`nixosSystems`/`darwinSystems` sections |
-| `systemModule` | attrset or `cfg -> attrset` | No | System-level config (same sections) |
-| `dotfiles` | `{ path, source, target? }` | No | Live-editable symlinks |
-| `extraOptions` | attrset | No | Additional NixOS options (merged with `enable`) |
-| `imports` | list | No | Sub-module imports |
+| `requires` | list | No | Feature path dependencies (auto-enabled per user) |
+| `extraOptions` | attrset | No | Additional typed NixOS/HM options (merged per user) |
+| `dotfiles` | `{ path, source, target?, live? }` | No | Live-editable symlinks |
+| `homeModule` | function or attrset | No | Home Manager config for users enabling the feature |
+| `homeModuleLinux` | function or attrset | No | Linux-only Home Manager config |
+| `homeModuleDarwin` | function or attrset | No | Darwin-only Home Manager config |
+| `nixosModule` | function or attrset | No | System-level NixOS config when any user enables the feature |
+| `darwinModule` | function or attrset | No | System-level Darwin config when any user enables the feature |
 
 ## System Module (mkSystemModuleV2)
 
@@ -167,14 +162,14 @@ lib.my.mkSystemModuleV2 args {
 }
 ```
 
-Enable: `systemLinux.<category>.<name>.enable = true` in host config.
+Enable: `modules.system.linux.<category>.<name>.enable = true` in host config.
 
 ## Checklist
 
 1. Decide scope: System (`systems/*`) or User (`home/*`)
 2. Choose/create category subdirectory
 3. Create module file using templates above
-4. **System modules only**: Add import to `systems/*/default.nix`
-5. **User modules**: Auto-discovered — just add enable path to `hostUsers.<user>.modules`
+4. **System modules only**: Auto-discovered or added under `modules/systems/{all,linux,darwin}`
+5. **User features**: Auto-discovered — just add enable path to `hostUsers.<user>.modules`
 6. `git add` new files before `nix flake check`
 7. Test: `nix flake check`

checks.nix

@@ -2,36 +2,117 @@
 
 let
   user = "dgarifullin";
-  hasPackage = prefix: packages:
-    lib.any (package: lib.hasPrefix prefix (package.name or "")) packages;
+  hasPackage = nameOrPrefix: packages:
+    lib.any
+      (package:
+        let
+          pname = package.pname or "";
+          name = package.name or "";
+        in
+        pname == nameOrPrefix ||
+        lib.hasPrefix "${nameOrPrefix}-" name ||
+        lib.hasPrefix nameOrPrefix name ||
+        name == nameOrPrefix
+      )
+      packages;
 
   neovimConfig = inputs.nvim-nix.checks.${system}.neovim-config;
+
+  commonChecks = {
+    mcp-config-generation =
+      let
+        goldstarHome = self.nixosConfigurations.nix-goldstar.config.home-manager.users.${user}.home;
+        mcpFile = goldstarHome.file.".gemini/antigravity/mcp_config.json" or null;
+        mcpJson = if mcpFile != null then builtins.fromJSON mcpFile.text else { };
+      in
+      assert goldstarHome.file ? ".gemini/antigravity/mcp_config.json";
+      assert mcpJson ? mcpServers.nixos;
+      assert mcpJson ? mcpServers.ghidra;
+      pkgs.runCommand "mcp-config-generation-check" { } "touch $out";
+
+    multi-user-isolation =
+      let
+        testHost = self.nixosConfigurations.nix-goldstar.extendModules {
+          modules = [
+            {
+              hostUsers.bob = {
+                enable = true;
+                modules = {
+                  home.cli.htop.enable = true;
+                  home.games.soundpad.enable = true;
+                };
+              };
+            }
+          ];
+        };
+        bobPkgs = testHost.config.home-manager.users.bob.home.packages;
+        bobFiles = testHost.config.home-manager.users.bob.home.file;
+        bobGroups = testHost.config.users.users.bob.extraGroups or [ ];
+        dgarifullinPkgs = testHost.config.home-manager.users.${user}.home.packages;
+        dgarifullinFiles = testHost.config.home-manager.users.${user}.home.file;
+        dgarifullinGroups = testHost.config.users.users.${user}.extraGroups or [ ];
+      in
+      # bob receives htop
+      assert hasPackage "htop" bobPkgs;
+      # bob receives pamixer/pavucontrol (via transitive requires audio)
+      assert hasPackage "pamixer" bobPkgs;
+      assert hasPackage "pavucontrol" bobPkgs;
+      # bob does NOT receive telegram-desktop, google-antigravity-ide, .gemini/antigravity/mcp_config.json, or docker group
+      assert !(hasPackage "telegram-desktop" bobPkgs);
+      assert !(hasPackage "google-antigravity" bobPkgs);
+      assert !(bobFiles ? ".gemini/antigravity/mcp_config.json");
+      assert !(lib.elem "docker" bobGroups);
+      # dgarifullin retains all of their packages, configs, and groups
+      assert hasPackage "htop" dgarifullinPkgs;
+      assert hasPackage "telegram-desktop" dgarifullinPkgs;
+      assert (dgarifullinFiles ? ".gemini/antigravity/mcp_config.json");
+      assert (lib.elem "docker" dgarifullinGroups);
+      pkgs.runCommand "multi-user-isolation-check" { } "touch $out";
+
+    cascade-child-opt-out =
+      let
+        testDarwin = self.darwinConfigurations.mac-brightstar.extendModules {
+          modules = [
+            {
+              hostUsers.${user}.modules = {
+                home.utils.enable = lib.mkForce true;
+                home.utils.raycast.enable = lib.mkForce false;
+              };
+            }
+          ];
+        };
+        pkgsList = testDarwin.config.home-manager.users.${user}.home.packages;
+      in
+      # obsidian is enabled via category cascade
+      assert hasPackage "obsidian" pkgsList;
+      # raycast remains disabled via child opt-out
+      assert !(hasPackage "raycast" pkgsList);
+      pkgs.runCommand "cascade-child-opt-out-check" { } "touch $out";
+
+    neovim-config = neovimConfig;
+  };
 in
 if system == "x86_64-linux" then
   let
     home = self.nixosConfigurations.nix-goldstar.config.home-manager.users.${user}.home;
   in
-  {
+  commonChecks // {
     module-platform-merge =
       assert hasPackage "ripgrep-" home.packages;
       assert hasPackage "wl-clipboard-" home.packages;
       assert hasPackage "google-antigravity-ide-with-basic-store" home.packages;
       assert home.file ? ".gemini/config/AGENTS.md";
       pkgs.runCommand "module-platform-merge-check" { } "touch $out";
-
-    neovim-config = neovimConfig;
   }
 else if system == "aarch64-darwin" then
   let
     home = self.darwinConfigurations.mac-brightstar.config.home-manager.users.${user}.home;
   in
-  {
+  commonChecks // {
     module-platform-merge =
       assert hasPackage "ripgrep-" home.packages;
       assert !(hasPackage "wl-clipboard-" home.packages);
       pkgs.runCommand "module-platform-merge-check" { } "touch $out";
-
-    neovim-config = neovimConfig;
   }
 else
   { }