Defining the Goal
Once it was clear which components we needed to build, the next step was to define the goals in more detail.
Server Stubs
The stubs implement a handler interface that provides a clear separation between generated code and custom
implementation. Payloads and types are readily available, keeping the entire data flow strictly typed. Initializers make
dependencies explicit—the result remains router-agnostic, with examples provided for common routers like chi or
net/http.
Client Library
A comprehensive, type-safe client enables programmatic communication with the server. The library should have no
external runtime dependencies and integrate easily into existing HTTP logic.
Mock Server
The mock provides a testable representation of the API, controllable from the outside for complex scenarios while
remaining fully compliant with the spec.
CLI Client
A lightweight CLI allows for direct interaction—both at the command-line level and through declarative requests similar
to the JetBrains HTTP Client. Ideal for quick development tests or automated checks in CI/CD.
Payload Structs
The foundation consists of generated types, including validators. They ensure the integrity of the spec and support
features like unions, enums, and namespaces (packages).
Intermediate Format
A JSON-based Intermediate Representation (JSON-IR) serves as a bridge: it captures all relevant details—namespaces,
types, validations—resolves dependencies, and remains human-readable.
The generated code should feel handcrafted—clean, idiomatic, and free of unnecessary abstractions or external dependencies. Generation must be fully reproducible, ideally with traceable versioning—for instance, via comment headers containing the spec CLI version and spec hash.
Deliberately excluded from the initial scope: generating code for languages other than Go, no automated complex authentication flows, and no GUI frontend—the focus remains on CLI and pure code.
The goal is to enable productive work directly from a TypeSpec definition: run the Spec CLI and simply add your own handler logic. Without manual adjustments—that would be success.