@voxgig/sdkgen 4.21.0 → 4.23.0

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

@@ -118,7 +118,6 @@ class ProjectNameSDK {
 
     const options = this._options
 
-    // Build spec directly from SDK options + user-provided fetch args.
     const spec: any = {
       base: options.base,
       prefix: options.prefix,
@@ -134,7 +133,6 @@ class ProjectNameSDK {
 
     ctx.spec = spec
 
-    // Merge user-provided headers over SDK defaults.
     if (fetchargs.headers) {
       const uheaders = fetchargs.headers
       for (let key in uheaders) {
@@ -144,7 +142,6 @@ class ProjectNameSDK {
 
     // #SecretsResolve
 
-    // Apply SDK auth (apikey, auth prefix, etc.)
     const authResult = prepareAuth(ctx)
     if (authResult instanceof Error) {
       return authResult
@@ -237,18 +234,6 @@ class ProjectNameSDK {
 
 
 
-  // Raw GraphQL access: the pressure valve that makes the generated
-  // surface's deliberate omissions (per-call selection sets, typed filter
-  // builders, batching, subscriptions) livable — the whole schema stays
-  // reachable.
-  //
-  // Thin wrapper over the same prepare/fetch path `direct` uses, with the
-  // one thing raw `direct` cannot do for GraphQL: a GraphQL failure rides
-  // HTTP 200 as a top-level `errors` array, so status alone would report a
-  // failed query as ok.
-  //
-  // NOTE: like `direct`, this bypasses the feature pipeline — no retry,
-  // ratelimit or paging features apply.
   async graphql(query: string, variables?: any, ctrl?: any) {
     const options = this._options
 

package/project/.sdk/src/cmp/ts/fragment/MainStation.fragment.ts

@@ -1,17 +1,5 @@
 
 
-// Station self-registration (voxgig/station design §6.2, path 1): linking
-// this package is the whole bootstrap. When the station library is
-// installed beside this SDK, the {construct, config} factory pair is
-// registered under the api slug (config.main.slug, the descriptor slug) at
-// module init, so `station.sdk('<name>')` needs no imports in application
-// code. Registration is SOFT — the station library is a peer dependency of
-// the station feature, and a project without it skips registration and
-// gets exactly the SDK it always had. Only a genuine module-not-found is
-// swallowed: a station that RESOLVES but throws while loading must
-// propagate (a silently empty factory table has no visible cause), and so
-// must station_factory_conflict — two different builds of one SDK in one
-// process is not a thing to pick between quietly.
 let stationInstalled = true
 try { require.resolve('STATIONPKG') }
 catch (err: any) {

package/project/.sdk/src/cmp/ts/fragment/SdkError.fragment.ts

@@ -11,15 +11,6 @@ class ProjectNameError extends Error {
   code: string
   ctx: Context
 
-  // HTTP status of the response that caused this error, or -1 when the
-  // request never got one (transport failure, client-side abort).
-  //
-  // PROMOTED to the top level on purpose. It used to be reachable only at
-  // `err.result.status` — two levels into an object that reads as internal —
-  // so every consumer of every generated SDK wrote the same
-  // `404 === e?.result?.status` branch and coupled itself to the internal
-  // shape of `result`. Mapping "not found" to a null result is table stakes
-  // for a client integration.
   status: number = -1
 
 

package/project/.sdk/src/cmp/ts/utility_ts.ts

@@ -15,53 +15,24 @@ import {
 } from '@voxgig/struct'
 
 
-// --- Model-driven example literals -----------------------------------------
-// Doc snippets must use example values whose TYPE matches the generated
-// TypeScript types, or the snippet does not compile. The id/match params of
-// load/remove/update are the common trap: their generated
-// `<Name><Op>Match` / `<Name><Op>Data` type is built from the op's params
-// (see EntityTypes_ts.ts), so a `number` id shown as a quoted string is a
-// TS2322 error. These helpers derive the example literal from the SAME model
-// source, so the docs and the generated types can never disagree.
 
 // The declared canon-type sentinel of a named parameter of an op — looked up
-// in the op's `points[].args.params[]` exactly as the typed-model generator
+// in the op's `points[].g.params[]` exactly as the typed-model generator
 // does. Falls back to the entity field of the same name (used when the op
 // has no params and the generated match type is `Partial<Entity>`). Returns
 // undefined when neither is present.
 function paramCanonType(entity: any, op: any, paramName: string): unknown {
-  // opParams, NOT a raw walk of op.points.
-  //
-  // opParams drops points flagged with select['$action'] and merges what is
-  // left; the typed-model generator reaches the op's params through it, so
-  // anything else is a DIFFERENT set of params wearing the same name.
-  //
-  // A raw walk returned the first match on ANY point, action points included.
-  // github's `action` entity has a field `owner` (`$OBJECT`, "A GitHub user")
-  // and seven create points whose path carries `{owner}` (a string) — so the
-  // type said Record<string, any> and the doc example said 'example_owner',
-  // and ts/README.md stopped compiling. Same for workflow_id: `number` in the
-  // type, quoted string in the example.
-  //
-  // Deriving from opParams is what actually makes good on the promise below —
-  // that the docs and the generated types cannot disagree.
   const params = op ? each(opParams(op)) : []
-  const found = (params as any[]).find((p: any) => p && p.name === paramName)
+  const found = (params as any[]).find((p: any) => p && p.n === paramName)
   if (found) {
-    return found.type
+    return found.t
   }
   const field = (entity && entity.fields ? each(entity.fields) : [])
-    .find((f: any) => f && f.name === paramName) as any
-  return field && field.type
+    .find((f: any) => f && f.n === paramName) as any
+  return field && field.t
 }
 
 
-// A type-correct example literal for a named match/data parameter of an op,
-// derived entirely from the model. INTEGER/NUMBER render as the bare number
-// `1` (a quoted string on a `number` field is a compile error), BOOLEAN as
-// `true`, ARRAY as the empty `[]` and OBJECT as the empty `{}` (a quoted
-// string is not assignable to `any[]` / `Record<string, any>`), everything
-// else (STRING, unknown, missing) as the quoted `placeholder`.
 function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
   // canonScalarKey, not canonKey: a nullable field's sentinel is the union
   // ['`$ONE`', ['`$NUMBER`','`$NULL`']], which canonKey stringifies into
@@ -107,17 +78,14 @@ function formatJson(obj: any, flags?: { line?: boolean, margin?: number }): stri
   let json: string
 
   if (flags?.line) {
-    // One line with spaces for clarity
     json = JSON.stringify(obj)
       .replace(/([{:\[,])/g, '$1 ')
       .replace(/([}\]])/g, ' $1')
   }
   else {
-    // Pretty printed with 2-space indentation
     json = JSON.stringify(obj, null, 2)
   }
 
-  // Add margin to the left of every line
   if (marginSize > 0) {
     json = json.split('\n').map(line => marginStr + line).join('\n')
   }
@@ -126,41 +94,14 @@ function formatJson(obj: any, flags?: { line?: boolean, margin?: number }): stri
 }
 
 
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
-// Keys whose value IS the default the runtime already assumes when the key is
-// absent, so emitting them is pure payload.
 const CONFIG_DEFAULT: Record<string, any> = {
   active: true,
   req: false,
   reqd: false,
 }
 
-// Subtrees carrying user payload rather than schema. An active:true inside an
-// OpenAPI example is DATA, not a default, so default-pruning stops at these
-// keys and everything below them is passed through untouched.
 const PAYLOAD_KEYS = ['default', 'example', 'examples']
 
 function clean(o: any, dropDefaults?: boolean): any {

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

@@ -41,32 +41,8 @@ const Config = cmp(async function Config(props: any) {
   // helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  // The canonical config OBJECT and its JSON, from the shared helper. Both
-  // representations render from the same `def`, so they cannot describe
-  // different configs - and this target picks up `options.server` (the
-  // OpenAPI server-variable defaults), which the hand-rolled build here
-  // omitted entirely. Passing target.name opts this target into the main
-  // slug/version/target identity fields (read by station's descriptor -
-  // see configDefinition).
   const { def: config } = configDefinition(model, target.name)
 
-  // WHERE the credential goes and UNDER WHAT NAME travel with the prefix
-  // now. apidef resolved both from the spec's securityScheme all along and
-  // generation dropped them, so an apiKey-in-query API got an authorization
-  // header it does not read. Emitted ONLY when they differ from the
-  // defaults, so every header/Authorization SDK's core/config.zig is
-  // byte-identical to what it generated before.
-  //
-  // Written onto configDefinition's OWN def rather than into a hand-built
-  // options literal, and the JSON re-serialised from that same def below -
-  // so this target's two representations (the h.jo(...) literal and the
-  // embedded CONFIG_DATA string above the size threshold) cannot disagree
-  // about where the credential goes. Both render from `config`.
-  //
-  // make_options_util's optspec must declare the same two keys or this is
-  // worse than inert: validate is CLOSED and discards the whole merged
-  // options object on an undeclared key. tm/zig/core/utility.zig carries
-  // them.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
   if (null != config.options && null != config.options.auth) {
@@ -83,16 +59,6 @@ const Config = cmp(async function Config(props: any) {
 
   File({ name: 'config.' + target.ext }, () => {
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // The literal is one nested expression that Zig's comptime evaluator has
-    // to walk in full at every build; a string constant is one token, and
-    // `json_parse` (std.json at the boundary, then fromStdJson) builds the
-    // same Value at runtime.
-    //
-    // The escaping is JSON.stringify's, which is valid Zig: it escapes every
-    // backslash, so the JSON's own `\uXXXX` reaches the file as `\\uXXXX` and
-    // no Zig escape sequence is ever formed from it.
     if (asData) {
       Content(`// Generated API configuration (mirrors go/rust core/config).
 
@@ -183,16 +149,6 @@ pub fn make_feature(name: []const u8) Feature {
 `)
     }
 
-    // The factory must be able to instantiate any built-in feature by name,
-    // not just the ones the current API model configures — a caller can enable
-    // a shipped feature (e.g. netsim) purely through runtime options even when
-    // 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 - 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)) {
@@ -224,27 +180,6 @@ const BUILTIN_FEATURES = [
 ]
 
 
-// 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
@@ -265,12 +200,9 @@ const FeaturePlugins = cmp(async function FeaturePlugins(props: any) {
       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 || {})) {
@@ -302,8 +234,6 @@ 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};

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

@@ -29,7 +29,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/zig/fragment/')
 
-  // Entity files go to entity/ as one file per entity.
   Folder({ name: 'entity' }, () => {
 
     File({ name: zigVarName(entity.name) + '.' + target.ext }, () => {
@@ -73,8 +72,6 @@ const Entity = cmp(function Entity(props: any) {
 
           EntyClass: cls,
 
-          // Matches every `// #<Stage>-Hook` marker in run_op (where `ctx` is
-          // the operation context). // comments -> default marker works.
           '#Entity-Hook': ({ name, indent }: any) =>
             Content({ indent }, `self.utility.feature_hook(ctx, "${name}");`),
 

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

@@ -28,42 +28,11 @@ import { Package } from './Package_zig'
 import { PrepareAuth } from './PrepareAuth_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
@@ -107,23 +76,6 @@ const Main = cmp(async function Main(props: any) {
   // 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 }) || {}
@@ -141,23 +93,10 @@ const Main = cmp(async function Main(props: any) {
     }
   }
 
-  // build.zig.zon — the package manifest, stamped with the model package name.
   Package({ target })
 
   Gitignore({})
 
-  // Copy tm/zig files with replacements. The tm src/ subtree only stages the
-  // per-feature custom-source dirs (target add), so it is excluded here
-  // exactly like the go/rust targets. build.zig.zon is generated by Package
-  // (above), so it is excluded from the verbatim copy. The SDK source lives at
-  // 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,
     // pluginExcludes: the generate-time plugin trim for an ACTIVE feature's
@@ -186,11 +125,6 @@ const Main = cmp(async function Main(props: any) {
 
   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',
@@ -233,8 +167,6 @@ const Main = cmp(async function Main(props: any) {
     })
   })
 
-  // 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',
@@ -243,7 +175,6 @@ const Main = cmp(async function Main(props: any) {
 
         '#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`)
@@ -261,19 +192,6 @@ const Main = cmp(async function Main(props: any) {
   // branded error type (error.zig) is a plain template (copied above).
   Folder({ name: 'core' }, () => {
 
-    // core/prepare_auth.zig is GENERATED, not copied from tm/zig: where the
-    // credential goes (header / query / cookie, and under what name) is a
-    // fact about the API, and the template it was extracted from -
-    // tm/zig/core/utility.zig - could only hold one answer. See
-    // PrepareAuth_zig.
-    //
-    // INSIDE THIS `core` FOLDER, and the component opens none of its own -
-    // the Config_zig arrangement, for the same reason. The extracted body
-    // lived in core/utility.zig, which `Copy({from: 'tm/zig'})` lands at
-    // `<root>/core/`, and core/utility.zig re-exports the function with a
-    // SIBLING-relative `@import("prepare_auth.zig")`. A second Folder here
-    // would write core/core/prepare_auth.zig, which that import cannot
-    // reach and `zig build` never analyses.
     PrepareAuth({ target })
 
     File({ name: 'sdk.' + target.ext }, () => {
@@ -286,7 +204,6 @@ const Main = cmp(async function Main(props: any) {
           }
         },
 
-        // Entity accessors - injected at SLOT
         () => {
           each(entity, (ent: ModelEntity) => {
             MainEntity({ target, entity: ent })

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

@@ -15,28 +15,6 @@ import type {
 import { zigModuleName, zigPackageFingerprint } from './utility_zig'
 
 
-// build.zig.zon — the Zig package manifest. Zig has no central package
-// registry, so there are no external registry dependencies to declare: the
-// voxgig struct port is vendored in-tree (utility/voxgigstruct) and wired as a
-// local module by build.zig. This generator only stamps the manifest with the
-// model-derived package name (the go/rust Package generators emit go.mod /
-// Cargo.toml the same way).
-//
-// The `.paths` allow-list mirrors the (registry-less) template: it only
-// matters when packaging for a registry, which zig does not do, so it is kept
-// stable.
-//
-// TOOLCHAIN: zig 0.16. `.name` is an ENUM LITERAL (`.solar_sdk`), and a
-// `.fingerprint` is required beside it. That pairing is what a modern zig
-// wants: 0.14 rejects the older plain-string form outright —
-// `build.zig.zon:2:13: error: expected enum literal` — and 0.13 rejects the
-// enum-literal form, so the two cannot both be supported from one generator.
-// A move BACK to 0.13 would mean reverting both fields here and the CI pin in
-// create-sdkgen project/standard/.github/workflows/ci.yml together.
-//
-// The fingerprint is derived from the package name, not random, so
-// regenerating the same model does not rewrite this file — see
-// zigPackageFingerprint for why, and for what zig checks.
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
   const target = props.target