@voxgig/sdkgen 2.0.1 → 3.0.0

package/project/.sdk/src/cmp/zig/fragment/EntityUpdateOp.fragment.zig

@@ -1,6 +1,6 @@
 // EJECT-START
 
-pub fn update(self: *EntyClass, reqdata: Value, ctrl: Value) OpResult {
+pub fn update(self: *EntyClass, reqdata: Value, ctrl: Value) EntResult {
     const ctx = self.utility.make_context(CtxSpec{
         .opname = "update",
         .ctrl = ctrl,
@@ -8,7 +8,7 @@ pub fn update(self: *EntyClass, reqdata: Value, ctrl: Value) OpResult {
         .data = self.data,
         .reqdata = reqdata,
     }, self.ent_ctx());
-    return self.run_op(ctx, update_post_done);
+    return self.run_op_ent(ctx, update_post_done);
 }
 
 fn update_post_done(self: *EntyClass, ctx: *Context) void {

package/project/.sdk/tm/c/VERSION

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

package/project/.sdk/tm/c/core/helpers.c

@@ -5,6 +5,7 @@
 #include "sdk.h"
 
 #include <stdarg.h>
+#include <stdio.h>   // snprintf
 #include <stdlib.h>
 #include <string.h>
 #include <time.h>

package/project/.sdk/tm/c/core/sdk.h

@@ -303,17 +303,33 @@ voxgig_value* utility_fetch(Utility* u, Context* ctx, const char* url,
 // Entity (vtable; mirrors core/types.rs Entity + ProjectNameEntity)
 // ===========================================================================
 
+// Every operation resolves to the ENTITY, not the raw data. `list` resolves
+// to a NULL-terminated array of them, one per record; the record is reached
+// through `data`. See AGENTS.md "Entity operations return ENTITIES".
+//
+// `voxgig_value` cannot carry an entity - it is a closed data union
+// (UNDEF|NULL|BOOL|INT|DOUBLE|STRING|LIST|MAP|FUNC|SENTINEL), and adding a
+// variant to a general-purpose struct library to hold SDK objects would be
+// wrong - so the CONTRACT lives in these signatures instead.
 typedef struct EntityVT {
   const char* (*get_name)(Entity*);
   Entity* (*make)(Entity*);
   voxgig_value* (*data)(Entity*, voxgig_value* args);   // args NULL => none
   voxgig_value* (*matchv)(Entity*, voxgig_value* args); // args NULL => none
-  // CRUD ops (ProjectNameEntity). On error set *err.
-  voxgig_value* (*load)(Entity*, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
-  voxgig_value* (*list)(Entity*, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
-  voxgig_value* (*create)(Entity*, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
-  voxgig_value* (*update)(Entity*, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
-  voxgig_value* (*remove)(Entity*, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
+
+  // `remove` 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.
+  void (*mark_deleted)(Entity*);
+  bool (*deleted)(Entity*);
+
+  // CRUD ops (ProjectNameEntity). On error set *err and return NULL.
+  Entity* (*load)(Entity*, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
+  // Returns a NULL-terminated Entity* array (never NULL on success).
+  Entity** (*list)(Entity*, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
+  Entity* (*create)(Entity*, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
+  Entity* (*update)(Entity*, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
+  Entity* (*remove)(Entity*, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
 } EntityVT;
 
 struct Entity {

package/project/.sdk/tm/c/tests/feature_harness.h

@@ -15,6 +15,7 @@
 #include "ctest.h" // -> api.h -> sdk.h, plus voxgig_struct.h
 
 #include <ctype.h>
+#include <stdio.h>   // snprintf
 #include <stdlib.h>
 #include <string.h>
 

package/project/.sdk/tm/c/tests/primary_utility_test.c

@@ -241,7 +241,10 @@ static void test_primary_make_fetch_def_basic(void) {
 static void test_primary_make_fetch_def_with_body(void) {
   base_client();
   Context* ctx = full_ctx();
-  ctx->spec = spec_new(cmap(9, "base", v_str("http://localhost:8080"), "prefix", v_str(""),
+  // 8 pairs, not 9 - cmap is variadic and reads exactly npairs, so an
+  // overcount walks off the argument list and the trailing entry (method) is
+  // whatever the read finds.
+  ctx->spec = spec_new(cmap(8, "base", v_str("http://localhost:8080"), "prefix", v_str(""),
                             "path", v_str("items"), "suffix", v_str(""), "params", v_map(),
                             "query", v_map(), "headers", v_map(), "method", v_str("POST")));
   ctx->spec->body = cmap(1, "name", v_str("test"));

package/project/.sdk/tm/c/utility/graphql.c

@@ -72,7 +72,7 @@ const char* graphql_error_code(voxgig_value* gqlerr) {
 // generated create/update call look exactly like its REST equivalent.
 voxgig_value* graphql_body_util(Context* ctx) {
   voxgig_value* gql = getp(ctx->point, "graphql");
-  if (!voxgig_is_map(gql)) return voxgig_new_noval();
+  if (!voxgig_is_map(gql)) return voxgig_new_undef();
 
   // reqmatch/reqdata hold the caller's arguments for THIS call; data/match
   // hold the entity's current state. Which pair depends on whether the op

package/project/.sdk/tm/c/utility/make_url.c

@@ -2,6 +2,7 @@
 
 #include "sdk.h"
 
+#include <stdio.h>   // snprintf
 #include <stdlib.h>
 #include <string.h>
 

package/project/.sdk/tm/c/utility/param.c

@@ -2,6 +2,7 @@
 
 #include "sdk.h"
 
+#include <stdio.h>   // snprintf
 #include <string.h>
 
 voxgig_value* param_util(Context* ctx, voxgig_value* paramdef) {

package/project/.sdk/tm/clojure/VERSION

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

package/project/.sdk/tm/cpp/VERSION

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

package/project/.sdk/tm/cpp/core/types.hpp

@@ -347,6 +347,12 @@ public:
   virtual EntityPtr make() = 0;
   virtual Value data(const Value& arg = Value::undef()) = 0;
   virtual Value match(const Value& arg = Value::undef()) = 0;
+
+  // `remove` 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.
+  virtual void markDeleted() = 0;
+  virtual bool deleted() = 0;
 };
 
 // ---- Feature contract -------------------------------------------------
@@ -575,22 +581,33 @@ public:
 
 // ---- SdkEntity contract -----------------------------------------------
 
+class SdkEntity;
+using SdkEntityPtr = std::shared_ptr<SdkEntity>;
+
+// Every operation resolves to the ENTITY, not the raw data - `list` to a
+// vector of them, one per record. The record is reached through `data()`.
+// See AGENTS.md "Entity operations return ENTITIES".
+//
+// `Value` cannot carry an entity: it is a closed data union, and adding a
+// variant to a general-purpose struct library to hold SDK objects would be
+// wrong. So the CONTRACT lives in these signatures instead.
 class SdkEntity : public Entity {
 public:
-  virtual Value load(const Value& reqmatch, const Value& ctrl) = 0;
-  virtual Value list(const Value& reqmatch, const Value& ctrl) = 0;
-  virtual Value create(const Value& reqdata, const Value& ctrl) = 0;
-  virtual Value update(const Value& reqdata, const Value& ctrl) = 0;
-  virtual Value remove(const Value& reqmatch, const Value& ctrl) = 0;
+  virtual SdkEntityPtr load(const Value& reqmatch, const Value& ctrl) = 0;
+  virtual std::vector<SdkEntityPtr> list(const Value& reqmatch, const Value& ctrl) = 0;
+  virtual SdkEntityPtr create(const Value& reqdata, const Value& ctrl) = 0;
+  virtual SdkEntityPtr update(const Value& reqdata, const Value& ctrl) = 0;
+  virtual SdkEntityPtr remove(const Value& reqmatch, const Value& ctrl) = 0;
 };
 
-using SdkEntityPtr = std::shared_ptr<SdkEntity>;
-
 // ---- EntityBase (shared entity runtime + runOp) -----------------------
 
-class EntityBase : public SdkEntity {
+class EntityBase : public SdkEntity,
+                   public std::enable_shared_from_this<EntityBase> {
 public:
   std::string name_ = "";
+  // Set once a successful `remove` resolves on this instance.
+  bool deleted_ = false;
   SdkClient* client = nullptr;
   UtilityPtr utility;
   Value entopts = Value::undef();
@@ -602,6 +619,14 @@ public:
 
   std::string getName() override { return name_; }
 
+  void markDeleted() override { deleted_ = true; }
+  bool deleted() override { return deleted_; }
+
+  // The handle for this instance, as the ops return it.
+  SdkEntityPtr self() {
+    return std::static_pointer_cast<SdkEntity>(shared_from_this());
+  }
+
   Value data(const Value& arg = Value::undef()) override;
   Value match(const Value& arg = Value::undef()) override;
 

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

@@ -43,6 +43,11 @@ struct PlEntity : public Entity {
     return Value::undef();
   }
   Value match(const Value& arg = Value::undef()) override { return Value::undef(); }
+
+  // Every operation resolves to the entity; `remove` marks it. The fake has
+  // to satisfy the same interface the real entities do.
+  void markDeleted() override {}
+  bool deleted() override { return false; }
 };
 
 static std::string errCodeOf(const std::function<void()>& fn) {

package/project/.sdk/tm/cpp/test/runner_support.hpp

@@ -74,8 +74,8 @@ inline std::string getenv_local(const std::string& key) {
 }
 
 inline Value env_override(Value m) {
-  std::string live = getenv_local("PROJECTNAME_TEST_LIVE");
-  std::string over = getenv_local("PROJECTNAME_TEST_OVERRIDE");
+  std::string live = getenv_local("PROJECTENV_TEST_LIVE");
+  std::string over = getenv_local("PROJECTENV_TEST_OVERRIDE");
   if (live == "TRUE" || over == "TRUE") {
     if (m.is_map()) {
       for (const auto& k : Struct::keysof(m)) {
@@ -92,8 +92,8 @@ inline Value env_override(Value m) {
       }
     }
   }
-  std::string explain = getenv_local("PROJECTNAME_TEST_EXPLAIN");
-  if (!explain.empty()) map_put(m, "PROJECTNAME_TEST_EXPLAIN", Value(explain));
+  std::string explain = getenv_local("PROJECTENV_TEST_EXPLAIN");
+  if (!explain.empty()) map_put(m, "PROJECTENV_TEST_EXPLAIN", Value(explain));
   return m;
 }
 

package/project/.sdk/tm/csharp/VERSION

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

package/project/.sdk/tm/csharp/core/Types.cs

@@ -11,6 +11,12 @@ public interface IEntity
     IEntity Make();
     object? Data(object? data = null);
     object? Match(object? match = null);
+
+    // Every operation resolves to the entity; Remove additionally marks it.
+    // The instance keeps the data it held - a caller can still read what was
+    // deleted - but it is no longer a live record.
+    void MarkDeleted();
+    bool Deleted();
 }
 
 // Transport function: performs the HTTP (or mock) request. Returns a

package/project/.sdk/tm/csharp/test/FeatureHarness.cs

@@ -0,0 +1,396 @@
+// Offline feature-test harness: a faithful miniature of the real operation
+// pipeline (same hook order and short-circuit rules as the generated entity
+// op code) driven against a configurable mock transport, with no live server
+// and no API-specific fixtures. C# twin of tm/go/test/feature_harness_test.go.
+//
+// SEPARATE FROM FeatureTest.cs ON PURPOSE. `target add` drops the
+// cross-feature suite when a project trims its feature set (it constructs
+// every shipped feature by name), but PipelineTest.cs uses these Fh* helpers
+// too - leaving them in FeatureTest.cs took the whole test assembly down
+// with it.
+
+using System.Text.RegularExpressions;
+
+using Voxgig.Struct;
+using Xunit;
+
+using ProjectNameSdk;
+using ProjectNameSdk.Feature;
+
+namespace ProjectNameSdk.Test;
+
+// --- harness ----------------------------------------------------------------
+
+// FhClock is a deterministic virtual clock: Now() advances only when
+// Sleep(ms) is called, so timing-based features can be asserted without
+// real delays.
+internal class FhClock
+{
+    public long T;
+    public long Now() => T;
+    public void Sleep(int ms) => T += ms;
+    public void Advance(int ms) => T += ms;
+}
+
+// FhRecorder is a mock transport recording every call, replying via an
+// optional Reply func (default: 200 with a call counter).
+internal class FhRecorder
+{
+    public List<Dictionary<string, object?>> Calls = new();
+    public Func<int, Dictionary<string, object?>, object?>? Reply;
+
+    public object? Fetch(Context ctx, string url, Dictionary<string, object?> fetchdef)
+    {
+        Calls.Add(new Dictionary<string, object?>
+        {
+            ["url"] = url,
+            ["fetchdef"] = fetchdef,
+        });
+        if (Reply != null)
+        {
+            return Reply(Calls.Count, fetchdef);
+        }
+        return Fh.Response(200, new Dictionary<string, object?>
+        {
+            ["ok"] = true,
+            ["n"] = Calls.Count,
+        }, null);
+    }
+
+    public Dictionary<string, object?> Headers(int i)
+    {
+        var fetchdef = Calls[i]["fetchdef"] as Dictionary<string, object?>;
+        return fetchdef?["headers"] as Dictionary<string, object?>
+            ?? new Dictionary<string, object?>();
+    }
+
+    public Dictionary<string, object?> Fetchdef(int i)
+    {
+        return Calls[i]["fetchdef"] as Dictionary<string, object?>
+            ?? new Dictionary<string, object?>();
+    }
+
+    public string Url(int i)
+    {
+        return Calls[i]["url"] as string ?? "";
+    }
+}
+
+internal class FhOpSpec
+{
+    public string Entity = "";
+    public string Op = "";
+    public string Method = "";
+    public string Path = "";
+    public Dictionary<string, object?>? Query;
+    public Dictionary<string, object?>? Headers;
+    public object? Body;
+    public Dictionary<string, object?>? Ctrl;
+}
+
+internal class FhOpResult
+{
+    public bool Ok;
+    public object? Data;
+    public Exception? Err;
+    public Result? Result;
+    public Context? Ctx;
+}
+
+// FhHarness wires features (in init order) to a mock transport and a mini
+// operation pipeline.
+internal class FhHarness
+{
+    public ProjectNameSDK Client = null!;
+    public Utility Utility = null!;
+    public Context Rootctx = null!;
+    public string Base = "http://api.test";
+
+    private static string FhDefaultMethod(string op)
+    {
+        return op switch
+        {
+            "create" => "POST",
+            "update" => "PATCH",
+            "remove" => "DELETE",
+            _ => "GET",
+        };
+    }
+
+    private static string FhBuildUrl(Spec spec)
+    {
+        var keys = spec.Query.Where(kv => kv.Value != null)
+            .Select(kv => kv.Key).OrderBy(k => k, StringComparer.Ordinal).ToList();
+        var qs = string.Join("&", keys.Select(k =>
+            Uri.EscapeDataString(k) + "=" +
+            Uri.EscapeDataString(StructUtils.Stringify(spec.Query[k]))));
+        var url = spec.Base + spec.Path;
+        if (qs != "")
+        {
+            url += "?" + qs;
+        }
+        return url;
+    }
+
+    // Op runs one operation through the mini pipeline (mirrors the generated
+    // entity op code: hook, short-circuit, make*, hook, ...).
+    public FhOpResult Op(FhOpSpec o)
+    {
+        var entity = o.Entity == "" ? "widget" : o.Entity;
+        var opname = o.Op == "" ? "load" : o.Op;
+        var method = o.Method == "" ? FhDefaultMethod(opname) : o.Method;
+        var ctrl = o.Ctrl ?? new Dictionary<string, object?>();
+
+        var ctx = Utility.MakeContext(new Dictionary<string, object?>
+        {
+            ["opname"] = opname,
+            ["ctrl"] = ctrl,
+        }, Rootctx);
+        ctx.Op = new Operation(new Dictionary<string, object?>
+        {
+            ["entity"] = entity,
+            ["name"] = opname,
+        });
+
+        Utility.FeatureHook(ctx, "PostConstructEntity");
+
+        Utility.FeatureHook(ctx, "PrePoint");
+        if (ctx.Out.TryGetValue("point", out var pointOut) && pointOut is Exception perr)
+        {
+            return Fail(ctx, perr);
+        }
+
+        Utility.FeatureHook(ctx, "PreSpec");
+        var path = o.Path == "" ? "/" + entity : o.Path;
+        var headers = new Dictionary<string, object?>(o.Headers
+            ?? new Dictionary<string, object?>());
+        var query = new Dictionary<string, object?>(o.Query
+            ?? new Dictionary<string, object?>());
+        ctx.Spec = new Spec(new Dictionary<string, object?>
+        {
+            ["method"] = method,
+            ["base"] = Base,
+            ["path"] = path,
+            ["headers"] = headers,
+            ["query"] = query,
+            ["step"] = "start",
+        });
+        if (o.Body != null)
+        {
+            ctx.Spec.Body = o.Body;
+        }
+
+        Utility.FeatureHook(ctx, "PreRequest");
+        ctx.Spec.Url = FhBuildUrl(ctx.Spec);
+
+        var fetchdef = new Dictionary<string, object?>
+        {
+            ["url"] = ctx.Spec.Url,
+            ["method"] = ctx.Spec.Method,
+            ["headers"] = ctx.Spec.Headers,
+        };
+        if (ctx.Spec.Body != null)
+        {
+            fetchdef["body"] = ctx.Spec.Body;
+        }
+
+        object? response = null;
+        Exception? fetchErr = null;
+        if (ctx.Out.TryGetValue("request", out var reqOut) && reqOut != null)
+        {
+            response = reqOut;
+        }
+        else
+        {
+            try
+            {
+                response = Utility.Fetcher(ctx, ctx.Spec.Url, fetchdef);
+            }
+            catch (Exception ex)
+            {
+                fetchErr = ex;
+            }
+        }
+        if (response is Dictionary<string, object?> rm)
+        {
+            ctx.Response = new Response(rm);
+        }
+
+        Utility.FeatureHook(ctx, "PreResponse");
+        FhPopulateResult(ctx, response, fetchErr);
+        Utility.FeatureHook(ctx, "PreResult");
+        Utility.FeatureHook(ctx, "PreDone");
+
+        if (ctx.Result != null && ctx.Result.Ok)
+        {
+            return new FhOpResult
+            {
+                Ok = true,
+                Data = ctx.Result.Resdata,
+                Result = ctx.Result,
+                Ctx = ctx,
+            };
+        }
+
+        Exception err;
+        if (ctx.Result?.Err != null)
+        {
+            err = ctx.Result.Err;
+        }
+        else
+        {
+            err = ctx.MakeError("op_failed", "operation failed");
+        }
+        return Fail(ctx, err);
+    }
+
+    private FhOpResult Fail(Context ctx, Exception err)
+    {
+        ctx.Ctrl.Err = err;
+        Utility.FeatureHook(ctx, "PreUnexpected");
+        return new FhOpResult
+        {
+            Ok = false,
+            Err = err,
+            Result = ctx.Result,
+            Ctx = ctx,
+        };
+    }
+
+    private static void FhPopulateResult(Context ctx, object? response, Exception? fetchErr)
+    {
+        var result = new Result(new Dictionary<string, object?>());
+        ctx.Result = result;
+
+        if (fetchErr != null)
+        {
+            result.Err = fetchErr;
+            return;
+        }
+
+        if (response is not Dictionary<string, object?> rm)
+        {
+            result.Err = ctx.MakeError("request_no_response", "response: undefined");
+            return;
+        }
+
+        var resp = new Response(rm);
+        result.Status = resp.Status;
+        result.StatusText = resp.StatusText;
+        if (resp.Headers is Dictionary<string, object?> hm)
+        {
+            result.Headers = hm;
+        }
+        if (resp.JsonFunc != null)
+        {
+            result.Body = resp.JsonFunc();
+        }
+        result.Resdata = result.Body;
+
+        if (result.Status >= 400)
+        {
+            result.Err = ctx.MakeError("request_status",
+                $"request: {result.Status}: {result.StatusText}");
+        }
+        else if (resp.Err != null)
+        {
+            result.Err = resp.Err;
+        }
+        if (result.Err == null)
+        {
+            result.Ok = true;
+        }
+    }
+}
+
+internal static class Fh
+{
+    // HasFeature is true when this SDK was generated with the named feature.
+    public static bool HasFeature(string name)
+    {
+        var config = SdkConfig.MakeConfig();
+        return config.TryGetValue("feature", out var fraw) &&
+            fraw is Dictionary<string, object?> fm &&
+            fm.TryGetValue(name, out var f) && f != null;
+    }
+
+    public static bool SkipWithout(params string[] names)
+    {
+        return names.Any(name => !HasFeature(name));
+    }
+
+    // Response builds a transport-shaped response the pipeline understands.
+    public static Dictionary<string, object?> Response(int status, object? data,
+        Dictionary<string, object?>? headers)
+    {
+        var h = new Dictionary<string, object?>();
+        if (headers != null)
+        {
+            foreach (var kv in headers)
+            {
+                h[kv.Key.ToLowerInvariant()] = kv.Value;
+            }
+        }
+        return new Dictionary<string, object?>
+        {
+            ["status"] = status,
+            ["statusText"] = status >= 400 ? "ERR" : "OK",
+            ["body"] = "not-used",
+            ["json"] = (Func<object?>)(() => data),
+            ["headers"] = h,
+        };
+    }
+
+    // Make 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.
+    public static FhHarness Make(FetcherFunc? server,
+        params (BaseFeature f, Dictionary<string, object?>? options)[] features)
+    {
+        var client = ProjectNameSDK.TestSDK(null, null);
+        client.Features = new List<BaseFeature>();
+
+        var utility = client.GetUtility();
+        if (server == null)
+        {
+            var rec = new FhRecorder();
+            server = rec.Fetch;
+        }
+        utility.Fetcher = server;
+
+        var rootctx = utility.MakeContext(new Dictionary<string, object?>
+        {
+            ["client"] = client,
+            ["utility"] = utility,
+        }, client.GetRootCtx());
+
+        foreach (var (f, options) in features)
+        {
+            var fopts = new Dictionary<string, object?> { ["active"] = true };
+            if (options != null)
+            {
+                foreach (var kv in options)
+                {
+                    fopts[kv.Key] = kv.Value;
+                }
+            }
+            f.Init(rootctx, fopts);
+            client.Features.Add(f);
+        }
+
+        utility.FeatureHook(rootctx, "PostConstruct");
+
+        return new FhHarness
+        {
+            Client = client,
+            Utility = utility,
+            Rootctx = rootctx,
+        };
+    }
+
+    // ErrCode extracts the SDK error code, "" otherwise.
+    public static string ErrCode(Exception? err)
+    {
+        return err is ProjectNameError se ? se.Code : "";
+    }
+}