@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/go/TestEntity_go.ts

@@ -1,4 +1,4 @@
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, opReachable } from '@voxgig/sdkgen'
 
 import {
   flatten,
@@ -27,7 +27,9 @@ import {
   isAuthActive,
   serverVarEnv,
   serverVariables,
-  entityDataIdField, envName, envToken
+  entityDataIdField, envName, envToken,
+  invalidRequest,
+  liveFlowNeeds, liveStrict, liveStrictNote,
 } from '@voxgig/sdkgen'
 
 
@@ -56,11 +58,11 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const entity: ModelEntity = props.entity
   const gomodule: string = props.gomodule
 
-  // The stream test streams the "list" op and asserts a 3-item collection, so
-  // it only applies to entities that declare a list op. Others (e.g. Batch =
-  // create/load) have no list endpoint — make_point errors and the stream
-  // yields nothing — so skip the stream test for them.
-  const hasList = !!(entity.op && (entity.op as any)?.list)
+  // The stream test streams the "list" op with no match and asserts a 3-item
+  // collection, so it only applies to an entity whose list a bare call can
+  // reach: not one without a list (e.g. Batch = create/load), not a nested
+  // list needing its parent's id, and not one whose routes all need an action.
+  const hasList = opReachable((entity.op as any)?.list, [])
 
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
@@ -105,6 +107,9 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const genCtx: GenCtx = { model, entity, gomodule, flow: basicflow, PROJUPPER }
 
+  const strict = liveStrict(model, target.name)
+  const strictConst = entity.name + 'EntityLiveStrict'
+
   // fmt is only used by the TextFieldMark Update branch — omit the import
   // when no step needs it, otherwise Go's strict unused-import check fails.
   const needsFmt = allSteps.some((s: any) =>
@@ -132,6 +137,10 @@ import (
 	vs "${gomodule}/utility/struct"
 )
 
+${liveStrictNote(strict, '//')}
+const ${strictConst} = ${strict}
+
+${hasList ? failHookType(entity) : ''}
 func Test${entity.Name}Entity(t *testing.T) {
 	t.Run("instance", func(t *testing.T) {
 		testsdk := sdk.TestSDK(nil, nil)
@@ -159,8 +168,11 @@ ${hasList ? `
 		// Fallback: streaming inactive -> yields the materialised list items.
 		base := sdk.TestSDK(seed, nil)
 		var seen []any
-		for item := range base.${entity.Name}(nil).Stream("list", nil, nil) {
-			seen = append(seen, item)
+		for si := range base.${entity.Name}(nil).Stream("list", nil, nil) {
+			if si.Err != nil {
+				t.Fatalf("stream failed: %v", si.Err)
+			}
+			seen = append(seen, si.Item)
 		}
 		if len(seen) != 3 {
 			t.Fatalf("expected 3 streamed items, got %d", len(seen))
@@ -176,11 +188,14 @@ ${hasList ? `
 				"feature": map[string]any{"streaming": map[string]any{"active": true}},
 			})
 			var got []any
-			for item := range streamSdk.${entity.Name}(nil).Stream("list", nil, nil) {
-				if sub, ok := item.([]any); ok {
+			for si := range streamSdk.${entity.Name}(nil).Stream("list", nil, nil) {
+				if si.Err != nil {
+					t.Fatalf("stream failed: %v", si.Err)
+				}
+				if sub, ok := si.Item.([]any); ok {
 					got = append(got, sub...)
 				} else {
-					got = append(got, item)
+					got = append(got, si.Item)
 				}
 			}
 			if len(got) != 3 {
@@ -188,8 +203,9 @@ ${hasList ? `
 			}
 		}
 	})
-` : ''}
-	t.Run("basic", func(t *testing.T) {
+${failureTests(model, entity)}` : ''}${validateTest(model, entity)}
+	t.Run("basic", func(tt *testing.T) {
+		var t testing.TB = tt
 		setup := ${entity.name}BasicSetup(nil)
 		// Per-op sdk-test-control.json skip — basic test exercises a flow
 		// with multiple ops; skipping any op skips the whole flow.
@@ -206,13 +222,8 @@ ${hasList ? `
 				return
 			}
 		}
-		// The basic flow consumes synthetic IDs from the fixture. In live mode
-		// without an *_ENTID env override, those IDs hit the live API and 4xx.
-		if setup.syntheticOnly {
-			t.Skip("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID JSON to run live")
-			return
-		}
-${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
+${liveFlowGate(entity, liveFlowNeeds(entity, basicflow), strict, strictConst,
+      PROJUPPER + '_TEST_' + envToken(entity.name) + '_ENTID', allSteps.length > 0)}`)
 
     // Check if the flow has a create step; if not, bootstrap entity data
     const flowHasCreate = allSteps.some((s: any) => s.o === 'create')
@@ -292,9 +303,8 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
     Content('\t)\n')
 
     Content(`
-	// Detect ENTID env override before envOverride consumes it. When live
-	// mode is on without a real override, the basic test runs against synthetic
-	// IDs from the fixture and 4xx's. Surface this so the test can skip.
+	// Whether *_ENTID supplied the idmap, read before envOverride consumes it:
+	// without it, the ids a live flow binds are the fixture's synthetic ones.
 	entidEnvRaw := os.Getenv("${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID")
 	idmapOverridden := entidEnvRaw != "" && strings.HasPrefix(strings.TrimSpace(entidEnvRaw), "{")
 
@@ -358,6 +368,51 @@ ${allSteps.length > 0 ? '\t\tclient := setup.client\n\n' : ''}`)
 })
 
 
+// The live prologue of a flow built from offline fixtures: blocked without
+// the ids it binds, a create-less load reading the first listed record, and
+// a lenient run observing its checks rather than failing on them.
+function liveFlowGate(entity: any, needs: any, strict: boolean, strictConst: string,
+  entidEnv: string, hasSteps: boolean): string {
+  let out = ''
+  if (0 < needs.keys.length) {
+    out += `		if setup.live {
+			for _, _liveKey := range []string{${needs.keys.map((k: string) => JSON.stringify(k)).join(', ')}} {
+				if setup.syntheticOnly || setup.idmap[_liveKey] == nil {
+					liveMiss(t, ${strictConst}, "Live entity test blocked: needs %s via ${entidEnv}", _liveKey)
+				}
+			}
+		}
+`
+  }
+  if (null != needs.blocked) {
+    out += `		if setup.live {
+			liveMiss(t, ${strictConst}, "Live entity test blocked: %s", ${JSON.stringify(needs.blocked)})
+		}
+`
+  }
+  if (hasSteps) {
+    out += '\t\tclient := setup.client\n'
+  }
+  if (null != needs.discover) {
+    const match = Object.entries(needs.discover)
+      .map(([k, v]: any) => `${JSON.stringify(k)}: setup.idmap[${JSON.stringify(v)}]`).join(', ')
+    out += `		if setup.live {
+			liveExisting(t, ${strictConst}, setup.data, ${JSON.stringify(entity.name)}, func() (any, error) {
+				return client.${entity.Name}(nil).List(map[string]any{${match}}, nil)
+			})
+		}
+`
+  }
+  if (!strict) {
+    out += `		if setup.live {
+			t = liveObserver{tt}
+		}
+`
+  }
+  return out + (hasSteps ? '\n' : '')
+}
+
+
 const generateCreate: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
   const ref = step.i.ref ?? entity.name + '_ref01'
@@ -715,6 +770,131 @@ const GENERATE_OP: Record<string, OpGen> = {
 }
 
 
+// A feature whose PreSpec hook panics, counting the PreUnexpected calls it sees.
+function failHookType(entity: ModelEntity): string {
+  return `
+type ${entity.name}FailHook struct {
+	sdk.BaseFeature
+	unexpected int
+}
+
+func (f *${entity.name}FailHook) PreSpec(ctx *sdk.Context) {
+	panic("${entity.name} hook failed")
+}
+
+func (f *${entity.name}FailHook) PreUnexpected(ctx *sdk.Context) {
+	f.unexpected++
+}
+`
+}
+
+
+// A failed operation ends a stream with its error as the last value: a
+// transport failure, and a hook that rejects the call. A panicking hook
+// fires PreUnexpected. The caller's ctrl stays its own.
+function failureTests(model: Model, entity: ModelEntity): string {
+  const Name = entity.Name
+  const SdkError = 'core.' + model.const.Name + 'Error'
+  return `
+	t.Run("stream-error", func(t *testing.T) {
+		offline := map[string]any{"net": map[string]any{"offline": true}}
+		var streamerr error
+		for si := range sdk.TestSDK(offline, nil).${Name}(nil).Stream("list", nil, nil) {
+			if si.Err != nil {
+				streamerr = si.Err
+			}
+		}
+		if nil == streamerr || !strings.Contains(streamerr.Error(), "offline") {
+			t.Fatalf("expected the transport failure as a stream value, got %v", streamerr)
+		}
+
+		quiet := map[string]any{"ctrl": map[string]any{"throw": false}}
+		for si := range sdk.TestSDK(offline, nil).${Name}(nil).Stream("list", nil, quiet) {
+			if si.Err != nil {
+				t.Fatalf("throw false: expected no error value, got %v", si.Err)
+			}
+		}
+
+		if fhHasFeature("rbac") {
+			denied := sdk.TestSDK(nil, map[string]any{
+				"feature": map[string]any{"rbac": map[string]any{"active": true, "deny": true}},
+			})
+			var denyerr error
+			for si := range denied.${Name}(nil).Stream("list", nil, nil) {
+				if si.Err != nil {
+					denyerr = si.Err
+				}
+			}
+			if sdkerr, ok := denyerr.(*${SdkError}); !ok || "rbac_denied" != sdkerr.Code {
+				t.Fatalf("expected the rbac denial as a stream value, got %v", denyerr)
+			}
+		}
+	})
+
+	t.Run("stream-ctrl", func(t *testing.T) {
+		explain := map[string]any{}
+		ctrl := map[string]any{"explain": explain}
+		for range sdk.TestSDK(nil, nil).${Name}(nil).Stream("list", nil, map[string]any{"ctrl": ctrl}) {
+		}
+		if _, has := ctrl["stream"]; has || 1 != len(ctrl) {
+			t.Fatalf("the stream changed the caller's ctrl")
+		}
+		if 0 == len(explain) {
+			t.Fatalf("the caller's explain record was not filled")
+		}
+	})
+
+	t.Run("unexpected", func(t *testing.T) {
+		hook := &${entity.name}FailHook{
+			BaseFeature: sdk.BaseFeature{Version: "0.0.1", Name: "failhook", Active: true}}
+		client := sdk.TestSDK(nil, map[string]any{"extend": []any{hook}})
+
+		_, err := client.${Name}(nil).List(nil, nil)
+		if nil == err || !strings.Contains(err.Error(), "hook failed") {
+			t.Fatalf("expected the hook's failure, got %v", err)
+		}
+		if 0 == hook.unexpected {
+			t.Fatalf("PreUnexpected did not fire")
+		}
+
+		fired := hook.unexpected
+		if _, err := client.${Name}(nil).List(nil, map[string]any{"throw": false}); nil != err {
+			t.Fatalf("throw false: expected no error, got %v", err)
+		}
+		if fired == hook.unexpected {
+			t.Fatalf("throw false: PreUnexpected did not fire")
+		}
+	})
+`
+}
+
+
+// An invalid request fails with validate's own error, before it is sent.
+function validateTest(model: Model, entity: ModelEntity): string {
+  const bad = invalidRequest(entity)
+  if (null == bad) {
+    return ''
+  }
+  const SdkError = 'core.' + model.const.Name + 'Error'
+  const args = Object.entries(bad.args)
+    .map(([k, v]) => JSON.stringify(k) + ': ' + JSON.stringify(v)).join(', ')
+  return `
+	t.Run("validate", func(t *testing.T) {
+		if !fhHasFeature("validate") {
+			t.Skip("feature not present in this SDK: validate")
+		}
+		client := sdk.TestSDK(nil, map[string]any{
+			"feature": map[string]any{"validate": map[string]any{"active": true}},
+		})
+		_, err := client.${entity.Name}(nil).${bad.op[0].toUpperCase() + bad.op.slice(1)}(map[string]any{${args}}, nil)
+		if sdkerr, ok := err.(*${SdkError}); !ok || "validate_failed" != sdkerr.Code {
+			t.Fatalf("expected validate_failed, got %v", err)
+		}
+	})
+`
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/go/fragment/Entity.fragment.go

@@ -54,8 +54,7 @@ func NewEntyClass(client *core.ProjectNameSDK, entopts map[string]any) *EntyClas
 func (e *EntyClass) GetName() string { return e.name }
 
 // An entity prints and serialises as its data, as ts's toString and toJSON
-// do: the match state can carry a query credential, and the client holds
-// the options.
+// do: the client it holds carries the options.
 func (e *EntyClass) String() string {
 	return "EntityName " + vs.Jsonify(e.data, map[string]any{"indent": 0})
 }
@@ -141,8 +140,8 @@ func (e *EntyClass) MatchTyped(match ...EntityName) EntityName {
 	return typedFrom[EntityName](e.Match())
 }
 
-func (e *EntyClass) Stream(action string, args map[string]any, callopts map[string]any) <-chan any {
-	out := make(chan any)
+func (e *EntyClass) Stream(action string, args map[string]any, callopts map[string]any) <-chan core.StreamItem {
+	out := make(chan core.StreamItem)
 
 	if callopts == nil {
 		callopts = map[string]any{}
@@ -184,7 +183,7 @@ func (e *EntyClass) Stream(action string, args map[string]any, callopts map[stri
 		ctx.Meta["stream_out"] = body
 	}
 
-	send := func(item any) bool {
+	send := func(item core.StreamItem) bool {
 		select {
 		case <-signal:
 			return false
@@ -193,89 +192,107 @@ func (e *EntyClass) Stream(action string, args map[string]any, callopts map[stri
 		}
 	}
 
+	// What MakeError or Done hands back: the error, as the last value, or
+	// under `throw: false` the data there is.
+	sendData := func(data any, err error) {
+		if err != nil {
+			send(core.StreamItem{Err: err})
+			return
+		}
+		switch d := data.(type) {
+		case []any:
+			for _, item := range d {
+				if !send(core.StreamItem{Item: item}) {
+					return
+				}
+			}
+		case nil:
+			// nothing to yield
+		default:
+			send(core.StreamItem{Item: d})
+		}
+	}
+
 	go func() {
 		defer close(out)
 
-		// With no error channel, a panicking hook or stream function ends the
-		// stream as runOp's error would. A goroutine the stream function
-		// starts is out of reach of this recover.
+		// A panicking hook or stream function leaves through MakeError, as
+		// runOp's does. A goroutine the stream function starts is out of reach.
 		defer func() {
 			if r := recover(); r != nil {
-				e.recovered(ctx, r)
+				sendData(e.recovered(ctx, r))
 			}
 		}()
 
-		utility.FeatureHook(ctx, "PrePoint")
-		point, err := utility.MakePoint(ctx)
-		ctx.Out["point"] = point
-		if err != nil {
-			return
-		}
-
-		utility.FeatureHook(ctx, "PreSpec")
-		spec, err := utility.MakeSpec(ctx)
-		ctx.Out["spec"] = spec
-		if err != nil {
-			return
-		}
-
-		utility.FeatureHook(ctx, "PreRequest")
-		req, err := utility.MakeRequest(ctx)
-		ctx.Out["request"] = req
-		if err != nil {
-			return
-		}
-
-		utility.FeatureHook(ctx, "PreResponse")
-		resp, err := utility.MakeResponse(ctx)
-		ctx.Out["response"] = resp
-		if err != nil {
-			return
-		}
-
-		utility.FeatureHook(ctx, "PreResult")
-		result, err := utility.MakeResult(ctx)
-		ctx.Out["result"] = result
-		if err != nil {
+		// A failed step leaves through MakeError, as an operation's does.
+		if err := e.streamSteps(ctx); err != nil {
+			sendData(utility.MakeError(ctx, err))
 			return
 		}
 
-		utility.FeatureHook(ctx, "PreDone")
-
 		// Inbound: prefer the streaming feature's incremental iterator; else
 		// fall back to the materialised items so Stream always yields.
 		if ctx.Result != nil && ctx.Result.Stream != nil {
 			// Done does not run on this path, so its record is cleaned here.
 			utility.CleanExplain(ctx)
 			for item := range ctx.Result.Stream() {
-				if !send(item) {
+				if !send(core.StreamItem{Item: item}) {
 					return
 				}
 			}
 			return
 		}
 
-		data, derr := utility.Done(ctx)
-		if derr != nil {
-			return
-		}
-		switch d := data.(type) {
-		case []any:
-			for _, item := range d {
-				if !send(item) {
-					return
-				}
-			}
-		case nil:
-			// nothing to yield
-		default:
-			send(d)
-		}
+		sendData(utility.Done(ctx))
 	}()
 
 	return out
 }
 
+// The steps an operation runs, with their hooks; the first that fails hands
+// back its error.
+func (e *EntyClass) streamSteps(ctx *core.Context) error {
+	utility := e.utility
+
+	utility.FeatureHook(ctx, "PrePoint")
+	point, err := utility.MakePoint(ctx)
+	ctx.Out["point"] = point
+	if err != nil {
+		return err
+	}
+
+	utility.FeatureHook(ctx, "PreSpec")
+	spec, err := utility.MakeSpec(ctx)
+	ctx.Out["spec"] = spec
+	if err != nil {
+		return err
+	}
+
+	utility.FeatureHook(ctx, "PreRequest")
+	req, err := utility.MakeRequest(ctx)
+	ctx.Out["request"] = req
+	if err != nil {
+		return err
+	}
+
+	utility.FeatureHook(ctx, "PreResponse")
+	resp, err := utility.MakeResponse(ctx)
+	ctx.Out["response"] = resp
+	if err != nil {
+		return err
+	}
+
+	utility.FeatureHook(ctx, "PreResult")
+	result, err := utility.MakeResult(ctx)
+	ctx.Out["result"] = result
+	if err != nil {
+		return err
+	}
+
+	utility.FeatureHook(ctx, "PreDone")
+	return nil
+}
+
 // #LoadOp
 
 // #ListOp
@@ -284,6 +301,8 @@ func (e *EntyClass) Stream(action string, args map[string]any, callopts map[stri
 
 // #UpdateOp
 
+// #PatchOp
+
 // #RemoveOp
 
 func (e *EntyClass) runOp(ctx *core.Context, postDone func()) (out any, err error) {

package/project/.sdk/src/cmp/go/fragment/EntityPatchOp.fragment.go

@@ -0,0 +1,49 @@
+package entity
+
+import (
+	"GOMODULE/core"
+
+	vs "github.com/voxgig/struct"
+)
+
+type entityPatchOp struct{}
+
+// EJECT-START
+
+func (e *EntyClass) Patch(reqdata map[string]any, ctrl map[string]any) (any, error) {
+	utility := e.utility
+	ctx := utility.MakeContext(map[string]any{
+		"opname":  "patch",
+		"ctrl":    ctrl,
+		"match":   e.match,
+		"data":    e.data,
+		"reqdata": reqdata,
+	}, e.entctx)
+
+	return e.runOp(ctx, func() {
+		if ctx.Result != nil {
+			if ctx.Result.Resmatch != nil {
+				e.match = ctx.Result.Resmatch
+			}
+			if ctx.Result.Resdata != nil {
+				e.data = core.ToMapAny(vs.Clone(ctx.Result.Resdata))
+				if e.data == nil {
+					e.data = map[string]any{}
+				}
+			}
+		}
+	})
+}
+
+// PatchTyped is the statically-typed variant of Patch: it takes an
+// EntityNamePatchData and returns an EntityName. It delegates to the untyped
+// Patch (identical runtime) and converts at the typed boundary.
+func (e *EntyClass) PatchTyped(reqdata EntityNamePatchData, ctrl map[string]any) (EntityName, error) {
+	res, err := e.Patch(asMap(reqdata), ctrl)
+	if err != nil {
+		return EntityName{}, err
+	}
+	return typedFrom[EntityName](res), nil
+}
+
+// EJECT-END

package/project/.sdk/src/cmp/go/fragment/Main.fragment.go

@@ -146,6 +146,14 @@ func (sdk *ProjectNameSDK) Prepare(fetchargs map[string]any) (map[string]any, er
 	if method == "" {
 		method = "GET"
 	}
+	method = strings.ToUpper(method)
+
+	allowMethodVal := vs.GetPath(options, []any{"allow", "method"})
+	if !Allowed(allowMethodVal, method) {
+		allowMethod, _ := allowMethodVal.(string)
+		return nil, ctx.MakeError("spec_method_allow",
+			"Method \""+method+"\" not allowed by SDK option allow.method value: \""+allowMethod+"\"")
+	}
 
 	params := ToMapAny(vs.GetProp(fetchargs, "params"))
 	if params == nil {
@@ -205,8 +213,7 @@ func (sdk *ProjectNameSDK) Direct(fetchargs map[string]any) (map[string]any, err
 
 // Is this raw-access op permitted by the SDK's allow.op option?
 func (sdk *ProjectNameSDK) opAllowed(op string) bool {
-	allowOp, _ := vs.GetPath(sdk.options, []any{"allow", "op"}).(string)
-	return strings.Contains(allowOp, op)
+	return Allowed(vs.GetPath(sdk.options, []any{"allow", "op"}), op)
 }
 
 func (sdk *ProjectNameSDK) opDenied(op string) map[string]any {
@@ -278,20 +285,34 @@ func (sdk *ProjectNameSDK) rawRequest(fetchargs map[string]any) (map[string]any,
 		noBody := status == 204 || status == 304 || contentLength == "0"
 
 		var jsonData any
+		var bodyErr error
 		if !noBody {
 			if jf := vs.GetProp(fm, "json"); jf != nil {
 				if f, ok := jf.(func() any); ok {
 					jsonData = f()
 				}
 			}
+			if unreadable, _ := vs.GetProp(fm, "unreadable").(bool); unreadable {
+				var failed error
+				if status < 200 || status >= 300 {
+					failed = ctx.MakeError("request_status",
+						fmt.Sprintf("request: %d: %v", status, vs.GetProp(fm, "statusText")))
+				}
+				bodyErr = UnreadableBody(ctx, status, headers, vs.GetProp(fm, "body"),
+					fetchdef["headers"], failed)
+			}
 		}
 
-		return map[string]any{
-			"ok":      status >= 200 && status < 300,
+		out := map[string]any{
+			"ok":      bodyErr == nil && status >= 200 && status < 300,
 			"status":  status,
 			"headers": headers,
 			"data":    jsonData,
-		}, nil
+		}
+		if bodyErr != nil {
+			out["err"] = sdk.cleanErr(ctx, bodyErr)
+		}
+		return out, nil
 	}
 
 	return map[string]any{"ok": false, "err": ctx.MakeError("direct_invalid", "invalid response type")}, nil

package/project/.sdk/src/cmp/go/utility_go.ts

@@ -68,7 +68,7 @@ function exampleValue(entity: any, op: any, paramName: string, placeholder: stri
   if ('NULL' === key) {
     return 'nil'
   }
-  return `"${placeholder}"`
+  return formatGoString(placeholder)
 }
 
 

package/project/.sdk/src/cmp/go-cli/Main_go-cli.ts

@@ -2,7 +2,7 @@
 import * as Path from 'node:path'
 
 import {
-  cmp, each, deriveEntityNames,
+  cmp, each, deriveEntityNames, entityOps,
   File, Content, Fragment, Slot, goModule, goVersion
 } from '@voxgig/sdkgen'
 
@@ -85,19 +85,17 @@ const Main = cmp(function Main(props: any) {
     .map(op => CLI_VERB_ROWS[op])
     .join('\n')
 
-  // First / second active entity for concrete, truthful examples, gated on
-  // the FIRST entity's own ops so an example never shows a verb it lacks.
+  // Concrete examples, each gated on the ops the entity it names can run
+  // without an action, so no example is refused.
   const activeEntityObjs: any[] =
     Object.values(entityMap).filter((e: any) => e && e.active !== false)
   const firstEntityObj: any = activeEntityObjs[0]
   const firstEntity = firstEntityObj
     ? String(firstEntityObj.name).toLowerCase()
     : (entityNames[0] || 'entity')
-  const secondEntity = activeEntityObjs.length > 1
-    ? String(activeEntityObjs[1].name).toLowerCase()
-    : firstEntity
-  const firstOps: any = (firstEntityObj && firstEntityObj.op) || {}
-  const firstHas = (op: string) => !!(firstOps[op] && firstOps[op].active !== false)
+  const hasOp = (entity: any, op: string) => entityOps(entity).includes(op)
+  const firstHas = (op: string) => hasOp(firstEntityObj, op)
+  const otherLister = activeEntityObjs.slice(1).find((e: any) => hasOp(e, 'list'))
   const entityNoun = entityCount === 1 ? 'entity' : 'entities'
   // The best single example expression this SDK can actually run, for the
   // tutorial/REPL walkthroughs (never demonstrates an unsupported op).
@@ -127,8 +125,8 @@ const Main = cmp(function Main(props: any) {
     ex.push(`./${bin} load '{id:1}' ${firstEntity}       # explicit match map`)
   }
   if (firstHas('update')) ex.push(`./${bin} update '{name:"x"}' ${firstEntity}`)
-  if (firstHas('list') && secondEntity !== firstEntity) {
-    ex.push(`./${bin} list ${secondEntity}`)
+  if (null != otherLister) {
+    ex.push(`./${bin} list ${String(otherLister.name).toLowerCase()}`)
   }
   ex.push('')
   ex.push('# 5. Override the API base URL for a single call')