feat(REL-12755): adding --fields flag

[nieblara]

Add a --fields persistent flag that filters JSON output to only include specified top-level fields. A flag response can be 50KB+ with targeting configs for every environment. --fields key,name,kind,temporary returns only those fields. Applies to JSON output only. Handles both singular and collection responses (filters each item in items array, preserves totalCount). Error responses are never filtered.

---

Note

Medium Risk
Moderate risk because it changes the shared output.CmdOutput API and alters default plaintext rendering for several commands, which could break scripts or expected CLI output. JSON filtering is additive but could mask fields if misused or if responses are non-object JSON.

Overview
Adds a new persistent --fields flag (and cliflags.GetFields) to filter JSON command output down to selected top-level fields, supporting both singular responses and items collections while preserving totalCount/_links.

Refactors output.CmdOutput to accept optional field filters and per-resource formatting options, and updates resource/flags/members/config commands to pass ResourceName so plaintext output can render as tables (lists) or key/value blocks (singular) for supported resources.

Hardens plaintext formatting to avoid panics on non-string values, introduces new table/key-value rendering utilities, and expands/updates golden and unit tests to cover the new --fields behavior and changed plaintext output.

^{Reviewed by Cursor Bugbot for commit c64ba94. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Related Jira issue: REL-12755: --fields flag for response shaping

[JackDanger]

Clean implementation — the filtering logic is solid, collection handling is thoughtful, and the tests are thorough. This is purely additive (opt-in via --fields), so no breaking change concerns. A few design questions:

1. Top-level only filtering leaves the biggest win on the table
The Confluence doc says a flag response can be 50KB+, and the main culprit is the environments object with targeting configs for every environment. But --fields key,name,environments still returns the full 50KB environments blob. The token savings come from not requesting environments at all, which this handles. But if someone wants environments.production.on, they either get the full environments object or nothing.

Not saying you need dot-path filtering in v1, but it's worth noting in the --fields help text that this is top-level only. And: have you considered a complementary --exclude flag? --exclude environments,_links would be the more common use case — "give me everything except the huge stuff."

2. --fields with plaintext is silently ignored
If an agent passes --fields key,name but is in plaintext mode (e.g., FORCE_TTY=1, or explicit --output plaintext), the flag has zero effect with no feedback. An agent won't know its request was ignored. Consider: (a) emitting a stderr warning, or (b) having --fields imply JSON output (like --json does).

3. The CmdOutput function signature is getting heavy

CmdOutput(action, outputKind, input, fields)

And in the very next PR (#663) it becomes:

CmdOutput(action, outputKind, input, fields, opts)

Since you're already adding CmdOutputOpts in #663, consider moving fields into that struct now to avoid the intermediate signature. One refactor instead of two.

4. GetFields silently swallows errors

func GetFields(cmd *cobra.Command) []string {
    fields, err := cmd.Root().PersistentFlags().GetStringSlice(FieldsFlag)
    if err != nil {
        return nil
    }
    return fields
}

If the flag registration is misconfigured, this silently returns nil and filtering never happens. The user gets back 50KB thinking they asked for 3 fields. Probably fine in practice, but a log.Debug would help future debugging.

5. Nice touch: preserving totalCount and _links on collections
This is the right call — pagination metadata shouldn't be filtered. Agents need _links.next to paginate and totalCount to know if there are more pages.