fix: address PR #21 review round 3 — test coverage, trailing JSON, docs accuracy

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

Author: michaelmcnees

docs/superpowers/plans/2026-03-24-data-transformation.md

@@ -822,8 +822,9 @@ In `functions.go`, add to `collectionLib.CompileOptions()`:
 			cel.Overload("default_any_any",
 				[]*cel.Type{cel.DynType, cel.DynType},
 				cel.DynType,
+				cel.OverloadIsNonStrict(),
 				cel.BinaryBinding(func(lhs, rhs ref.Val) ref.Val {
-					if types.IsError(lhs) || types.IsUnknown(lhs) {
+					if types.IsError(lhs) || types.IsUnknown(lhs) || lhs == types.NullValue {
 						return rhs
 					}
 					return lhs
@@ -836,20 +837,20 @@ In `functions.go`, add to `collectionLib.CompileOptions()`:
 				cel.ListType(cel.DynType),
 				cel.UnaryBinding(func(val ref.Val) ref.Val {
 					list := val.(traits.Lister)
-					var result []ref.Val
+					var result []any
 					it := list.Iterator()
 					for it.HasNext() == types.True {
 						item := it.Next()
 						if sub, ok := item.(traits.Lister); ok {
 							subIt := sub.Iterator()
 							for subIt.HasNext() == types.True {
-								result = append(result, subIt.Next())
+								result = append(result, refToNative(subIt.Next()))
 							}
 						} else {
-							result = append(result, item)
+							result = append(result, refToNative(item))
 						}
 					}
-					return types.DefaultTypeAdapter.NativeToValue(nativeSlice(result))
+					return types.DefaultTypeAdapter.NativeToValue(result)
 				}),
 			),
 		),
@@ -974,11 +975,13 @@ func (l *jsonLib) CompileOptions() []cel.EnvOption {
 				cel.DynType,
 				cel.UnaryBinding(func(val ref.Val) ref.Val {
 					s := string(val.(types.String))
+					dec := json.NewDecoder(strings.NewReader(s))
+					dec.UseNumber()
 					var result any
-					if err := json.Unmarshal([]byte(s), &result); err != nil {
+					if err := dec.Decode(&result); err != nil {
 						return types.NewErr("jsonDecode: %v", err)
 					}
-					return types.DefaultTypeAdapter.NativeToValue(result)
+					return types.DefaultTypeAdapter.NativeToValue(normalizeJSONNumbers(result))
 				}),
 			),
 		),
@@ -1091,11 +1094,20 @@ func (l *timeLib) CompileOptions() []cel.EnvOption {
 				cel.TimestampType,
 				cel.UnaryBinding(func(val ref.Val) ref.Val {
 					s := string(val.(types.String))
-					t, err := time.Parse(time.RFC3339, s)
-					if err != nil {
-						return types.NewErr("parseTimestamp: %v", err)
+					layouts := []string{
+						time.RFC3339,
+						time.RFC3339Nano,
+						"2006-01-02T15:04:05",
+						"2006-01-02",
+						"01/02/2006",
+						"Jan 2, 2006",
+					}
+					for _, layout := range layouts {
+						if t, err := time.Parse(layout, s); err == nil {
+							return types.Timestamp{Time: t}
+						}
 					}
-					return types.Timestamp{Time: t}
+					return types.NewErr("parseTimestamp: unable to parse %q (tried RFC3339, ISO 8601 date, and common formats)", s)
 				}),
 			),
 		),
@@ -1258,27 +1270,29 @@ In `examples/data-transform-api-to-db.yaml`:
 ```yaml
 name: data-transform-api-to-db
 description: >
-  Fetches user data from an API, transforms each record using CEL
-  expressions to match a database schema, and inserts the normalized
-  records into Postgres. Demonstrates map(), obj(), toLower(), and
-  type coercion without requiring an AI model.
+  Fetches a user from an API, transforms the record using CEL expressions
+  to match a database schema, and inserts the normalized data into Postgres.
+  Demonstrates toLower() and string functions without requiring an AI model.
 
 steps:
-  - name: fetch-users
+  - name: fetch-user
     action: http/request
     timeout: "15s"
     params:
       method: GET
-      url: "https://jsonplaceholder.typicode.com/users"
+      url: "https://jsonplaceholder.typicode.com/users/1"
       headers:
         Accept: "application/json"
 
-  - name: store-users
+  - name: store-user
     action: postgres/query
     credential: app-db
     params:
       query: "INSERT INTO users (username, email, city) VALUES ($1, $2, $3)"
-      params: "{{ steps['fetch-users'].output.json.map(u, [u.username.toLower(), u.email.toLower(), u.address.city]) }}"
+      args:
+        - "{{ steps['fetch-user'].output.json.username.toLower() }}"
+        - "{{ steps['fetch-user'].output.json.email.toLower() }}"
+        - "{{ steps['fetch-user'].output.json.address.city }}"
 ```
 
 - [ ] **Step 2: Create AI enrichment example**
@@ -1346,7 +1360,7 @@ steps:
       query: >
         INSERT INTO urgent_tickets (priority, category, products, raw_body)
         VALUES ($1, $2, $3, $4)
-      params:
+      args:
         - "{{ steps.classify.output.json.priority }}"
         - "{{ steps.classify.output.json.category }}"
         - "{{ jsonEncode(steps.classify.output.json.products) }}"

internal/cel/functions.go

@@ -280,6 +280,10 @@ func (l *jsonLib) CompileOptions() []cel.EnvOption {
 					if err := dec.Decode(&result); err != nil {
 						return types.NewErr("jsonDecode: %v", err)
 					}
+					// Reject trailing data (e.g., "{} {}")
+					if dec.More() {
+						return types.NewErr("jsonDecode: unexpected trailing data after JSON value")
+					}
 					return types.DefaultTypeAdapter.NativeToValue(normalizeJSONNumbers(result))
 				}),
 			),

internal/cel/functions_test.go

@@ -253,20 +253,31 @@ func TestFunc_Default(t *testing.T) {
 	eval, err := NewEvaluator()
 	require.NoError(t, err)
 	tests := []struct {
-		name string
-		expr string
-		want any
+		name    string
+		expr    string
+		want    any
+		wantErr bool
 	}{
-		{"value exists returns value", `default("hello", "fallback")`, "hello"},
-		{"empty string returns empty string", `default("", "fallback")`, ""},
-		{"null returns fallback", `default(null, "fallback")`, "fallback"},
-		{"non-null int unchanged", `default(42, 0)`, int64(42)},
+		{"value exists returns value", `default("hello", "fallback")`, "hello", false},
+		{"empty string returns empty string", `default("", "fallback")`, "", false},
+		{"null returns fallback", `default(null, "fallback")`, "fallback", false},
+		{"non-null int unchanged", `default(42, 0)`, int64(42), false},
+		{
+			"missing_key_returns_fallback",
+			`default(steps.fetch.output.missing, "fallback")`,
+			"fallback",
+			false,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			result, err := eval.Eval(tt.expr, newTestContext())
-			require.NoError(t, err)
-			assert.Equal(t, tt.want, result)
+			if tt.wantErr {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.want, result)
+			}
 		})
 	}
 }
@@ -362,6 +373,11 @@ func TestFunc_JsonDecode(t *testing.T) {
 			expr:    `jsonDecode("not json")`,
 			wantErr: true,
 		},
+		{
+			name:    "trailing_data",
+			expr:    `jsonDecode("{} {}")`,
+			wantErr: true,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

site/src/content/docs/getting-started/data-transformations.md

@@ -86,9 +86,8 @@ steps:
 
   - name: classify
     action: ai/completion
+    credential: openai
     params:
-      provider: openai
-      credential: openai
       model: gpt-4o-mini
       prompt: >
         Classify the following support ticket. Extract the priority, product
@@ -180,9 +179,8 @@ steps:
 
   - name: enrich
     action: ai/completion
+    credential: openai
     params:
-      provider: openai
-      credential: openai
       model: gpt-4o-mini
       prompt: >
         Analyze the following product reviews and classify the sentiment