codegen: add file generator, templates, and CLI entry point (PRINFRA-121)

[somanshreddy]

Description

The output stage of the codegen pipeline. Takes the grouped command specs from the previous PR and writes them as Go source files.

What it produces: For each command group, a .go file with exported command.Spec variables. Plus a registry file that maps group names to their specs.

Example — given this grouper output:

command.Groups{
    "video": []*Spec{{Group: "video", Name: "list", Endpoint: "/v3/videos", Method: "GET"}},
}

The generator writes gen/video.go:

var VideoList = &command.Spec{
    Group:    "video",
    Name:     "list",
    Endpoint: "/v3/videos",
    Method:   "GET",
    ...
}

And gen/registry.go:

var Groups = command.Groups{
    "video": {VideoList, VideoGet, VideoCreate, VideoDelete},
}

How it works:

• Generate() in generate.go iterates groups in sorted order, executes Go text/templates, and writes gofmt'd output
• command.go.tmpl produces one file per group with all specs as exported vars. Variable names are PascalCase from group + command name (e.g., VideoList, WebhookEndpointsCreate)
• registry.go.tmpl produces the Groups map that the runtime builder reads at startup
• Template helpers: strcase.ToCamel for PascalCase, intPtrLiteral for min/max pointers, stringSlice for enum arrays

CLI entry point — go run ./codegen/ -spec <path> -out gen/ -examples codegen/examples.yaml orchestrates the full pipeline: load examples → load spec → group endpoints → validate examples → generate files. Fails if any command is missing examples.

make generate target — make generate SPEC=path/to/external-api.json clears gen/, runs codegen, formats output.

Testing

Tested via golden file tests in the next PR.

Files

• codegen/generate.go — Generate function, template loading, gofmt, template helpers
• codegen/main.go — CLI entry point with -spec, -out, -examples flags
• codegen/templates/command.go.tmpl — per-group command file template
• codegen/templates/registry.go.tmpl — registry map template
• Makefile — added generate target

[somanshreddy]

• codegen: add file generator, templates, and CLI entry point (PRINFRA-121) #14 : 2 dependent PRs (#15 , #16 ) 👈 (View in Graphite)
• codegen: add endpoint grouper with agent-first naming (PRINFRA-121) #13
• codegen: add examples.yaml and simplify ArgSpec (PRINFRA-121) #11 : 1 other dependent PR (#12 )
• client: add multipart form-data support for file uploads (PRINFRA-121) #6 : 1 other dependent PR (#7 )
• cmd: add generic command builder (PRINFRA-121) #10
• client: refactor executor to use Spec + Invocation (PRINFRA-121) #9
• add command.Spec and command.Invocation types (PRINFRA-121) #5
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[linear]

PRINFRA-121 CLI M1: OpenAPI codegen pipeline

Build the code generation pipeline that reads openapi/external-api.json and produces CommandSpec structs.

Scope

• Go program in codegen/ using text/template
• Parse OpenAPI spec, filter to v3 endpoints only
• Generate CommandSpec data structs in gen/ (zero logic)
• overrides.yaml for:
  • Positional arg promotion (prompt, text, file)
  • Command group naming (video-translations → translate, webhooks/endpoints → webhook)
  • Help examples per command
• make generate SPEC=... target
• Nested path collapsing (e.g., /webhooks/endpoints/{id}/rotate-secret → webhook rotate-secret)
• Golden file tests for codegen output stability
• Generate all ~30 commands, wire into Cobra at startup

Mapping Rules

• OpenAPI tag → command group
• POST → create, GET (list) → list, GET (by id) → get, DELETE → delete, PATCH → update
• Path params → positional args, query params → flags, body fields → flags
• overrides.yaml exceptions for positional promotion and group naming

Acceptance Criteria

• make generate produces compilable CommandSpec files for all v3 endpoints
• Adding a new endpoint to spec + re-running codegen produces new command
• Generated help text includes descriptions and examples
• Golden file tests pass
• Override validation: make generate fails if overrides reference non-existent endpoints

[somanshreddy]

Merge activity

• Apr 1, 7:16 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 1, 7:20 PM UTC: Graphite rebased this pull request as part of a merge.
• Apr 1, 7:22 PM UTC: @somanshreddy merged this pull request with Graphite.