@voxgig/sdkgen 1.3.8 → 1.3.10

package/project/.sdk/src/cmp/perl/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir":"../dist",
+    "rootDir":".",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "declaration": true,
+    "declarationDir": "../dist"
+  }
+}

package/project/.sdk/src/cmp/perl/utility_perl.ts

@@ -0,0 +1,30 @@
+
+import * as Path from 'node:path'
+
+import {
+  clone,
+  walk,
+} from '@voxgig/struct'
+
+
+function projectPath(suffix?: string): string {
+  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
+}
+
+
+// Strip model-internal keys (ending in `$`) so generated config JSON only
+// carries API-shaped data.
+function clean(o: any) {
+  return walk(clone(o), (k: any, v: any, p: any) => {
+    if (null != k && k.endsWith('$')) {
+      delete p[k]
+    }
+    return v
+  })
+}
+
+
+export {
+  clean,
+  projectPath,
+}

package/project/.sdk/src/cmp/php/TestEntity_php.ts

@@ -48,6 +48,12 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
+  // 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)
+
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
   if (null == basicflow || true !== basicflow.active) {
@@ -105,7 +111,46 @@ class ${entity.Name}EntityTest extends TestCase
         $ent = $testsdk->${accessor}(null);
         $this->assertNotNull($ent);
     }
+${hasList ? `
+    // Feature #4: the entity stream(action, ...) method runs the op pipeline
+    // and yields result items. With the streaming feature active it yields the
+    // feature's incremental output; otherwise it falls back to the materialised
+    // list so stream always yields.
+    public function test_stream(): void
+    {
+        $seed = [
+            "entity" => [
+                "${entity.name}" => [
+                    "s1" => ["id" => "s1"],
+                    "s2" => ["id" => "s2"],
+                    "s3" => ["id" => "s3"],
+                ],
+            ],
+        ];
 
+        // Fallback: streaming inactive -> yields the materialised list items.
+        $base = ${model.const.Name}SDK::test($seed, null);
+        $seen = iterator_to_array($base->${accessor}(null)->stream("list", null, null), false);
+        $this->assertCount(3, $seen);
+
+        // Inbound: streaming active -> yields each item from the feature.
+        $cfg = ${model.const.Name}Config::make_config();
+        if (isset($cfg["feature"]) && is_array($cfg["feature"]) && isset($cfg["feature"]["streaming"])) {
+            $sdk = ${model.const.Name}SDK::test($seed, ["feature" => ["streaming" => ["active" => true]]]);
+            $got = [];
+            foreach ($sdk->${accessor}(null)->stream("list", null, null) as $item) {
+                if (is_array($item) && array_is_list($item)) {
+                    foreach ($item as $sub) {
+                        $got[] = $sub;
+                    }
+                } else {
+                    $got[] = $item;
+                }
+            }
+            $this->assertCount(3, $got);
+        }
+    }
+` : ''}
     public function test_basic_flow(): void
     {
         $setup = ${entity.name}_basic_setup(null);
@@ -144,6 +189,14 @@ class ${entity.Name}EntityTest extends TestCase
 
     // Model-driven step iteration
     each(basicflow.step, (step: any, index: any) => {
+      // Never emit a REMOVE (or its removed-item verify LIST) without a
+      // preceding CREATE: a coherent CRUD flow only removes what it created,
+      // so a create-less remove would mutate pre-existing (live) data.
+      if (!flowHasCreate) {
+        if ('remove' === step.op) { return }
+        if ('list' === step.op &&
+          (step.valid || []).some((v: any) => 'ItemNotExists' === v.apply)) { return }
+      }
       const opgen: OpGen = GENERATE_OP[step.op]
       if (opgen) {
         opgen(genCtx, step, index)

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

@@ -95,6 +95,130 @@ class EntyClass
         return Struct::clone($this->_match);
     }
 
+    /**
+     * Feature #4: run `action` through the full pipeline and yield result
+     * items, so the `streaming` feature's incremental output is reachable from
+     * a generated entity (a normal op call materialises the whole result).
+     * `callopts` parameterises the call:
+     *   - inbound (download): yield items/chunks (from the streaming feature
+     *     when active, else the materialised items);
+     *   - outbound (upload): an iterable `body` in callopts is attached to the
+     *     request so the transport can stream the payload;
+     *   - `ctrl` (pipeline control) and `signal` (cancellation) honoured.
+     */
+    public function stream(string $action, ?array $args = null, ?array $callopts = null): \Generator
+    {
+        $utility = $this->_utility;
+        $callopts = $callopts ?? [];
+        $signal = $callopts['signal'] ?? null;
+
+        $ctrl = is_array($callopts['ctrl'] ?? null) ? $callopts['ctrl'] : [];
+        $ctrl['stream'] = $callopts;
+
+        $ctxmap = [
+            "opname" => $action,
+            "ctrl" => $ctrl,
+            "match" => $this->_match,
+            "data" => $this->_data,
+        ];
+        if (is_array($args)) {
+            foreach ($args as $k => $v) {
+                $ctxmap[$k] = $v;
+            }
+        }
+
+        $ctx = ($utility->make_context)($ctxmap, $this->_entctx);
+
+        // Outbound: expose the caller's iterable payload so the request builder
+        // / transport can stream it as the request body.
+        $body = $callopts['body'] ?? null;
+        if ($body !== null) {
+            $ctx->reqdata['body$'] = $body;
+            $ctx->meta['stream_out'] = $body;
+        }
+
+        $aborted = function () use ($signal): bool {
+            if ($signal === null) {
+                return false;
+            }
+            if (is_callable($signal)) {
+                return (bool)$signal();
+            }
+            if (is_object($signal) && isset($signal->aborted)) {
+                return (bool)$signal->aborted;
+            }
+            return false;
+        };
+
+        ($utility->feature_hook)($ctx, "PrePoint");
+        [$point, $err] = ($utility->make_point)($ctx);
+        $ctx->out["point"] = $point;
+        if ($err) {
+            return;
+        }
+
+        ($utility->feature_hook)($ctx, "PreSpec");
+        [$spec, $err] = ($utility->make_spec)($ctx);
+        $ctx->out["spec"] = $spec;
+        if ($err) {
+            return;
+        }
+
+        ($utility->feature_hook)($ctx, "PreRequest");
+        [$resp, $err] = ($utility->make_request)($ctx);
+        $ctx->out["request"] = $resp;
+        if ($err) {
+            return;
+        }
+
+        ($utility->feature_hook)($ctx, "PreResponse");
+        [$resp2, $err] = ($utility->make_response)($ctx);
+        $ctx->out["response"] = $resp2;
+        if ($err) {
+            return;
+        }
+
+        ($utility->feature_hook)($ctx, "PreResult");
+        [$result, $err] = ($utility->make_result)($ctx);
+        $ctx->out["result"] = $result;
+        if ($err) {
+            return;
+        }
+
+        ($utility->feature_hook)($ctx, "PreDone");
+
+        $result = $ctx->result;
+
+        // Inbound: prefer the streaming feature's incremental generator; else
+        // fall back to the materialised items so stream always yields.
+        $streamfn = ($result !== null && isset($result->stream) && is_callable($result->stream))
+            ? $result->stream : null;
+        if ($streamfn !== null) {
+            foreach ($streamfn() as $item) {
+                if ($aborted()) {
+                    return;
+                }
+                yield $item;
+            }
+            return;
+        }
+
+        $data = ($utility->done)($ctx);
+        if (is_array($data) && array_is_list($data)) {
+            $items = $data;
+        } elseif ($data === null) {
+            $items = [];
+        } else {
+            $items = [$data];
+        }
+        foreach ($items as $item) {
+            if ($aborted()) {
+                return;
+            }
+            yield $item;
+        }
+    }
+
     // #LoadOp
 
     // #ListOp

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

@@ -18,6 +18,10 @@ require_once __DIR__ . '/features.php';
 
 use Voxgig\Struct\Struct;
 
+// Features record diagnostic state on the client as dynamic properties
+// (_retry, _cache, _metrics, ...); allow them explicitly (PHP 8.2+
+// deprecates implicit dynamic properties).
+#[\AllowDynamicProperties]
 class ProjectNameSDK
 {
     public string $mode;
@@ -54,14 +58,17 @@ class ProjectNameSDK
 
         $this->_rootctx->options = $this->options;
 
-        // Add features from config.
+        // Add features in the resolved order (make_options puts an explicit
+        // list order first, else defaults to test-first). Ordering matters: the
+        // `test` feature installs the base mock transport and the transport
+        // features (retry/cache/netsim/proxy/ratelimit) wrap whatever is
+        // current, so `test` must be added before them to sit at the base.
         $feature_opts = ProjectNameHelpers::to_map(Struct::getprop($this->options, "feature"));
         if ($feature_opts) {
-            $items = Struct::items($feature_opts);
-            if ($items) {
-                foreach ($items as $item) {
-                    $fname = $item[0];
-                    $fopts = ProjectNameHelpers::to_map($item[1]);
+            $featureorder = Struct::getpath($this->options, "__derived__.featureorder");
+            if (is_array($featureorder)) {
+                foreach ($featureorder as $fname) {
+                    $fopts = ProjectNameHelpers::to_map($feature_opts[$fname] ?? null);
                     if ($fopts && isset($fopts["active"]) && $fopts["active"] === true) {
                         ($utility->feature_add)($this->_rootctx, ProjectNameFeatures::make_feature($fname));
                     }

package/project/.sdk/src/cmp/py/Entity_py.ts

@@ -88,15 +88,14 @@ const Entity = cmp(function Entity(props: any) {
           // frag slots) — fills in the typed-model import for this entity.
           '# #TypeImports': typeImport,
 
-          // Fill the six per-op pipeline hook markers with real feature_hook
-          // calls. jostraca's `//`-based `#Name` slot pattern does not fire for
-          // Python's `# #`-comment markers, so substitute them as literal keys
-          // (exactly like the op fragments and `# #TypeImports` above).
-          ...Object.fromEntries(
-            ['PrePoint', 'PreSpec', 'PreRequest', 'PreResponse', 'PreResult', 'PreDone']
-              .map((h: string) => [`# #${h}-Hook`,
-              ({ indent }: any) => Content({ indent }, `utility.feature_hook(ctx, "${h}")`)])
-          ),
+          // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is
+          // hardcoded to `//` comments, so the Python fragment's
+          // `# #<Name>-Hook` marker lines never matched it and the pipeline
+          // hooks (PrePoint, PreRequest, ...) were silently dropped from the
+          // generated op runner. Match the `#`-comment form explicitly.
+          '/(?<indent>[ \\t]*)#[ \\t]*#(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\n?/':
+            ({ name, indent }: any) =>
+              `${indent}utility.feature_hook(ctx, "${name}")\n`,
 
           ...opfrags,
         }

package/project/.sdk/src/cmp/py/TestEntity_py.ts

@@ -77,6 +77,12 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const genCtx: GenCtx = { model, entity, flow: basicflow, PROJUPPER }
 
+  // The stream test streams the "list" op and asserts a 3-item collection, so
+  // it only applies to entities that actually declare a `list` op. Others
+  // (e.g. Batch = create/load) have no list endpoint — make_point would error
+  // and the stream would yield nothing — so skip the test for them.
+  const hasList = !!(entity.op && (entity.op as any).list)
+
   File({ name: 'test_' + entity.name + '_entity.' + target.ext }, () => {
 
     Content(`# ${entity.Name} entity test
@@ -101,7 +107,41 @@ class Test${entity.Name}Entity:
         testsdk = ${model.const.Name}SDK.test(None, None)
         ent = testsdk.${entity.Name}(None)
         assert ent is not None
+${hasList ? `
+    def test_should_stream(self):
+        # Feature #4: the entity stream(action, ...) method runs the op
+        # pipeline and yields result items. With the streaming feature active
+        # it yields the feature's incremental output; otherwise it falls back
+        # to the materialised list so stream always yields.
+        seed = {
+            "entity": {
+                "${entity.name}": {
+                    "s1": {"id": "s1"},
+                    "s2": {"id": "s2"},
+                    "s3": {"id": "s3"},
+                }
+            }
+        }
 
+        # Fallback: streaming inactive -> yields the materialised list items.
+        base = ${model.const.Name}SDK.test(seed, None)
+        seen = list(base.${entity.Name}(None).stream("list", None, None))
+        assert len(seen) == 3
+
+        # Inbound: streaming active -> yields each item from the feature.
+        from config import make_config
+        cfg = make_config()
+        if isinstance(cfg.get("feature"), dict) and "streaming" in cfg["feature"]:
+            sdk = ${model.const.Name}SDK.test(
+                seed, {"feature": {"streaming": {"active": True}}})
+            got = []
+            for item in sdk.${entity.Name}(None).stream("list", None, None):
+                if isinstance(item, list):
+                    got.extend(item)
+                else:
+                    got.append(item)
+            assert len(got) == 3
+` : ''}
     def test_should_run_basic_flow(self):
         setup = _${entity.name}_basic_setup(None)
         # Per-op sdk-test-control.json skip — basic test exercises a flow with
@@ -137,6 +177,14 @@ class Test${entity.Name}Entity:
 
     // Model-driven step iteration
     each(basicflow.step, (step: any, index: any) => {
+      // Never emit a REMOVE (or its removed-item verify LIST) without a
+      // preceding CREATE: a coherent CRUD flow only removes what it created,
+      // so a create-less remove would mutate pre-existing (live) data.
+      if (!flowHasCreate) {
+        if ('remove' === step.op) { return }
+        if ('list' === step.op &&
+          (step.valid || []).some((v: any) => 'ItemNotExists' === v.apply)) { return }
+      }
       const opgen: OpGen = GENERATE_OP[step.op]
       if (opgen) {
         opgen(genCtx, step, index)

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

@@ -60,6 +60,107 @@ class EntyClass:
         self._utility.feature_hook(self._entctx, "GetMatch")
         return vs.clone(self._match)
 
+    def stream(self, action, args=None, callopts=None):
+        # Feature #4: run `action` through the full pipeline and yield result
+        # items, so the `streaming` feature's incremental output is reachable
+        # from a generated entity (a normal op call materialises the whole
+        # result). `callopts` parameterises the call:
+        #   - inbound (download): yield items/chunks (from the streaming
+        #     feature when active, else the materialised items);
+        #   - outbound (upload): an iterable `body` in callopts is attached to
+        #     the request so the transport can stream the payload;
+        #   - `ctrl` (pipeline control) and `signal` (cancellation) honoured.
+        utility = self._utility
+
+        if callopts is None:
+            callopts = {}
+        signal = callopts.get("signal")
+
+        ctrl = dict(callopts.get("ctrl") or {})
+        ctrl["stream"] = callopts
+
+        ctxmap = {
+            "opname": action,
+            "ctrl": ctrl,
+            "match": self._match,
+            "data": self._data,
+        }
+        if isinstance(args, dict):
+            for k, v in args.items():
+                ctxmap[k] = v
+
+        ctx = utility.make_context(ctxmap, self._entctx)
+
+        # Outbound: expose the caller's iterable payload so the request builder
+        # / transport can stream it as the request body.
+        body = callopts.get("body")
+        if body is not None:
+            ctx.reqdata = dict(ctx.reqdata or {})
+            ctx.reqdata["body$"] = body
+            ctx.meta["stream_out"] = body
+
+        def aborted():
+            if signal is None:
+                return False
+            if callable(signal):
+                return bool(signal())
+            return bool(getattr(signal, "aborted", False))
+
+        utility.feature_hook(ctx, "PrePoint")
+        point, err = utility.make_point(ctx)
+        ctx.out["point"] = point
+        if err is not None:
+            return
+
+        utility.feature_hook(ctx, "PreSpec")
+        spec, err = utility.make_spec(ctx)
+        ctx.out["spec"] = spec
+        if err is not None:
+            return
+
+        utility.feature_hook(ctx, "PreRequest")
+        resp, err = utility.make_request(ctx)
+        ctx.out["request"] = resp
+        if err is not None:
+            return
+
+        utility.feature_hook(ctx, "PreResponse")
+        resp2, err = utility.make_response(ctx)
+        ctx.out["response"] = resp2
+        if err is not None:
+            return
+
+        utility.feature_hook(ctx, "PreResult")
+        result, err = utility.make_result(ctx)
+        ctx.out["result"] = result
+        if err is not None:
+            return
+
+        utility.feature_hook(ctx, "PreDone")
+
+        result = ctx.result
+
+        # Inbound: prefer the streaming feature's incremental generator; else
+        # fall back to the materialised items so stream always yields.
+        stream_fn = getattr(result, "stream", None) if result is not None else None
+        if callable(stream_fn):
+            for item in stream_fn():
+                if aborted():
+                    return
+                yield item
+        else:
+            data = utility.done(ctx)
+            if isinstance(data, list):
+                items = data
+            elif data is None:
+                items = []
+            else:
+                items = [data]
+            for item in items:
+                if aborted():
+                    return
+                yield item
+
     # #LoadOp
 
     # #ListOp
@@ -73,43 +174,49 @@ class EntyClass:
     def _run_op(self, ctx, post_done):
         utility = self._utility
 
-        # #PrePoint-Hook
+        try:
+            # #PrePoint-Hook
 
-        point, err = utility.make_point(ctx)
-        ctx.out["point"] = point
-        if err is not None:
-            return utility.make_error(ctx, err)
+            point, err = utility.make_point(ctx)
+            ctx.out["point"] = point
+            if err is not None:
+                return utility.make_error(ctx, err)
 
-        # #PreSpec-Hook
+            # #PreSpec-Hook
 
-        spec, err = utility.make_spec(ctx)
-        ctx.out["spec"] = spec
-        if err is not None:
-            return utility.make_error(ctx, err)
+            spec, err = utility.make_spec(ctx)
+            ctx.out["spec"] = spec
+            if err is not None:
+                return utility.make_error(ctx, err)
 
-        # #PreRequest-Hook
+            # #PreRequest-Hook
 
-        resp, err = utility.make_request(ctx)
-        ctx.out["request"] = resp
-        if err is not None:
-            return utility.make_error(ctx, err)
+            resp, err = utility.make_request(ctx)
+            ctx.out["request"] = resp
+            if err is not None:
+                return utility.make_error(ctx, err)
 
-        # #PreResponse-Hook
+            # #PreResponse-Hook
 
-        resp2, err = utility.make_response(ctx)
-        ctx.out["response"] = resp2
-        if err is not None:
-            return utility.make_error(ctx, err)
+            resp2, err = utility.make_response(ctx)
+            ctx.out["response"] = resp2
+            if err is not None:
+                return utility.make_error(ctx, err)
 
-        # #PreResult-Hook
+            # #PreResult-Hook
 
-        result, err = utility.make_result(ctx)
-        ctx.out["result"] = result
-        if err is not None:
-            return utility.make_error(ctx, err)
+            result, err = utility.make_result(ctx)
+            ctx.out["result"] = result
+            if err is not None:
+                return utility.make_error(ctx, err)
+
+            # #PreDone-Hook
+
+            post_done()
 
-        # #PreDone-Hook
+            return utility.done(ctx)
 
-        post_done()
+        except Exception:
+            # #PreUnexpected-Hook
 
-        return utility.done(ctx)
+            raise

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

@@ -41,14 +41,17 @@ class ProjectNameSDK:
 
         self._rootctx.options = self.options
 
-        # Add features from config.
+        # Add features in the resolved order (make_options puts an explicit
+        # list order first, else defaults to test-first). Ordering matters: the
+        # `test` feature installs the base mock transport and the transport
+        # features (retry/cache/netsim/proxy/ratelimit) wrap whatever is
+        # current, so `test` must be added before them to sit at the base.
         feature_opts = helpers.to_map(vs.getprop(self.options, "feature"))
         if feature_opts is not None:
-            feature_items = vs.items(feature_opts)
-            if feature_items is not None:
-                for item in feature_items:
-                    fname = item[0]
-                    fopts = helpers.to_map(item[1])
+            featureorder = vs.getpath(self.options, "__derived__.featureorder")
+            if isinstance(featureorder, list):
+                for fname in featureorder:
+                    fopts = helpers.to_map(feature_opts.get(fname))
                     if fopts is not None and fopts.get("active") is True:
                         utility.feature_add(self._rootctx, _make_feature(fname))
 

package/project/.sdk/src/cmp/rb/Entity_rb.ts

@@ -60,15 +60,14 @@ const Entity = cmp(function Entity(props: any) {
           // Entity.fragment.rb so the class can be renamed independently.
           EntyClass: cls,
 
-          // Fill the six per-op pipeline hook markers with real feature_hook
-          // calls. jostraca's `//`-based `#Name` slot pattern does not fire for
-          // Ruby's `# #`-comment markers, so substitute them as literal keys
-          // (exactly like the op fragments above).
-          ...Object.fromEntries(
-            ['PrePoint', 'PreSpec', 'PreRequest', 'PreResponse', 'PreResult', 'PreDone']
-              .map((h: string) => [`# #${h}-Hook`,
-              ({ indent }: any) => Content({ indent }, `utility.feature_hook.call(ctx, "${h}")`)])
-          ),
+          // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is
+          // hardcoded to `//` comments, so the Ruby fragment's
+          // `# #<Name>-Hook` marker lines never matched it and the pipeline
+          // hooks (PrePoint, PreRequest, ...) were silently dropped from the
+          // generated op runner. Match the `#`-comment form explicitly.
+          '/(?<indent>[ \\t]*)#[ \\t]*#(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\n?/':
+            ({ name, indent }: any) =>
+              `${indent}utility.feature_hook.call(ctx, "${name}")\n`,
 
           ...opfrags,
         }

package/project/.sdk/src/cmp/rb/ReadmeExamplesTest_rb.ts

@@ -117,7 +117,10 @@ ${entityLines}
     blocks = []
     DOCS.each do |label, path|
       assert File.exist?(path), "missing documentation source: #{label}"
-      File.read(path).scan(/#{fence}ruby\\r?\\n(.*?)#{fence}/m).each_with_index do |a, i|
+      # Explicit UTF-8: the docs contain non-ASCII punctuation, and under a
+      # POSIX/US-ASCII locale a default-encoded read makes scan raise
+      # ArgumentError (invalid byte sequence).
+      File.read(path, encoding: "UTF-8").scan(/#{fence}ruby\\r?\\n(.*?)#{fence}/m).each_with_index do |a, i|
         blocks << { doc: label, n: i, code: a[0] }
       end
     end