codegen: add endpoint grouper with agent-first naming (PRINFRA-121)

[somanshreddy]

Description

Takes an OpenAPI spec and produces command.Groups — CLI command definitions grouped by name. This is the core of the codegen pipeline.

Naming algorithm

Derives CLI command names from URL path structure. No hardcoded maps or word classification.

Steps:

1. Group name from tag — lowercase, spaces to hyphens, singularize ("Video Translate" → "video-translate")
2. Parse path segments — drop version prefix + group root, classify the rest: literals → sub-groups, {params} → positional args
3. Append terminal verb from HTTP method (GET→list/get, POST→create, DELETE→delete, PATCH/PUT→update)
4. Exception — endpoints marked x-cli-action: true in the OpenAPI spec skip the terminal verb. This flag is an extension (like x-cli-visible) set by the API team on RPC-style action endpoints where the last path segment is already a verb — without it, POST .../stop would produce stop create. The codegen reads the flag; the spec annotations are tracked in PRINFRA-145.

Common case — standard CRUD:

GET /v3/videos/{video_id}
  tag "Videos" → group "video"
  remaining: [{video_id}]
  {video_id} → positional arg
  last is param → GET → terminal verb "get"
  → heygen video get <video-id>

Edge case — nested action endpoint:

POST /v3/video-agents/sessions/{session_id}/stop   [x-cli-action: true]
  tag "Video Agent" → group "video-agent"
  remaining: [sessions, {session_id}, stop]
  sessions → sub-group, {session_id} → arg, stop → sub-group
  x-cli-action → no terminal verb (without it, this would be "sessions stop create")
  → heygen video-agent sessions stop <session-id>

Automation

Of every generated command, the following is fully automatic from the spec:

• Group name, command name, sub-group hierarchy, flags, args, pagination, multipart, body encoding

The only manual inputs are:

• x-cli-visible in the spec — 15 v1/v2 endpoints excluded (set by API team)
• x-cli-action in the spec — 3 action endpoints where the path segment is the verb (set by API team)
• examples.yaml in the CLI repo — curated usage examples for every command

Other responsibilities

• Filters endpoints by x-cli-visible
• Detects pagination from response schema (has_more + token field)
• Detects multipart from content type; emits Source: "file" flags that route to inv.FilePath
• Classifies body fields as simple (→ flag) or complex (→ skipped, covered by -d/--data)
• Validates no generated flag name collides with reserved names (-d, --help, --version)

Design decisions

• Agent-first grammar — every command ends with a verb for predictable structure
• PUT → update (not upload) — correct REST semantics; PUT is idempotent update
• Plural sub-groups — mirror the URL path (sessions, endpoints, proofreads)
• Safe path decomposition — bounds-checked segment indexing, handles short paths gracefully

Testing

11 tests covering: hidden endpoint filtering, group name singularization, terminal verbs, query flags, complex field skipping, path args, pagination, multipart with Source:"file", examples, x-cli-action, sub-group naming.

Files

• codegen/grouper.go — GroupEndpoints, buildSpec, deriveCommandName, schema/pagination/multipart helpers
• codegen/grouper_test.go — 11 tests
• codegen/testdata/test_spec.yaml — test OpenAPI spec (videos, avatars, assets, action and hidden endpoints)

[somanshreddy]

• codegen: add file generator, templates, and CLI entry point (PRINFRA-121) #14 : 2 dependent PRs (#15 , #16 )
• codegen: add endpoint grouper with agent-first naming (PRINFRA-121) #13 👈 (View in Graphite)
• 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:18 PM UTC: Graphite rebased this pull request as part of a merge.
• Apr 1, 7:19 PM UTC: @somanshreddy merged this pull request with Graphite.