postgres: add --json body example to create-role help

[jamesbroadhead]

Summary

databricks postgres create-role's --json flag binds to the inner Role object (CreateRoleRequest.Role, JSON-tagged "role"), so users must supply spec / name / etc. directly. Without an example this isn't obvious — the auto-generated help leaves the spec fields unflagged (// TODO: complex arg: spec in the generator), and the server's error when the body is wrong is vague:

Field 'role' is required and must contain at least one subfield with a non-default value

That fires whenever the inner Role has no recognized fields, which most commonly happens when a user wraps the body in {"role": ...} (matching the wire format the SDK marshals to). The CLI strips the unknown outer key with Warning: unknown field: role and ships an empty body. Walking out of that loop currently requires reading the SDK source.

This adds a curated override (cmd/workspace/postgres/overrides.go) that appends a concrete service-principal-role example to cmd.Long, plus a short note on the wrapping pitfall.

Help output (after)

Arguments:
  PARENT: The Branch where this Role is created. Format:
    projects/{project_id}/branches/{branch_id}

Body shape (passed via --json): fields go directly on the Role object.
Do not wrap them in '{"role": ...}' — the CLI will strip the unknown
outer key and the server will reject the empty body with "Field 'role'
is required".

Example — create a service-principal-backed role:

  databricks postgres create-role projects/<PROJECT_ID>/branches/<BRANCH_ID> \
    --role-id <SP_CLIENT_ID> \
    --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<SP_CLIENT_ID>", "auth_method": "LAKEBASE_OAUTH_V1", "membership_roles": ["DATABRICKS_SUPERUSER"]}}'

Scope

This PR only touches create-role. The same shape gap (// TODO: complex arg: spec + opaque error) exists for create-endpoint, create-branch, create-project, and create-database. Happy to extend if the approach is right; left them out so reviewers can decide on the pattern first.

Test plan

• go build ./cmd/workspace/postgres/...
• databricks postgres create-role --help shows the new section (output above)
• make fmt clean
• Reproduced the original confusion with a service-principal payload before the change; with this PR the example would have led me straight to the working body shape

This pull request and its description were written by Isaac.

[simonfaltum]

I took a look. I think the underlying problem is real: create-role --json binds to the inner Role, and the SDK sends request.Role as the body, so {"role": ...} is genuinely the wrong CLI shape. The help text plus early error are useful.

A few things I would want addressed or discussed before merge:

• Design / scope concern: cmd/workspace/postgres/overrides.go hardcodes a one-off role wrapper check, but the same inner-body --json pattern exists for sibling Postgres commands (branch, database, endpoint, project, etc.). If we add JsonFlag.Raw() for this, I would rather see a small reusable helper or generator-level pattern than command-specific JSON parsing that will spread by copy-paste.

• Should fix: rejectWrappedRoleJSON silently returns nil if the json flag is not *flags.JsonFlag. That is an internal invariant for this generated command; it should fail loudly with %T so a future generator/refactor does not silently disable the validation.

• Should fix: this changes user-facing help and adds a new client-side error, but there is no NEXT_CHANGELOG.md entry.

Test/CI note: lint, generated validation, and unit test jobs are passing on GitHub; the integration test check is currently failing.

[jamesbroadhead]

👋 @simonfaltum @andrewnester — Claude here on James's behalf.

Rebased onto current main. Diff unchanged from the prior shape: 3 files, +150 / -0 (new overrides.go + overrides_test.go + a 7-line addition in libs/flags/json_flag.go). Build clean, unit tests pass locally.

Ready for review whenever you've got a moment.

(comment posted by Claude)

[jamesbroadhead]

👋 @simonfaltum @andrewnester — Claude here on James's behalf.

Apologies for the long delay — I missed Simon's May 7 review when I rebased and pinged on May 18. Catching up now. All three of Simon's items are addressed in 76a59789c:

1. Design / scope — Generalized the wrapped-body rejection. New method (*flags.JsonFlag).RejectWrappedJSON(outerKey, example) error in libs/flags/json_flag.go does the detection + error rendering. The postgres override is now a one-liner:

return jf.RejectWrappedJSON("role", `databricks postgres create-role projects/<PROJECT_ID>/branches/<BRANCH_ID> \
    --role-id <SP_CLIENT_ID> \
    --json '{"spec": {...}}'`)

Sibling postgres commands (create-branch, create-database, create-endpoint, create-project) can adopt the same guard in a one-line override each — happy to follow up with those in a small separate PR if the helper shape lands well here.

2. Should-fix (loud type-assertion) — rejectWrappedRoleJSON now returns fmt.Errorf("internal: ... got %T", flag.Value) if the --json flag is missing or has an unexpected type. Comment notes this is a generator/refactor tripwire, not a user-reachable path. Test case updated (was previously asserting the old silent-nil; now asserts the loud error).

3. Should-fix (NEXT_CHANGELOG) — Entry added under ### CLI.

Diff: 5 files, +93/-27. Added a TestRejectWrappedJSON table to libs/flags/json_flag_test.go covering empty body, non-object body, object without/with outer key, sibling keys, mismatched key, plus a separate test for the Example: hint formatting.

Re the CI integration-test failure you flagged: passing CI now; the rebase pulled in fixes since.

(comment posted by Claude)

[simonfaltum]

Thanks, the changelog regression is fixed now.