feat(gog): add batch begin / batch end primitive with --batch flag on edit commands

[sebsnyk]

Motivation

The Google Docs documents.batchUpdate endpoint accepts up to 500 requests in a single call. Sheets spreadsheets.batchUpdate and Slides presentations.batchUpdate have the same shape with per-service request schemas.

gog already uses BatchUpdate internally on every edit command (docs_table_column_width.go, docs_cell_style.go, docs_insert_image.go, docs_smart_chips.go, docs_write_*.go) — each command builds []*docs.Request and submits as one Documents.BatchUpdate(...). But the unit of batching today is one CLI invocation, so consumer scripts that orchestrate dozens of edits per doc burn one API call per command.

Concrete profile of a typical markdown-import workflow that pushes one doc:

Edit kind	Calls / push	Request type
docs table-column-width (N cols x M tables)	12 - 25	UpdateTableColumnProperties
docs cell-style (background + bold + col-span headers)	8 - 14	UpdateTableCellStyle + UpdateTextStyle
docs insert-person (raw walk + delete + insert-person, reverse-index)	3 x N	DeleteContentRange + InsertPerson
docs insert-image --at <placeholder>	1 - 6	InsertInlineImage / ReplaceImage
docs find-replace	0 - 4	ReplaceAllText
Total	~30	mixed

• Today: ~30 sequential calls = ~30 write-quota items + ~15 s wall-clock.
• With batch primitive: 1 batchUpdate = 1 quota item + ~1.5 s wall-clock. 30x quota reduction, 10x wall-clock reduction.

Direct evidence: the same consumer is hitting quotaExceeded (429) on back-to-back pushes when several docs are pushed inside a minute. Per-doc quota cost goes from 30 to 1.

Proposed CLI surface

gog batch begin --doc=<id> [--service=docs|sheets|slides] [--name=<label>]
gog batch list
gog batch show <batch-id> [-j|--verbose]
gog batch end <batch-id> [--dry-run] [--continue-on-error] [--auto-split]
gog batch abort <batch-id>
gog batch prune --older-than=72h

And a --batch=<batch-id> flag on every edit command (docs write, insert, delete, update, find-replace, format, cell-style, table-column-width, insert-image, insert-person, insert-page-break). When set, the command resolves its arguments and anchors as it does today, builds the []*docs.Request payload it would have submitted, and appends to the batch state file instead of calling the API.

begin returns the batch id (UUID v7, sortable). Plain-mode output is the bare id so BID=$(gog batch begin --doc=$DOC) works without jq. --service defaults to docs; required to be set upfront (state-file shape depends on it).

State file

Use the existing config.StateDir() helper — siblings the existing gmail-watch/ directory. Honours GOG_HOME and GOG_STATE_DIR overrides.

<StateDir>/batches/<batch-id>.json

Schema:

{
  "batch_id": "01HXYZ...",
  "name": "docs:1ISHDn3...",
  "service": "docs",
  "doc_id": "1ISHDn3...",
  "account": "user@example.com",
  "client": "default",
  "created_at": "2026-06-05T14:23:11Z",
  "updated_at": "2026-06-05T14:23:47Z",
  "requests": [
    {
      "appended_at": "...",
      "command": "docs table-column-width",
      "argv": ["--table-index=1", "--col=1", "--width=200"],
      "request": { /* docs.Request JSON */ }
    }
  ]
}

Concurrent appends from multiple shells use the gmail-watch pattern: flock(LOCK_EX) + read + append + write-temp + rename. Same code shape as internal/cmd/gmail_watch_state.go. No auto-expiry; batch list shows age, batch prune is explicit.

Atomicity

documents.batchUpdate is strictly atomic — if any request fails, none are applied. This is a behavioural change from today's per-call independence.

Recommendation: strict-atomic by default. It matches the API guarantee and the principle of least surprise (batch end either applies all or none).

Add an opt-in --continue-on-error flag on batch end: on a 400 from the batched submit, gog re-submits each accumulated request as its own batchUpdate and reports per-request status. Lossier semantics, but recovers the "today" recovery behaviour for callers who explicitly want it. Stderr warning is unambiguous: "atomic batch failed; falling back to per-request submission (request N of M)".

Anchor resolution (--at <text>) happens at append time against the live doc, not at submit time. Resolving at submit time would require gog to rebuild index-shift tracking inside the batch executor — significant scope escalation. Keep append-time resolution; document the moving-target caveat.

write --replace --markdown distinction

This command today does delete-all + insert-converted-body + apply-tables-styles as one big internal batchUpdate. In --batch mode it should append every constituent request to the batch, not submit. But because its first request is a DeleteContentRange over the full body, appending it to a non-empty batch makes prior appends moot. Recommendation: refuse with a clear error when appending write --replace --markdown to a non-empty batch; future --allow-replace-after if a legit case emerges.

Multi-doc + cross-service

A single batchUpdate is scoped to one doc and one service. CLI rejects mismatched appends with batch <id> targets <service>:<doc-id>; this command targets <other>. For the parallel multi-doc case the pattern is "open N batches and end them in parallel" — already possible with the proposed surface.

>500 request limit

The Docs API caps at 500 requests per call. Recommendation: refuse by default with a clear error; offer --auto-split for callers who explicitly want non-atomic chunked submission (chunk size 500, stderr warning on each chunk).

Migration path

Before (~30 sequential API calls):

gog docs table-column-width $DOC --table-index=1 --col=1 --width=200
gog docs table-column-width $DOC --table-index=1 --col=2 --width=200
gog docs cell-style $DOC --table-index=2 --row=2 --col=0 --col-span=6 \
  --background-color=#C8E6C9 --bold
# ... 27 more sequential calls ...

After (1 API call):

BID=$(gog batch begin --doc=$DOC --service=docs)
gog docs table-column-width $DOC --table-index=1 --col=1 --width=200 --batch=$BID
gog docs table-column-width $DOC --table-index=1 --col=2 --width=200 --batch=$BID
gog docs cell-style $DOC --table-index=2 --row=2 --col=0 --col-span=6 \
  --background-color=#C8E6C9 --bold --batch=$BID
# ... 27 more --batch=$BID appends ...
gog batch end $BID

Optional pre-submit review:

gog batch end $BID --dry-run   # inspect payload
gog batch end $BID             # submit

Tiny diff to consumer scripts: one begin, one end, one extra flag.

Relationship to other open issues

All of these add edit commands or extend existing ones; each should support --batch from day one:

• feat(docs): add find-range primitive that maps text to Document index ranges #682 docs find-range — feeds resolved index ranges into batched edits.
• feat(docs): add --at <text> anchor to insert / delete / update / insert-person / insert-page-break #683 --at <text> on insert / delete / update / insert-person / insert-page-break — every new flag form supports --batch.
• feat(docs): add --link and --no-link to docs format #684 docs format --link / --no-link, feat(docs): add --code flag to docs format for monospace + grey background #685 docs format --code — UpdateTextStyle variants.
• feat(docs): top-level table-row / table-column / table-merge commands #686 top-level docs table-row / table-column / table-merge — high request-count operations where --batch matters most.
• feat(docs comments): add locate subcommand to resolve a comment to a body range #687 docs comments locate — read-only, feeds anchors into batched edits.
• feat(docs write): pre-flight orphan-comment check on --replace --markdown #691 docs write --check-orphans — pre-flight, runs before batch begin.
• feat(docs): named-range create / list / delete / replace-content commands #692 named-range commands — CreateNamedRange / ReplaceNamedRangeContent / DeleteNamedRange.

Once --batch lands, the per-command increment for every future edit command is: build []*docs.Request -> if --batch set, append; else submit. Trivial.

Acceptance criteria

1. gog batch begin --doc=<id> creates <StateDir>/batches/<id>.json and prints the batch id (plain) or {"batch_id": "..."} in -j.
2. Any gog docs edit command with --batch=<id> appends its []*docs.Request payload to the state file under a file lock and does not call the API.
3. gog batch end <id> submits accumulated requests as one documents.batchUpdate and deletes the state file on success.
4. gog batch end <id> --dry-run prints the would-be payload, does not call the API, keeps the state file.
5. gog batch end <id> --continue-on-error falls back to per-request submission on atomic-batch failure and reports per-request status on stderr.
6. --batch=<id> rejects mismatched (service, doc_id) appends with a clear error before any state mutation.
7. Batches > 500 requests refuse batch end unless --auto-split is passed; --auto-split chunks at 500 with stderr warning on each chunk.
8. gog batch list / show / abort / prune behave as documented; batch show -j emits the exact wire payload.

References

• batchUpdate (Docs): https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate
• Request shape (Docs): https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request
• batchUpdate (Sheets): https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate
• batchUpdate (Slides): https://developers.google.com/slides/api/reference/rest/v1/presentations/batchUpdate
• State-file precedent inside gog: internal/cmd/gmail_watch_state.go, internal/config/paths.go (StateDir, EnsureStateDir).

[clawsweeper]

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

Summary
Keep open: current main does not provide the requested persisted gog batch workflow or --batch append path, and the proposal is useful but broad enough to need maintainer direction before implementation.

Reproducibility: not applicable. this is an enhancement request rather than broken existing behavior. Source inspection shows the requested CLI primitive and --batch flags are absent on current main.

Ways to help us reproduce this

• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
This is real remaining work, but it is not a safe autonomous fix lane until maintainers choose the command surface, service scope, and batching semantics.

Review details

Best possible solution:

Keep the issue open, decide the staged command surface and batching semantics, then implement a shared request-submission abstraction and persisted batch store before wiring individual edit commands to it.

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

Not applicable; this is an enhancement request rather than broken existing behavior. Source inspection shows the requested CLI primitive and --batch flags are absent on current main.

Is this the best way to solve the issue?

Unclear; a persisted batch primitive is a plausible solution, but the broad cross-command surface and opt-in non-atomic modes need maintainer product judgment before this is the best permanent design.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The proposed --continue-on-error and --auto-split modes intentionally change all-or-nothing semantics and need maintainer policy choices before implementation.
• Adding --batch across many existing edit commands creates a second mutation path that must preserve stdout/stderr behavior, dry-run behavior, tab/revision handling, and existing script compatibility.
• The proposal mentions Docs, Sheets, and Slides shapes; maintainers should decide whether the first implementation is Docs-only or a cross-service primitive.

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

Label changes

Label changes:

• add P2: This is a substantial but bounded Docs automation improvement with quota and wall-clock impact for edit-heavy workflows.
• add impact:other: The issue concerns quota/performance pressure for multi-command Google Docs edit workflows, which is meaningful but outside the more specific impact taxonomy.
• 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 substantial but bounded Docs automation improvement with quota and wall-clock impact for edit-heavy workflows.
• impact:other: The issue concerns quota/performance pressure for multi-command Google Docs edit workflows, which is meaningful but outside the more specific impact taxonomy.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read in full; its scriptable-output and state/secrets guidance is relevant to this CLI feature. (AGENTS.md:1, 3d5c9cef65fa)
• Docs command tree has no batch command: The current Docs command struct lists write, insert, cell-style, table-column-width, insert-image, insert-person, find-replace, format, sed, and other commands, but no batch command. (internal/cmd/docs.go:20, 3d5c9cef65fa)
• Top-level CLI has no batch command: The top-level CLI command struct has service commands such as Docs, Sheets, Gmail, etc., but no top-level batch command. (internal/cmd/root.go:51, 3d5c9cef65fa)
• Existing Docs write submits immediately: docs write builds Docs requests and immediately calls svc.Documents.BatchUpdate, so the requested append-instead-of-submit path is not present there. (internal/cmd/docs_edit.go:151, 3d5c9cef65fa)
• Existing format command submits immediately: docs format builds request slices and immediately submits them through Documents.BatchUpdate, with no --batch field on the command struct. (internal/cmd/docs_format.go:15, 3d5c9cef65fa)
• Existing table/cell edits submit immediately: Docs table column width and cell style commands resolve targets, build requests, and submit Documents.BatchUpdate directly. (internal/cmd/docs_cell_style.go:101, 3d5c9cef65fa)

Likely related people:

• Peter Steinberger: Current blame and available follow history for the Docs command definitions and edit paths point to the v0.21.0 release snapshot authored by Peter Steinberger. (role: recent Docs command snapshot author; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/docs.go, internal/cmd/docs_edit.go, internal/cmd/docs_cell_style.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.