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>

internal/metrics/build_metrics.go

@@ -0,0 +1,99 @@
+package metrics
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+// BuildCollector holds all Prometheus metrics for the builder.
+type BuildCollector struct {
+	buildsTotal              *prometheus.CounterVec
+	buildHostTotal           *prometheus.CounterVec
+	buildDuration            *prometheus.HistogramVec
+	buildLastTimestamp       *prometheus.GaugeVec
+	buildLastSuccessTime     *prometheus.GaugeVec
+	buildLastFailureTime     *prometheus.GaugeVec
+}
+
+// NewBuildCollector creates a new build metrics collector and registers it with the given registerer.
+func NewBuildCollector(reg prometheus.Registerer) *BuildCollector {
+	c := &BuildCollector{
+		buildsTotal: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "homelab_deploy_builds_total",
+				Help: "Total builds processed",
+			},
+			[]string{"repo", "status"},
+		),
+		buildHostTotal: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "homelab_deploy_build_host_total",
+				Help: "Total host builds processed",
+			},
+			[]string{"repo", "host", "status"},
+		),
+		buildDuration: prometheus.NewHistogramVec(
+			prometheus.HistogramOpts{
+				Name:    "homelab_deploy_build_duration_seconds",
+				Help:    "Build execution time per host",
+				Buckets: []float64{30, 60, 120, 300, 600, 900, 1200, 1800, 3600},
+			},
+			[]string{"repo", "host"},
+		),
+		buildLastTimestamp: prometheus.NewGaugeVec(
+			prometheus.GaugeOpts{
+				Name: "homelab_deploy_build_last_timestamp",
+				Help: "Timestamp of last build attempt",
+			},
+			[]string{"repo"},
+		),
+		buildLastSuccessTime: prometheus.NewGaugeVec(
+			prometheus.GaugeOpts{
+				Name: "homelab_deploy_build_last_success_timestamp",
+				Help: "Timestamp of last successful build",
+			},
+			[]string{"repo"},
+		),
+		buildLastFailureTime: prometheus.NewGaugeVec(
+			prometheus.GaugeOpts{
+				Name: "homelab_deploy_build_last_failure_timestamp",
+				Help: "Timestamp of last failed build",
+			},
+			[]string{"repo"},
+		),
+	}
+
+	reg.MustRegister(c.buildsTotal)
+	reg.MustRegister(c.buildHostTotal)
+	reg.MustRegister(c.buildDuration)
+	reg.MustRegister(c.buildLastTimestamp)
+	reg.MustRegister(c.buildLastSuccessTime)
+	reg.MustRegister(c.buildLastFailureTime)
+
+	return c
+}
+
+// RecordBuildSuccess records a successful build.
+func (c *BuildCollector) RecordBuildSuccess(repo string) {
+	c.buildsTotal.WithLabelValues(repo, "success").Inc()
+	c.buildLastTimestamp.WithLabelValues(repo).SetToCurrentTime()
+	c.buildLastSuccessTime.WithLabelValues(repo).SetToCurrentTime()
+}
+
+// RecordBuildFailure records a failed build.
+func (c *BuildCollector) RecordBuildFailure(repo, errorCode string) {
+	c.buildsTotal.WithLabelValues(repo, "failure").Inc()
+	c.buildLastTimestamp.WithLabelValues(repo).SetToCurrentTime()
+	c.buildLastFailureTime.WithLabelValues(repo).SetToCurrentTime()
+}
+
+// RecordHostBuildSuccess records a successful host build.
+func (c *BuildCollector) RecordHostBuildSuccess(repo, host string, durationSeconds float64) {
+	c.buildHostTotal.WithLabelValues(repo, host, "success").Inc()
+	c.buildDuration.WithLabelValues(repo, host).Observe(durationSeconds)
+}
+
+// RecordHostBuildFailure records a failed host build.
+func (c *BuildCollector) RecordHostBuildFailure(repo, host string, durationSeconds float64) {
+	c.buildHostTotal.WithLabelValues(repo, host, "failure").Inc()
+	c.buildDuration.WithLabelValues(repo, host).Observe(durationSeconds)
+}

internal/metrics/server.go

@@ -74,6 +74,11 @@ func (s *Server) Collector() *Collector {
 	return s.collector
 }
 
+// Registry returns the Prometheus registry.
+func (s *Server) Registry() *prometheus.Registry {
+	return s.registry
+}
+
 // ScrapeCh returns a channel that receives a signal each time the metrics endpoint is scraped.
 func (s *Server) ScrapeCh() <-chan struct{} {
 	return s.scrapeCh