Add programmatic API-shape output: --raw flag + --params passthrough

[omriariav]

Motivation

Today the CLI is great for interactive/ergonomic use, but scripts that integrate with gws end up needing the raw Google API JSON shape (Gmail API, Chat API, People API payloads as documented by Google). Two friction points hit programmatic consumers:

1. Output is flattened/transformed — fields are renamed, base64 bodies are decoded, header arrays are collapsed, etc. Great for humans, lossy for machines that already speak the API.
2. Not every API param is exposed as a flag — e.g. Chat API's filter parameter supports expressions like createTime > "2025-01-01T00:00:00Z" or spaceType = "DIRECT_MESSAGE" that aren't accessible from the current flag surface.

Adding a small programmatic mode would unblock scripting/automation use cases without disturbing the existing ergonomic UX.

Proposed changes

1. Global --raw flag

When --raw is set on a resource command, return the unmodified Google API response JSON instead of the flattened/pretty shape. Implementation-wise: skip the transform layer between SDK response and stdout.

2. --params <json> escape hatch on resource commands

Accept a JSON object that maps to the underlying API request's parameters. Merges with / overrides any flag-derived params. Example:

gws chat messages list --params '{\"parent\":\"spaces/AAA\",\"pageSize\":100,\"filter\":\"createTime > \\\"2025-01-01T00:00:00Z\\\"\"}' --raw

This avoids having to flag-ify every API parameter and unblocks features like Chat filters immediately.

3. Pagination under --raw

--all should aggregate across pages while preserving API shape:

• Concatenate top-level list fields (messages, spaces, members, ...) across pages
• Drop nextPageToken from the final aggregated output

NDJSON (one page object per line) is an acceptable alternative — easy for callers to merge.

Endpoints that matter most for programmatic use

Command	Underlying API	Notes
gmail list	users.messages.list	needs q, maxResults, pagination
gmail thread <id>	users.threads.get	needs full payload tree: headers, parts[*].body.data (base64), internalDate, labelIds
chat spaces list	spaces.list	needs filter (DM filter especially)
chat members list	spaces.members.list	needs parent, pagination
chat messages list	spaces.messages.list	needs parent, filter (createTime), pagination
people get	people.get	needs resourceName, personFields

These cover the highest-value programmatic use cases. Other resources can follow the same pattern incrementally.

Backwards compatibility

• --raw is opt-in; default behavior unchanged.
• --params is additive; existing flags continue to work and take precedence (or merge — designer's call).
• No change to auth, config, or command structure.

Why this matters

Right now, programmatic consumers either (a) reach past the CLI directly to the Google SDK, or (b) reverse-engineer the flattened shape and write fragile decoders. Both defeat the value of having a unified CLI. --raw + --params makes the CLI a first-class building block for scripts and pipelines without compromising the human-friendly default.

[omriariav]

PR ready: #189

Hard requirement → commits/files map

#	Requirement	Implementation
1	Global --raw (skip transform)	cmd/raw.go (addRawParamsFlags, isRaw, printRaw, writeRaw); each runXxxRaw marshals the SDK response struct directly so Google's JSON tags drive the shape.
2	--params <json>, precedence documented	cmd/raw.go (parseParams + accessors). Precedence: --params keys override CLI flags ("params win") — surfaced in flag help and README.md "Programmatic mode" section.
3	--all under --raw preserves API shape	runGmailListRaw in cmd/gmail.go; runChatListRaw / runChatMessagesRaw / runChatMembersRaw in cmd/chat_raw.go. Each concatenates the top-level list field and drops nextPageToken from the final output.
4	Six commands wired	gmail list + gmail thread → cmd/gmail.go; chat spaces list / chat messages list / chat members list (new noun-verb paths) → cmd/chat_raw.go; people get (new top-level command) → cmd/people.go; existing chat list / chat messages / chat members / contacts get also accept the new flags.
5	Verification	Live invocation is blocked by a read-only sandbox hook in my environment — I have to ask you to paste the truncated output for the canonical set in the PR. The shape (header arrays, base64 body data, parts tree, camelCase keys, nextPageToken dropped under --all) is asserted in cmd/raw_test.go.
6	Shape tests	cmd/raw_test.go snapshot-tests --raw for all six commands (top-level keys + nested structure for payload.headers, parts[*].body.data, sender object, etc.) and --params parsing edge cases. New command paths are also asserted in cmd/commands_test.go.
7	Backwards compat / additive	Existing test suite passes unchanged. No flags renamed or removed. Documented precedence: --params overrides CLI flags.

Verification still TODO

The five canonical commands need to be run against a live account and the truncated output pasted in the PR description. I could not execute them from here (read-only sandbox). Could you run them and post the output, or unblock and I'll do it next?