moonctl

struct Route

One route in a service spec: HTTP verb, path pattern, handler name, and an optional summary. A modern goctl route (verb /path (Req) returns (Resp)) also carries its request/response type names (its @doc fills summary); both are empty for the legacy inline form (verb /path handler "summary").

struct Field

One field of a type block: its name, the (already MoonBit-mapped) type, and the raw back-tick struct tag (json:"…"/path/form/header, empty when absent) that carries the wire name and binding location.

struct TypeDef

A named message schema declared by a type Name { field: Type … } block, generated into a MoonBit struct (goctl's request/response types).

struct Spec

A parsed .api service specification.

fn Field::json_name(self : Field) -> String

The field's serialized name: the json struct-tag name (with any ,optional/,omitempty option stripped) when the tag carries one, else the field's own name.

fn parse(source : String) -> Spec

Read a goctl-style .api description into a Spec: the service name, its routes, the type blocks, and the info block. A line that matches nothing is skipped rather than raising — a spec is written by hand, and half of one should still generate what it does describe.

fn generate(spec : Spec, template? : String) -> String raise TemplateError

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 Lfan-ke/moonapi and Lfan-ke/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.

enum Value

Dynamic template data. .Field lookups resolve against Dict; range iterates List (index/element) or Dict (sorted key/value). This is the explicit stand-in for the arbitrary Go values goctl reflects over.

suberror TemplateError

A template parse or execution failure, carrying a human-readable message.

type FuncFn = (Array[Value]) -> Value raise TemplateError

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.

struct Template

A parsed, reusable template — moonctl's text/template equivalent. Build it with Template::new, register extra functions with func, parse a source with parse, then render it against a Value any number of times. The parsed node tree stays private, captured inside renderer.

fn Template::new() -> Template

A fresh template preloaded with the default function library. Rendering before parse yields the empty string.

fn Template::func(self : Template, name : String, f : FuncFn) -> Template

Register (or override) a pipeline function, returning self for chaining — the analogue of Go's Template.Funcs. Register before parse.

fn Template::parse( self : Template, source : String) -> Template raise TemplateError

Parse source into this template's node tree, returning self for chaining. Raises ParseError on a syntax error (unclosed action, dangling {{end}}, …).

fn Template::render( self : Template, data : Value) -> String raise TemplateError

Render the template against data, producing the output string. Raises ExecError on an execution fault (undefined variable/function, bad range target, …).

fn render(source : String, data : Value) -> String raise TemplateError

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

fn spec_to_value(spec : Spec) -> Value

Expose a parsed .api Spec as template Value data: a Dict with service (string), routes (list of {verb, path, handler, summary, hasSummary}), types (list of {name, fields:[{name, type}]}) and hasTypes (bool). This is what the template-driven generator ranges over.

fn generate_with( spec : Spec, template_source : String) -> String raise TemplateError

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)).

struct ProtoField

One field of a protobuf message: its name, the (already MoonBit-mapped) type, and its wire number (the = N). repeated becomes Array[T] and map<K, V> becomes Map[K, V].

struct ProtoOneof

A protobuf oneof group: its name and the members (exactly one may be set). Generated into a MoonBit enum — the faithful equivalent of the "exactly one" invariant, which flattening to optional fields would lose.

struct ProtoMessage

A protobuf message declaration, generated into a MoonBit struct. oneof groups are lifted out of fields into oneofs; reserved field numbers and names are recorded so a reused one can be caught.

struct ProtoEnumValue

One value of a protobuf enum: its name and its integer number.

struct ProtoEnum

A protobuf enum declaration, generated into a MoonBit enum plus an integer mapping (proto3 enums are int-backed, and the value numbered 0 is the default).

struct Rpc

One rpc method of a service: its name, request and response message names, and whether either side is a stream (client/server/bidi streaming).

struct ProtoService

A protobuf service declaration and its RPC methods.

struct Proto

A parsed .proto file: its package (empty when none) and the services and messages it declares.

fn proto_reserved_conflicts(m : ProtoMessage) -> Array[String]

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.

fn parse_proto(source : String) -> Proto

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; } ``

fn generate_grpc(proto : Proto) -> String

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 Lfan-ke/moonrpc.

fn generate_model(spec : Spec) -> String

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 Lfan-ke/moonorm + Lfan-ke/moondb; a consuming package imports both.

struct DdlColumn

One parsed column of a CREATE TABLE statement: the SQL column name, the MoonBit type_ its SQL type maps to (Int/Int64/String/Double/Bool/ Bytes), whether it is a primary key, whether it accepts NULL, and its literal DEFAULT clause if any (kept as source text — it is emitted into DDL comments, never bound).

struct DdlTable

A parsed CREATE TABLE: the SQL table name and its ordered columns.

fn parse_ddl(source : String) -> Array[DdlTable]

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.

fn generate_crud(tables : Array[DdlTable]) -> String

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 Lfan-ke/moonorm + Lfan-ke/moondb; a consuming package imports both. This is the .sql-schema counterpart of goctl's model mysql ddl.

fn generate_crud_from_ddl(source : String) -> String

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

struct GenFile

One file a plugin asks mctl to write: a destination path (relative to the output directory) and its full content.

fn spec_to_json(spec : Spec) -> Json

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

fn plugin_request(spec : Spec) -> String

The plugin request as a two-space-indented JSON string, ready to write to the plugin's stdin.

fn spec_from_json(j : Json) -> Spec

Reconstruct a Spec from the request JSON — the reader a plugin written in MoonBit uses on its stdin. Missing or mistyped members degrade to empty rather than raising, so a partial request still parses.

fn parse_gen_files(j : Json) -> Array[GenFile]

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.

fn gen_files_to_json(files : Array[GenFile]) -> Json

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

enum DocVersion

Target OpenAPI / Swagger document version. mctl emits every mainstream version from one .api spec — the same shape moonapi's runtime emitter takes, so a generated service and a hand-built moonapi app document the same way.

fn openapi_document( spec : Spec, version? : DocVersion = OpenApi31, title? : String = "", api_version? : String = "0.1.0") -> Json

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.

fn generate_doc( spec : Spec, version? : DocVersion = OpenApi31, title? : String = "", api_version? : String = "0.1.0") -> String

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

fn swagger_ui_stub( spec_url? : String = "/openapi.json", title? : String = "API Docs") -> String

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.

struct PgTarget

A PostgreSQL connection target parsed from a postgres:// DSN.

enum DataSource

A parsed datasource DSN: which backend to read, and how to reach it.

suberror DataSourceError

Raised when a DSN string cannot be parsed into a DataSource.

fn parse_dsn(dsn : String) -> DataSource raise DataSourceError

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.

struct ReflectedColumn

One column of a reflected database schema: the table it belongs to, its name, its raw SQL type text (INTEGER, character varying, VARCHAR(255), …), and whether it is a primary key / accepts NULL. This is the neutral shape a live reader (SQLite PRAGMA table_info, PostgreSQL information_schema.columns) produces and tables_from_reflection folds into DdlTables.

fn tables_from_reflection(cols : Array[ReflectedColumn]) -> Array[DdlTable]

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.

fn generate_crud_from_reflection(cols : Array[ReflectedColumn]) -> String

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.

fn scaffold_api(name : String) -> Array[GenFile]

Scaffold a runnable moonapi service project under <name>/: a moon.mod.json (depending on the published moonapi + moonasgi), a sample <name>.api spec, its generated routes+handlers in src/app.mbt (through the same generate the gen api command uses, so it compiles), and a README. This is goctl's goctl api new.

fn scaffold_rpc(name : String) -> Array[GenFile]

Scaffold a moonrpc service project under <name>/: a moon.mod.json (depending on the published moonrpc), a sample <name>.proto, its generated service stub in src/service.mbt (through the same generate_grpc as gen proto), and a README. goctl's goctl rpc new.

fn scaffold_model(name : String) -> Array[GenFile]

Scaffold a moonorm data-layer project under <name>/: a moon.mod.json (depending on the published moonorm + moondb), a sample schema.sql, its generated models + CRUD in src/model.mbt (through the same generate_crud_from_ddl as gen crud), and a README. goctl's goctl model … new.

fn scaffold_docker(name : String, port? : Int = 8080) -> Array[GenFile]

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.

fn scaffold_kube( name : String, port? : Int = 8080, replicas? : Int = 2) -> Array[GenFile]

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.

fn generate_gql(spec : Spec) -> String

Generate a moongql code-first schema and resolver stubs from spec's type blocks. Each type becomes an object type with its fields mapped to GraphQL types; a Query root gains a <type>(id: ID!): <Type> lookup per type; and every field gets a resolver stub. The output compiles against Lfan-ke/moongql; fill in the stub bodies to make it run.

fn generate_agent(spec : Spec) -> String

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 Lfan-ke/moonkoog; fill in each execute_raw to make it run.

fn reflect_sqlite( db : @sqlite.SqliteDriver) -> Array[@moonctl.ReflectedColumn] raise @moondb.DbError

Read every user table's columns from a live SQLite database and return them as @moonctl.ReflectedColumns, ready for @moonctl.generate_crud_from_reflection. Tables are listed from sqlite_master (skipping SQLite's own sqlite_* tables), and each table's columns come from PRAGMA table_info — its name, declared type, notnull flag, and pk index. This is the SQLite half of goctl's model … datasource. The table name is interpolated into the PRAGMA (which cannot bind parameters); it comes from sqlite_master, i.e. the database's own schema, not from user input.

async fn reflect_postgres( conn : @pg.PgConn) -> Array[@moonctl.ReflectedColumn] raise @moondb.DbError

Read every table in the public schema of a live PostgreSQL database and return its columns as @moonctl.ReflectedColumns. The introspection joins information_schema.columns against the primary-key columns from table_constraints / key_column_usage, ordered by table and column position, so column order and primary keys survive. This is the PostgreSQL half of goctl's model pg datasource; it runs over @pg.PgConn's async wire protocol, so call it inside an event loop.