@voxgig/sdkgen 4.10.0 → 4.11.0

package/project/.sdk/src/cmp/ocaml/Package_ocaml.ts

@@ -9,17 +9,41 @@ import {
 
 
 import { packageName } from './utility_ocaml'
+import { secretsBuild } from './Config_ocaml'
 
 
 // <name>.opam — opam package metadata (publish is declared pending in the
 // model; the build itself is stock ocamlc via the Makefile and needs no opam
 // packages). Twin of rust Cargo.toml, but the runtime is dependency-free so
 // there is no depends list beyond the OCaml compiler.
+//
+// The secrets feature's build model is NOT emitted from here, unlike
+// Package_rust's rustls dependency table: the Makefile reads the generated
+// feature/secrets/feature.mk (Main_ocaml), which lists the vendored modules
+// in dependency order and turns the OpenSSL binding on only when a plugin
+// group needing a transport is active. What this manifest CAN state is the
+// system dependency that binding introduces - `depexts`, opam's word for a
+// distribution package - and it states it on exactly the same condition,
+// read from the same helper, so the two cannot drift.
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
   const model = ctx$.model
 
+  const secrets = secretsBuild(model, target)
+  const depexts = null != secrets && secrets.tls
+    ? `# The secrets feature's plugin groups (${secrets.tlsGroups.join(', ')}) bind
+# OpenSSL through the vendored plugins/tls_stubs.c (-lssl -lcrypto), the
+# one external dependency an ocaml SDK can have. Linked only because those
+# groups are active - see feature/secrets/feature.mk.
+depexts: [
+  ["libssl-dev"] {os-family = "debian"}
+  ["openssl-devel"] {os-family = "rhel"}
+  ["openssl"] {os = "macos" & os-distribution = "homebrew"}
+]
+`
+    : ''
+
   // WHO WROTE THIS PACKAGE. Per target, falling back to the model-wide value
   // and then to the publisher — so a manifest cannot go on naming Voxgig
   // while the model names someone else, which is exactly what the hardcoded
@@ -46,7 +70,7 @@ depends: [
 build: [
   [make "build"]
 ]
-`)
+${depexts}`)
   })
 })
 

package/project/.sdk/src/cmp/zig/Config_zig.ts

@@ -2,6 +2,7 @@
 import {
   Content,
   File,
+  Folder,
   cmp,
   configDefinition,
   configReprSetting,
@@ -156,14 +157,11 @@ pub fn make_feature(name: []const u8) Feature {
     // the API def does not list it. The built-in set mirrors the feature
     // templates in tm/zig/feature/ (excluding `base`, the fallback, and
     // `support`, a helper module). Any model feature not already built in is
-    // appended so bespoke features still resolve.
-    const builtinFeatures = [
-      'audit', 'cache', 'clienttrack', 'cost', 'debug', 'idempotency', 'log',
-      'metrics', 'netsim', 'paging', 'proxy', 'ratelimit', 'rbac',
-      'retry', 'streaming', 'telemetry', 'test', 'timeout',
-    ]
-
-    const featureNames: string[] = [...builtinFeatures]
+    // appended so bespoke features still resolve - and so does a GATED one
+    // (`secrets`), whose source ships with the tree but whose `@import`s name
+    // build modules that exist only when the model activates it: naming it
+    // here unconditionally would make every zig SDK fail to build.
+    const featureNames: string[] = [...BUILTIN_FEATURES]
     each(feature, (f: any) => {
       if (f.name !== 'base' && !featureNames.includes(f.name)) {
         featureNames.push(f.name)
@@ -183,6 +181,129 @@ pub fn make_feature(name: []const u8) Feature {
 })
 
 
+// The features tm/zig/feature/ ships UNGATED: every zig SDK has their source
+// and root.zig exports their types statically, so Config's factory can name
+// them whatever the model says. Shared with Main_zig, which uses the same
+// list to decide which ACTIVE features still need a root.zig export.
+const BUILTIN_FEATURES = [
+  'audit', 'cache', 'clienttrack', 'cost', 'debug', 'idempotency', 'log',
+  'metrics', 'netsim', 'paging', 'proxy', 'ratelimit', 'rbac',
+  'retry', 'streaming', 'telemetry', 'test', 'timeout',
+]
+
+
+// THE PLUGIN DEFINITIONS, as the root of the `sekretoplugins` build module:
+// feature/<name>/plugins.zig (the zig peer of Config_go's featurePlugins map
+// and of the plugins.rs index Main_rust emits).
+//
+// Upstream sekreto's contract since its registry was retired: a provider
+// kind not handed to the constructor is unknown to that Sekreto. So this
+// file IS the SDK's provider vocabulary - and in zig it is also what makes
+// the plugin trim REAL: a module root reaches only what it names, so a kind
+// missing here is neither in the vocabulary nor compiled, and a kind named
+// here whose file the trim removed is a compile error rather than a silent
+// one. That is exactly the shape upstream recommends for a lean consumer
+// (plugins/all.zig: "roots its plugins module at the one file it needs").
+//
+// It sits one level ABOVE the vendored `plugins/` directory, deliberately:
+// the vendoring guard fails any non-vendored file inside a vendored dir, and
+// a zig module root reaches its whole SUBTREE, so `plugins/<kind>.zig` is
+// within reach from here while the file itself is outside the guarded tree.
+//
+// Emitted only for a feature that is ACTIVE for this target (targetFeatures),
+// which is also exactly when build.zig declares the module that roots here -
+// an inactive model gets neither, so nothing dangles.
+const FeaturePlugins = cmp(async function FeaturePlugins(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+  const model: Model = ctx$.model
+
+  const feature = targetFeatures(model, target)
+
+  each(feature, (feat: any) => {
+    // `only_active: false`, the subtlety pluginExcludesFor documents: the
+    // feature object a component is handed has already been filtered, so a
+    // feature whose plugins are ALL inactive would arrive with nothing here
+    // and the module root build.zig points at would not be emitted at all.
+    const declared = getModelPath(model,
+      `main.${KIT}.feature.${feat.name}.plugin`,
+      { required: false, only_active: false }) || {}
+
+    if (0 === Object.keys(declared).length) {
+      return
+    }
+
+    // symbol -> the file (target-root-relative) that exports it.
+    const defs: Record<string, string> = {}
+
+    each(declared, (plugin: any) => {
+      // Filter on `active` HERE (Config_go's note): getting this wrong names
+      // a file the trim just removed, which is a compile error.
+      if (true !== plugin.active) return
+
+      for (const [sym, one] of Object.entries(plugin.def?.zig || {})) {
+        defs[sym] = String(one)
+      }
+    })
+
+    Folder({ name: 'feature' }, () => {
+      Folder({ name: feat.name }, () => {
+        File({ name: 'plugins.' + target.ext }, () => {
+          Content(`// The plugin definitions the model selected for the \`${feat.name}\`
+// feature (generated - see Config_zig FeaturePlugins). The ROOT of the
+// \`sekretoplugins\` build module: zig analyses only what a module root
+// reaches, so a kind this file does not name is neither in the provider
+// vocabulary nor compiled - this file IS the plugin trim.
+//
+// Upstream sekreto's contract since its registry was retired: a provider
+// kind not handed to the constructor is unknown to that Sekreto.
+
+const sekreto = @import("sekreto");
+
+// The shared HTTP round-trip the vault kinds import by relative path, and
+// the exchange's fetch of last resort (feature/${feat.name}.zig). In NO
+// plugin group, so it is always reachable from here - which is what
+// upstream's own all.zig does.
+pub const httpjson = @import("plugins/httpjson.zig");
+
+`)
+          const syms = Object.keys(defs).sort()
+
+          for (const sym of syms) {
+            // 'feature/secrets/plugins/aws.zig' -> 'plugins/aws.zig', relative
+            // to this file's directory (feature/<name>/).
+            const rel = defs[sym].replace(new RegExp('^feature/' +
+              feat.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/'), '')
+            Content(`pub const ${sym} = @import("${rel}").${sym};
+`)
+          }
+
+          if (0 < syms.length) {
+            Content(`
+pub const SELECTED = [_]sekreto.Definition{
+`)
+            for (const sym of syms) {
+              Content(`    ${sym},
+`)
+            }
+            Content(`};
+`)
+          }
+          else {
+            Content(`// No plugin group is active: the chain can name the four built-in kinds
+// (env, memory, dotenv, file) and nothing else.
+pub const SELECTED = [_]sekreto.Definition{};
+`)
+          }
+        })
+      })
+    })
+  })
+})
+
+
 export {
-  Config
+  Config,
+  FeaturePlugins,
+  BUILTIN_FEATURES,
 }

package/project/.sdk/src/cmp/zig/Main_zig.ts

@@ -3,7 +3,9 @@ import * as Path from 'node:path'
 
 import {
   cmp, each,
-  File, Copy, Folder, Fragment,
+  File, Content, Copy, Folder, Fragment,
+  pluginExcludes,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -18,18 +20,124 @@ import {
 } from '@voxgig/apidef'
 
 
-import { Config } from './Config_zig'
+import { Config, FeaturePlugins, BUILTIN_FEATURES } from './Config_zig'
 import { Gitignore } from './Gitignore_zig'
 import { MainEntity } from './MainEntity_zig'
 import { Package } from './Package_zig'
 
 
+// Which features ship a zig test suite under test/feature/<name>/, and the
+// file build.zig must NAME to run it. zig has no test auto-discovery: a
+// suite the build file does not list exists and never runs. A map rather
+// than a convention because the file has to EXIST - `zig build` fails the
+// whole build on a test path it cannot find - so this may only name suites
+// the templates actually carry.
+//
+// The suite sits under test/feature/<name>/ so that it belongs to the
+// feature (helpers/featureSource), exactly as go's tm/go/test/feature/
+// secrets/ and rust's tests/feature/secrets/ do; and it is wired only for
+// a feature that is ACTIVE for this target, which is when its build modules
+// (below) exist for the suite to reach.
+//
+// Each suite gets its OWN build step (`zig build test-<name>`) as well as a
+// place in the all-tests `test` step: the corpus suites need a project's
+// compiled `.sdk/test/test.json` beside the SDK, so a checker that has the
+// feature but no corpus (sdkgen's own generatedcompile lane) can still run
+// the feature suite alone and read its count.
+const FEATURE_TESTS: Record<string, string> = {
+  secrets: 'test/feature/secrets/secrets_test.zig',
+}
+
+
+// The GATED features' build modules: what a feature's `@import("<name>")`
+// lines resolve to, declared only when the feature is active. Each entry is
+// the block of build.zig statements that wires one feature; `secrets` is
+// the first and, today, the only one.
+//
+// Upstream's own three-module boundary (sekreto's zig Makefile builds
+// exactly these): `plugin` (voxgig/plugin, rooted at its consumer root),
+// `sekreto` (the core, which imports `plugin` by name and nothing under
+// plugins/), and `sekretoplugins`, rooted at the GENERATED
+// feature/secrets/plugins.zig (Config_zig FeaturePlugins) so that only the
+// selected kinds are compiled. The sdk module gets `sekreto` and
+// `sekretoplugins`; the feature file reaches `plugin` through
+// `sekreto.plugin`, so it needs no import of its own.
+const FEATURE_MODULES: Record<string, string> = {
+  secrets: `// The secrets feature's vendored libraries (@voxgig/sekreto and
+// voxgig/plugin at the shared vendor tag), as the three named modules
+// upstream builds them as. Declared ONLY when the model activates the
+// feature: feature/secrets.zig is the sole importer, and an inactive SDK
+// never analyses it (zig compiles only what a module root reaches).
+const plugin_mod = b.addModule("plugin", .{
+    .root_source_file = b.path("feature/secrets/plugin/plugin.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+const sekreto_mod = b.addModule("sekreto", .{
+    .root_source_file = b.path("feature/secrets/sekreto/sekreto.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+sekreto_mod.addImport("plugin", plugin_mod);
+// Rooted at the GENERATED selection (feature/secrets/plugins.zig), never
+// at upstream's full-set all.zig: the root decides which kinds compile.
+const sekretoplugins_mod = b.addModule("sekretoplugins", .{
+    .root_source_file = b.path("feature/secrets/plugins.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+sekretoplugins_mod.addImport("sekreto", sekreto_mod);
+sekretoplugins_mod.addImport("plugin", plugin_mod);
+sdk_mod.addImport("sekreto", sekreto_mod);
+sdk_mod.addImport("sekretoplugins", sekretoplugins_mod);
+`,
+}
+
+
 const Main = cmp(async function Main(props: any) {
 
   const { target } = props
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
+
+  // THE PLUGIN TRIM FOR AN INACTIVE FEATURE (the scala shape, for the same
+  // reason). pluginExcludes(model) walks only the model's ACTIVE features,
+  // which is right for a target whose feature trim is on: an inactive
+  // feature's whole tree is already gone at `target add`. zig's feature trim
+  // is OFF (model/target/zig.aon `feature: { trim: false }` - root.zig's
+  // built-in exports are static), so an inactive feature's tree is all still
+  // here, and its provider plugins are the part that costs the most. EVERY
+  // declared group of an inactive feature goes, not just the groups marked
+  // inactive: a feature that is off has no active plugins whatever its
+  // `plugin` map says, because targetFeatures drops the feature before
+  // Config ever reads a group. What stays is the two vendored cores and the
+  // ungrouped httpjson/sigv4 helpers - dead files zig never analyses, since
+  // build.zig declares no module rooted in them (FEATURE_MODULES).
+  //
+  // Rooting matches pluginExcludes': zig's declared paths are
+  // target-root-relative, which is this Copy's root, and the other targets'
+  // paths in the same list cannot match anything in a zig tree.
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const allfeature = getModelPath(model, `main.${KIT}.feature`,
+    { required: false, only_active: false }) || {}
+  const inactivePluginExcludes: RegExp[] = []
+  for (const fname of Object.keys(allfeature)) {
+    if (null != (feature as any)[fname]) continue
+    const groups = getModelPath(model, `main.${KIT}.feature.${fname}.plugin`,
+      { required: false, only_active: false }) || {}
+    for (const gname of Object.keys(groups)) {
+      for (const one of (groups[gname].path || [])) {
+        const pat = esc(String(one))
+        inactivePluginExcludes.push(new RegExp('(^|/)' +
+          pat.replace(/\\\/$/, '') + (/\/$/.test(String(one)) ? '/' : '$')))
+      }
+    }
+  }
 
   // build.zig.zon — the package manifest, stamped with the model package name.
   Package({ target })
@@ -43,14 +151,110 @@ const Main = cmp(async function Main(props: any) {
   // the tree root (core/, feature/, utility/, entity/, test/) — Zig's
   // idiomatic src/ is not used, to keep the exclude rule identical to the
   // reference targets.
+  //
+  // build.zig and root.zig are NOT in tm/zig any more: both carry
+  // model-driven slots (a gated feature's build modules, test step and root
+  // export) and are emitted below from src/cmp/zig/fragment/, the way
+  // core/sdk.zig always was.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//, /build\.zig\.zon$/],
+    // pluginExcludes: the generate-time plugin trim for an ACTIVE feature's
+    // inactive groups (the model's `path` entries are target-root-relative,
+    // which is this Copy's root); inactivePluginExcludes (above) for the
+    // groups of a feature that is itself off.
+    exclude: [
+      /src\//,
+      /build\.zig\.zon$/,
+      ...pluginExcludes(model),
+      ...inactivePluginExcludes,
+    ],
     replace: {
       ...props.ctx$.stdrep,
     }
   })
 
+  // The active features that root.zig does not export statically: the
+  // BUILT-IN set is in the template, so this is the gated ones (`secrets`)
+  // and any bespoke feature the model adds. Config_zig names the same
+  // features in make_feature, from the same list, so the two cannot drift.
+  const extraFeatures = each(feature)
+    .filter((f: any) => 'base' !== f.name && !BUILTIN_FEATURES.includes(f.name))
+    .map((f: any) => f.name)
+    .sort()
+
+  const fragdir = Path.normalize(__dirname + '/../../../src/cmp/zig/fragment/')
+
+  // build.zig: the template with its two slots filled - a gated feature's
+  // modules after the sdk module, and its test suite as a step of its own
+  // that the all-tests step also depends on. Both empty for a model that
+  // activates no gated feature, which leaves the file byte-identical to the
+  // fragment minus the marker lines.
+  File({ name: 'build.zig' }, () => {
+    Fragment({
+      from: fragdir + 'Build.fragment.zig',
+      replace: {
+        ...props.ctx$.stdrep,
+
+        '#FeatureModules': ({ indent }: any) => {
+          for (const fname of extraFeatures) {
+            const block = FEATURE_MODULES[fname]
+            if (null != block) Content({ indent }, block)
+          }
+        },
+
+        '#FeatureTestSteps': ({ indent }: any) => {
+          for (const fname of extraFeatures) {
+            const suite = FEATURE_TESTS[fname]
+            if (null == suite) continue
+            Content({ indent }, `// The ${fname} feature suite: part of \`zig build test\`, and alone as
+// \`zig build test-${fname}\` (see FEATURE_TESTS in Main_zig).
+{
+    const ${fname}_mod = b.createModule(.{
+        .root_source_file = b.path("${suite}"),
+        .target = target,
+        .optimize = optimize,
+    });
+    ${fname}_mod.addImport("voxgig-struct", struct_mod);
+    ${fname}_mod.addImport("sdk", sdk_mod);
+    ${fname}_mod.addImport("omni", omni_mod);
+    const ${fname}_test = b.addTest(.{ .root_module = ${fname}_mod });
+    const run_${fname} = b.addRunArtifact(${fname}_test);
+    run_${fname}.has_side_effects = true;
+    test_step.dependOn(&run_${fname}.step);
+    const ${fname}_step = b.step("test-${fname}", "Run the ${fname} feature suite alone");
+    ${fname}_step.dependOn(&run_${fname}.step);
+}
+`)
+          }
+        },
+      }
+    })
+  })
+
+  // root.zig: the module root, with the gated features' type exports
+  // appended to the static built-in ones.
+  File({ name: 'root.zig' }, () => {
+    Fragment({
+      from: fragdir + 'Root.fragment.zig',
+      replace: {
+        ...props.ctx$.stdrep,
+
+        '#FeatureExports': ({ indent }: any) => {
+          for (const fname of extraFeatures) {
+            // MUST match Config_zig's make_feature spelling of the type.
+            const tname = fname.charAt(0).toUpperCase() + fname.slice(1)
+            Content({ indent },
+              `pub const ${tname}Feature = @import("feature/${fname}.zig").${tname}Feature;\n`)
+          }
+        },
+      }
+    })
+  })
+
+  // feature/<name>/plugins.zig: the selected plugin definitions, as the root
+  // of the `sekretoplugins` module build.zig declares above (active only).
+  FeaturePlugins({ target })
+
   // Generated core files: the client (sdk.zig) and the API config. The
   // branded error type (error.zig) is a plain template (copied above).
   Folder({ name: 'core' }, () => {
@@ -59,7 +263,7 @@ const Main = cmp(async function Main(props: any) {
 
       Fragment(
         {
-          from: Path.normalize(__dirname + '/../../../src/cmp/zig/fragment/Main.fragment.zig'),
+          from: fragdir + 'Main.fragment.zig',
           replace: {
             ...props.ctx$.stdrep,
           }

package/project/.sdk/{tm/zig/build.zig → src/cmp/zig/fragment/Build.fragment.zig}

@@ -15,6 +15,11 @@ const std = @import("std");
 // The Zig test framework can crash with signal 11 during cleanup *after* all
 // tests pass, due to *MapRef/*ListRef cross-references in arena teardown. The
 // Makefile filters the output: "N/N tests passed" with N==total is success.
+//
+// GENERATED from src/cmp/zig/fragment/Build.fragment.zig (Main_zig): the
+// `// #...` marker lines there are slots the generator fills from the model -
+// a GATED feature's build modules and its test step appear only when the
+// feature is active, so an SDK without that feature declares none of them.
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
@@ -44,6 +49,7 @@ pub fn build(b: *std.Build) void {
         .optimize = optimize,
     });
     sdk_mod.addImport("voxgig-struct", struct_mod);
+    // #FeatureModules
 
     const test_step = b.step("test", "Run all tests");
 
@@ -73,4 +79,5 @@ pub fn build(b: *std.Build) void {
         run_t.has_side_effects = true;
         test_step.dependOn(&run_t.step);
     }
+    // #FeatureTestSteps
 }

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

@@ -40,6 +40,22 @@ pub const ProjectNameSDK = struct {
     rootctx: ?*Context = null,
 
     pub fn new(options: Value) *ProjectNameSDK {
+        return new_with(options, &.{});
+    }
+
+    // The `extend` seam, in zig's spelling. go/ts/py read live Feature
+    // objects off `options.extend`; a zig Value is a CLOSED data union that
+    // cannot carry a Feature, so the extension list is a second argument
+    // instead - same meaning, same position in construction (added after the
+    // config-driven features, before any init runs).
+    //
+    // DELIBERATE DIVERGENCE: an extension whose NAME the config already
+    // installed is skipped. go adds it regardless and the kotlin/java suites
+    // work around the resulting double install (two transport wraps, two
+    // purchases) by probing the config first; here the seam itself keeps the
+    // set to one feature per name, so a suite can always hand in the feature
+    // it needs and hold in any generated tree.
+    pub fn new_with(options: Value, extend: []const Feature) *ProjectNameSDK {
         const sdk = h.A().create(ProjectNameSDK) catch unreachable;
         sdk.* = .{
             .mode = "live",
@@ -92,6 +108,15 @@ pub const ProjectNameSDK = struct {
             }
         }
 
+        // Add extension features (see new_with).
+        for (extend) |f| {
+            var present = false;
+            for (sdk.features.items) |have| {
+                if (std.mem.eql(u8, have.name(), f.name())) present = true;
+            }
+            if (!present) sdk.sdkUtility.feature_add(rootctx, f);
+        }
+
         // Initialize features.
         var snap: std.ArrayList(Feature) = .empty;
         for (sdk.features.items) |f| snap.append(h.A(), f) catch {};

package/project/.sdk/{tm/zig/root.zig → src/cmp/zig/fragment/Root.fragment.zig}

@@ -1,5 +1,8 @@
 // ProjectName SDK for Zig (generated by @voxgig/sdkgen).
 //
+// GENERATED from src/cmp/zig/fragment/Root.fragment.zig (Main_zig) - see the
+// FeatureExports marker below for the one model-driven slot.
+//
 // The module root: it re-exports the public surface and pulls in the whole
 // SDK graph (core -> config -> features/utility/entities) so `@import("sdk")`
 // from the test suite sees everything. Layout mirrors the other targets:
@@ -59,6 +62,12 @@ pub const DebugFeature = @import("feature/debug.zig").DebugFeature;
 pub const AuditFeature = @import("feature/audit.zig").AuditFeature;
 pub const ClienttrackFeature = @import("feature/clienttrack.zig").ClienttrackFeature;
 pub const RbacFeature = @import("feature/rbac.zig").RbacFeature;
+// GATED features (model/feature/<name>.aon `needs:`), exported ONLY when the
+// model activates them: their source reaches a named build module (the
+// vendored sekreto for `secrets`) that build.zig declares under the same
+// condition, so a static export here would name a module an inactive SDK
+// does not have. Filled by Main_zig from this marker.
+// #FeatureExports
 
 // Value helpers, re-exported so tests/consumers can build data.
 pub const h = helpers;