Library API

Generate a moonkoog agent scaffold from spec. Every route becomes a Tool whose descriptor advertises the operation (a single string input parameter to fill out) and whose execute_raw is a stub, and build_agent assembles them into an AIAgent with the service's name in its system prompt. The output compiles against moonbitstack/moonkoog; fill in each execute_raw to make it run.

The files source imports, each resolved against from — the path source itself was read from. A caller that can read files walks a multi-file spec with this: read a file, follow its deps, and hand everything it collected to parse_all.

The TypeDef named name, or None when the spec declared no such block.

Every field a type block carries with its inline embeds folded in first, which is both the shape an embedded Go struct serialises to and the only one MoonBit can spell — a MoonBit struct has no embedding. An embed naming a block that is not in types, and one that leads back to a block already folded in, contribute nothing.

Format an .api source. Nesting is read off braces and off the two blocks that open with a parenthesis — a multi-line @server ( and a type ( group; blank lines collapse to one; the result ends in exactly one newline. Comments and struct tags survive verbatim, and the function is idempotent: formatting an already formatted spec returns it unchanged.

Whether any finding is an Error — what makes mctl api validate exit non-zero.

Index of the first ch in s at or after from, or -1 if absent.

Read a goctl-style .api description into a Spec. Grammar (one statement per line):

syntax = "v1"

info (
  title:   "greet"
  version: "v2"
)

type LoginReq {
  name: string
}

@server (
  group:      user
  prefix:     /api/v1
  middleware: Log
)
service greet {
  @doc "health check"
  @handler ping
  get /ping

  @handler login
  post /login (LoginReq) returns (LoginResp)

  get /legacy legacy_handler "the inline form"
}

A type block declares a message schema (its fields become a MoonBit struct); field types use goctl's Go spellings (string, int64, []T, map[K]V, …). An @server( … ) block annotates every route of the service block that follows it: the routes carry its prefix in their paths and its Group on their group. Verbs are lower-cased, blank lines and // comments are dropped.

Any other line raises a Refused naming it — a misspelt verb or a missing brace would otherwise generate a quietly truncated program. Use parse_lenient for a best-effort read of a spec that is still being written.

Parse source — the spec at from — together with everything it imports, taken from files (a map from resolved path to source, the shape deps resolves to). What the imports describe is merged in first, in the order they were declared, then the importing file's own: types, routes and @server groups all end up in one Spec. A file is scanned once however many times it is imported, so a cycle terminates.

The service name is the one the importing file declares, or else the last one its imports declared, so a spec that does nothing but import still takes the name from what it imported.

An import naming a file that is not in files raises Missing; a file that does not parse raises its first complaint the way parse does, with the file it came from named alongside the line.

parse without the diagnostics: a line the parser cannot read is skipped and whatever the spec does describe is returned. For a caller that generates from a half-written spec on every keystroke; anything that reports to a user should call parse.

An import path resolved against the file that declared it: taken relative to that file's directory, with ./.. folded away. An already-absolute path is left where it points.

s read as a non-negative decimal, or None when it is not one.

Whitespace-split a line into tokens, keeping a "quoted string" as one token (with the quotes stripped).

Check a parsed spec: the routes, the types and the places one names the other. Findings come in spec order — routes first, then types — so a report reads the way the file does.

Validate one file of a spec together with everything it imports, files being every source the walk has read keyed by the path it was read from. Without this a spec that embeds a type from another file is told that the type does not exist — true of the file on its own, false of the spec it belongs to.

Validate a spec given as source. A spec the parser cannot read is reported as the one finding it is — syntax, naming the line — rather than raising, so a caller checks a file the same way whether it is broken or merely wrong.

mctl bug: a report with the environment filled in and the questions a maintainer would otherwise have to ask. title may be empty, in which case the report asks for one.

The executable a moon run --build-only built, from what it prints.

The words a shell should complete at the first position.

Every command mctl accepts, in the order help prints them: the generators, the scaffolds, the spec tools, then the housekeeping.

A shell completion script for shell, or "" for a shell mctl has none for. Completion is generated from commands and subcommands, so a new command is completable the moment it is in the table.

The value of one key, or None when mctl has no such key.

The keys config get and config set accept.

c with one key set. template appends — a config may name several — while a scalar key replaces what was there. An unknown key is returned unchanged, so a caller checks the key against config_keys first.

The configuration as the file it is stored in, with a comment saying what the file is for and where the keys come from.

The branch --remote reads when --branch names none.

The file mctl writes when there is none yet: the bundled library, the default branch, the gozero spelling.

mctl env: one line per setting, then a hint at what to change. rows pairs a setting with its value and, in parentheses, where it came from.

The template called name, or None.

Whether this is the bundled library, which is code rather than files.

Whether a directory is left out of the walk: what the build itself writes, and anything hidden.

Whether a save to this file calls for a rebuild: MoonBit source, or the manifests that say how it is built.

The library the three flags describe. --home wins over --remote when both are given: a local directory is already checked out.

A v1 configuration — the uppercase, environment-style keys mctl read before it had a file — rewritten as the current shape. Returns the new text and one line per key that changed, so mctl config migrate can say what it did.

The version strings of mod, as (name, version) pairs: every pin the file carries, in order.

Read a configuration. A key mctl does not know is kept out of the result rather than refused, so a file written by a newer mctl still loads. An empty or unreadable-text file is the default configuration.

Read mctl serve [package] [--reload] [--reload-dir dir]... [--reload-delay seconds] [-- args]. Everything after -- is the server's own.

mod with name pinned at version, or mod unchanged when it does not pin that name. Returns the new text and the change it made, if any.

The version name is pinned at in mod, or None when the file does not pin it.

How long to wait between looks at the sources, in milliseconds (← uvicorn's --reload-delay, 0.25 seconds).

Which directories are watched when none are named (← uvicorn's --reload-dir, the current directory).

The second word of a command that takes a sub-command, for a completion script that completes two levels deep.

mctl template show <name>: one entry, and where it sits in the library.

The directory t is read from, given the root the library resolves to. The root is the --home directory, or where --remote was checked out.

The files mctl template init writes: one entry under api/service, small enough to read in a minute and complete enough to serve the spec it is given. Both the file names and the text are templates, so a library is edited as templates and read back the same way.

mctl template list: a table a reader scans rather than a paragraph they read.

The bundled library, in the order it is listed.

The templates of one kind — the ones a gen of that kind may pick.

mctl upgrade <version>: every name in modules moved to version, plus one line per name that changed. A name the file does not pin is left alone and reported as skipped — pinning it would be a change the user did not ask for.

The mctl help page: what mctl is, then one line per command, then the flags every generator shares.

The file name and the source of the client lang for spec, which is what mctl api ts <file.api> writes.

The file a client for service lands in: greet_client.ts and friends, named after the service so two specs generated into one directory do not collide.

Generate the client of lang for spec. The result is one file: the models the spec declares, then the client class, in that order, so a reader meets the data before the calls that carry it.

Generate an OpenAPI / Swagger document from spec, stringified with two-space indentation. version picks the dialect (Swagger 2.0 / OpenAPI 3.0 / 3.1).

The whole reference: the service, a route table, then a table per type. title replaces the service name in the heading for a reader who wants the document to say what the service is for.

The file name a Markdown reference lands in: greet → greet_api.md.

Build the OpenAPI / Swagger document for spec as a Json value. Routes fold into paths → HTTP method → operation (with operationId, any :name path parameters, and a 200 response); every type block becomes a component schema (definitions in 2.0, components/schemas in 3.x). version selects the document dialect; title/api_version fill the info block.

A self-contained Swagger UI page for the document served at spec_url. The same stub moonapi ships, so a generated service and a live app render alike.

Whether any binder reads a value out of text, which is what moonbitlang/core/string is imported for. A spec whose request fields are all text or all in the body needs none of it, and an unused import fails moon check in a generated project.

The request types spec's routes declare, in the order they first appear, each with its fields — the types a binder is written for. A route naming a type the spec never declares is left out: there is nothing to build.

Generate compilable moonapi scaffolding from a spec: a MoonBit struct for every type block, a build_app that wires every route to its handler, plus a stub for each handler. The routing part depends only on moonbitstack/moonapi and moonbitstack/moonasgi; the emitted schemas are dependency-free.

Pass template to render the spec through the runtime template engine (see generate_with) instead of the built-in generator; omit it for the default scaffold.

Generate code from a Spec with a caller-supplied template instead of the built-in generator — the runtime-template path goctl exposes for custom scaffolds. Equivalent to render(template_source, spec_to_value(spec)).

A group's annotations spelled the way the spec wrote them, e.g. group: user, prefix: /api/v1, middleware: Log. Empty for a group that carries nothing.

raw as a JSON number, or as a string when it does not read as one — a tag option is text until something asks it to be a number.

bind_<type> for one request type: read every field from the place its tag names, then build the struct. A field bound from the body and one bound from the path are read the same way the request puts them there, so a request whose body and path disagree takes each value from where its tag says.

Every binder spec needs, with the helpers they read through, as the internal/types package's generated source tail. Empty when no route declares a request type.

A MoonBit struct for every type block, in the order the spec declared them, each followed by whatever its tags asked to be checked (see render_checks).

Render every file of a template directory. The result is in the order the caller listed them, so a file that has to exist first (a moon.mod) can be put first.

Render t's path and text over spec, returning the file to write. A path is rendered like any other template, so {{.service}}/moon.mod becomes greet/moon.mod.

A spec path as the route template moonapi reads: each :name segment of the spec becomes {name}.

Expose a parsed .api Spec as template Value data: a Dict with service (string), services (list of {name, routes}), routes (list of {verb, path, route, handler, summary, hasSummary, group, hasGroup, req, resp, hasReq, hasResp}, where route is path as the framework spells it), types (list of {name, fields:[{name, type}]}), groups (list of the @server blocks) and hasTypes (bool). This is what the template-driven generator ranges over.

Generate a moongql code-first schema from spec's type blocks. Each type becomes an object type with its fields mapped to GraphQL types, and the Query root has ping: String! plus a <type>(id: ID!): <Type> lookup per type.

Only the schema is generated: the resolvers are the author's code. A root field needs one; an object field without one reads its parent's member of that name.

The file a cached layer lands in: greet → greet_cache.mbt, beside the <service>_model.mbt whose records it caches.

The typed CRUD helpers for one table, against the model model_expr names. nullable_aware binds an optional field of a nullable column as SQL NULL, which is what the annotated form's optional types need.

Generate the cached CRUD layer for every table of spec: for a type block with a field to look records up by, the key function plus read-through find, invalidating write, and evict. A block with no single-valued field has no key to cache under, so it gets no layer and the file says why.

The output needs no import and no driver: the record types it names are the ones mctl model generates for the same spec.

Generate a moonorm data-access layer from parsed DDL: for every table, the record struct, its @moonorm.Model (columns + from_row + to_columns), a @moonorm.Table descriptor, an up/down migration pair, and typed CRUD (insert/all, plus find_by_id/update/delete_by_id when the table has a single-column primary key). The output compiles against moonbitstack/moonorm + moonbitstack/moondb; a consuming package imports both. This is the .sql-schema counterpart of goctl's model mysql ddl.

Parse a SQL DDL script and generate its moonorm data-access layer in one step.

Generate a moonorm data-access layer (models + typed CRUD) straight from a live schema's reflected columns — the in-memory counterpart of generate_crud_from_ddl. The reflect sub-package produces the ReflectedColumns from a real connection.

The migration file for a spec: one CREATE TABLE per type. service names the file and the header, so two specs migrated into one directory do not look alike.

Generate a moonorm data layer for every type block in spec. A block whose fields are all storable yields: the model struct; a <table>_model : @moonorm.Model[T] built with @moonorm.Model::new — declared columns (an id column is the primary key), a from_row decoder, and the to_columns projection an INSERT binds; a <table>_table : @moonorm.Table descriptor; and a <table>_up / <table>_down migration pair (create the table idempotently / drop it). This is the explicit MoonBit stand-in for a SQLAlchemy declarative class plus an Alembic revision, which reflection would otherwise synthesise. A block with a non-storable field (a slice, map, or nested message) still gets its struct and a plain @moonorm.Table descriptor.

The output compiles against moonbitstack/moonorm + moonbitstack/moondb; a consuming package imports both.

Generate a Mongo document model for every type block of spec: a Doc struct that is the document as stored, and a Repo over the Collection port with insert, all, and — when the spec has a key field — find, replace and delete.

The output compiles against MoonBit core: Json and ToJson are builtin, and the file imports moonbitlang/core/json as @json for from_json. A driver supplies the port; without one, nothing here needs a database to typecheck.

The name a migration file takes: greet → greet_migrate.sql.

The <table>_up / <table>_down migration pair for one table, against the model model_expr names.

The <table>_up / <table>_down migration pair, against the model model_expr names — user_model for the flat generator, User::model() for an annotated one.

The file a document model lands in: greet → greet_mongo.mbt, named after the service so two specs generated into one directory do not collide.

Parse a SQL DDL script into its CREATE TABLE definitions. Recognises CREATE TABLE [IF NOT EXISTS] name ( … ) (quoted or bare name), skipping any other statement. Column types, primary keys (column- or table-level), NOT NULL and DEFAULT clauses are captured; everything needed to emit a moonorm model.

Parse a datasource DSN into a DataSource. Recognised forms:

• SQLite: sqlite:PATH, sqlite://PATH, sqlite3:PATH, file:PATH, the literal :memory:, or a bare path ending in .db / .sqlite / .sqlite3.
• PostgreSQL: postgres://[user[:password]@]host[:port][/database][?…] (and the postgresql:// spelling). The port defaults to 5432, the user to postgres; the database name is required.

Raises BadDsn on an unrecognised scheme or a PostgreSQL URL missing its host or database.

The ColumnType constructor for a field type, or None when the type has no single-column storage class (Array, Map, a nested type, Float, unsigned ints — none map onto one @moondb.Value). Only a type in this set gets a declared column, a from_row read, and a to_columns bind, so a model is only generated when every field is storable.

Fold reflected columns into DdlTables, grouping by table in first-seen order and mapping each raw SQL type onto its MoonBit scalar (the leading type keyword drives the mapping, so character varying and VARCHAR(255) both land on String). The result feeds generate_crud, so a live schema and a .sql file reach the same model generator.

Serialise a list of generated files into the plugin-reply JSON — the writer a MoonBit plugin uses on its stdout. Emits the {"files": [...]} envelope.

Parse a plugin's stdout into the files to write. Two shapes are accepted: a bare array [{path, content}, …], or an object {"files": [ … ]} (goctl-style envelope). An element missing path or content is skipped. The list preserves the plugin's order.

Split a plugin invocation into the program to run and the arguments to run it with, the way goctl reads its -plugin value: the first whitespace-separated word is the executable, the rest are its argv. A quoted word keeps its spaces.

Read the request a plugin was handed on stdin. Missing members degrade to empty rather than raising, so a hand-written request still parses.

What a plugin run will actually write: the files whose path is safe, and a note per file that was refused or superseded. A later file for a path an earlier one already claimed is refused rather than silently overwriting it — a plugin that emits the same file twice has a bug, and the report should say so rather than leave a coin-flip in the output.

The plugin request as a two-space-indented JSON string, ready to write to the plugin's stdin: goctl's four keys — the spec under Api, plus the file it was read from, the --style template and the output directory, which is everything a plugin needs to decide where its output goes and what to call it.

Whether a path a plugin supplies lands inside the directory mctl writes to. A plugin runs as its own process and its reply is arbitrary text, so the one thing mctl must not do is believe it: ../../.ssh/authorized_keys, /etc/passwd and C:/Windows/system32/… are all accepted by a naive writer, and all three write where a code generator has no business writing. Only a relative path with no .. segment is allowed; a path with one is refused and named in the run's report.

Reconstruct a Spec from the request JSON — the reader a plugin written in MoonBit uses on its stdin. The whole request ({Api, ApiFilePath, Style, Dir}) and a bare spec are both accepted, so a plugin that wants nothing but the routes need not unwrap the envelope. Missing or mistyped members degrade to empty rather than raising, so a partial request still parses.

Serialise a Spec into the plugin request JSON. The shape mirrors the Spec itself — service, routes (verb/path/handler/summary, plus the group the route was declared under), types (name plus fields of name/type) and groups — so a plugin in any language parses it with an ordinary JSON reader. type_ is written as type, the name a caller expects.

Join parts with ", " — the codegen workhorse for column/argument lists.

Every RPC of proto as the default route: POST /<Service>/<Method> — the gRPC path with its package dropped, because a gateway in front of one package does not need the package repeated in the URL. A POST is the method gRPC itself uses, so the mapping is the one that always works.

The file a gateway lands in: the .proto's own name, without its directory and without its extension — proto/greet.proto → greet_gateway.mbt. A .proto may declare several services, so the file name comes from the file rather than from one of them.

Generate the gateway for proto with routes: the route table, the gateway itself, and the two entry points — handle, which takes a JSON body already parsed, and handle_text, which parses the body a request carried.

Status codes are the four an HTTP client cares about: 200 for a reply, 400 for a body that is not JSON, 404 for a path no route answers, and 502 for a call the upstream failed. A gRPC status does not leak through: an HTTP client reads it where it is meaningful — in the reply body.

Generate a moonrpc service stub from a parsed .proto: a MoonBit struct per message, a @moonrpc.Method descriptor per RPC (its gRPC :path is /package.Service/Method), a <Service>Server handler-registration struct (one synchronous-core handler field per RPC, each returning its reply or a gRPC @moonrpc.Status), and a <service>_methods() listing. The output compiles against moonbitstack/moonrpc.

Whether proto declares the gRPC method target (/package.Service/Method), so a hand-written route that names a method the spec does not have is caught here rather than at the first request.

Parse a minimal .proto (proto3). Recognises the package declaration, service blocks with their rpc methods (including stream), message blocks with scalar/repeated/map fields, and top-level enum declarations. syntax, import, and option are skipped.

syntax = "proto3";
package greet;
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply   { string message = 1; }

The routes a mapping file declares, in the order it declares them. A line is VERB /path /package.Service/Method; # starts a comment, and a blank line is skipped. A line naming a method the .proto does not declare, or one that streams, is left out — skipped reports it so the caller can say which.

The names of m's fields (oneof members included) that reuse a reserved field number or name — protobuf forbids reusing either, and this surfaces an accidental reuse. Empty when the message is clean.

The layered GraphQL tree for spec under dir: internal/schema with the annotated types and root fields (seeded once — the resolvers are yours to write), the rule that regenerates the schema from them, internal/config and the entry point serving it on 12000.

Hand the result to tree_plan to keep what the author has filled in.

The MCP server tree for the service spec describes: the same module, packages and build rule as generate_mcp_tree, with the spec's routes as its tools.

The MCP server tree for module module_ under dir: the shared module, configuration and context, internal/tools with the annotated functions, their generated registration and a test, and the build rule that keeps the registration in step with the functions.

The annotated models and migrations for spec: every type block is a table, its id field (when it has one) the primary key, and a field with no single column — a slice, a map, a nested type — is skipped rather than stored.

The annotated models, migrations and CRUD helpers for a SQL schema. The table and column names are the schema's; a nullable column is declared optional, so #orm reads it as one.

The layered gRPC tree goctl writes for a .proto, in MoonBit, under dir: pb/ with the messages, codecs and handler tables (rewritten on every run), internal/logic with one function per RPC and internal/config/internal/svc (seeded once), internal/server wiring the logic into each service, client/ with a typed client per service, and the entry point serving it all on 12000.

Hand the result to tree_plan to keep what the author has filled in.

Generate the layered project tree goctl writes, in MoonBit: the service entry point and its moon.mod, etc/<service>.yaml, internal/config, internal/svc, internal/types, internal/handler (the generated routes plus a stub per handler, under internal/handler/<group>/ for a grouped route), internal/logic, internal/middleware for every middleware an @server block named, and a moon.pkg for each of those packages.

style (default gozero) names the files and the handler, logic and middleware entry points inside them. Names the spec itself chose — the type blocks and their fields — are left as written, since a MoonBit type name has to keep its capital. dir puts the whole tree under a directory.

Each file says whether a regeneration may overwrite it; hand the result to tree_plan to apply that.

The moonx command that runs one of a library's generators, for the rule(...) that wires it into moon.mod.

The fields of a type block that GraphQL has no type for, as <type>.<field> (<type>), for the command to report.

Whether moongql has a GraphQL type for ty. A slice or an optional is that of its element; Bytes and Map have none, and a field of one of those keeps the generated ToGql impl from compiling, so it is dropped from the schema and reported instead.

The seeded schema for spec: one annotated struct per type block, one root field per route.

The test a spec-derived server is seeded with: every offered route registered as a tool, counted through tools/list.

internal/tools/tools.g.mbt: what moonmcp regenerates from those functions, so a fresh project compiles before its first build.

The routes a generated server does not offer, each as <verb> <path>: they declare no request type, so there is nothing for a tool to take.

internal/tools/tools.mbt for spec: one annotated function per offered route.

The version of each library generated code imports.

These are the versions this repository's CI scaffolds a project against and builds, so a generated project is promised to compile with them. A project that wants a later release edits its own moon.mod.

The port a scaffolded service listens on.

12000, the one every server in this family defaults to: HTTP, WebSocket and h2c share it because one listener tells them apart, so a generated manifest and a generated configuration name the same number without anyone saying which they meant.

The rule(...) entry that wires a moonx generator into moon.mod, on one line when it fits in the width moon fmt breaks at and one argument per line when it does not — the two shapes the formatter leaves it in, so a generated moon.mod never changes on the first format.

Scaffold a moonapi service under <name>/: goctl's api new. The layered tree of generate_tree for a sample spec with GET /ping, a test calling it, and an entry point serving it on mooncat.

Scaffold container files for a native mctl-generated service: a Dockerfile (a MoonBit build stage that produces the native binary, then a slim runtime stage that runs it) and a .dockerignore. name is the binary/image name, port the port the service listens on. goctl's goctl docker.

Scaffold a moongql service under <name>/: the annotated tree of generate_gql_tree for a sample spec — the types as #gql.type, the routes as root fields — and a test that asks the schema what it is.

Scaffold a Kubernetes deployment for the service under deploy/: a Deployment (replicas pods of the <name> image, a container port, and a liveness probe on /ping) and a Service exposing it. goctl's goctl kube deploy.

The manifests are built as values and written by moonyaml, not joined out of string fragments. A generator that joins fragments has the indentation in its string literals, where a missed space is invisible, and quotes nothing — so the first service name with a colon in it emits a file Kubernetes reads as something else.

Scaffold an MCP server under <name>/: annotated tools, a resource and a prompt, a test calling the tool, and an entry point serving them over Streamable HTTP or, with --stdio, over stdio.

Scaffold a moonorm data-layer project under <name>/: a moon.mod carrying the orm rule, a sample schema.sql, the tables as #orm annotations under internal/model (through the same generate_orm_tree_from_ddl as gen crud), and a README. goctl's goctl model … new.

Scaffold a moonrpc service under <name>/: goctl's rpc new. The layered tree of generate_rpc_tree for a sample proto with a Ping that answers pong, and a test serving it and calling it through the typed client.

The files of tree a run should actually write, given a way to ask whether a path is already on disk. A file moonctl owns (Always — the routes and the types) is always written; anything else is written only when it is not there yet, so a second run refreshes what follows the spec and leaves every handler and logic body the author has since filled in exactly as it is.

Parse and render source against data in one call, with the default function library.

A pipeline function: it receives the already-evaluated argument list (with the piped-in value, if any, appended last, mirroring Go) and returns a Value.