feat(docs raw): add --tab to traverse a specific tab; default returns tab 0 only

[sebsnyk]

Motivation

gog docs raw <docId> returns the document body but only for tab 0. Multi-tab documents have additional content under a tabs[] structure (per the Docs API's includeTabsContent parameter on documents.get), and that content is invisible to raw today. Any consumer that walks body.content to find textRuns, mailto links, named ranges, or table positions can only see tab 0 — content in tabs 1+ is silently absent.

The most concrete consumer hurt by this: any "scan the whole doc for mailto-linked names then promote them to Person smart chips" loop. That loop reads gog docs raw, walks body.content, finds mailto runs, computes (startIndex, endIndex) per match, calls delete + insert-person --index=N in reverse-index order. On a doc with tabs, the loop misses every mailto in tabs 1+. Today that path silently returns 0 promotions instead of erroring.

Adjacent prior art: #323 closed (added --tab to editing commands: write, insert, delete, find-replace). The read side — raw, plus any other walk-style command — never got the same treatment. This issue closes that gap.

Repro

# Create a doc with two tabs; put a mailto link in tab 2:
DOC=$(gog docs create "raw --tab test" -j | jq -r .id)
gog docs tabs add "$DOC" --title "Tab 2"
TAB2=$(gog docs list-tabs "$DOC" -j | jq -r '.tabs[1].id')
gog docs write "$DOC" --replace --markdown --tab="$TAB2" \
  --file <(printf 'Hello [Sample Person](mailto:sample@example.com).\n')

# Today: gog docs raw misses the tab-2 mailto entirely:
gog docs raw "$DOC" | jq -r '
  .body.content[]
  | (.paragraph?.elements // [])[]
  | .textRun?.textStyle?.link?.url // empty
'
# Output: (empty — no mailto found, because raw returned tab 0)

# Wanted:
gog docs raw "$DOC" --tab="$TAB2" | jq -r '...'
# Output: mailto:sample@example.com

Proposed surface

gog docs raw <docId> [flags]
  --tab=STRING        Target a specific tab by title or ID (matches the --tab
                      flag on write/insert/delete/find-replace from #323)
  --all-tabs          Return a JSON envelope { tabs: [ { tabId, title, body }, ... ] }
                      instead of a single body. Useful for walk-everything consumers.

Behaviour:

• Without --tab and without --all-tabs: backward-compatible (returns the default tab's body, same as today).
• With --tab=<id|title>: returns just that tab's body, same JSON shape as today (so consumers don't need a new parser).
• With --all-tabs: returns the envelope above. Consumers that want to walk the whole doc can iterate the array.

Same pattern as the existing gog docs export --tab= (experimental flag already in v0.21).

Acceptance criteria

• gog docs raw <doc> --tab=<id> returns the body of the specified tab, with body.content semantics identical to the default-tab return.
• --tab accepts either a tab ID (e.g. t.abc123) or the visible title (matching the existing --tab resolution on write/insert/delete).
• --all-tabs returns every tab including nested child tabs (Docs supports tab hierarchy via childTabs). Document the shape in --help.
• Without either flag, behaviour is unchanged from today (no breaking change for existing scripts).
• The same pattern applies to any other walk-style command that today silently operates on tab 0 only: most relevant are find-replace (already covered by feat(docs): add --tab flag to editing commands (write, insert, delete, find-replace) #323) and any future find-range / comments-locate / named-range-list helpers that walk body content.

References

• Docs API documents.get with includeTabsContent=true: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get
• Tab resource (with childTabs for nested-tab hierarchy): https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#Tab
• Closed precedent on the edit side: feat(docs): add --tab flag to editing commands (write, insert, delete, find-replace) #323 — feat(docs): add --tab flag to editing commands.
• Adjacent: bug(docs write --tab): markdown path drops nested-list nesting (children render as plain text) #696 (bug on --tab per-tab markdown nesting), feat(docs): add find-range primitive that maps text to Document index ranges #682 (find-range primitive), feat(docs comments): add locate subcommand to resolve a comment to a body range #687 (comments locate). All three benefit from / require a tab-aware raw walk.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 5, 2026, 10:08 AM ET / 14:08 UTC.

Summary
Keep open: current main does not add --tab or --all-tabs to the dedicated gog docs raw command. There is adjacent tab-aware behavior in gog docs cat --raw --all-tabs, but it is not the requested command surface and does not settle the raw output-shape decision.

Reproducibility: yes. from source inspection: DocsRawCmd has only docId and --pretty, and it calls Documents.Get without IncludeTabsContent. I did not run the live Google Docs mutation repro because current source already establishes the missing CLI surface.

Next step
A maintainer should choose the raw output contract for the new flags before this becomes a safe autonomous fix PR.

Review details

Best possible solution:

Expose tab-aware docs raw behavior using the existing tab traversal and title-or-ID resolution helpers, with tests and help text that preserve the no-flag raw API shape and clearly define the flagged output shape.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection: DocsRawCmd has only docId and --pretty, and it calls Documents.Get without IncludeTabsContent. I did not run the live Google Docs mutation repro because current source already establishes the missing CLI surface.

Is this the best way to solve the issue?

Unclear on the exact output shape: adding tab flags is the right narrow direction, but maintainers should decide whether --all-tabs returns a custom envelope or the canonical Documents.Get response with tabs populated.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The requested --all-tabs envelope would make docs raw return a non-canonical wrapper under that flag, while the command is currently documented and tested as a bare Documents.Get API dump.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label changes:

• add P2: This is a bounded Docs CLI enhancement for an existing command that affects multi-tab document automation.
• add impact:other: The issue affects scriptable inspection of multi-tab Docs content, which is maintainer-visible but outside the specific owned impact labels.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded Docs CLI enhancement for an existing command that affects multi-tab document automation.
• impact:other: The issue affects scriptable inspection of multi-tab Docs content, which is maintainer-visible but outside the specific owned impact labels.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd

What I checked:

• Repository policy read: Read the full target AGENTS.md; its parseable-output and conservative review guidance was applied. (AGENTS.md:1, 3d5c9cef65fa)
• Current raw command lacks tab flags: DocsRawCmd exposes only docId and --pretty, then calls svc.Documents.Get(id).Context(ctx).Do() without IncludeTabsContent. (internal/cmd/docs.go:69, 3d5c9cef65fa)
• Generated help confirms missing surface: The generated gog docs raw help lists --pretty but no --tab or --all-tabs flag. (docs/commands/gog-docs-raw.md:20, 3d5c9cef65fa)
• Raw output contract is currently a bare API object: The existing raw test asserts top-level keys are Document fields rather than a wrapper and requires body.content in the default output. (internal/cmd/docs_raw_test.go:114, 3d5c9cef65fa)
• Adjacent tab-aware implementation exists elsewhere: DocsCatCmd already supports --tab, --all-tabs, and --raw; raw cat mode sets IncludeTabsContent(true) when those flags are present. (internal/cmd/docs_read.go:19, 3d5c9cef65fa)
• Reusable tab helpers already cover child tabs and title-or-ID lookup: flattenTabs recurses into ChildTabs, and findTab resolves either exact tab ID or case-folded tab title. (internal/cmd/docs_tabs.go:10, 3d5c9cef65fa)

Likely related people:

• Peter Steinberger: git blame for the current DocsRawCmd, tab helpers, and related read-side tab code points to the v0.21.0 release commit. (role: recent area contributor; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/docs.go, internal/cmd/docs_tabs.go, internal/cmd/docs_read.go)
• karbassi: CHANGELOG credits the raw API command work that introduced docs raw and the raw-output audit. (role: raw command feature contributor; confidence: medium; files: CHANGELOG.md, docs/raw-audit.md)
• alexknowshtml: CHANGELOG credits the original Docs read-side tab support, including docs cat --tab and docs cat --all-tabs. (role: Docs tab support contributor; confidence: medium; files: CHANGELOG.md, internal/cmd/docs_read.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.