refactor: Overhaul external user modules

templates/user/README.md

@@ -10,12 +10,14 @@ External user modules allow users to maintain their personal configurations (dot
 
 ```
 user-dotfiles-repo/
-├── home.nix          # Required: Home-manager configuration
+├── user.nix          # Optional: User options AND home-manager configuration
 ├── nixos.nix         # Optional: System-level NixOS configuration
 ├── README.md         # Documentation
 └── dotfiles/         # Optional: Dotfiles to symlink
 ```
 
+**Note:** Both `.nix` files are optional, but at least one should be present for the module to be useful.
+
 ## Usage
 
 ### 1. Create Your User Configuration Repository
@@ -30,24 +32,22 @@ Copy the templates from this directory to your own Git repository:
 {
   ugaif.users = {
     myusername = {
+      # Option 1: Set user options in users.nix
       description = "My Name";
       extraGroups = [ "wheel" "networkmanager" ];
       shell = pkgs.zsh;
       
-      # Option 1: External module from Git
-      home = builtins.fetchGit {
+      # Option 2: Or let the external module's user.nix set these options
+      
+      # Reference external dotfiles module
+      external = builtins.fetchGit {
         url = "https://github.com/username/dotfiles";
         rev = "abc123def456...";  # Full commit hash for reproducibility
         ref = "main";              # Optional: branch/tag name
       };
       
-      # Option 2: Local path for testing
-      # home = /path/to/local/dotfiles;
-      
-      # Option 3: Inline configuration
-      # home = {
-      #   home.packages = [ pkgs.vim ];
-      #   programs.git.enable = true;
+      # Or use local path for testing
+      # external = /path/to/local/dotfiles;
       # };
     };
   };
@@ -63,7 +63,7 @@ Enable the user in `inventory.nix`:
   "my-system" = {
     devices = {
       "hostname" = {
-        extraUsers = [ "myusername" ];
+        ugaif.users.myusername.enable = true;
       };
     };
   };
@@ -72,18 +72,32 @@ Enable the user in `inventory.nix`:
 
 ## File Descriptions
 
-### home.nix (Required)
+### user.nix (Optional)
 
-This file contains your home-manager configuration. It must be a valid NixOS module that accepts `{ inputs, ... }` and returns a home-manager configuration.
+This file serves dual purpose:
+1. Sets `ugaif.users.<username>` options (description, shell, extraGroups, etc.)
+2. Provides home-manager configuration (programs.*, home.*, services.*)
 
-**Must export:**
-- Home-manager options (programs.*, home.packages, etc.)
+**How it works:**
+- The `ugaif.users.<username>` options are extracted and loaded as **data** during module evaluation
+- These options override any defaults set in `users.nix` (which uses `lib.mkDefault`)
+- The home-manager options (`home.*`, `programs.*`, etc.) are imported as a module for home-manager
+- External module options take precedence over `users.nix` base configuration
+
+The same file is imported in two contexts:
+- As a NixOS module to read ugaif.users options
+- As a home-manager module for home.*, programs.*, services.*, etc.
+
+Simply include both types of options in the same file.
 
 **Receives:**
 - `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
-- `config` - Home-manager config
+- `config` - Config (NixOS or home-manager depending on context)
+- `lib` - Nixpkgs library
 - `pkgs` - Nixpkgs package set
-- `osConfig` - Access to OS-level configuration
+- `osConfig` - (home-manager context only) OS-level configuration
+
+**Example:** See `user.nix` template
 
 ### nixos.nix (Optional)
 
@@ -92,16 +106,29 @@ This file contains system-level NixOS configuration. Only needed for:
 - System packages requiring root
 - Special permissions or system settings
 
+**Receives:**
+- `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
+- `config` - NixOS config
+- `lib` - Nixpkgs library
+- `pkgs` - Nixpkgs package set
+
 ## Examples
 
-### Minimal home.nix
+### Minimal user.nix
 
 ```nix
 { inputs, ... }:
-
 { config, lib, pkgs, ... }:
 
 {
+  # User account options (imported as NixOS module)
+  ugaif.users.myuser = {
+    description = "My Name";
+    shell = pkgs.zsh;
+    extraGroups = [ "wheel" "networkmanager" ];
+  };
+
+  # Home-manager configuration (imported into home-manager)
   home.packages = with pkgs; [
     vim
     git
@@ -120,10 +147,14 @@ This file contains system-level NixOS configuration. Only needed for:
 
 ```nix
 { inputs, ... }:
-
 { config, lib, pkgs, ... }:
 
 {
+  ugaif.users.myuser = {
+    description = "My Name";
+    shell = pkgs.zsh;
+  };
+
   home.packages = with pkgs; [ ripgrep fd bat ];
 
   # Symlink dotfiles
@@ -158,20 +189,22 @@ This file contains system-level NixOS configuration. Only needed for:
 
 External user modules:
 - Receive the same flake inputs as nixos-systems
-- Can use all home-manager options
+- Can set user options via user.nix (description, shell, extraGroups, etc.)
+- Can use all home-manager options via home.nix
 - Optionally provide system-level configuration (nixos.nix)
 - System zsh theme applied if `useZshTheme = true` (default)
 - System nvim config applied if `useNvimPlugins = true` (default)
-- Merged with inventory.nix user settings (groups, shell, etc.)
+- Settings from user.nix override base users.nix definitions
 
 ## Development Workflow
 
-1. Create your user config repository with `home.nix`
-2. Test locally: `home = /path/to/local/repo;`
-3. Build: `nix build .#nixosConfigurations.hostname.config.system.build.toplevel`
-4. Commit and push changes
-5. Update users.nix with commit hash
-6. Deploy to systems
+1. Create your user config repository with `user.nix`, `home.nix`, and/or `nixos.nix`
+2. Set user options in user.nix OR in the main users.nix
+3. Test locally: `external = /path/to/local/repo;`
+4. Build: `nix build .#nixosConfigurations.hostname.config.system.build.toplevel`
+5. Commit and push changes
+6. Update users.nix with commit hash
+7. Deploy to systems
 
 ## Benefits
 

templates/user/home.nix

@@ -1,20 +1,29 @@
 { inputs, ... }:
 
 # ============================================================================
-# User Home Manager Configuration Template
+# User Home Manager Configuration Template (Optional)
 # ============================================================================
 # This file provides home-manager configuration for a user.
 # It will be imported into the NixOS system's home-manager configuration.
 #
+# This file is optional - if not present, no home-manager configuration
+# will be loaded from this external module.
+#
 # Usage in users.nix:
 #   myusername = {
+#     # Set user options here OR in the external module's user.nix
 #     description = "My Name";
-#     home = builtins.fetchGit {
+#     shell = pkgs.zsh;
+#     extraGroups = [ "wheel" "networkmanager" ];
+#     
+#     external = builtins.fetchGit {
 #       url = "https://github.com/username/dotfiles";
 #       rev = "commit-hash";
 #     };
 #   };
 #
+# Or use user.nix in your external module to set user options.
+#
 # This module receives the same `inputs` flake inputs as the main
 # nixos-systems configuration (nixpkgs, home-manager, etc.).
 

templates/user/nixos.nix

@@ -11,6 +11,9 @@
 # - Special system permissions or configurations
 # - Installing system packages that require root
 #
+# Note: User options (description, shell, extraGroups, etc.) should be set
+# in the main users.nix file, not here.
+#
 # This module receives the same `inputs` flake inputs as the main
 # nixos-systems configuration.
 

templates/user/user.nix

@@ -0,0 +1,93 @@
+{ inputs, ... }:
+
+# ============================================================================
+# User Configuration (Optional)
+# ============================================================================
+# This file can configure BOTH:
+# 1. User account options (ugaif.users.<username>) when imported as NixOS module
+# 2. Home-manager configuration (home.*, programs.*, services.*) when imported
+#    into home-manager
+#
+# This file is optional - if not present, these options should be set
+# directly in the main users.nix file.
+#
+# This module receives the same `inputs` flake inputs as the main
+# nixos-systems configuration (nixpkgs, home-manager, etc.).
+
+{
+  config,
+  lib,
+  pkgs,
+  osConfig ? null, # Only available in home-manager context
+  ...
+}:
+
+{
+  # ========== User Account Configuration ==========
+  # These are imported as a NixOS module to set ugaif.users options
+  # Replace "myusername" with your actual username
+  
+  ugaif.users.myusername = {
+    description = "Your Full Name";
+
+    extraGroups = [
+      "wheel" # Sudo access
+      "networkmanager" # Network configuration
+      # "docker"         # Docker access (if needed)
+    ];
+
+    shell = pkgs.zsh;
+
+    # Optional: Override editor
+    # editor = pkgs.helix;
+
+    # Optional: Disable system theme/nvim plugins
+    # useZshTheme = false;
+    # useNvimPlugins = false;
+
+    # Optional: Add system-level packages
+    # extraPackages = with pkgs; [ docker ];
+  };
+
+  # Note: You don't need to set 'enable = true' - that's controlled
+  # per-host in inventory.nix
+
+  # ========== Home Manager Configuration ==========
+  # These are imported into home-manager for user environment
+  # System theme (zsh) and nvim config are applied automatically based on flags above
+
+  # Packages
+  home.packages = with pkgs; [
+    # Add your preferred packages here
+    # ripgrep
+    # fd
+    # bat
+  ];
+
+  # ========== Programs ==========
+
+  # Git configuration
+  programs.git = {
+    enable = true;
+    userName = "Your Name";
+    userEmail = "your.email@example.com";
+    extraConfig = {
+      init.defaultBranch = "main";
+    };
+  };
+
+  # ========== Shell Environment ==========
+
+  home.sessionVariables = {
+    # EDITOR is set automatically based on ugaif.users.*.editor
+    # Add your custom environment variables here
+  };
+
+  # ========== Dotfiles ==========
+
+  # You can manage dotfiles with home.file
+  # home.file.".bashrc".source = ./dotfiles/bashrc;
+  # home.file.".vimrc".source = ./dotfiles/vimrc;
+
+  # Or use programs.* options for better integration
+}