refactor: Move sw into properly nested modules with unconditional import

2026-01-27 13:59:57 -05:00
parent bd50f894ae
commit f669845bf7
36 changed files with 788 additions and 347 deletions
--- a/sw/builders/default.nix
+++ b/sw/builders/default.nix
@@ -11,21 +11,111 @@
  ...
 }:

-lib.mkMerge [
-  (import ./programs.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./services.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-]
+with lib;
+
+let
+  cfg = config.athenix.sw.builders;
+in
+{
+  options.athenix.sw.builders = {
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable build server configuration.
+
+        Includes:
+        - SSH host keys for common Git servers (factory.uga.edu, github.com)
+        - Gitea Actions runner support (optional)
+        - Build tools and dependencies
+
+        Recommended for: CI/CD servers, build containers, development infrastructure
+      '';
+      example = true;
+    };
+
+    giteaRunner = {
+      enable = mkOption {
+        type = types.bool;
+        default = false;
+        description = ''
+          Enable Gitea Actions self-hosted runner.
+
+          This runner will connect to a Gitea instance and execute CI/CD workflows.
+          Requires manual setup of the token file before the service will start.
+        '';
+        example = true;
+      };
+
+      url = mkOption {
+        type = types.str;
+        description = ''
+          URL of the Gitea instance to connect to.
+          This should be the base URL without any path components.
+        '';
+        example = "https://git.factory.uga.edu";
+      };
+
+      tokenFile = mkOption {
+        type = types.path;
+        default = "/var/lib/gitea-runner-token";
+        description = ''
+          Path to file containing Gitea runner registration token.
+
+          To generate:
+          1. Go to your Gitea repository settings
+          2. Navigate to Actions > Runners
+          3. Click "Create new Runner"
+          4. Save the token to this file:
+             echo "TOKEN=your-token-here" | sudo tee /var/lib/gitea-runner-token > /dev/null
+
+          The service will not start until this file exists.
+        '';
+        example = "/var/secrets/gitea-runner-token";
+      };
+
+      extraLabels = mkOption {
+        type = types.listOf types.str;
+        default = [ ];
+        description = ''
+          Additional labels to identify this runner in workflow files.
+          Use labels to target specific runners for different job types.
+        '';
+        example = [
+          "self-hosted"
+          "nix"
+          "x86_64-linux"
+        ];
+      };
+
+      name = mkOption {
+        type = types.str;
+        default = "athenix";
+        description = ''
+          Unique name for this runner instance.
+          Shown in Gitea's runner list and logs.
+        '';
+        example = "nix-builder-1";
+      };
+    };
+  };
+
+  config = mkIf cfg.enable (mkMerge [
+    (import ./programs.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./services.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+  ]);
+}
--- a/sw/builders/programs.nix
+++ b/sw/builders/programs.nix
@@ -1,8 +1,6 @@
 {
  config,
  lib,
-  pkgs,
-  inputs,
  ...
 }:

@@ -10,7 +8,7 @@ with lib;

 let
  cfg = config.athenix.sw;
-  basePackages = with pkgs; [
+  basePackages = [
    # Build-related packages can be added here if needed
  ];
 in
--- a/sw/default.nix
+++ b/sw/default.nix
@@ -10,19 +10,14 @@
 # Software Module Entry Point
 # ============================================================================
 # This module manages the software configuration for the system. It provides
-# options to select the system type ('desktop' or 'kiosk') and handles
-# the conditional importation of the appropriate sub-modules.
+# enable options for each system type (desktop, headless, builders, etc.)
+# that can be enabled independently or in combination. Each type is a proper
+# NixOS submodule with its own enable flag and type-specific options.

 with lib;

 let
  cfg = config.athenix.sw;
-
-  # Normalize type to always be a list
-  swTypes = if isList cfg.type then cfg.type else [ cfg.type ];
-
-  # Helper to check if a type is enabled
-  hasType = type: elem type swTypes;
 in
 {
  imports = [
@@ -31,169 +26,83 @@ in
    ./gc.nix
    ./updater.nix
    ./update-ref.nix
+    ./desktop
+    ./headless
+    ./builders
+    ./tablet-kiosk
+    ./stateless-kiosk
    inputs.home-manager.nixosModules.home-manager
    inputs.agenix.nixosModules.default
    inputs.disko.nixosModules.disko
  ];

  options.athenix.sw = {
-    enable = mkEnableOption "Standard Workstation Configuration";
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable standard workstation configuration with base packages.

+        Provides:
+        - Base CLI tools (htop, git, binutils)
+        - Shell configuration (Zsh)
+        - Secret management (agenix)
+        - Oh My Posh shell theme
+
+        This is typically enabled automatically when any sw type is enabled.
+      '';
+    };
+
+    # DEPRECATED: Backwards compatibility for external modules
+    # Use athenix.sw.<type>.enable instead
    type = mkOption {
-      type = types.oneOf [
-        (types.enum [
-          "desktop"
-          "tablet-kiosk"
-          "headless"
-          "stateless-kiosk"
-          "builders"
-        ])
-        (types.listOf (
-          types.enum [
-            "desktop"
-            "tablet-kiosk"
-            "headless"
-            "stateless-kiosk"
-            "builders"
-          ]
-        ))
-      ];
-      default = "desktop";
-      description = "Type(s) of system configuration. Can be a single type or a list of types to combine multiple configurations.";
+      type = types.nullOr (types.either types.str (types.listOf types.str));
+      default = null;
+      description = "DEPRECATED: Use athenix.sw.<type>.enable instead. Legacy type selection.";
+      visible = false;
    };

    extraPackages = mkOption {
      type = types.listOf types.package;
      default = [ ];
-      description = "Extra packages to install.";
+      description = ''
+        Additional system packages to install beyond the defaults.
+        These packages are added to environment.systemPackages.
+      '';
+      example = lib.literalExpression "[ pkgs.vim pkgs.wget pkgs.curl ]";
    };

    excludePackages = mkOption {
      type = types.listOf types.package;
      default = [ ];
-      description = "Packages to exclude from the default list.";
-    };
-
-    kioskUrl = mkOption {
-      type = types.str;
-      default = "https://ha.factory.uga.edu";
-      description = "URL to open in Chromium kiosk mode.";
-    };
-
-    # Builders-specific options
-    builders = mkOption {
-      type = types.submodule {
-        options = {
-          giteaRunner = {
-            enable = mkEnableOption "Gitea Actions self-hosted runner";
-
-            url = mkOption {
-              type = types.str;
-              description = "Gitea instance URL for the runner";
-            };
-
-            tokenFile = mkOption {
-              type = types.path;
-              default = "/var/lib/gitea-runner-token";
-              description = ''
-                Path to file containing Gitea runner token.
-                Generate in Gitea repository settings under Actions > Runners.
-                The token must have runner registration access.
-              '';
-            };
-
-            extraLabels = mkOption {
-              type = types.listOf types.str;
-              default = [ ];
-              description = "Extra labels to identify this runner in workflows";
-            };
-
-            name = mkOption {
-              type = types.str;
-              default = "athenix";
-              description = "Name of the Gitea runner service";
-            };
-          };
-        };
-      };
-      default = { };
-      description = "Builder-specific configuration options";
+      description = ''
+        Packages to exclude from the default package list.
+        Useful for removing unwanted default packages.
+      '';
+      example = lib.literalExpression "[ pkgs.htop ]";
    };
  };

-  config = mkIf cfg.enable (mkMerge [
-    {
-      # ========== System-Wide Configuration ==========
-      nixpkgs.config.allowUnfree = true;
+  config = mkIf cfg.enable {
+    # ========== System-Wide Configuration ==========
+    nixpkgs.config.allowUnfree = true;

-      # ========== Shell Configuration ==========
-      programs.zsh.enable = true;
-      programs.nix-ld.enable = true; # Allow running non-NixOS binaries
+    # ========== Shell Configuration ==========
+    programs.zsh.enable = true;
+    programs.nix-ld.enable = true; # Allow running non-NixOS binaries

-      # ========== Base Packages ==========
-      environment.systemPackages =
-        with pkgs;
-        subtractLists cfg.excludePackages [
-          htop # System monitor
-          binutils # Binary utilities
-          zsh # Z shell
-          git # Version control
-          oh-my-posh # Shell prompt theme
-          age # Simple file encryption tool
-          age-plugin-fido2-hmac # age FIDO2 support
-          inputs.agenix.packages.${stdenv.hostPlatform.system}.default # Secret management
-        ];
-    }
-    # ========== Software Profile Imports ==========
-    (mkIf (hasType "desktop") (
-      import ./desktop {
-        inherit
-          config
-          lib
-          pkgs
-          inputs
-          ;
-      }
-    ))
-    (mkIf (hasType "tablet-kiosk") (
-      import ./tablet-kiosk {
-        inherit
-          config
-          lib
-          pkgs
-          inputs
-          ;
-      }
-    ))
-    (mkIf (hasType "headless") (
-      import ./headless {
-        inherit
-          config
-          lib
-          pkgs
-          inputs
-          ;
-      }
-    ))
-    (mkIf (hasType "stateless-kiosk") (
-      import ./stateless-kiosk {
-        inherit
-          config
-          lib
-          pkgs
-          inputs
-          ;
-      }
-    ))
-    (mkIf (hasType "builders") (
-      import ./builders {
-        inherit
-          config
-          lib
-          pkgs
-          inputs
-          ;
-      }
-    ))
-  ]);
+    # ========== Base Packages ==========
+    environment.systemPackages =
+      with pkgs;
+      subtractLists cfg.excludePackages [
+        htop # System monitor
+        binutils # Binary utilities
+        zsh # Z shell
+        git # Version control
+        oh-my-posh # Shell prompt theme
+        age # Simple file encryption tool
+        age-plugin-fido2-hmac # age FIDO2 support
+        inputs.agenix.packages.${stdenv.hostPlatform.system}.default # Secret management
+      ];
+  };
 }
--- a/sw/desktop/default.nix
+++ b/sw/desktop/default.nix
@@ -10,21 +10,50 @@
  inputs,
  ...
 }:
-lib.mkMerge [
-  (import ./programs.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./services.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-]
+
+with lib;
+
+let
+  cfg = config.athenix.sw.desktop;
+in
+{
+  options.athenix.sw.desktop = {
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable full desktop environment with KDE Plasma 6.
+
+        Includes:
+        - KDE Plasma 6 desktop with SDDM display manager
+        - Full graphical software suite (Firefox, Chromium, LibreOffice)
+        - Printing and scanning support (CUPS)
+        - Virtualization (libvirt, virt-manager)
+        - Bluetooth and audio (PipeWire)
+        - Video conferencing (Zoom, Teams)
+
+        Recommended for: Workstations, development machines, user desktops
+      '';
+      example = true;
+    };
+  };
+
+  config = mkIf cfg.enable (mkMerge [
+    (import ./programs.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./services.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+  ]);
+}
--- a/sw/desktop/programs.nix
+++ b/sw/desktop/programs.nix
@@ -2,7 +2,6 @@
  config,
  lib,
  pkgs,
-  inputs,
  ...
 }:

--- a/sw/desktop/services.nix
+++ b/sw/desktop/services.nix
@@ -1,5 +1,4 @@
 {
-  config,
  lib,
  pkgs,
  ...
--- a/sw/gc.nix
+++ b/sw/gc.nix
@@ -1,7 +1,6 @@
 {
  config,
  lib,
-  pkgs,
  ...
 }:
 {
@@ -10,22 +9,40 @@
      enable = lib.mkOption {
        type = lib.types.bool;
        default = true;
-        description = "Whether to enable automatic garbage collection.";
+        description = ''
+          Enable automatic garbage collection of old NixOS generations.
+          Helps keep disk usage under control on long-running systems.
+        '';
      };
      frequency = lib.mkOption {
        type = lib.types.str;
        default = "weekly";
-        description = "How often to run garbage collection (systemd timer format).";
+        description = ''
+          How often to run garbage collection (systemd timer format).
+
+          Common values: "daily", "weekly", "monthly"
+          Advanced: "*-*-* 03:00:00" (daily at 3 AM)
+        '';
+        example = "daily";
      };
      retentionDays = lib.mkOption {
        type = lib.types.int;
        default = 30;
-        description = "Number of days to keep old generations before deletion.";
+        description = ''
+          Number of days to keep old system generations before deletion.
+
+          Older generations allow rolling back system changes.
+          Recommended: 30-90 days for workstations, 7-14 for servers.
+        '';
+        example = 60;
      };
      optimise = lib.mkOption {
        type = lib.types.bool;
        default = true;
-        description = "Whether to automatically optimize the Nix store.";
+        description = ''
+          Whether to automatically hard-link identical files in the Nix store.
+          Can save significant disk space but uses CPU during optimization.
+        '';
      };
    };

--- a/sw/ghostty.nix
+++ b/sw/ghostty.nix
@@ -1,6 +1,4 @@
 {
-  config,
-  lib,
  pkgs,
  ...
 }:
--- a/sw/headless/default.nix
+++ b/sw/headless/default.nix
@@ -11,21 +11,47 @@
  ...
 }:

-lib.mkMerge [
-  (import ./programs.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./services.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-]
+with lib;
+
+let
+  cfg = config.athenix.sw.headless;
+in
+{
+  options.athenix.sw.headless = {
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable minimal headless server configuration.
+
+        Includes:
+        - SSH server with password authentication
+        - Minimal CLI tools (tmux, man)
+        - Systemd-networkd for networking
+        - No graphical environment
+
+        Recommended for: Servers, containers (LXC), WSL, remote systems
+      '';
+      example = true;
+    };
+  };
+
+  config = mkIf cfg.enable (mkMerge [
+    (import ./programs.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./services.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+  ]);
+}
--- a/sw/headless/programs.nix
+++ b/sw/headless/programs.nix
@@ -2,7 +2,6 @@
  config,
  lib,
  pkgs,
-  inputs,
  ...
 }:

--- a/sw/headless/services.nix
+++ b/sw/headless/services.nix
@@ -1,7 +1,4 @@
 {
-  config,
-  lib,
-  pkgs,
  ...
 }:

--- a/sw/stateless-kiosk/default.nix
+++ b/sw/stateless-kiosk/default.nix
@@ -7,37 +7,77 @@
  inputs,
  ...
 }:
-lib.mkMerge [
-  (import ./kiosk-browser.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./services.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./net.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./programs.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-]
+
+with lib;
+
+let
+  cfg = config.athenix.sw.stateless-kiosk;
+in
+{
+  options.athenix.sw.stateless-kiosk = {
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable stateless kiosk mode for diskless PXE boot systems.
+
+        Includes:
+        - Sway (Wayland compositor)
+        - Chromium in fullscreen kiosk mode
+        - MAC address-based URL routing
+        - Network-only boot (no local storage)
+        - Auto-start browser on boot
+
+        Recommended for: Assembly line stations, diskless kiosks, PXE boot displays
+      '';
+      example = true;
+    };
+
+    kioskUrl = mkOption {
+      type = types.str;
+      default = "https://ha.factory.uga.edu";
+      description = ''
+        Default URL to display in the kiosk browser.
+
+        Note: For stateless-kiosk, MAC address-based routing may override this.
+        See sw/stateless-kiosk/mac-hostmap.nix for MAC-to-URL mappings.
+      '';
+      example = "https://homeassistant.lan:8123/lovelace/dashboard";
+    };
+  };
+
+  config = mkIf cfg.enable (mkMerge [
+    (import ./kiosk-browser.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./services.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./net.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./programs.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+  ]);
+}
--- a/sw/stateless-kiosk/kiosk-browser.nix
+++ b/sw/stateless-kiosk/kiosk-browser.nix
@@ -1,7 +1,6 @@
 # This module configures Chromium for kiosk mode under Sway.
 # It includes a startup script that determines the kiosk URL based on the machine's MAC address.
 {
-  config,
  lib,
  pkgs,
  ...
--- a/sw/tablet-kiosk/default.nix
+++ b/sw/tablet-kiosk/default.nix
@@ -5,29 +5,68 @@
  inputs,
  ...
 }:
-lib.mkMerge [
-  (import ./programs.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./services.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-  (import ./gsettings.nix {
-    inherit
-      config
-      lib
-      pkgs
-      inputs
-      ;
-  })
-]
+
+with lib;
+
+let
+  cfg = config.athenix.sw.tablet-kiosk;
+in
+{
+  options.athenix.sw.tablet-kiosk = {
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable tablet kiosk mode with touch-optimized interface.
+
+        Includes:
+        - Phosh mobile desktop environment
+        - Chromium in fullscreen kiosk mode
+        - On-screen keyboard (Squeekboard)
+        - Auto-login and auto-start browser
+        - Touch gesture support
+        - Optimized for Surface Pro tablets
+
+        Recommended for: Surface tablets, touchscreen kiosks, interactive displays
+      '';
+      example = true;
+    };
+
+    kioskUrl = mkOption {
+      type = types.str;
+      default = "https://ha.factory.uga.edu";
+      description = ''
+        URL to display in the kiosk browser on startup.
+        The browser will automatically navigate to this URL in fullscreen mode.
+      '';
+      example = "https://dashboard.example.com";
+    };
+  };
+
+  config = mkIf cfg.enable (mkMerge [
+    (import ./programs.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./services.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+    (import ./gsettings.nix {
+      inherit
+        config
+        lib
+        pkgs
+        inputs
+        ;
+    })
+  ]);
+}
--- a/sw/tablet-kiosk/services.nix
+++ b/sw/tablet-kiosk/services.nix
@@ -155,7 +155,7 @@
          --noerrdialogs \
          --disable-session-crashed-bubble \
          --disable-infobars \
-          ${config.athenix.sw.kioskUrl}
+          ${config.athenix.sw.tablet-kiosk.kioskUrl}
      '';
    };
  };
--- a/sw/theme.nix
+++ b/sw/theme.nix
@@ -1,7 +1,6 @@
 {
  pkgs,
  config,
-  osConfig,
  lib,
  ...
 }:
--- a/sw/updater.nix
+++ b/sw/updater.nix
@@ -14,22 +14,42 @@ with lib;
        hosts = mkOption {
          type = types.listOf types.str;
          default = [ "engr-ugaif@192.168.11.133 x86_64-linux" ];
-          description = "List of remote build hosts for system rebuilding.";
+          description = ''
+            List of remote build hosts for system rebuilding.
+
+            Format: "user@hostname architecture"
+            Each host must have SSH access and nix-daemon available.
+
+            Useful for offloading builds from low-power devices (tablets, laptops)
+            to more powerful build servers.
+          '';
+          example = lib.literalExpression ''
+            [
+                        "builder@nix-builder x86_64-linux"
+                        "user@192.168.1.100 aarch64-linux"
+                      ]'';
        };

        enable = mkOption {
          type = types.bool;
          default = false;
-          description = "Whether to enable remote build for 'update-system' command.";
+          description = ''
+            Whether to enable remote builds for the 'update-system' command.
+
+            When enabled, 'update-system' will use the configured remote hosts
+            to build the new system configuration instead of building locally.
+
+            Automatically enabled for tablet-kiosk systems.
+          '';
        };
      };
    };
    default = { };
-    description = "Remote build configuration";
+    description = "Remote build configuration for system updates.";
  };

  config = {
-    athenix.sw.remoteBuild.enable = lib.mkDefault (config.athenix.sw.type == "tablet-kiosk");
+    athenix.sw.remoteBuild.enable = lib.mkDefault (config.athenix.sw.tablet-kiosk.enable);

    environment.systemPackages = [
      (pkgs.writeShellScriptBin "update-system" ''