@voxgig/sdkgen 4.20.0 → 4.22.0

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

@@ -8,12 +8,6 @@ const FEATURE_CLASS: Record<string, typeof BaseFeature> = {
 }
 
 
-// Per-feature plugin DEFINITIONS (voxgig/plugin `Definition` values), from
-// the model's active plugin groups. A feature that takes a `plugins` option
-// (secrets over sekreto) reads its own entry; a feature with no plugins has
-// none. Named imports above make each definition statically reachable, so
-// an SDK carries exactly the plugin modules its model selects — the same
-// leanness the old side-effect registry imports bought, without a registry.
 const FEATURE_PLUGINS: Record<string, any[]> = {
   // #FeaturePlugins
 }
@@ -24,7 +18,6 @@ class Config {
   makeFeature(this: any, fn: string) {
     const fc = FEATURE_CLASS[fn]
     const fi = new fc()
-    // TODO: errors etc
     return fi
   }
 

package/project/.sdk/src/cmp/ts/fragment/Direct.test.fragment.ts

@@ -17,10 +17,6 @@ import {
 } from '../../utility'
 
 
-// AFTER the imports on purpose: TypeScript hoists `import` above any
-// statement in the emitted CommonJS, so a loader placed above them would
-// run only after every imported module had already been evaluated - and
-// anything reading process.env at module scope would miss these values.
 loadEnvLocal(__dirname + '/../../../.env.local')
 
 
@@ -32,9 +28,6 @@ describe('EntityNameDirect', async () => {
 
   test('direct-exists', async () => {
     const sdk = new ProjectNameSDK({
-      // Concrete base: a live construction must satisfy any server
-      // variables a templated base URL declares; overriding base with a
-      // literal (as the direct flow tests do) sidesteps the requirement.
       base: 'http://localhost:8080',
       system: { fetch: async () => ({}) }
     })

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

@@ -17,7 +17,6 @@ import type {
 // #TypeImports
 
 
-// TODO: needs Entity superclass
 class EntyClass extends ProjectNameEntityBase<EntityDataType> {
 
   constructor(client: ProjectNameSDK, entopts: any) {

package/project/.sdk/src/cmp/ts/fragment/Entity.test.fragment.ts

@@ -25,10 +25,6 @@ import {
 } from '../../utility'
 
 
-// AFTER the imports on purpose: TypeScript hoists `import` above any
-// statement in the emitted CommonJS, so a loader placed above them would
-// run only after every imported module had already been evaluated - and
-// anything reading process.env at module scope would miss these values.
 loadEnvLocal(__dirname + '/../../../.env.local')
 
 

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

@@ -14,9 +14,6 @@ import type {
 } from './types'
 
 
-// TODO: needs Entity superclass
-// `D` is the entity's typed data model (e.g. Advice); subclasses bind it via
-// `class AdviceEntity extends ProjectNameEntityBase<Advice>`.
 class ProjectNameEntityBase<D = any> {
   name = ''
   name_ = ''
@@ -32,9 +29,6 @@ class ProjectNameEntityBase<D = any> {
   _match: Partial<D>
   _entctx: Context
 
-  // Set once a successful `remove` resolves on this instance. The entity
-  // KEEPS the data it held — a caller can still read what was deleted — but
-  // it is no longer a live record.
   _deleted: boolean
 
 
@@ -114,15 +108,6 @@ class ProjectNameEntityBase<D = any> {
   }
 
 
-  // Streaming operations. Runs `action` through the full pipeline and returns
-  // an async iterator over 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): iterate the yielded items/chunks (from the
-  //     streaming feature when active, else the materialised items);
-  //   - outbound (upload): pass an async-iterable `body` to stream a request
-  //     payload — it is attached to the request so the transport can send it;
-  //   - `ctrl` (pipeline control) and `signal` (AbortSignal) are honoured.
   async *stream(this: any, action: string, args?: any, callopts?: any): AsyncGenerator<any> {
     const utility = this._utility
     const {
@@ -197,11 +182,6 @@ class ProjectNameEntityBase<D = any> {
 
   toJSON() {
     const struct = this._utility.struct
-  // The marker is NAMESPACED. It used to be `entity$` — a short, generic
-  // name, and the `$`-suffix convention is not unique to sdkgen. Seneca uses
-  // `entity$` on its own entities to hold the canon, so an SDK record fed
-  // into `entize` silently overwrote it and produced entities claiming a
-  // canon that does not exist: no error, just wrong entities.
     return struct.merge([{}, struct.getdef(this._data, {}), { 'voxgig$entity': this.Name }])
   }
 

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

@@ -87,12 +87,6 @@ class EntityOperation {
 
       const out = done(ctx)
 
-      // An operation resolves to the ENTITY, not the raw data — the record
-      // has just been absorbed into this instance and is reached through
-      // data(). `done` still runs: it completes the pipeline and raises on
-      // failure, and when throwing is disabled it hands back the error
-      // payload, which passes through unchanged. See AGENTS.md "Entity
-      // operations return ENTITIES".
       return (ctx.result && ctx.result.ok) ? this : out
     }
     catch (err: any) {

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

@@ -92,12 +92,6 @@ class EntityOperation {
 
       const out = done(ctx)
 
-      // An operation resolves to the ENTITY, not the raw data — the record
-      // has just been absorbed into this instance and is reached through
-      // data(). `done` still runs: it completes the pipeline and raises on
-      // failure, and when throwing is disabled it hands back the error
-      // payload, which passes through unchanged. See AGENTS.md "Entity
-      // operations return ENTITIES".
       return (ctx.result && ctx.result.ok) ? this : out
     }
     catch (err: any) {

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

@@ -10,14 +10,6 @@ class EntityOperation {
 
   // EJECT-START
 
-  // Resolves to THIS entity, marked as deleted — like every other operation,
-  // which resolve to the entity too (see AGENTS.md). The instance keeps the
-  // data it held, so a caller can still read what was removed; `deleted()`
-  // reports that it is no longer a live record.
-  //
-  // A DELETE that answers 204 No Content therefore still resolves to
-  // something useful, where returning the raw body resolved to `undefined`
-  // against a signature that promised a record.
   async remove(
     this: any, reqmatch?: EntityNameRemoveMatch, ctrl?: Control,
   ): Promise<EntyClass> {
@@ -103,14 +95,7 @@ class EntityOperation {
 
       const out = done(ctx)
 
-      // An operation resolves to the ENTITY, not the raw data — the record
-      // has just been absorbed into this instance and is reached through
-      // data(). `done` still runs: it completes the pipeline and raises on
-      // failure, and when throwing is disabled it hands back the error
-      // payload, which passes through unchanged. See AGENTS.md "Entity
-      // operations return ENTITIES".
       if (ctx.result && ctx.result.ok) {
-        // A removed entity keeps its data but is no longer a live record.
         this.markDeleted()
         return this
       }

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

@@ -93,12 +93,6 @@ class EntityOperation {
 
       const out = done(ctx)
 
-      // An operation resolves to the ENTITY, not the raw data — the record
-      // has just been absorbed into this instance and is reached through
-      // data(). `done` still runs: it completes the pipeline and raises on
-      // failure, and when throwing is disabled it hands back the error
-      // payload, which passes through unchanged. See AGENTS.md "Entity
-      // operations return ENTITIES".
       return (ctx.result && ctx.result.ok) ? this : out
     }
     catch (err: any) {

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,14 +15,6 @@ 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
@@ -30,21 +22,6 @@ import {
 // 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)
   if (found) {
@@ -56,12 +33,6 @@ function paramCanonType(entity: any, op: any, paramName: string): unknown {
 }
 
 
-// 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}");`),