feat(cli): add catalog command defaults and groups

[TristanSpeakEasy]

Why

Offline enum catalogs currently support only one global default and a flat list. Shared enums cannot describe which options are defaults for different commands or organise values into named sections.

What changed

• Add defaults mappings accepting a command name or an array of command names, with human labels and optional default_for metadata.
• Add ordered groups, first-seen deduplication, filtering of unknown values, and a trailing Other section for unmatched enum values. Human and machine output use the same order.
• Preserve scalar default semantics, existing JSON fields, and exact legacy spacing. Dynamic widths apply only when non-empty new options are configured.
• Expand catalog tests with neutral fixtures and document the extension. Add the CLI changeset. Regenerated review output is unchanged because the review specification has no catalog affected by these options.

Testing

• Primary generation, compilation and staticcheck passed. The full primary runtime run executed 1,453 tests and failed only two new exact JSON assertions that expected pretty rather than the existing compact format. After correcting the assertions and regenerating, all catalog tests passed with go test -C testSDKs/sdk-cli-primary ./tests -run '^TestCatalog' -count=1 -v. The full runtime suite was not repeated for this test-only correction.
• Review generation, compilation and staticcheck passed; ./scripts/test-target.sh cli review passed with 547 tests, including two existing skips.
• Human and JSON catalog smoke checks passed, including grouped order, default labels and the Other remainder.
• npm run format, all template TypeScript checks, both module tidy checks and git diff --check passed.
• make lint failed on an existing gofmt complaint in the unchanged templates/perms.go. The local -trimpath setting also prevents permission generation; clearing it for the lint invocation allowed that stage to finish. No permissions-file changes are included.
• The primary usage check completed with its existing warning that CLI has no usage build command.

Public-safety check

• This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
• Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
• Generated fixtures and review SDK changes are public-safe.
• I reviewed git diff --check.

---

Summary by cubic

Adds per-command defaults and ordered groups to offline enum catalogs in the generated CLI, so shared enums can mark which values are defaults for different commands and arrange options into named sections. Previously a catalog only had one global default and a flat list. Release workflow snapshots now also fail when a tag version does not match the generated CLI version, and PHP model constructors now qualify shared enum defaults with the model's namespace instead of the enum's.

• defaults maps each enum value to a command name or array of command names; only the scalar default sets the machine-output default boolean. Renders as <value> (default: <command>, ...).
• groups renders titled sections in declared order, deduplicating by first occurrence, ignoring unknown values, and placing unmatched values in a trailing Other section. Malformed group and command-default entries are skipped.
• Machine output stays a flat ordered array, adding default_for and group fields only when the corresponding options are configured; existing JSON fields are unchanged.
• Catalogs with no effective defaults or groups keep the legacy fixed label width of 42; catalogs with effective options size to the longest label.
• The PHP fix uses the model's output location when resolving enumeration qualifiers for constructor defaults, with a new test covering default and overridden shared-enum values.

^{Written for commit 74631fa. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 6 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Adds optional per-command defaults and ordered groups to generated CLI enum catalogs, gated so existing output is unchanged; tests cover legacy, grouped, and malformed cases, and invalid groups fall back to Other.

Re-trigger cubic</sub>

[TristanSpeakEasy]

Catalog normalization updated in dd77aea:

• Trim command names and group titles.
• Omit groups with empty, unknown-only or already-claimed values.
• If no declared group matches, retain flat schema-order output without an Other heading or JSON group fields. Invalid groups already retained all enum values; this changes their presentation.
• Base dynamic widths on resolved defaults and groups, so ineffective metadata preserves legacy spacing.

Added human and JSON assertions for these cases, including a long-label fixture that checks exact legacy spacing, and updated the documentation.

Validation passed: primary CLI generation, compilation and staticcheck; focused catalog tests; template type-check; formatting and diff checks; and human-output smoke checks. The full test matrix is left to CI. Full repository lint was not repeated because the existing local permissions-file formatting failure is unchanged.

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Adds optional per-command defaults and ordered groups to generated CLI enum catalogs, with tests, docs, changeset, and a release-workflow version-check snapshot; existing output is preserved when the new options are unused.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Adds optional per-command defaults and ordered groups to CLI enum catalogs while preserving legacy output when unused, fixes PHP constructor enum default namespace qualification with a regression test, and adds a release-tag version guard; all changes are additive or corrective with test coverage.

Re-trigger cubic</sub>

[AshGodfrey]

• The PHP enum-default qualification fix (php/includes/sanitization.ts, php/includes/templating.ts, the PHP test, and the second changeset) is an independent bug fix with its own changelog entry. It is correct as far as I can tell, since usageLocation already exists on TemplateValueContext, but it should probably land in its own PR so the PHP changelog entry and any revert are not tied to a CLI feature.
• testSharedEnumConstructorDefault does not call CommonHelpers::recordTest, unlike the other tests in that file.

[ThomasRooney]

I find the concept of "Group" confusing as it makes me feel a bit dumb understanding how CliCatalogValue and CliCatalog now map together.

Can we get a bit more documentation in the PR description with an example of how this might be used?

[ThomasRooney]

Propose this refinement in configuration:

1. default is calculated based on preset in each command, rather than doubly specified. To make this work, would recommend the logic lives on the go side similar to where we evaluate which openapi node is associated with the expression.
2. x-speakeasy-enum-groups is created inline with the x-speakeasy-enum-descriptions extension, with linting / validation for this living on the go side to avoid generating invalid inputs (rather than drop them). This would simplify the test cases and DX significantly, and also be something we could do to improve SDK-generated enum descriptions..

[ThomasRooney]

Temporarily blocking this with proposals for improved interface to reach same functionality. Non-blocking though: happy for push-back / review dismissal if you disagree.