Generated, not take-it-or-leave-it

The fork you are trying to avoid#

Every team that adopts a generator asks the same question first: what happens on the day the output is not quite right?

With most tools the answer is a fork. You eject, you patch the generated code by hand, and regeneration stops being safe. From then on every spec change is a manual merge, which is the exact maintenance tax the generator was supposed to remove.

Voxgig's answer is structural. Three things drive generation, and all three land in your repo when you scaffold a project. The model holds the type-safe description of your API and every decision your project makes about itself, from package names to active features, and regeneration re-reads it every time. Templates are the literal source copied into every SDK. Components are the generators that write the API-shaped parts. Your files, under your license. Customizing them is how the tool is meant to be held.

The rule underneath: regeneration must always be safe. Anything you own is declared in the model or added through an extension point, so running generate twice, or upgrading sdkgen, can never silently destroy your work. A verifier, voxgig-sdkgen doctor, enforces the rule in CI.

The model#

The model is where your project describes itself: one set of declarations that every target and every feature reads.

It is written in aontu, a JSON-based specification language designed for building ontologies like this one. The syntax is JSON with the ceremony removed, easy to edit by hand, and files unify: every declaration, wherever it sits, merges into one consistent model, and a contradiction is an error rather than a silent override. Your API's entities and operations land in the model from your OpenAPI spec. Your decisions go in project.aon, a file the toolchain creates once and never overwrites.

# .sdk/model/project.aon, from the demo repo
main: kit: repo: path: 'voxgig-sdk/voxgig-elementdemo-sdk'
main: kit: target: ts: publish: version: '0.1.0'
main: kit: test: live: strict: true

Package names, release versions, module paths, which features are active, which entities generate: all declarations here, all re-read on every generate. This is the first lever to pull, because nothing declared in the model can be lost to a regeneration or an upgrade.

Components#

Components are the generators: TypeScript classes in .sdk/src/cmp/ that write the API-shaped parts of each SDK.

The line between the two layers is one question. Same for every API? Template. Depends on your API? Component. Entity classes, test suites and READMEs all depend on your entities, so a component writes each of them by walking the model.

Add a component of your own, a changelog writer, a docs page per entity, a manifest for your internal registry, and it runs on every generation beside the stock ones. doctor reports it as additive and a resync leaves it alone, because additions are the supported path. Fork a stock component instead and it is reported as forked, because the next resync would revert it: the same durability rule as templates, enforced by the same tool.

Targets#

A target is an output product: a complete artifact generated from the model, the way the TypeScript SDK, the CLI or the MCP server are.

The generator keeps no list of allowed targets. It walks the target index in the model, and every entry gets the same treatment, so a target you add behaves exactly like one we ship: target add installs it, generate emits it, doctor watches it.

Adding one takes three ingredients. A model file declares the facts every stage needs: the file extension, the comment syntax, the module name. A template tree carries the source that is the same for every API. Components write the API-shaped parts, typically the package skeleton, one file per entity, and the test suite. Generation phases can be switched per target, which is how the demo's Bash target keeps its README as a plain template instead of a composed one:

# ext/.sdk/model/target/bash.aon (demo repo, trimmed)
main: kit: target: bash: {
  title: 'Bash'
  ext: sh
  comment: line: "#"
  phase: {
    readme:     { active: false }
    agentguide: { active: false }
  }
}

The worked example: a periodic table, in five languages and Bash#

Claims about extensibility are cheap. So we built the demo and published the repo: voxgig-elementdemo-sdk.

It is an SDK for a periodic-table API, elements, isotopes, groups and series, generated in TypeScript, Go, Python and Java. Then it customizes everything this page talks about, from inside its own repo, without touching sdkgen:

An entirely custom target: the same model that emits the four SDKs also emits a Bash library, curl for transport and jq for data, with one generated function per entity operation, an offline test mode, and a thin CLI.

$ source bash/elementdemo.sh
$ elementdemo_element_load id=fe | jq -r .name
Iron

$ echo '{"charge":3}' | elementdemo_element_ionize id=fe
{"ok":true,"ion":"Fe3+"}

A custom feature, elementcard, that renders any element-shaped result as an ASCII periodic-table tile. One model file, one implementation per language, hooked into the same pipeline stage in all five:

$ bash/bin/elementdemo element card id=fe
+---------+
|26     Fe|
|  Iron   |
| 55.845  |
+---------+

And the part that proves it: the feature's behaviour is asserted by language-neutral corpus cases in the project's own test data. The exact card string above is checked, byte for byte, by the TypeScript, Go, Python, Java and Bash test suites, from one file of cases.

# .sdk/test/feature/elementcard.aon
{
  name: 'renders an element-shaped result and records it'
  feature: [ { name: 'elementcard', active: true } ]
  res: [ { status: 200, body: {
    id: 'fe', name: 'Iron', symbol: 'Fe', number: 26, mass: 55.845 } } ]
  op: [ { op: '#OP1' } ]
  out: {
    count: 1
    last: "+---------+\n|26     Fe|\n|  Iron   |\n| 55.845  |\n+---------+"
  }
}

Both the target and the feature come from the repo's own sdkgen package, ext/, installed with one command:

cd .sdk
npx voxgig-sdkgen package add ../ext
npm run generate