feat: add builder mode for centralized Nix builds

Add a new "builder" capability to trigger Nix builds on a dedicated
build host via NATS messaging. This allows pre-building NixOS
configurations before deployment.

New components:
- Builder mode: subscribes to build.<repo>.* subjects, executes nix build
- Build CLI command: triggers builds with progress tracking
- MCP build tool: available with --enable-builds flag
- Builder metrics: tracks build success/failure per repo and host
- NixOS module: services.homelab-deploy.builder

The builder uses a YAML config file to define allowed repositories
with their URLs and default branches. Builds can target all hosts
or specific hosts, with real-time progress updates.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

nixos/module.nix

@@ -2,32 +2,47 @@
 { config, lib, pkgs, ... }:
 
 let
-  cfg = config.services.homelab-deploy.listener;
+  listenerCfg = config.services.homelab-deploy.listener;
+  builderCfg = config.services.homelab-deploy.builder;
 
-  # Build command line arguments from configuration
-  args = lib.concatStringsSep " " ([
-    "--hostname ${lib.escapeShellArg cfg.hostname}"
-    "--tier ${cfg.tier}"
-    "--nats-url ${lib.escapeShellArg cfg.natsUrl}"
-    "--nkey-file ${lib.escapeShellArg cfg.nkeyFile}"
-    "--flake-url ${lib.escapeShellArg cfg.flakeUrl}"
-    "--timeout ${toString cfg.timeout}"
-    "--discover-subject ${lib.escapeShellArg cfg.discoverSubject}"
+  # Build command line arguments for listener from configuration
+  listenerArgs = lib.concatStringsSep " " ([
+    "--hostname ${lib.escapeShellArg listenerCfg.hostname}"
+    "--tier ${listenerCfg.tier}"
+    "--nats-url ${lib.escapeShellArg listenerCfg.natsUrl}"
+    "--nkey-file ${lib.escapeShellArg listenerCfg.nkeyFile}"
+    "--flake-url ${lib.escapeShellArg listenerCfg.flakeUrl}"
+    "--timeout ${toString listenerCfg.timeout}"
+    "--discover-subject ${lib.escapeShellArg listenerCfg.discoverSubject}"
   ]
-  ++ lib.optional (cfg.role != null) "--role ${lib.escapeShellArg cfg.role}"
-  ++ map (s: "--deploy-subject ${lib.escapeShellArg s}") cfg.deploySubjects
-  ++ lib.optionals cfg.metrics.enable [
+  ++ lib.optional (listenerCfg.role != null) "--role ${lib.escapeShellArg listenerCfg.role}"
+  ++ map (s: "--deploy-subject ${lib.escapeShellArg s}") listenerCfg.deploySubjects
+  ++ lib.optionals listenerCfg.metrics.enable [
     "--metrics-enabled"
-    "--metrics-addr ${lib.escapeShellArg cfg.metrics.address}"
+    "--metrics-addr ${lib.escapeShellArg listenerCfg.metrics.address}"
+  ]);
+
+  # Build command line arguments for builder from configuration
+  builderArgs = lib.concatStringsSep " " ([
+    "--nats-url ${lib.escapeShellArg builderCfg.natsUrl}"
+    "--nkey-file ${lib.escapeShellArg builderCfg.nkeyFile}"
+    "--config ${lib.escapeShellArg builderCfg.configFile}"
+    "--timeout ${toString builderCfg.timeout}"
+  ]
+  ++ lib.optionals builderCfg.metrics.enable [
+    "--metrics-enabled"
+    "--metrics-addr ${lib.escapeShellArg builderCfg.metrics.address}"
   ]);
 
   # Extract port from metrics address for firewall rule
-  metricsPort = let
-    addr = cfg.metrics.address;
+  extractPort = addr: let
     # Handle both ":9972" and "0.0.0.0:9972" formats
     parts = lib.splitString ":" addr;
   in lib.toInt (lib.last parts);
 
+  listenerMetricsPort = extractPort listenerCfg.metrics.address;
+  builderMetricsPort = extractPort builderCfg.metrics.address;
+
 in
 {
   options.services.homelab-deploy.listener = {
@@ -124,43 +139,136 @@ in
     };
   };
 
-  config = lib.mkIf cfg.enable {
-    systemd.services.homelab-deploy-listener = {
-      description = "homelab-deploy listener";
-      wantedBy = [ "multi-user.target" ];
-      after = [ "network-online.target" ];
-      wants = [ "network-online.target" ];
+  options.services.homelab-deploy.builder = {
+    enable = lib.mkEnableOption "homelab-deploy builder service";
 
-      # Prevent self-interruption during nixos-rebuild switch
-      # The service will continue running the old version until manually restarted
-      stopIfChanged = false;
-      restartIfChanged = false;
-
-      environment = cfg.environment // {
-        # Nix needs a writable cache for git flake fetching
-        XDG_CACHE_HOME = "/var/cache/homelab-deploy";
-      };
-
-      path = [ pkgs.git config.system.build.nixos-rebuild ];
-
-      serviceConfig = {
-        CacheDirectory = "homelab-deploy";
-        Type = "simple";
-        ExecStart = "${cfg.package}/bin/homelab-deploy listener ${args}";
-        Restart = "always";
-        RestartSec = 10;
-
-        # Minimal hardening - nixos-rebuild requires broad system access:
-        # - Write access to /nix/store for building
-        # - Kernel namespace support for nix sandbox builds
-        # - Ability to activate system configurations
-        # - Network access for fetching from git/cache
-        # Following the approach of nixos auto-upgrade which has no hardening
-      };
+    package = lib.mkOption {
+      type = lib.types.package;
+      default = self.packages.${pkgs.system}.homelab-deploy;
+      description = "The homelab-deploy package to use";
     };
 
-    networking.firewall.allowedTCPPorts = lib.mkIf (cfg.metrics.enable && cfg.metrics.openFirewall) [
-      metricsPort
-    ];
+    natsUrl = lib.mkOption {
+      type = lib.types.str;
+      description = "NATS server URL";
+      example = "nats://nats.example.com:4222";
+    };
+
+    nkeyFile = lib.mkOption {
+      type = lib.types.path;
+      description = "Path to NKey seed file for NATS authentication";
+      example = "/run/secrets/homelab-deploy-builder-nkey";
+    };
+
+    configFile = lib.mkOption {
+      type = lib.types.path;
+      description = "Path to builder configuration file (YAML)";
+      example = "/etc/homelab-deploy/builder.yaml";
+    };
+
+    timeout = lib.mkOption {
+      type = lib.types.int;
+      default = 1800;
+      description = "Build timeout in seconds per host";
+    };
+
+    environment = lib.mkOption {
+      type = lib.types.attrsOf lib.types.str;
+      default = { };
+      description = "Additional environment variables for the service";
+      example = { GIT_SSH_COMMAND = "ssh -i /run/secrets/deploy-key"; };
+    };
+
+    metrics = {
+      enable = lib.mkEnableOption "Prometheus metrics endpoint";
+
+      address = lib.mkOption {
+        type = lib.types.str;
+        default = ":9973";
+        description = "Address for Prometheus metrics HTTP server";
+        example = "127.0.0.1:9973";
+      };
+
+      openFirewall = lib.mkOption {
+        type = lib.types.bool;
+        default = false;
+        description = "Open firewall for metrics port";
+      };
+    };
   };
+
+  config = lib.mkMerge [
+    (lib.mkIf listenerCfg.enable {
+      systemd.services.homelab-deploy-listener = {
+        description = "homelab-deploy listener";
+        wantedBy = [ "multi-user.target" ];
+        after = [ "network-online.target" ];
+        wants = [ "network-online.target" ];
+
+        # Prevent self-interruption during nixos-rebuild switch
+        # The service will continue running the old version until manually restarted
+        stopIfChanged = false;
+        restartIfChanged = false;
+
+        environment = listenerCfg.environment // {
+          # Nix needs a writable cache for git flake fetching
+          XDG_CACHE_HOME = "/var/cache/homelab-deploy";
+        };
+
+        path = [ pkgs.git config.system.build.nixos-rebuild ];
+
+        serviceConfig = {
+          CacheDirectory = "homelab-deploy";
+          Type = "simple";
+          ExecStart = "${listenerCfg.package}/bin/homelab-deploy listener ${listenerArgs}";
+          Restart = "always";
+          RestartSec = 10;
+
+          # Minimal hardening - nixos-rebuild requires broad system access:
+          # - Write access to /nix/store for building
+          # - Kernel namespace support for nix sandbox builds
+          # - Ability to activate system configurations
+          # - Network access for fetching from git/cache
+          # Following the approach of nixos auto-upgrade which has no hardening
+        };
+      };
+
+      networking.firewall.allowedTCPPorts = lib.mkIf (listenerCfg.metrics.enable && listenerCfg.metrics.openFirewall) [
+        listenerMetricsPort
+      ];
+    })
+
+    (lib.mkIf builderCfg.enable {
+      systemd.services.homelab-deploy-builder = {
+        description = "homelab-deploy builder";
+        wantedBy = [ "multi-user.target" ];
+        after = [ "network-online.target" ];
+        wants = [ "network-online.target" ];
+
+        environment = builderCfg.environment // {
+          # Nix needs a writable cache for git flake fetching
+          XDG_CACHE_HOME = "/var/cache/homelab-deploy-builder";
+        };
+
+        path = [ pkgs.git pkgs.nix ];
+
+        serviceConfig = {
+          CacheDirectory = "homelab-deploy-builder";
+          Type = "simple";
+          ExecStart = "${builderCfg.package}/bin/homelab-deploy builder ${builderArgs}";
+          Restart = "always";
+          RestartSec = 10;
+
+          # Minimal hardening - nix build requires broad system access:
+          # - Write access to /nix/store for building
+          # - Kernel namespace support for nix sandbox builds
+          # - Network access for fetching from git/cache
+        };
+      };
+
+      networking.firewall.allowedTCPPorts = lib.mkIf (builderCfg.metrics.enable && builderCfg.metrics.openFirewall) [
+        builderMetricsPort
+      ];
+    })
+  ];
 }