Skip to content

mikejhill/codapact

unversioned · d246f391a25dMIT

Skills for working with Codapact and the codas it generates.


type: overview status: active authority: informative criticality: low review: status: unreviewed

CodaPact

CodaPact wordmark

Contracts into callable tools. Read an API contract (OpenAPI 3.0/3.1 or GraphQL), generate a typed library, then generate a CLI on top of that library.

contract ──► sources ──► semantic model ──► shaping ──► library surface ──► command model
 (OpenAPI,     (L1)          (L2)            (L3)          (L4)              (L5)
  GraphQL)                                                   │                 │
                                                             ▼                 ▼
                                                   library targets      CLI targets
                                                   (Python, TS, plugin) (Python CLI)

Try it

Prerequisites: Git and uv.

git clone https://github.com/mikejhill/codapact.git
cd codapact
uv sync --locked
uv run codapact generate -c examples/petstore/codapact.yaml
uv run --with . --with ./examples/petstore/generated/python petstore pets list --help

Quick mode, no project file:

uv run codapact generate --source openapi.yaml --target python --target python-cli \
  --package acme --program acme --out out/

Inspect any intermediate layer as JSON:

uv run codapact inspect model   -c examples/library/codapact.yaml
uv run codapact inspect surface -c examples/library/codapact.yaml
uv run codapact inspect commands -c examples/library/codapact.yaml

What you get

OutputContents
pythonInstallable package: TypedDict types, a resource-per-namespace client, paging iterators, py.typed
python-cliargparse CLI calling the Python library: --help with examples, --version, describe (JSON catalog for agents), doctor, shell completion, --dry-run, JSON/JSONL/YAML/table output, JSON errors, documented exit codes; env + XDG settings
typescriptFetch-based client with bundled runtime; strict tsc clean
external pluginAny executable speaking the JSON plugin protocol

Generated code is a thin facade over codapact.runtime: retries, auth, validation, and pagination live in one tested place and improve without regenerating.

Documents

  • Architecture: layers, dependency rules, extension seams, and lessons taken from Smithy, Fern, Kiota, protoc, Stainless, Speakeasy, graphql-codegen, and restish.
  • Configuration: codapact.yaml, shaping transforms, target options, and generated CLI settings.
  • Agent skills: create-coda-skill writes the thin skill that lets an agent use a coda's CLI. The repository is a plugin marketplace for Claude Code, GitHub Copilot, and Codex: <agent> plugin marketplace add mikejhill/codapact.
  • Contributing