feat(cel): merge config env with MANTLE_ENV_, log overrides (#74)

Rename envVars() to mergeEnvVars(configEnv) which starts with config
values from mantle.yaml env: section, then overlays MANTLE_ENV_*
OS environment variables. When a key exists in both sources, the OS
env var wins and an info log is emitted. Add SetConfigEnv setter to
avoid changing the NewEvaluator signature.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michaelmcnees

packages/engine/internal/cel/cel.go

@@ -2,6 +2,7 @@ package cel
 
 import (
 	"fmt"
+	"log/slog"
 	"os"
 	"reflect"
 	"strings"
@@ -25,7 +26,8 @@ const maxProgramCacheSize = 10000
 // Evaluator evaluates CEL expressions against a runtime context.
 type Evaluator struct {
 	env          *cel.Env
-	envCache     map[string]string // cached, filtered environment variables
+	configEnv    map[string]string      // config-sourced env values from mantle.yaml
+	envCache     map[string]string      // cached, filtered environment variables
 	programMu    sync.Mutex
 	programCache map[string]cel.Program // expression string -> compiled cel.Program
 }
@@ -45,7 +47,7 @@ func NewEvaluator() (*Evaluator, error) {
 	if err != nil {
 		return nil, fmt.Errorf("creating CEL environment: %w", err)
 	}
-	return &Evaluator{env: env, envCache: envVars(), programCache: make(map[string]cel.Program)}, nil
+	return &Evaluator{env: env, envCache: mergeEnvVars(nil), programCache: make(map[string]cel.Program)}, nil
 }
 
 // Eval evaluates a CEL expression and returns the result as a Go value.
@@ -206,17 +208,37 @@ func (e *Evaluator) resolveValue(v any, ctx *Context) (any, error) {
 	}
 }
 
-// envVars returns only environment variables with the MANTLE_ENV_ prefix,
-// stripping the prefix for cleaner access (e.g., MANTLE_ENV_FOO -> env.FOO).
+// SetConfigEnv sets the config-sourced env values and rebuilds the env cache.
+// This merges config values with MANTLE_ENV_* environment variables, where
+// OS env vars take precedence over config values.
+func (e *Evaluator) SetConfigEnv(configEnv map[string]string) {
+	e.configEnv = configEnv
+	e.envCache = mergeEnvVars(configEnv)
+}
+
+// mergeEnvVars builds the env map available to CEL expressions.
+// It starts with config-sourced values (from the env: section in mantle.yaml),
+// then overlays MANTLE_ENV_* environment variables (stripping the prefix).
+// When a key exists in both, the OS env var wins and an info log is emitted.
 // This prevents CEL expressions from reading sensitive variables like
 // MANTLE_ENCRYPTION_KEY, MANTLE_DATABASE_URL, or AWS_SECRET_ACCESS_KEY.
-func envVars() map[string]string {
+func mergeEnvVars(configEnv map[string]string) map[string]string {
 	env := make(map[string]string)
+
+	// Start with config values.
+	for k, v := range configEnv {
+		env[k] = v
+	}
+
+	// Overlay MANTLE_ENV_* from OS environment (env var wins).
 	const prefix = "MANTLE_ENV_"
 	for _, e := range os.Environ() {
 		parts := strings.SplitN(e, "=", 2)
 		if len(parts) == 2 && strings.HasPrefix(parts[0], prefix) {
 			key := strings.TrimPrefix(parts[0], prefix)
+			if _, exists := env[key]; exists {
+				slog.Info("env variable overrides config", "key", prefix+key, "config_key", "env."+key)
+			}
 			env[key] = parts[1]
 		}
 	}

packages/engine/internal/cel/cel_test.go

@@ -296,25 +296,115 @@ func TestEval_EnvVarBlocksSensitive(t *testing.T) {
 }
 
 func TestEnvVars_PrefixStripping(t *testing.T) {
-	// Directly test the envVars function.
+	// Directly test the mergeEnvVars function.
 	os.Setenv("MANTLE_ENV_TEST_KEY", "test-value")
 	defer os.Unsetenv("MANTLE_ENV_TEST_KEY")
 
 	os.Setenv("MANTLE_DATABASE_URL", "should-not-appear")
 	defer os.Unsetenv("MANTLE_DATABASE_URL")
 
-	result := envVars()
+	result := mergeEnvVars(nil)
 
 	if v, ok := result["TEST_KEY"]; !ok || v != "test-value" {
-		t.Errorf("envVars()[TEST_KEY] = %q, %v; want %q, true", v, ok, "test-value")
+		t.Errorf("mergeEnvVars()[TEST_KEY] = %q, %v; want %q, true", v, ok, "test-value")
 	}
 
 	if _, ok := result["MANTLE_DATABASE_URL"]; ok {
-		t.Error("envVars() should not contain MANTLE_DATABASE_URL")
+		t.Error("mergeEnvVars() should not contain MANTLE_DATABASE_URL")
 	}
 
 	if _, ok := result["DATABASE_URL"]; ok {
-		t.Error("envVars() should not contain DATABASE_URL (MANTLE_ prefix without ENV_)")
+		t.Error("mergeEnvVars() should not contain DATABASE_URL (MANTLE_ prefix without ENV_)")
+	}
+}
+
+func TestEnvVars_ConfigEnvMerge(t *testing.T) {
+	configEnv := map[string]string{
+		"APP_NAME": "my-workflow-app",
+		"REGION":   "us-east-1",
+	}
+
+	eval, err := NewEvaluator()
+	if err != nil {
+		t.Fatalf("NewEvaluator() error: %v", err)
+	}
+	eval.SetConfigEnv(configEnv)
+
+	ctx := newTestContext()
+
+	result, err := eval.Eval(`env.APP_NAME`, ctx)
+	if err != nil {
+		t.Fatalf("Eval(env.APP_NAME) error: %v", err)
+	}
+	if result != "my-workflow-app" {
+		t.Errorf("env.APP_NAME = %v, want %q", result, "my-workflow-app")
+	}
+
+	result, err = eval.Eval(`env.REGION`, ctx)
+	if err != nil {
+		t.Fatalf("Eval(env.REGION) error: %v", err)
+	}
+	if result != "us-east-1" {
+		t.Errorf("env.REGION = %v, want %q", result, "us-east-1")
+	}
+}
+
+func TestEnvVars_OsEnvOverridesConfig(t *testing.T) {
+	t.Setenv("MANTLE_ENV_REGION", "eu-west-1")
+
+	configEnv := map[string]string{
+		"REGION":   "us-east-1",
+		"APP_NAME": "my-app",
+	}
+
+	eval, err := NewEvaluator()
+	if err != nil {
+		t.Fatalf("NewEvaluator() error: %v", err)
+	}
+	eval.SetConfigEnv(configEnv)
+
+	ctx := newTestContext()
+
+	// MANTLE_ENV_REGION should override the config value.
+	result, err := eval.Eval(`env.REGION`, ctx)
+	if err != nil {
+		t.Fatalf("Eval(env.REGION) error: %v", err)
+	}
+	if result != "eu-west-1" {
+		t.Errorf("env.REGION = %v, want %q (OS env override)", result, "eu-west-1")
+	}
+
+	// APP_NAME should still come from config (no OS env override).
+	result, err = eval.Eval(`env.APP_NAME`, ctx)
+	if err != nil {
+		t.Fatalf("Eval(env.APP_NAME) error: %v", err)
+	}
+	if result != "my-app" {
+		t.Errorf("env.APP_NAME = %v, want %q", result, "my-app")
+	}
+}
+
+func TestEnvVars_NilConfigEnv(t *testing.T) {
+	eval, err := NewEvaluator()
+	if err != nil {
+		t.Fatalf("NewEvaluator() error: %v", err)
+	}
+
+	// SetConfigEnv(nil) should not panic.
+	eval.SetConfigEnv(nil)
+
+	ctx := newTestContext()
+
+	// env map should still work (just no config values).
+	t.Setenv("MANTLE_ENV_SAFE_KEY", "safe-value")
+	eval.SetConfigEnv(nil)
+
+	result, err := eval.Eval(`env.SAFE_KEY`, ctx)
+	if err != nil {
+		t.Fatalf("Eval(env.SAFE_KEY) error: %v", err)
+	}
+	if result != "safe-value" {
+		t.Errorf("env.SAFE_KEY = %v, want %q", result, "safe-value")
 	}
 }