docs: update provider docs and improve error handling

- Add documentation for check modes, built-in CEL functions, and
  standard
  extensions in checks README
- Clarify default health behavior in HTTP provider docs
- Update Helm and Satellite provider docs for accuracy and new options
- Improve error context in TLS and HTTP providers
- Make config loading thread-safe and expose validation errors via
  method
- Use maps.Copy and slices utilities for safer map/slice operations
- Add input validation in Kubernetes resource fetcher
- Avoid panics on provider instantiation errors
- Minor test and code cleanup

Author: isometry

pkg/checks/README.md

@@ -21,6 +21,45 @@ ph context my-app -o yaml
 
 CEL expressions must evaluate to a boolean (`true` for healthy, `false` for unhealthy). Expressions have access to provider-specific context variables (e.g., `response` for HTTP, `resource` for Kubernetes).
 
+### Check Modes
+
+Each check can optionally specify a `mode` field:
+
+- **default** (no `mode` field): The expression is evaluated once against the full provider context.
+- **`mode: "each"`**: The expression is evaluated per-item for providers that return collections (e.g., Kubernetes with label selectors). Each item is evaluated independently, and failures reference the specific item.
+
+```yaml
+checks:
+  - check: "resource.status.readyReplicas >= resource.spec.replicas"
+    message: "Not all replicas ready"
+    mode: "each"
+```
+
+## Built-in Functions
+
+The following custom functions are available in all CEL expressions:
+
+- `time.Now()` - Returns the current timestamp
+- `time.Since(timestamp)` - Returns the duration elapsed since the given timestamp
+- `time.Until(timestamp)` - Returns the duration until the given timestamp
+
+```yaml
+checks:
+  - check: "time.Until(tls.validUntil) > duration('168h')"
+    message: "Certificate expires within 7 days"
+```
+
+## Standard Extensions
+
+The following CEL extension libraries are available:
+
+- **Strings**: Additional string functions (`charAt`, `indexOf`, `replace`, `split`, `substring`, `trim`, `upperAscii`, `lowerAscii`)
+- **Lists**: List manipulation functions (`slice`, `flatten`)
+- **Encoders**: Base64 encoding/decoding (`base64.encode`, `base64.decode`)
+- **Math**: Math functions (`math.greatest`, `math.least`)
+- **Sets**: Set operations (`sets.contains`, `sets.intersects`, `sets.equivalent`)
+- **Bindings**: Variable binding via `cel.bind()`
+
 ## Common CEL Patterns
 
 > **Note:** The examples below use `data` as a generic illustrative placeholder variable. Actual CEL context variables are provider-specific — for example, `response` for [HTTP](../provider/http), `resource` for [Kubernetes](../provider/kubernetes), `tls` for [TLS](../provider/tls), `health` for [Vault](../provider/vault), and `release`/`chart` for [Helm](../provider/helm). See each provider's README for its available CEL variables, or use `ph context` to inspect the evaluation context.

pkg/commands/migrate/migrate.go

@@ -3,6 +3,7 @@ package migrate
 import (
 	"bytes"
 	"fmt"
+	"maps"
 	"os"
 	"strings"
 
@@ -51,9 +52,7 @@ func transformRest(config map[string]any) {
 	if !ok {
 		return
 	}
-	for k, v := range reqMap {
-		config[k] = v
-	}
+	maps.Copy(config, reqMap)
 	delete(config, "request")
 }
 

pkg/commands/shared/providers.go

@@ -3,6 +3,7 @@ package shared
 
 import (
 	"fmt"
+	"log/slog"
 
 	"github.com/spf13/cobra"
 
@@ -24,7 +25,8 @@ func AddProviderSubcommands(parent *cobra.Command, opts ProviderSubcommandOption
 	for _, providerType := range provider.ProviderList() {
 		instance, err := provider.New(providerType)
 		if err != nil {
-			panic(err)
+			slog.Error("failed to instantiate provider", "type", providerType, "error", err)
+			continue
 		}
 
 		if opts.RequireChecks && !provider.SupportsChecks(instance) {

pkg/commands/validate/validate.go

@@ -91,7 +91,7 @@ func collectResults(result *config.LoadResult) ValidationSummary {
 	var results []ValidationResult
 
 	// Add errors from config loading (instances that failed to load)
-	for _, err := range result.ValidationErrors {
+	for _, err := range result.ValidationErrors() {
 		// Try to extract instance info from InstanceError
 		if instErr, ok := err.(provider.InstanceError); ok {
 			results = append(results, ValidationResult{

pkg/config/config.go

@@ -6,6 +6,8 @@ import (
 	"fmt"
 	"log/slog"
 	"path/filepath"
+	"slices"
+	"sync"
 
 	"github.com/fsnotify/fsnotify"
 	"github.com/spf13/viper"
@@ -25,23 +27,24 @@ type abstractConfig map[string]any
 // Structure: map[providerType][]provider.Instance
 type concreteConfig map[string][]provider.Instance
 
-// LoadResult wraps config with validation errors from loading
+// LoadResult wraps config with validation errors from loading.
+// It is safe for concurrent use; the config reload callback (from fsnotify)
+// writes under a write lock, while GetInstances and friends read under a read lock.
 type LoadResult struct {
+	mu               sync.RWMutex
 	config           concreteConfig
-	ValidationErrors []error
-	v                *viper.Viper // viper instance for config reloading
+	validationErrors []error
+	v                *viper.Viper   // viper instance for config reloading
+	log              *slog.Logger   // logger captured at Load time
 }
 
-var log *slog.Logger
-
 // Load loads and validates configuration from the specified paths.
 // If strict is true, validation errors are collected; otherwise invalid instances are skipped with warnings.
 func Load(ctx context.Context, configPaths []string, configName string, strict bool) (*LoadResult, error) {
-	log = phctx.Logger(ctx)
-
 	result := &LoadResult{
 		config: make(concreteConfig),
 		v:      phctx.Viper(ctx), // use viper from context (has :: delimiter)
+		log:    phctx.Logger(ctx),
 	}
 
 	if err := result.initialize(configPaths, configName, strict); err != nil {
@@ -52,24 +55,37 @@ func Load(ctx context.Context, configPaths []string, configName string, strict b
 
 // HasErrors returns true if any validation errors were collected.
 func (r *LoadResult) HasErrors() bool {
-	return len(r.ValidationErrors) > 0
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return len(r.validationErrors) > 0
+}
+
+// ValidationErrors returns a copy of the validation errors.
+func (r *LoadResult) ValidationErrors() []error {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return slices.Clone(r.validationErrors)
 }
 
 // EnforceStrict logs all validation errors and returns an error if any exist.
 // Used in strict mode to abort on configuration errors.
 func (r *LoadResult) EnforceStrict(log *slog.Logger) error {
-	if !r.HasErrors() {
+	errs := r.ValidationErrors()
+	if len(errs) == 0 {
 		return nil
 	}
-	for _, e := range r.ValidationErrors {
+	for _, e := range errs {
 		log.Error("configuration error", slog.Any("error", e))
 	}
-	return fmt.Errorf("configuration validation failed with %d error(s)", len(r.ValidationErrors))
+	return fmt.Errorf("configuration validation failed with %d error(s)", len(errs))
 }
 
 // GetInstances returns a flat slice of all loaded provider instances.
 func (r *LoadResult) GetInstances() []provider.Instance {
-	flatInstances := make([]provider.Instance, 0, r.totalInstances())
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	flatInstances := make([]provider.Instance, 0, r.totalInstancesLocked())
 
 	for _, instances := range r.config {
 		flatInstances = append(flatInstances, instances...)
@@ -80,7 +96,7 @@ func (r *LoadResult) GetInstances() []provider.Instance {
 
 // initialize sets up provider configuration using viper
 func (r *LoadResult) initialize(configPaths []string, configName string, strict bool) (err error) {
-	log.Debug("initializing server configuration")
+	r.log.Debug("initializing server configuration")
 
 	// r.v is already set from context with :: delimiter
 
@@ -95,52 +111,62 @@ func (r *LoadResult) initialize(configPaths []string, configName string, strict
 
 		if err = r.v.ReadInConfig(); err != nil {
 			if _, ok := err.(viper.ConfigFileNotFoundError); ok {
-				log.Info("no configuration file found - using defaults")
+				r.log.Info("no configuration file found - using defaults")
 			} else {
-				log.Error("failed to read config", "error", err)
+				r.log.Error("failed to read config", "error", err)
 				return err
 			}
 		} else {
-			log.Info("read config", slog.String("file", r.v.ConfigFileUsed()))
+			r.log.Info("read config", slog.String("file", r.v.ConfigFileUsed()))
 			r.v.WatchConfig()
 			r.v.OnConfigChange(func(e fsnotify.Event) {
-				log.Debug("config change")
+				r.log.Debug("config change")
 				if err := r.v.ReadInConfig(); err != nil {
-					log.Error("failed to read config", "error", err)
+					r.log.Error("failed to read config", "error", err)
 					return
 				}
 
+				r.mu.Lock()
 				prevConfig := r.config
-				prevErrors := r.ValidationErrors
+				prevErrors := r.validationErrors
+				r.mu.Unlock()
 
 				if err := r.update(strict); err != nil {
-					log.Error("failed to load config", "error", err)
+					r.log.Error("failed to load config", "error", err)
+					r.mu.Lock()
 					r.config = prevConfig
-					r.ValidationErrors = prevErrors
+					r.validationErrors = prevErrors
+					r.mu.Unlock()
 					return
 				}
 
-				if strict && r.HasErrors() {
-					for _, e := range r.ValidationErrors {
-						log.Error("configuration error", slog.Any("error", e))
+				r.mu.RLock()
+				hasErrors := len(r.validationErrors) > 0
+				r.mu.RUnlock()
+
+				if strict && hasErrors {
+					for _, e := range r.ValidationErrors() {
+						r.log.Error("configuration error", slog.Any("error", e))
 					}
-					log.Warn("config reload rejected due to strict validation errors")
+					r.log.Warn("config reload rejected due to strict validation errors")
+					r.mu.Lock()
 					r.config = prevConfig
-					r.ValidationErrors = prevErrors
+					r.validationErrors = prevErrors
+					r.mu.Unlock()
 					return
 				}
 
-				log.Info("config reloaded", slog.Any("instances", r.countByProvider()))
+				r.log.Info("config reloaded", slog.Any("instances", r.countByProvider()))
 			})
 		}
 	}
 
 	if err := r.update(strict); err != nil {
-		log.Error("failed to load config", "error", err)
+		r.log.Error("failed to load config", "error", err)
 		return err
 	}
 
-	log.Info("config loaded", slog.Any("instances", r.countByProvider()))
+	r.log.Info("config loaded", slog.Any("instances", r.countByProvider()))
 
 	return nil
 }
@@ -149,7 +175,7 @@ func (r *LoadResult) update(strict bool) error {
 	raw := make(map[string]any)
 
 	if err := r.v.Unmarshal(&raw); err != nil {
-		log.Error("failed to unmarshal config", "error", err)
+		r.log.Error("failed to unmarshal config", "error", err)
 		return err
 	}
 
@@ -160,7 +186,7 @@ func (r *LoadResult) update(strict bool) error {
 
 	processed, err := ProcessIncludes(raw, basePath, nil)
 	if err != nil {
-		log.Error("failed to process includes", "error", err)
+		r.log.Error("failed to process includes", "error", err)
 		return fmt.Errorf("failed to process includes: %w", err)
 	}
 
@@ -170,12 +196,16 @@ func (r *LoadResult) update(strict bool) error {
 	}
 
 	abstract := abstractConfig(components)
-	r.config, r.ValidationErrors = abstract.harden(strict)
+	config, validationErrors := abstract.harden(r.log, strict)
+
+	r.mu.Lock()
+	r.config, r.validationErrors = config, validationErrors
+	r.mu.Unlock()
 
 	return nil
 }
 
-func (a abstractConfig) harden(strict bool) (concreteConfig, []error) {
+func (a abstractConfig) harden(log *slog.Logger, strict bool) (concreteConfig, []error) {
 	concrete := make(concreteConfig)
 	var validationErrors []error
 
@@ -236,14 +266,18 @@ func (a abstractConfig) harden(strict bool) (concreteConfig, []error) {
 	return concrete, validationErrors
 }
 
-func (r *LoadResult) totalInstances() (count int) {
+// totalInstancesLocked returns the total instance count. Caller must hold r.mu.
+func (r *LoadResult) totalInstancesLocked() (count int) {
 	for _, instances := range r.config {
 		count += len(instances)
 	}
 	return count
 }
 
 func (r *LoadResult) countByProvider() map[string]int {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
 	counts := make(map[string]int)
 
 	for providerType, instances := range r.config {

pkg/config/config_test.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"context"
+	"log/slog"
 	"testing"
 	"time"
 
@@ -12,9 +13,7 @@ import (
 	"github.com/isometry/platform-health/pkg/provider/mock"
 )
 
-func init() {
-	log = phctx.Logger(context.Background())
-}
+var testLog = slog.Default()
 
 // testContext creates a context with a viper instance for testing
 func testContext(t *testing.T) context.Context {
@@ -136,7 +135,7 @@ func TestHarden(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			instances, _ := tt.abstract.harden(false)
+			instances, _ := tt.abstract.harden(testLog, false)
 			assert.Equal(t, tt.expectedProviders, len(instances), "providers count mismatch")
 			// Count total instances
 			total := 0
@@ -153,7 +152,7 @@ func TestHardenSetName(t *testing.T) {
 		"myinstance": map[string]any{"type": "mock", "spec": map[string]any{}},
 	}
 
-	result, _ := abstract.harden(false)
+	result, _ := abstract.harden(testLog, false)
 
 	// Check instance name is set from key
 	instance := findInstanceByName(result["mock"], "myinstance")
@@ -171,7 +170,7 @@ func TestHardenDurationParsing(t *testing.T) {
 		},
 	}
 
-	result, _ := abstract.harden(false)
+	result, _ := abstract.harden(testLog, false)
 	assert.Equal(t, 1, len(result["mock"]))
 
 	instance := findInstanceByName(result["mock"], "test").(*mock.Component)
@@ -224,7 +223,7 @@ func TestTotalInstances(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			assert.Equal(t, tt.expected, tt.result.totalInstances())
+			assert.Equal(t, tt.expected, len(tt.result.GetInstances()))
 		})
 	}
 }
@@ -281,7 +280,7 @@ func TestUnknownComponentKeysFixtures(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result, err := Load(testContext(t), []string{testdataPath}, tt.configFile, tt.strict)
 			assert.NoError(t, err, "Load should not return error")
-			assert.Equal(t, tt.expectErrors, len(result.ValidationErrors), "validation error count mismatch")
+			assert.Equal(t, tt.expectErrors, len(result.ValidationErrors()), "validation error count mismatch")
 			assert.Equal(t, tt.expectInstances, len(result.GetInstances()), "instance count mismatch")
 		})
 	}
@@ -332,7 +331,7 @@ func TestUnknownSpecKeysFixtures(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result, err := Load(testContext(t), []string{testdataPath}, tt.configFile, tt.strict)
 			assert.NoError(t, err, "Load should not return error")
-			assert.Equal(t, tt.expectErrors, len(result.ValidationErrors), "validation error count mismatch")
+			assert.Equal(t, tt.expectErrors, len(result.ValidationErrors()), "validation error count mismatch")
 			assert.Equal(t, tt.expectInstances, len(result.GetInstances()), "instance count mismatch")
 		})
 	}