@voxgig/sdkgen 1.3.14 → 1.3.18

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

@@ -0,0 +1,61 @@
+
+import {
+  Content,
+  File,
+  cmp,
+} from '@voxgig/sdkgen'
+
+
+import type {
+  Model,
+} from '@voxgig/apidef'
+
+
+import { zigModuleName } 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. `.name` is a plain string here rather than the newer enum-literal +
+// fingerprint form.
+//
+// TOOLCHAIN PIN: the string form REQUIRES zig <= 0.13. Zig 0.14 rejects it
+// outright — `build.zig.zon:2:13: error: expected enum literal` — so the
+// generated SDK will not build at all on a newer toolchain. The consumer CI
+// job pins 0.13.0 to match (create-sdkgen
+// project/standard/.github/workflows/ci.yml). Moving to a newer zig means
+// changing BOTH: `.name = .${name}` plus a `.fingerprint` here, and the CI
+// pin there.
+const Package = cmp(async function Package(props: any) {
+  const ctx$ = props.ctx$
+  const model: Model = ctx$.model
+
+  const name = zigModuleName(model)
+
+  File({ name: 'build.zig.zon' }, () => {
+    Content(`.{
+    .name = "${name}",
+    .version = "0.0.1",
+    .dependencies = .{},
+    .paths = .{
+        "src",
+        "test",
+        "build.zig",
+        "build.zig.zon",
+    },
+}
+`)
+  })
+})
+
+
+export {
+  Package
+}

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

@@ -0,0 +1,188 @@
+
+import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { zigVarName } from './utility_zig'
+
+
+// Canonical type sentinel -> a zig type name for the field/param tables.
+// (The shared canonToType helper has no zig column, so map locally.) Every
+// value is dynamically a `Value`, so the type column is documentary.
+function zigType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return '[]const u8'
+  if ('INTEGER' === k) return 'i64'
+  if ('NUMBER' === k) return 'f64'
+  if ('BOOLEAN' === k) return 'bool'
+  if ('ARRAY' === k) return 'Value (array)'
+  if ('OBJECT' === k) return 'Value (object)'
+  return 'Value'
+}
+
+
+// A type-correct zig expression constructing a voxgig struct Value.
+function zigLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
+  if ('BOOLEAN' === k) return 'h.vbool(true)'
+  if ('ARRAY' === k) return 'h.olist()'
+  if ('OBJECT' === k) return 'h.omap()'
+  return `h.vstr("${placeholder}")`
+}
+
+
+// Operation method descriptions (language-agnostic wording, zig signatures).
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(reqmatch, ctrl)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(reqmatch, ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(reqdata, ctrl)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(reqdata, ctrl)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(reqmatch, ctrl)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    const idF = entityIdField(entity)
+    const eVar = zigVarName(entity.name)
+    const method = zigVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`const ${eVar} = client.${method}(h.vnull());\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+Each operation returns an \`OpResult\` — \`switch\` on it: \`.ok => |data|\`
+carries the result \`Value\`, \`.err => |e|\` carries the branded error.
+
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${zigType(field.type)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `h.jo(&.{${loadItems.map((it: any) =>
+          `.{ "${it.name}", ${zigLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)} }`).join(', ')}})`
+        : 'h.vnull()'
+      Content(`#### Example: Load
+
+\`\`\`zig
+switch (client.${method}(h.vnull()).load(${loadArg}, h.vnull())) {
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .err => |e| std.debug.print("load failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`zig
+switch (client.${method}(h.vnull()).list(h.vnull(), h.vnull())) {
+    .ok => |${eVar}s| std.debug.print("{s}\\n", .{h.stringify(${eVar}s)}),
+    .err => |e| std.debug.print("list failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`zig
+switch (client.${method}(h.vnull()).create(h.jo(&.{
+`)
+      createItems.map((it: any) => {
+        Content(`    .{ "${it.name}", ${zigLit(it.type, 'example_' + it.name)} }, // ${zigType(it.type)}
+`)
+      })
+      Content(`}), h.vnull())) {
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}),
+    .err => |e| std.debug.print("create failed: {s}\\n", .{e.msg}),
+}
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

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

@@ -0,0 +1,58 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+// Validates the documented README/REFERENCE quick-start examples for the Zig
+// SDK.
+//
+// DESIGN NOTE vs the go/rust gates (ReadmeExamplesTest_go.ts /
+// ReadmeExamplesTest_rust.ts): the go version shells out to `go build`/`go run`
+// to compile and run every fenced block; the rust version reads the doc files
+// and checks that each block is structurally well-formed. Zig's test harness
+// uses an EXPLICIT test-file list in build.zig (no auto-discovery of test/*.zig
+// and no per-block temp compilation), and the doc files are not on the package
+// path at test time — so neither a filesystem scan nor a per-snippet compile can
+// be authored safely without a build to validate against.
+//
+// Instead this gate emits a real, always-compiling zig `test` block INTO the
+// shared generated_test.zig (the only generated test file build.zig picks up).
+// It exercises the exact top-level entry points the docs advertise — the
+// test-mode constructor and the `direct()` escape hatch — so the documented
+// quick-start surface is guaranteed to exist and run. Upgrading it to a true
+// per-block compile gate is left as a follow-up.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+
+  Content(`
+// Documented quick-start surface (README.md / REFERENCE.md). Exercises the
+// test-mode constructor and the direct() escape hatch exactly as documented.
+test "readme_quickstart_surface" {
+    // \`sdk.test_sdk(...)\` — the documented mock constructor.
+    const client = sdk.test_sdk(vnull(), vnull());
+    try std.testing.expect(std.mem.eql(u8, client.mode, "test"));
+
+    // \`client.direct(...)\` — the documented escape hatch. It always returns a
+    // result map carrying an \`ok\` flag (never an error union).
+    const result = client.direct(h.jo(&.{
+        .{ "path", h.vstr("/api/resource/{id}") },
+        .{ "method", h.vstr("GET") },
+        .{ "params", h.jo(&.{.{ "id", h.vstr("example") }}) },
+    }));
+    try std.testing.expect(result == .object);
+    try std.testing.expect(h.get_bool(result, "ok") != null);
+
+    // \`client.prepare(...)\` — build a request without sending it.
+    const fetchdef = client.prepare(h.jo(&.{
+        .{ "path", h.vstr("/api/resource/{id}") },
+        .{ "method", h.vstr("GET") },
+        .{ "params", h.jo(&.{.{ "id", h.vstr("example") }}) },
+    })) catch h.vnull();
+    _ = fetchdef;
+}
+`)
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -0,0 +1,45 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as \`Value\`
+
+The Zig SDK uses a single dynamic \`Value\` type throughout rather than a
+typed struct per entity. \`Value\` is the vendored voxgig struct port's
+\`JsonValue\` (a JSON-shaped tagged union: \`.string\`, \`.integer\`,
+\`.float\`, \`.bool\`, \`.array\`, \`.object\`, \`.null\`). This mirrors the
+dynamic nature of the API and keeps the SDK flexible — no code generation is
+needed when the API schema changes.
+
+Build request maps with the \`h.jo\` / \`h.ja\` helpers and read fields back
+with \`h.getp\` (or the typed \`h.get_str\` / \`h.get_bool\` / \`h.to_int\`
+accessors); use \`h.to_map\` to safely coerce a value to a map.
+
+### Module structure
+
+\`\`\`
+${target.name}/
+├── root.zig                     -- Module root (re-exports the public surface)
+├── build.zig                    -- Build + test wiring
+├── core/                        -- Pipeline types, config, client (sdk.zig)
+├── entity/                      -- Per-entity clients (one file each)
+├── feature/                     -- Built-in features (base, test, log)
+├── utility/                     -- Utilities + the vendored voxgig struct port
+└── test/                        -- Test suites
+\`\`\`
+
+The public API is re-exported from \`root.zig\`, so \`@import("sdk")\` reaches
+the SDK client, \`Value\`, and the \`h\` (helpers) namespace directly. Import
+entity or utility modules only when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,143 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { zigVarName } from './utility_zig'
+
+
+// A type-correct zig expression constructing a voxgig struct Value.
+function zigLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'h.vnum(1)'
+  if ('BOOLEAN' === k) return 'h.vbool(true)'
+  if ('ARRAY' === k) return 'h.olist()'
+  if ('OBJECT' === k) return 'h.omap()'
+  return 'h.vstr("example")'
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Pick an entity with a real op (prefer a read op). primaryOp is null only
+  // when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  const eVar = exampleEntity ? zigVarName(exampleEntity.name) : 'entity'
+  const method = exampleEntity ? zigVarName(exampleEntity.name) : 'entity'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = 'h.vnull()'
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `h.jo(&.{.{ "${idF}", h.vstr("test01") }})` : 'h.vnull()'
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => it.name !== idF && it.name !== 'id')
+    const required = items.filter((it: any) => !it.optional)
+    const chosen = required.length ? required : items.slice(0, 3)
+    testArg = 0 < chosen.length
+      ? `h.jo(&.{${chosen.map((it: any) => `.{ "${it.name}", ${zigLit(it.type)} }`).join(', ')}})`
+      : 'h.omap()'
+  }
+
+  // The op-driven test-mode line. A direct()-only SDK shows a direct() call.
+  const testModeExample = primaryOp
+    ? `// Entity ops return an OpResult — .ok carries the record, .err the error.
+switch (client.${method}(h.vnull()).${primaryOp}(${testArg}, h.vnull())) {
+    .ok => |${eVar}| std.debug.print("{s}\\n", .{h.stringify(${eVar})}), // the mock record
+    .err => |e| std.debug.print("${primaryOp} failed: {s}\\n", .{e.msg}),
+}`
+    : `const result = client.direct(h.jo(&.{
+    .{ "path", h.vstr("/api/resource") },
+    .{ "method", h.vstr("GET") },
+}));
+std.debug.print("{s}\\n", .{h.stringify(result)});`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`zig
+const result = client.direct(h.jo(&.{
+    .{ "path", h.vstr("/api/resource/{id}") },
+    .{ "method", h.vstr("GET") },
+    .{ "params", h.jo(&.{.{ "id", h.vstr("example") }}) },
+}));
+
+if (h.get_bool(result, "ok") orelse false) {
+    std.debug.print("{d}\\n", .{h.to_int(h.getp(result, "status"))}); // 200
+    std.debug.print("{s}\\n", .{h.stringify(h.getp(result, "data"))}); // response body
+} else {
+    // A non-2xx response carries status + data (the error body); a
+    // transport-level failure carries err instead. Only one is present.
+    std.debug.print("{s}\\n", .{h.get_str(result, "err") orelse ""});
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`zig
+// prepare() returns the fetch definition (an error union — use \`catch\`/\`try\`).
+const fetchdef = client.prepare(h.jo(&.{
+    .{ "path", h.vstr("/api/resource/{id}") },
+    .{ "method", h.vstr("DELETE") },
+    .{ "params", h.jo(&.{.{ "id", h.vstr("example") }}) },
+})) catch unreachable;
+
+std.debug.print("{s}\\n", .{h.get_str(fetchdef, "url") orelse ""});
+std.debug.print("{s}\\n", .{h.get_str(fetchdef, "method") orelse ""});
+std.debug.print("{s}\\n", .{h.stringify(h.getp(fetchdef, "headers"))});
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`zig
+const client = sdk.test_sdk(h.vnull(), h.vnull());
+
+${testModeExample}
+\`\`\`
+
+### Point at a different server
+
+Override the base URL to reach a local or staging server:
+
+\`\`\`zig
+const client = sdk.${model.const.Name}SDK.new(h.jo(&.{
+    .{ "base", h.vstr("http://localhost:8080") },
+}));
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd ${target.name} && zig build test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -0,0 +1,54 @@
+
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+${installCommand(model, target.name)}
+\`\`\`
+
+Or build it from a source checkout:
+
+\`\`\`bash
+cd ${target.name} && zig build
+\`\`\`
+
+`)
+    return
+  }
+
+  // Zig has no central package registry — the release IS the git tag. Depend
+  // on it via the Zig package manager (a git-tagged url in build.zig.zon) or
+  // build from a local source checkout.
+  const { releasesUrl } = repoInfo(model)
+  Content(`Zig has no central package registry, so this package is distributed as a
+git tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})). Add it to
+your \`build.zig.zon\` dependencies, or build from a source checkout:
+
+\`\`\`bash
+cd ${target.name} && zig build
+\`\`\`
+
+To depend on it from another project, add the tagged archive to
+\`build.zig.zon\`:
+
+\`\`\`zig
+.dependencies = .{
+    .sdk = .{
+        .url = "<repo-url>/archive/refs/tags/${target.name}/vX.Y.Z.tar.gz",
+        // .hash = "...", // filled in by \`zig fetch\`
+    },
+},
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

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

@@ -0,0 +1,66 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { zigVarName } from './utility_zig'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client following idiomatic Zig conventions.
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`client.${zigVarName(exampleEntity.name)}(h.vnull())\` — each`
+    : 'each'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, which
+keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}