@voxgig/sdkgen 2.0.2 → 3.0.0

package/project/.sdk/tm/go/test/feature_test.go

@@ -1,22 +1,18 @@
 package sdktest
 
-// Offline feature-test harness plus behavioural tests for the enterprise
-// features shipped with this SDK (retry, cache, rbac, telemetry, ...).
+// Behavioural tests for the enterprise features shipped with this SDK
+// (retry, cache, rbac, telemetry, ...). Each block runs only when its
+// feature is present (see fhSkipWithout in feature_harness_test.go, which
+// also holds the fh* pipeline harness these tests drive).
 //
-// Feature behaviour is unit-tested by driving each feature through a
-// faithful miniature of the real operation pipeline against a configurable
-// mock transport — the same hook order and short-circuit rules as the
-// generated Entity*Op code, but with no live server and no API-specific
-// fixtures. Each block runs only when its feature is present in this SDK
-// (see fhSkipWithout).
+// This file constructs every shipped feature type by name, so it only
+// compiles with the COMPLETE feature set — it is listed in the go target's
+// `feature.fullset` and dropped when a project trims its features.
 
 import (
-	"fmt"
-	neturl "net/url"
 	"os"
 	"reflect"
 	"regexp"
-	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -25,345 +21,6 @@ import (
 	feat "GOMODULE/feature"
 )
 
-// --- harness ----------------------------------------------------------------
-
-// fhHasFeature is true when this SDK was generated with the named feature.
-func fhHasFeature(name string) bool {
-	config := sdk.MakeConfig()
-	fm, _ := config["feature"].(map[string]any)
-	return fm != nil && fm[name] != nil
-}
-
-func fhSkipWithout(t *testing.T, names ...string) {
-	t.Helper()
-	for _, name := range names {
-		if !fhHasFeature(name) {
-			t.Skip("feature not present in this SDK: " + name)
-		}
-	}
-}
-
-// fhClock is a deterministic virtual clock: now() advances only when
-// sleep(ms) is called, so timing-based features can be asserted without
-// real delays.
-type fhClock struct {
-	t int64
-}
-
-func (c *fhClock) now() int64     { return c.t }
-func (c *fhClock) sleep(ms int)   { c.t += int64(ms) }
-func (c *fhClock) advance(ms int) { c.t += int64(ms) }
-
-// fhResponse builds a transport-shaped response the pipeline understands.
-func fhResponse(status int, data any, headers map[string]any) map[string]any {
-	h := map[string]any{}
-	for k, v := range headers {
-		h[strings.ToLower(k)] = v
-	}
-	statusText := "OK"
-	if status >= 400 {
-		statusText = "ERR"
-	}
-	return map[string]any{
-		"status":     status,
-		"statusText": statusText,
-		"body":       "not-used",
-		"json":       (func() any)(func() any { return data }),
-		"headers":    h,
-	}
-}
-
-// fhRecorder is a mock transport recording every call, replying via an
-// optional reply func (default: 200 with a call counter).
-type fhRecorder struct {
-	calls []map[string]any
-	reply func(n int, fetchdef map[string]any) (any, error)
-}
-
-func (r *fhRecorder) fetch(ctx *sdk.Context, url string, fetchdef map[string]any) (any, error) {
-	r.calls = append(r.calls, map[string]any{"url": url, "fetchdef": fetchdef})
-	if r.reply != nil {
-		return r.reply(len(r.calls), fetchdef)
-	}
-	return fhResponse(200, map[string]any{"ok": true, "n": len(r.calls)}, nil), nil
-}
-
-func (r *fhRecorder) headers(i int) map[string]any {
-	fetchdef, _ := r.calls[i]["fetchdef"].(map[string]any)
-	headers, _ := fetchdef["headers"].(map[string]any)
-	return headers
-}
-
-func (r *fhRecorder) fetchdef(i int) map[string]any {
-	fetchdef, _ := r.calls[i]["fetchdef"].(map[string]any)
-	return fetchdef
-}
-
-func (r *fhRecorder) url(i int) string {
-	url, _ := r.calls[i]["url"].(string)
-	return url
-}
-
-// fhFeature pairs a feature instance with its init options.
-type fhFeature struct {
-	f       sdk.Feature
-	options map[string]any
-}
-
-func fhF(f sdk.Feature, options map[string]any) fhFeature {
-	return fhFeature{f: f, options: options}
-}
-
-// fhHarness wires features (in init order) to a mock transport and a mini
-// operation pipeline.
-type fhHarness struct {
-	client  *sdk.ProjectNameSDK
-	utility *sdk.Utility
-	rootctx *sdk.Context
-	base    string
-}
-
-// fhMake constructs the harness: a real (test-mode) client, an isolated
-// utility whose fetcher is the mock server, and the requested features
-// initialised against it. Fires PostConstruct once wiring is complete.
-func fhMake(server sdk.FetcherFunc, features ...fhFeature) *fhHarness {
-	client := sdk.TestSDK(nil, nil)
-	client.Features = []sdk.Feature{}
-
-	utility := client.GetUtility()
-	if server == nil {
-		rec := &fhRecorder{}
-		server = rec.fetch
-	}
-	utility.Fetcher = server
-
-	rootctx := utility.MakeContext(map[string]any{
-		"client":  client,
-		"utility": utility,
-	}, client.GetRootCtx())
-
-	for _, fs := range features {
-		fopts := map[string]any{"active": true}
-		for k, v := range fs.options {
-			fopts[k] = v
-		}
-		fs.f.Init(rootctx, fopts)
-		client.Features = append(client.Features, fs.f)
-	}
-
-	utility.FeatureHook(rootctx, "PostConstruct")
-
-	return &fhHarness{
-		client:  client,
-		utility: utility,
-		rootctx: rootctx,
-		base:    "http://api.test",
-	}
-}
-
-type fhOpSpec struct {
-	entity  string
-	op      string
-	method  string
-	path    string
-	query   map[string]any
-	headers map[string]any
-	body    any
-	ctrl    map[string]any
-}
-
-type fhOpResult struct {
-	ok     bool
-	data   any
-	err    error
-	result *sdk.Result
-	ctx    *sdk.Context
-}
-
-func fhDefaultMethod(op string) string {
-	switch op {
-	case "create":
-		return "POST"
-	case "update":
-		return "PATCH"
-	case "remove":
-		return "DELETE"
-	}
-	return "GET"
-}
-
-func fhBuildUrl(spec *sdk.Spec) string {
-	var keys []string
-	for k, v := range spec.Query {
-		if v != nil {
-			keys = append(keys, k)
-		}
-	}
-	sort.Strings(keys)
-	qs := ""
-	for _, k := range keys {
-		if qs != "" {
-			qs += "&"
-		}
-		qs += neturl.QueryEscape(k) + "=" + neturl.QueryEscape(fmt.Sprintf("%v", spec.Query[k]))
-	}
-	url := spec.Base + spec.Path
-	if qs != "" {
-		url += "?" + qs
-	}
-	return url
-}
-
-// op runs one operation through the mini pipeline (mirrors the generated
-// Entity*Op fragment: hook, short-circuit, make*, hook, ...).
-func (h *fhHarness) op(o fhOpSpec) fhOpResult {
-	entity := o.entity
-	if entity == "" {
-		entity = "widget"
-	}
-	opname := o.op
-	if opname == "" {
-		opname = "load"
-	}
-	method := o.method
-	if method == "" {
-		method = fhDefaultMethod(opname)
-	}
-	ctrl := o.ctrl
-	if ctrl == nil {
-		ctrl = map[string]any{}
-	}
-
-	ctx := h.utility.MakeContext(map[string]any{
-		"opname": opname,
-		"ctrl":   ctrl,
-	}, h.rootctx)
-	ctx.Op = sdk.NewOperation(map[string]any{"entity": entity, "name": opname})
-
-	h.utility.FeatureHook(ctx, "PostConstructEntity")
-
-	h.utility.FeatureHook(ctx, "PrePoint")
-	if err, ok := ctx.Out["point"].(error); ok {
-		return h.fail(ctx, err)
-	}
-
-	h.utility.FeatureHook(ctx, "PreSpec")
-	path := o.path
-	if path == "" {
-		path = "/" + entity
-	}
-	headers := map[string]any{}
-	for k, v := range o.headers {
-		headers[k] = v
-	}
-	query := map[string]any{}
-	for k, v := range o.query {
-		query[k] = v
-	}
-	ctx.Spec = sdk.NewSpec(map[string]any{
-		"method":  method,
-		"base":    h.base,
-		"path":    path,
-		"headers": headers,
-		"query":   query,
-		"step":    "start",
-	})
-	if o.body != nil {
-		ctx.Spec.Body = o.body
-	}
-
-	h.utility.FeatureHook(ctx, "PreRequest")
-	ctx.Spec.Url = fhBuildUrl(ctx.Spec)
-
-	fetchdef := map[string]any{
-		"url":     ctx.Spec.Url,
-		"method":  ctx.Spec.Method,
-		"headers": ctx.Spec.Headers,
-	}
-	if ctx.Spec.Body != nil {
-		fetchdef["body"] = ctx.Spec.Body
-	}
-
-	var response any
-	var fetchErr error
-	if ctx.Out["request"] != nil {
-		response = ctx.Out["request"]
-	} else {
-		response, fetchErr = h.utility.Fetcher(ctx, ctx.Spec.Url, fetchdef)
-	}
-	if rm, ok := response.(map[string]any); ok {
-		ctx.Response = sdk.NewResponse(rm)
-	}
-
-	h.utility.FeatureHook(ctx, "PreResponse")
-	fhPopulateResult(ctx, response, fetchErr)
-	h.utility.FeatureHook(ctx, "PreResult")
-	h.utility.FeatureHook(ctx, "PreDone")
-
-	if ctx.Result != nil && ctx.Result.Ok {
-		return fhOpResult{ok: true, data: ctx.Result.Resdata, result: ctx.Result, ctx: ctx}
-	}
-
-	var err error
-	if ctx.Result != nil && ctx.Result.Err != nil {
-		err = ctx.Result.Err
-	} else {
-		err = ctx.MakeError("op_failed", "operation failed")
-	}
-	return h.fail(ctx, err)
-}
-
-func (h *fhHarness) fail(ctx *sdk.Context, err error) fhOpResult {
-	ctx.Ctrl.Err = err
-	h.utility.FeatureHook(ctx, "PreUnexpected")
-	return fhOpResult{ok: false, err: err, result: ctx.Result, ctx: ctx}
-}
-
-func fhPopulateResult(ctx *sdk.Context, response any, fetchErr error) {
-	result := sdk.NewResult(map[string]any{})
-	ctx.Result = result
-
-	if fetchErr != nil {
-		result.Err = fetchErr
-		return
-	}
-
-	rm, ok := response.(map[string]any)
-	if !ok || rm == nil {
-		result.Err = ctx.MakeError("request_no_response", "response: undefined")
-		return
-	}
-
-	resp := sdk.NewResponse(rm)
-	result.Status = resp.Status
-	result.StatusText = resp.StatusText
-	if hm, ok := resp.Headers.(map[string]any); ok {
-		result.Headers = hm
-	}
-	if resp.JsonFunc != nil {
-		result.Body = resp.JsonFunc()
-	}
-	result.Resdata = result.Body
-
-	if result.Status >= 400 {
-		result.Err = ctx.MakeError("request_status",
-			fmt.Sprintf("request: %d: %s", result.Status, result.StatusText))
-	} else if resp.Err != nil {
-		result.Err = resp.Err
-	}
-	if result.Err == nil {
-		result.Ok = true
-	}
-}
-
-// fhErrCode extracts the SDK error code, "" otherwise.
-func fhErrCode(err error) string {
-	if se, ok := err.(*sdk.ProjectNameError); ok {
-		return se.Code
-	}
-	return ""
-}
-
 // --- netsim -----------------------------------------------------------------
 
 func TestFeatureNetsim(t *testing.T) {

package/project/.sdk/tm/go/test/pipeline_test.go

@@ -37,6 +37,7 @@ func plCtx(client *sdk.ProjectNameSDK, utility *sdk.Utility, ctrl map[string]any
 
 // plEntity is a minimal fake entity for the list-wrap test.
 type plEntity struct {
+	deleted bool
 	name string
 	made *[]any
 }
@@ -51,6 +52,11 @@ func (e *plEntity) Data(args ...any) any {
 }
 func (e *plEntity) Match(args ...any) any { return nil }
 
+// Every operation resolves to the entity; `remove` marks it. The fake has
+// to satisfy the same interface the real entities do.
+func (e *plEntity) MarkDeleted() { e.deleted = true }
+func (e *plEntity) Deleted() bool { return e.deleted }
+
 func TestPipelineMakeResponse(t *testing.T) {
 	client, utility := plClient(t, nil)
 

package/project/.sdk/tm/go/test/runner_test.go

@@ -45,8 +45,8 @@ func loadEnvLocal() {
 }
 
 func envOverride(m map[string]any) map[string]any {
-	if os.Getenv("PROJECTNAME_TEST_LIVE") == "TRUE" ||
-		os.Getenv("PROJECTNAME_TEST_OVERRIDE") == "TRUE" {
+	if os.Getenv("PROJECTENV_TEST_LIVE") == "TRUE" ||
+		os.Getenv("PROJECTENV_TEST_OVERRIDE") == "TRUE" {
 		for key := range m {
 			envval := os.Getenv(key)
 			if envval != "" {
@@ -63,8 +63,8 @@ func envOverride(m map[string]any) map[string]any {
 		}
 	}
 
-	if explain := os.Getenv("PROJECTNAME_TEST_EXPLAIN"); explain != "" {
-		m["PROJECTNAME_TEST_EXPLAIN"] = explain
+	if explain := os.Getenv("PROJECTENV_TEST_EXPLAIN"); explain != "" {
+		m["PROJECTENV_TEST_EXPLAIN"] = explain
 	}
 
 	return m
@@ -551,6 +551,18 @@ func ctxToMatchMap(ctx *sdk.Context) map[string]any {
 	return m
 }
 
+// entityData extracts the data map from an op result.
+//
+// Every entity operation resolves to the ENTITY (see AGENTS.md), so a flow
+// test that wants the record takes this hop. A plain map passes through
+// unchanged, so this is safe for the direct/prepare results too.
+func entityData(v any) any {
+	if ent, ok := v.(sdk.Entity); ok {
+		return ent.Data()
+	}
+	return v
+}
+
 // entityListToData extracts data maps from a list of Entity objects.
 func entityListToData(list []any) []any {
 	var out []any

package/project/.sdk/tm/haskell/VERSION

@@ -1 +1 @@
-0.0.1
+PROJECTVERSION

package/project/.sdk/tm/haskell/src/SdkFeatures.hs

@@ -1313,6 +1313,7 @@ makeEntity client name entopts = do
   utility <- copyUtility (clUtility client)
   dataR <- newIORef =<< emptyMap
   matchR <- newIORef =<< emptyMap
+  deletedR <- newIORef False
   entctxR <- newIORef Nothing
   let entCtx = do m <- readIORef entctxR; case m of Just c -> pure c; Nothing -> error "entity context not initialised"
       setDataFrom rv = do
@@ -1339,11 +1340,33 @@ makeEntity client name entopts = do
         , eMake = do o <- clone entopts'; makeEntity client name o
         , eDataSet = \d -> writeIORef dataR d
         , eDataGet = readIORef dataR
-        , eLoad = \rm ctrl -> mkOp "load" "match" rm ctrl postLoad
-        , eList = \rm ctrl -> mkOp "list" "match" rm ctrl postList
-        , eCreate = \rd ctrl -> mkOp "create" "data" rd ctrl postCreate
-        , eUpdate = \rd ctrl -> mkOp "update" "data" rd ctrl postUpdate
-        , eRemove = \rm ctrl -> mkOp "remove" "match" rm ctrl postRemove
+        -- Ops resolve to the ENTITY (see SdkTypes). mkOp still runs the whole
+        -- pipeline and throws SdkException on failure; with throwing disabled
+        -- it returns the error payload, which an IO Entity cannot carry, so
+        -- that path resolves to the entity too and the caller reads ctrl.err
+        -- — the mechanism the no-throw mode documents anyway.
+        , eLoad = \rm ctrl -> mkOp "load" "match" rm ctrl postLoad >> pure ent
+        , eList = \rm ctrl -> do
+            out <- mkOp "list" "match" rm ctrl postList
+            -- `list` resolves to one ENTITY per record. makeResult cannot
+            -- build them — it works in Value — so this does.
+            case out of
+              VList _ -> do
+                items <- listItems out
+                mapM (\entry -> do
+                        e <- eMake ent
+                        case entry of VMap _ -> eDataSet e entry; _ -> pure ()
+                        pure e) items
+              _ -> pure []
+        , eCreate = \rd ctrl -> mkOp "create" "data" rd ctrl postCreate >> pure ent
+        , eUpdate = \rd ctrl -> mkOp "update" "data" rd ctrl postUpdate >> pure ent
+        , eRemove = \rm ctrl -> do
+            _ <- mkOp "remove" "match" rm ctrl postRemove
+            -- A removed entity keeps its data but is no longer a live record.
+            writeIORef deletedR True
+            pure ent
+        , eDeleted = deletedR
+        , eMarkDeleted = writeIORef deletedR True
         -- Streaming operation. Runs `action` through the full pipeline and
         -- returns a lazy list of result items, so the streaming feature's
         -- incremental output is reachable (a normal op call materialises the

package/project/.sdk/tm/haskell/src/SdkTypes.hs

@@ -111,11 +111,20 @@ data Entity = Entity
   , eMake    :: IO Entity
   , eDataSet :: Value -> IO ()
   , eDataGet :: IO Value
-  , eLoad    :: Value -> Value -> IO Value
-  , eList    :: Value -> Value -> IO Value
-  , eCreate  :: Value -> Value -> IO Value
-  , eUpdate  :: Value -> Value -> IO Value
-  , eRemove  :: Value -> Value -> IO Value
+  -- | Every operation resolves to the ENTITY, not the raw data — 'eList' to
+  -- one per record. The record is reached through 'eDataGet'. 'Value' cannot
+  -- carry an entity (it is a closed data union), so the CONTRACT lives in
+  -- these signatures. See AGENTS.md "Entity operations return ENTITIES".
+  , eLoad    :: Value -> Value -> IO Entity
+  , eList    :: Value -> Value -> IO [Entity]
+  , eCreate  :: Value -> Value -> IO Entity
+  , eUpdate  :: Value -> Value -> IO Entity
+  , eRemove  :: Value -> Value -> IO Entity
+  -- | 'eRemove' resolves to the entity, marked. The instance KEEPS the data
+  -- it held — a caller can still read what was deleted — but it is no longer
+  -- a live record.
+  , eDeleted     :: IORef Bool
+  , eMarkDeleted :: IO ()
   -- | stream action args callopts -> a lazy list of result items.
   , eStream  :: String -> Value -> Value -> IO [Value]
   }

package/project/.sdk/tm/java/VERSION

@@ -1 +1 @@
-0.0.1
+PROJECTVERSION

package/project/.sdk/tm/java/test/RunnerSupport.java

@@ -72,8 +72,8 @@ public final class RunnerSupport {
   }
 
   public static Map<String, Object> envOverride(Map<String, Object> m) {
-    if ("TRUE".equals(getenv("PROJECTNAME_TEST_LIVE"))
-        || "TRUE".equals(getenv("PROJECTNAME_TEST_OVERRIDE"))) {
+    if ("TRUE".equals(getenv("PROJECTENV_TEST_LIVE"))
+        || "TRUE".equals(getenv("PROJECTENV_TEST_OVERRIDE"))) {
       for (String key : new ArrayList<>(m.keySet())) {
         String envval = getenv(key);
         if (envval != null && !envval.isEmpty()) {
@@ -90,9 +90,9 @@ public final class RunnerSupport {
       }
     }
 
-    String explain = getenv("PROJECTNAME_TEST_EXPLAIN");
+    String explain = getenv("PROJECTENV_TEST_EXPLAIN");
     if (explain != null && !explain.isEmpty()) {
-      m.put("PROJECTNAME_TEST_EXPLAIN", explain);
+      m.put("PROJECTENV_TEST_EXPLAIN", explain);
     }
 
     return m;

package/project/.sdk/tm/java/utility/MakeError.java

@@ -62,6 +62,10 @@ final class MakeError {
     sdkErr.result = Clean.clean(ctx, result);
     sdkErr.spec = Clean.clean(ctx, spec);
 
+    // Promote the HTTP status to the top level, so a consumer can branch on
+    // `err.status` / `err.notFound()` instead of reaching into `err.result`.
+    sdkErr.status = result.status;
+
     ctx.ctrl.err = sdkErr;
 
     // Fire PreUnexpected so observability features (metrics, telemetry, audit,

package/project/.sdk/tm/js/src/utility/MakeErrorUtility.js

@@ -39,6 +39,10 @@ function makeError(ctx, err) {
   err.result = clean(ctx, result)
   err.spec = clean(ctx, spec)
 
+  // Promote the HTTP status to the top level, so a consumer can branch on
+  // `err.status` / `err.notFound` instead of reaching into `err.result`.
+  err.status = null == result.status ? -1 : result.status
+
   ctx.ctrl.err = err
 
   // Fire PreUnexpected so observability features (metrics, telemetry, audit,

package/project/.sdk/tm/js/test/utility.js

@@ -44,8 +44,8 @@ function makeCtrl(explain) {
 // Overrides configuration values with environment variables if available
 function envOverride(m) {
   if (
-    'TRUE' === process.env.PROJECTNAME_TEST_LIVE ||
-    'TRUE' === process.env.PROJECTNAME_TEST_OVERRIDE
+    'TRUE' === process.env.PROJECTENV_TEST_LIVE ||
+    'TRUE' === process.env.PROJECTENV_TEST_OVERRIDE
   ) {
     Object.entries(m).map(n => {
       let envval = process.env[n[0]]
@@ -56,7 +56,7 @@ function envOverride(m) {
     })
   }
 
-  m.PROJECTNAME_TEST_EXPLAIN = process.env.PROJECTNAME_TEST_EXPLAIN || m.PROJECTNAME_TEST_EXPLAIN
+  m.PROJECTENV_TEST_EXPLAIN = process.env.PROJECTENV_TEST_EXPLAIN || m.PROJECTENV_TEST_EXPLAIN
 
   return m
 }

package/project/.sdk/tm/kotlin/VERSION

@@ -1 +1 @@
-0.0.1
+PROJECTVERSION

package/project/.sdk/tm/kotlin/test/RunnerSupport.kt

@@ -63,7 +63,7 @@ object RunnerSupport {
   }
 
   fun envOverride(m: MutableMap<String, Any?>): MutableMap<String, Any?> {
-    if ("TRUE" == getenv("PROJECTNAME_TEST_LIVE") || "TRUE" == getenv("PROJECTNAME_TEST_OVERRIDE")) {
+    if ("TRUE" == getenv("PROJECTENV_TEST_LIVE") || "TRUE" == getenv("PROJECTENV_TEST_OVERRIDE")) {
       for (key in ArrayList(m.keys)) {
         var envval = getenv(key)
         if (envval != null && envval.isNotEmpty()) {
@@ -80,9 +80,9 @@ object RunnerSupport {
       }
     }
 
-    val explain = getenv("PROJECTNAME_TEST_EXPLAIN")
+    val explain = getenv("PROJECTENV_TEST_EXPLAIN")
     if (explain != null && explain.isNotEmpty()) {
-      m["PROJECTNAME_TEST_EXPLAIN"] = explain
+      m["PROJECTENV_TEST_EXPLAIN"] = explain
     }
 
     return m

package/project/.sdk/tm/lean/VERSION

@@ -1 +1 @@
-0.0.1
+PROJECTVERSION