[grubmeshi]

🤖 Written by AI agent

Draft for a first look. It is a prototype of a generator that writes the client's Go types and a thin typed client from meshStack's OpenAPI spec.

Why

The client's DTOs are written by hand today. meshStack now derives its OpenAPI spec from its controllers (meshcloud-internal: meshfed-release#11378), so the spec states every field, its type, whether it is required and in which direction. The generator turns that into Go, so the client follows the API without hand-written copies.

What it does

• client/openapi/generator is a library. A repository calls it from its own small main.go with a Go config, which selects operations by kind, action and version and can map a schema to its own Go type (for example types.SecretOrAny). The CLI's config is in client/internal/generate, run by go generate.
• One package per kind and version, named after the kind: client/meshworkspace/v2 is package meshworkspace, with Request, Response and a Client. Types that several packages use go to client/meshobject.
• Client has one method per action. List returns iter.Seq2[T, error], and pages.ReadAll collects it.
• A path parameter is named after the key it takes: Get(ctx, uuid uuid.UUID), Get(ctx, name string), with the key's description in the doc comment. A composite key such as {metadata.ownedByWorkspace}.{metadata.name} becomes one parameter per field (workspace, project string), and the client joins them, so a caller passes fields it already has and never builds the identifier format itself.
• A package of a deprecated API version, and its types and methods, carry a Deprecated: paragraph from the spec's lifecycle data, as does a deprecated operation or schema. staticcheck reports each use.
• The generated clients call the public client/meshapi (Api, Call, Path, HttpClient), so other repositories can generate their own packages; Config.Runtime names another runtime, and client.Client.HttpClient is what their NewClient takes. client/internal keeps the flat client's helpers.
• HAL entity models become the plain type with a Links field, with Href and Expand. Page wrappers are read by the generic pager.
• Required fields are values. Every other field is a pointer with omitzero, so a request can send false where the server default is true. Slices and maps are never pointers.
• Enums are typed string constants with an enum.Of registry. A discriminated oneOf becomes the discriminator field plus one pointer per variant.

This PR generates meshworkspace/v2, meshbuildingblock/v2 and meshbuildingblockrun/v1, and the workspace, building block and run commands use them. The old flat client types stay, because the Terraform provider imports them.

How to look at it

• The generated files: client/*/v*/generated.go and client/meshobject/generated.go.
• The golden test of the generator: client/openapi/generator/testdata.
• The generator downloads the dev spec by default. The dev site serves the derived spec only after meshfed-release#11378 is deployed, so these files come from that PR's spec: go run ./internal/generate -spec <file> in client/.

Open

• No tfsdk tags yet; the Terraform provider still uses the flat types.

🤖 Generated with Claude Code

[meshcloud-gh-actions]

Coverage of the acceptance run against the meshStack backend, on a4ad326e2d388eb5612173d799769e3300cccf00.

Scope	Coverage
Unit tests	78.0%
Acceptance tests	46.8%
Combined	79.5%

Uncovered functions

client/api_key.go:55: meshApiKeyClient.Create 0.0%
client/api_key.go:59: meshApiKeyClient.Read 0.0%
client/api_key.go:63: meshApiKeyClient.Update 0.0%
client/api_key.go:71: meshApiKeyClient.Delete 0.0%
client/api_key_permissions.go:20: ApiKeyPermissions.AllCodes 0.0%
client/api_key_permissions.go:33: ApiKeyPermissions.WorkspaceCodes 0.0%
client/api_key_permissions.go:295: AllApiKeyPermissions 0.0%
client/api_key_permissions.go:299: WorkspacePermissionCodes 0.0%
client/building_block_definition.go:71: MeshBuildingBlockDefinitionApprovalPolicies.NothingRequiresApproval 0.0%
client/building_block_definition.go:82: DisabledSchedule 0.0%
client/building_block_definition.go:89: MeshBuildingBlockDefinitionSchedule.IsDisabled 0.0%
client/building_block_definition.go:93: MeshBuildingBlockDefinitionSpec.HasNeutralPolicies 0.0%
client/building_block_definition.go:97: MeshBuildingBlockDefinitionSpec.WithNeutralPolicies 0.0%
client/building_block_definition.go:166: meshBuildingBlockDefinitionClient.List 0.0%
client/building_block_definition.go:173: meshBuildingBlockDefinitionClient.Read 0.0%
client/building_block_definition.go:177: meshBuildingBlockDefinitionClient.Create 0.0%
client/building_block_definition.go:181: meshBuildingBlockDefinitionClient.Update 0.0%
client/building_block_definition.go:185: meshBuildingBlockDefinitionClient.Delete 0.0%
client/building_block_definition_version.go:100: MeshBuildingBlockType.TagInputTargets 0.0%
client/building_block_definition_version.go:245: meshBuildingBlockDefinitionVersionClient.Create 0.0%
client/building_block_definition_version.go:254: meshBuildingBlockDefinitionVersionClient.Update 0.0%
client/building_block_definition_version_implementation.go:80: MeshBuildingBlockDefinitionImplementation.InferType 0.0%
client/building_block_definition_version_implementation.go:94: MeshBuildingBlockDefinitionImplementation.MarshalJSON 0.0%
client/building_block_definition_version_implementation.go:107: *MeshBuildingBlockDefinitionImplementation.UnmarshalJSON 0.0%
client/building_block_run.go:76: meshBuildingBlockRunClient.GetLogs 0.0%
... and 151 more

covdata func names a method without its receiver, so an entry can belong to an implementation nothing selects rather than to a function the tests never reached. Open the file and line before reading one as a coverage gap.

[sonarqubecloud]

Quality Gate passed

Issues
13 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.0% Duplication on New Code

See analysis details on SonarQube Cloud