feat(sheets): add copy-paste (fill) command mapping to CopyPasteRequest

[chrischall]

Fixes #661.

Problem

There's no primitive to copy a range's formulas/format down or across with relative-reference adjustment. sheets copy is sheet-level, sheets raw is read-only (Spreadsheets.Get), and sheets batch-update only writes value ranges. Filling per-row formulas down a column currently means inlining every fully-spelled-out formula via large value writes — high-token and error-prone.

Change

gog sheets copy-paste <spreadsheetId> <source> <dest> [--type=NORMAL|VALUES|FORMAT|FORMULA|NO_BORDERS|DATA_VALIDATION|CONDITIONAL_FORMATTING] [--transpose] (aliases fill, copy-range), mapping to spreadsheets.batchUpdate CopyPasteRequest. A destination larger than the source tiles it, so a fill-down is one call. Built on the existing parseSheetRange/gridRangeFromMap/runSheetsMutation/applySheetsBatchUpdate helpers (same shape as sheets merge). Command reference regenerated via make docs-commands; no CHANGELOG edit (release-owned).

Real-behavior proof (built from this branch)

gog sheets copy-paste --help:

Usage: gog sheets (sheet) copy-paste (fill,copy-range) <spreadsheetId> <source> <dest> [flags]

Copy a range's values/formulas/format to another range (tiles to fill down/across)

--dry-run (fill formulas down a buffer):

$ gog sheets copy-paste s1 'Sheet1!A2:H71' 'Sheet1!A2:H120' --type FORMULA --dry-run --json
{ "dry_run": true, "op": "sheets.copy-paste",
  "request": { "source": "Sheet1!A2:H71", "dest": "Sheet1!A2:H120",
               "type": "PASTE_FORMULA", "orientation": "NORMAL", "spreadsheet_id": "s1" } }

Tests

internal/cmd/sheets_copy_paste_test.go over the existing httptest Sheets stub: asserts the wire-level CopyPasteRequest (paste type incl. PASTE_FORMULA, transpose → TRANSPOSE orientation, source/dest GridRanges with a taller destination for fill-down), invalid-type rejection, and empty-range guards. make fmt + make lint (0 issues) + go test ./internal/cmd/ green.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 30, 2026, 4:00 PM ET / 20:00 UTC.

Summary
Adds a gog sheets copy-paste command with fill and copy-range aliases mapping A1 source/destination ranges to Sheets CopyPasteRequest, plus generated command docs, a changelog note, and httptest coverage.

Reproducibility: not applicable. This PR implements a new command rather than fixing broken existing behavior. Source inspection confirms current main only exposes spreadsheet copy, read-only raw, and values batch-update rather than range-level CopyPasteRequest.

Review metrics: 2 noteworthy metrics.

• Diff scope: 8 files; +315/-1. The patch is bounded to one Sheets command, generated command docs, a changelog note, and focused tests.
• Focused tests: 1 new test file; 6 subtests. The new coverage exercises request mapping, defaults, transpose behavior, and validation guards before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Optionally add a redacted terminal transcript from one live copy-paste against a disposable spreadsheet if maintainers want API-level proof before merge.

Risk before merge

• [P1] The posted proof shows CLI help, dry-run JSON, and httptest wire validation, but not a live mutation against a real Google Sheet; maintainers may want a redacted disposable-spreadsheet smoke before merge.

Maintainer options:

1. Request one live Sheets smoke
   Ask for a redacted terminal transcript that copies formulas in a disposable spreadsheet and reads formulas back to prove relative-reference adjustment against the real API.
2. Accept the current proof
   Land with the dry-run terminal proof and httptest wire validation if maintainers are comfortable that the request shape is enough for this scoped command.

Next step before merge

• No automated repair lane is needed because review found no discrete patch defect; the remaining action is maintainer review and merge gating.

Security
Cleared: No concrete security or supply-chain concern was found; the diff does not touch dependencies, workflows, scripts, package metadata, secrets, or auth plumbing.

Review details

Best possible solution:

Land the narrow command after normal maintainer review and CI, preserving the existing Sheets helper patterns and adding live disposable-spreadsheet proof only if maintainers want extra API confidence.

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

Not applicable; this PR implements a new command rather than fixing broken existing behavior. Source inspection confirms current main only exposes spreadsheet copy, read-only raw, and values batch-update rather than range-level CopyPasteRequest.

Is this the best way to solve the issue?

Yes; mapping the command to Sheets API CopyPasteRequest through the existing range parsing, GridRange, mutation, and batch-update helpers is the narrowest maintainable path I found.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 5e4daadbc929.

Label changes

Label changes:

• add merge-risk: 🚨 other: Dry-run and mock-server tests do not prove the new Google Sheets mutation path against the live API.

Label justifications:

• P2: This is a bounded Sheets feature PR with clear workflow value and limited blast radius.
• merge-risk: 🚨 other: Dry-run and mock-server tests do not prove the new Google Sheets mutation path against the live API.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal output from the branch showing the new help text and dry-run JSON request; httptest coverage supplements the request-shape proof.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal output from the branch showing the new help text and dry-run JSON request; httptest coverage supplements the request-shape proof.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was fully read; its read-only PR review guidance and generated-doc/testing expectations informed this review. (AGENTS.md:1, 5e4daadbc929)
• Current main lacks the command: Current SheetsCmd exposes copy, raw, and values batch-update, but no copy-paste, fill, or copy-range subcommand. (internal/cmd/sheets.go:28, 5e4daadbc929)
• Existing batch update is values-only: The existing sheets batch-update builds BatchUpdateValuesRequest and calls Spreadsheets.Values.BatchUpdate, so it does not expose spreadsheet-level CopyPasteRequest. (internal/cmd/sheets.go:267, 5e4daadbc929)
• PR implementation path: The PR validates spreadsheet/range inputs, normalizes paste type and orientation, resolves sheet IDs with existing helpers, and sends one CopyPasteRequest through applySheetsBatchUpdate. (internal/cmd/sheets_copy_paste.go:15, f27381e406e5)
• Focused test coverage: The new httptest coverage checks formula fill-down request shape, default PASTE_NORMAL, transpose orientation, invalid paste type rejection, and empty source/destination guards. (internal/cmd/sheets_copy_paste_test.go:67, f27381e406e5)
• PR discussion and proof: The PR body includes terminal help and dry-run JSON from the branch, and the follow-up comment says the --type default was restored and command docs regenerated.

Likely related people:

• Tsopic: Commit f911d6b added the current gog sheets batch-update values command that this PR explicitly distinguishes from spreadsheet-level copy/fill operations. (role: introduced related command surface; confidence: high; commits: f911d6b21835; files: internal/cmd/sheets.go, internal/cmd/sheets_batch_update_test.go, docs/sheets-batch-update.md)
• Mahmoud Ashraf: Commit 53225e2 added the existing Sheets CopyPasteRequest path for data-validation copying, including reusable range-resolution patterns. (role: adjacent CopyPasteRequest contributor; confidence: medium; commits: 53225e224720; files: internal/cmd/sheets_validation.go, internal/cmd/sheets_update_validation_test.go, internal/cmd/sheets.go)
• chrischall: Current-main history shows recent adjacent Sheets insert work by this contributor, and this PR is in the same Sheets automation area. (role: recent adjacent Sheets contributor; confidence: medium; commits: 8a9a90840823; files: internal/cmd/sheets_insert.go, internal/cmd/sheets_insert_test.go)
• Peter Steinberger: Current-main blame for the consolidated Sheets command/helper files points at the v0.19.0 release commit, and the PR branch includes a changelog/docs conflict-resolution commit by this author. (role: recent area integrator; confidence: medium; commits: b25a3c029b37, f27381e406e5; files: internal/cmd/sheets.go, internal/cmd/sheets_mutation_helpers.go, CHANGELOG.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.

[chrischall]

@clawsweeper re-review — restored default:"NORMAL" on the --type flag (the schema/docs now declare the default; addresses the P1/P2 drift) and regenerated the command reference via make docs-commands. The goconst concern that originally prompted dropping the default is handled by the pasteNormal constant, so make lint is still clean (0 issues).

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26692707684
• Updated: 2026-05-30T19:28:09.073Z