feat(docs): top-level table-row / table-column / table-merge commands

[sebsnyk]

Motivation

gog already implements row/column add/delete and cell merge via the gog docs sed brace DSL (|2|[+1,0]/foo/, |2|[1,1:1,3]/merge/, etc.). These are powerful but the syntax overhead is high for one-shot calls in scripts. A user who knows "I want to add a row at the end of the second table" should not have to learn the regex address syntax.

The implementation already exists in internal/cmd/docs_sed_table_ops.go (InsertTableRow / DeleteTableRow / InsertTableColumn / DeleteTableColumn / MergeTableCells / UnmergeTableCells emitted from the sed path). Lifting them into top-level commands is mostly a CLI surface change.

Repro

# Today (works but unwieldy):
gog docs sed <DOC_ID> '|2|[+1,0]//'                  # append empty row to 2nd table
gog docs sed <DOC_ID> '|2|[1,1:1,3]/merge/'           # merge top row cols 1-3

# Wanted:
gog docs table-row insert <DOC_ID> --table=2 --at=end
gog docs table-merge <DOC_ID> --table=2 --range=1,1:1,3

Proposed surface

gog docs table-row insert <docId> --table=<idx|header-text> --at=<n|end> [--values-json=...]
gog docs table-row delete <docId> --table=<idx|header-text> --row=N
gog docs table-column insert <docId> --table=<idx|header-text> --at=<n|end>
gog docs table-column delete <docId> --table=<idx|header-text> --col=N
gog docs table-merge <docId> --table=<idx|header-text> --range=r1,c1:r2,c2
gog docs table-unmerge <docId> --table=<idx|header-text> --cell=r,c

--table=<header-text> mode: resolves to the table whose first-row-first-cell text matches verbatim (Docs API has no native "table label" — this is the most stable proxy in practice).

All commands map to single batchUpdate requests; the brace-DSL implementation can be lifted into a shared helper.

Acceptance criteria

• 1:1 behavioural parity with the corresponding sed brace expressions.
• --table=<header-text> resolves the table by verbatim first-cell text; ambiguity errors out.
• Index-based --table=N matches the sed convention (1-based, negative from end, * for all).
• Returns the index of the new row/column or the merged range in JSON mode.

References

• InsertTableRowRequest / DeleteTableRowRequest / InsertTableColumnRequest / DeleteTableColumnRequest: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request
• MergeTableCellsRequest / UnmergeTableCellsRequest: same page
• Existing brace-DSL implementation: internal/cmd/docs_sed_table_ops.go

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 4, 2026, 7:52 AM ET / 11:52 UTC.

Summary
Keep open: current main still exposes Docs table row/column insert/delete and merge/unmerge only through docs sed, not through the requested top-level table-row, table-column, table-merge, or table-unmerge commands.

Reproducibility: not applicable. as a bug reproduction: this is a feature request. Source and generated docs show the requested top-level commands are absent while the underlying sed helpers exist.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
The issue is actionable, but it creates new user-facing commands and table selection semantics that need maintainer CLI-shape approval before a fix PR is queued.

Review details

Best possible solution:

Approve the command contract, then add a shared Docs table mutation layer used by both sed and top-level commands, with focused unit tests, generated command docs, and live Google Docs proof.

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

Not applicable as a bug reproduction: this is a feature request. Source and generated docs show the requested top-level commands are absent while the underlying sed helpers exist.

Is this the best way to solve the issue?

Unclear until maintainers approve the user-facing command contract. Technically, reusing or extracting the existing sed table mutation helpers looks like the narrowest maintainable path.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The proposed --table=<header-text> and --table=* behavior adds new CLI contract semantics that should be approved before implementation.
• Because these commands mutate live Google Docs tables, the eventual PR should include live Docs proof in addition to unit tests.

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

Label changes

Label changes:

• add P2: This is a normal, bounded Docs command-surface improvement in an existing supported area, not an urgent regression or security issue.
• add impact:other: The issue affects scriptable Google Docs table editing ergonomics, which is meaningful maintainer-visible impact outside the specific owned impact categories.
• add issue-rating: 🌊 off-meta tidepool: 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 normal, bounded Docs command-surface improvement in an existing supported area, not an urgent regression or security issue.
• impact:other: The issue affects scriptable Google Docs table editing ergonomics, which is meaningful maintainer-visible impact outside the specific owned impact categories.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd -run 'TestDocsTable|TestRunTableRowColOp|TestRunTableMerge'
• make docs-commands
• make ci
• Live Google Docs proof for row insert/delete, column insert/delete, merge, unmerge, header-text ambiguity, and JSON output

What I checked:

• AGENTS.md read: Repository policy was read fully before review; its parseable output and test guidance are relevant to the requested JSON command behavior. (AGENTS.md:1, 3d5c9cef65fa)
• Docs command registry lacks requested commands: DocsCmd registers existing Docs subcommands including insert-table, cell-update, cell-style, table-column-width, and sed, but no table-row, table-column, table-merge, or table-unmerge command. (internal/cmd/docs.go:20, 3d5c9cef65fa)
• Generated command docs lack requested commands: The generated gog docs subcommand list contains table-column-width and sed, but not the requested row/column/merge command surface. (docs/commands/gog-docs.md:19, 3d5c9cef65fa)
• Underlying sed row/column helpers exist: runTableRowColOp already builds InsertTableRow, DeleteTableRow, InsertTableColumn, and DeleteTableColumn requests through the sed path. (internal/cmd/docs_sed_table_ops.go:13, 3d5c9cef65fa)
• Underlying sed merge helpers exist: runTableMerge already builds MergeTableCells and UnmergeTableCells requests through the sed path. (internal/cmd/docs_sed_table_ops.go:190, 3d5c9cef65fa)
• Sed dispatch owns current merge surface: The sed runner routes table-cell merge, unmerge, and split replacements into runTableMerge, confirming the capability exists only behind sed syntax today. (internal/cmd/docs_sed.go:301, 3d5c9cef65fa)

Likely related people:

• steipete: Merged adjacent Docs table command work and current shallow blame ties the table operation files to the v0.21.0 release commit authored by Peter Steinberger. (role: recent adjacent contributor and merger; confidence: high; commits: 2c84d8981dd5, cf9c5150c0a2, 97dd2d30618d; files: internal/cmd/docs.go, internal/cmd/docs_sed_table_ops.go, internal/cmd/docs_table_column_width.go)
• chrischall: Merged PR metadata for feat(docs): add insert-table primitive #617 shows chrischall added the docs insert-table primitive and touched the Docs table insertion command/docs files that this request would sit beside. (role: introduced adjacent table command surface; confidence: medium; commits: 3a1b15592f47; files: internal/cmd/docs.go, internal/cmd/docs_insert_table.go, internal/cmd/docs_table_inserter.go)
• sebsnyk: Filed this issue and the earlier table column-width request credited in the v0.21.0 changelog, so they have useful context on Docs table ergonomics even though local code authorship is not shown in the shallow checkout. (role: recent related workflow reporter; confidence: medium; commits: 2c84d8981dd5; files: CHANGELOG.md, docs/docs-editing.md)

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.