@sioma/cli

Deterministic, zero-heuristic OpenAPI extraction from real code — the sioma command for Sioma, which makes any AI cheaper and more reliable by serving it only the context each request needs.

npx @sioma/cli scan .

scan walks your repo's actual routes, TypeScript types, and validators and writes a byte-stable openapi.json. Nothing is guessed: every field is traced through the TypeScript compiler to a declared type, and anything that can't be proven is dropped rather than invented. Scanning the same code twice produces byte-identical output, so a spec diff always means the code changed.

Supported today: Next.js (App + Pages Router), express, fastify, hono. Run it from the app's own directory (with its node_modules installed — types resolve through your real dependency graph, including generated clients like Prisma's).

Commands

sioma scan [dir]      # analyze the repo, write openapi.json
sioma verify [dir]    # build the entity graph from the spec, report problems
sioma publish [dir]   # upload + publish the spec to your Sioma workspace
sioma diff [dir]      # exit 1 if the code changed since the last publish
sioma version

publish needs a publish-scoped key from your workspace, via environment:

export SIOMA_PUBLISH_KEY=...                     # Control room → Keys → scope: publish
export SIOMA_APP_URL=https://app.sioma.ai       # your workspace origin (this is the default)
sioma publish .

The CI loop is two commands — a re-run when nothing changed is a no-op:

sioma diff . || sioma publish .

What leaves your machine

Nothing, except when you run publish — and then exactly one thing: the generated openapi.json. scan, verify, and diff never touch the network. Keys are read from the environment and never written to disk.

License

FSL-1.1-Apache-2.0 — source-available, not open source. Every use is permitted except a Competing Use: shipping a commercial product or service that substitutes for this software or offers substantially similar functionality. Internal use, non-commercial education and research, and professional services you provide to a licensee are all permitted. Each release converts to Apache 2.0 two years after it ships, irrevocably.

The grant covers everything in the published artifact, including the compiled code this package bundles from Sioma's internal libraries.

Versions 0.2.0 and earlier were released under MIT and stay MIT — a licence change binds new releases only.