mcp-gee-sweet 0.7.0.dev84__tar.gz → 0.7.0.dev87__tar.gz

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/.claude/commands/merge-pr.md

@@ -1,13 +1,14 @@
 Merge the current branch's PR and clean up its worktree. Uses `--admin` only to bypass the required-review gate (this is a solo-maintainer repo, so a second approver is never coming) — it must never be used to bypass a failing or pending status check.
 
-1. Get the PR for the current branch: `gh pr view --json number,title,url,state,mergeable,statusCheckRollup,reviewDecision`. If there's no open PR for this branch, stop and tell the user.
+1. Get the PR: if given a PR number (e.g. following on from `/verify-pr <number>`), use `gh pr view <number> --json ...` explicitly rather than relying on current-branch detection — `/verify-pr` may have checked out a locally-named `review/<headRefName>` branch (see its step 3) instead of the PR's real branch name, which current-branch auto-detection can't always resolve. Otherwise, get the PR for the current branch: `gh pr view --json number,title,url,state,mergeable,statusCheckRollup,reviewDecision`. If there's no open PR for this branch/number, stop and tell the user.
 2. Verify it's actually safe to merge:
    - `state` must be `OPEN`.
    - Every check in `statusCheckRollup` (in particular "Lint and test") must show success. If anything is failing or still pending, stop and report which — do not merge, and do not wait/poll.
    - `mergeable` must not be `CONFLICTING`.
 3. Show the user a summary: PR number, title, URL, check status, and review status (expected to be blocked only on the missing-approval requirement). State plainly that merging will use `--admin` to bypass that review gate. Ask for explicit confirmation before proceeding.
 4. On confirmation, squash-merge (matching this repo's existing history — commits land on `develop` as a single `title (#number)` commit): `gh pr merge <number> --admin --squash`. The remote branch is auto-deleted on merge (repo setting), so don't pass `--delete-branch`.
-5. Clean up the local worktree:
+5. Clean up:
+   - If the current branch is a `review/<headRefName>` branch created by `/verify-pr` (not a `.claude/worktrees/*` worktree — just a local branch in the main checkout), there's no worktree to remove: switch to `develop` and `git branch -D review/<headRefName>`.
    - If this session created the current worktree (i.e. it got here via `/start-worktree` or `/next-issue` earlier in this same session), use `ExitWorktree` with `action: "remove"`.
    - Otherwise (worktree predates this session), fall back to manual cleanup from the main checkout: `git worktree remove <path>`, then `git branch -d <branch>`, then `git worktree prune`.
 6. Update the roadmap: from the main checkout on `develop`, `git pull` then check `docs/roadmap.md` for a checkbox line referencing the issue(s) this PR closes (search by issue number). If found, check it off (`- [ ]` → `- [x]`) and append `(PR <number>)` in the existing style (e.g. `(PR #280)`) — see recent `- [x]` entries for the exact convention. If the roadmap has no line item for this issue (not every ticket is roadmap-tracked — chores, follow-up defects, etc.), skip this step silently. Commit directly to `develop` (`docs(roadmap): check off #<issue> (PR <number>)`) and push — `develop`'s branch protection has `enforce_admins: false`, so a direct push by the repo owner is allowed for this kind of small, reversible, docs-only change; don't open a separate PR for it.

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/.claude/commands/verify-pr.md

@@ -6,7 +6,13 @@ CI (the "Lint and test" check `/merge-pr` already gates on) covers unit tests. I
 
 2. **Identify the PR.** Take a PR number as an argument if given, otherwise use `gh pr list --state open` and ask the user which one if there's more than one. Get its details: `gh pr view <number> --json number,title,url,headRefName,baseRefName,statusCheckRollup,mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING`, stop here — report it and say the branch needs a rebase onto `<baseRefName>` before verification is worth doing. Don't spend code-review or live-QA effort on a branch that can't merge as-is; that cost is only worth paying once it's rebased.
 
-3. **Check out the branch.** `gh pr checkout <number>`. This fetches and switches the main checkout to the PR's branch directly (no worktree needed — the orchestrator owns the main checkout).
+3. **Check out the branch.** Don't use `gh pr checkout <number>` directly — if the worker's own worktree still has `<headRefName>` checked out (the normal case while that worker session is active), it fails with "already checked out," and the only recovery `gh` offers is unlocking/removing that worktree, which disrupts the worker for no reason. Git only blocks two worktrees from sharing the same branch *name*, not the same commit — so fetch the PR's branch into a locally-named review branch instead:
+   ```
+   git fetch origin <headRefName>:review/<headRefName> --force
+   git checkout review/<headRefName>
+   git branch --set-upstream-to=origin/<headRefName> review/<headRefName>
+   ```
+   This points the main checkout at the exact same commit without touching the worker's worktree at all. The `--set-upstream-to` matters: without it, `gh pr view`/`gh pr merge` with no PR number can't map the local `review/<headRefName>` branch back to the PR later (their current-branch auto-detection relies on tracked-branch info, not name matching) — `/merge-pr` should also be run with the PR number as an explicit argument here rather than relying on that auto-detection. When pushing QA-result commits later (step 9), push to the PR's real branch name via a refspec: `git push origin review/<headRefName>:<headRefName>`. Delete the local `review/<headRefName>` branch once you're done with this PR (switch away first, then `git branch -D review/<headRefName>`) so it doesn't accumulate across sessions.
 
 4. **Reconnect the MCP server.** The server hot-reloads on file change, but this Claude session's MCP connection stays on the old process. Tell the user to run:
    ```
@@ -26,7 +32,15 @@ CI (the "Lint and test" check `/merge-pr` already gates on) covers unit tests. I
 
 8. **Record results honestly.** For each test case actually executed, add `**Result (<date>) ✅ PASS**` or `**Result (<date>) ❌ FAIL — <what happened>**` directly below its `Checks` block. Never write a Result for a case you didn't actually invoke — if something blocks a case (fixture missing, tool errors before completing), write `**Result (<date>)** pending — <reason>` and say so plainly rather than guessing the outcome.
 
-9. **Commit and push the results.** If any Result entries were added, commit just those QA doc changes onto the PR branch (`qa: record live verification for PR #<number>`) and push, so the evidence lands in history before merge. Ask before pushing, per this repo's normal commit/push confirmation rule.
+9. **Commit and push the results.** If any Result entries were added, they need to land in a real file edit. If this session runs under an isolation policy that blocks edits outside `.claude/worktrees/*` (background jobs do — regardless of which branch is checked out in the main checkout), don't spin up a fresh throwaway worktree per PR (churn — create, edit, commit, push, remove, repeat). Instead keep **one persistent scratch worktree** for the whole orchestrator session, e.g. `.claude/worktrees/qa-scratch`, and reuse it every time this step comes up:
+   ```
+   git worktree add .claude/worktrees/qa-scratch -b orchestrator-qa-scratch develop   # first time only
+   ```
+   Its own branch name (`orchestrator-qa-scratch`) is arbitrary and never touches any PR branch, so it can never conflict with a worker's worktree. Each time this step comes up: enter it (`EnterWorktree` with `path`), `git fetch origin <headRefName> && git reset --hard origin/<headRefName>` to line it up with the PR's latest commit, make the edits, commit (`qa: record live verification for PR #<number>`), then push straight to the PR's real branch via refspec — same trick as step 3:
+   ```
+   git push origin HEAD:<headRefName>
+   ```
+   Ask before pushing, per this repo's normal commit/push confirmation rule. Leave the scratch worktree in place afterward (`ExitWorktree` with `action: "keep"`) for next time — don't remove it between PRs, only if the user asks for a cleanup pass.
 
 10. **Report.** Summarize: code review findings (if any), which test cases passed/failed/pending, any coverage gaps found in step 6, and whether the branch looks ready to merge. If everything passed, say the next step is `/merge-pr`. If something failed, say the PR needs to go back to its worker session — don't attempt the fix yourself here; this session's job is verification, not implementation.
 

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/CLAUDE.md

@@ -32,7 +32,7 @@ Tests live in `tests/` and can be run with `uv run pytest`.
 Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorator, resources), `auth.py` (lifespan, `SpreadsheetContext`), and `tools/` (domain-based layout):
 
 - `tools/sheets/data.py` — read/write cell data (`get_sheet_data`, `get_sheet_formulas`, `get_multiple_*`, `find_in_spreadsheet`, `clear_values`, `update_cells`, `batch_update_cells`, `batch_update`)
-- `tools/sheets/structure.py` — sheet structure (`list_sheets`, `copy_sheet`, `rename_sheet`, `create_sheet`, `delete_sheet`, `add_rows`, `add_columns`, `delete_rows`, `delete_columns`, `format_cells`, `merge_cells`, `unmerge_cells`, `freeze`, `sort_range`, `add_chart`)
+- `tools/sheets/structure.py` — sheet structure (`list_sheets`, `copy_sheet`, `duplicate_sheet`, `rename_sheet`, `create_sheet`, `delete_sheet`, `add_rows`, `add_columns`, `delete_rows`, `delete_columns`, `format_cells`, `merge_cells`, `unmerge_cells`, `freeze`, `sort_range`, `add_chart`)
 - `tools/sheets/helpers.py` — A1 notation helpers (`_parse_a1_notation`, `_column_index_to_letter`, etc.)
 - `tools/drive/files.py` — file/folder operations (`create_spreadsheet`, `import_csv_to_sheet`, `list_spreadsheets`, `list_files`, `search_files`, `create_folder`, `copy_file`, `move_file`, `rename_file`, `delete_file`, `list_shared_with_me`, `list_recent_files`, `get_storage_quota`, etc.)
 - `tools/drive/sharing.py` — permissions (`share_spreadsheet`, `share_file`, `list_permissions`, `update_permission`, `remove_permission`)

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.7.0.dev84
+Version: 0.7.0.dev87
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs, and Calendar. 60+ tools for AI clients.
 Project-URL: Homepage, https://github.com/khuisman/mcp-gee-sweet
 Project-URL: Bug Tracker, https://github.com/khuisman/mcp-gee-sweet/issues

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/docs/configuration.md

@@ -70,7 +70,7 @@ Access logs are emitted at `INFO` level — they appear when `DEBUG_LEVEL` is `D
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-By default all 92 tools are registered. Use `ENABLED_TOOLS` (or `--include-tools` on the CLI) to restrict the server to exactly the tools you need. This reduces the AI's context window cost — each registered tool is a name the model must reason about on every call.
+By default all 93 tools are registered. Use `ENABLED_TOOLS` (or `--include-tools` on the CLI) to restrict the server to exactly the tools you need. This reduces the AI's context window cost — each registered tool is a name the model must reason about on every call.
 
 ```bash
 # Environment variable

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/docs/qa/tests/sheets_mgmt.md

@@ -125,6 +125,94 @@ Tests marked **⚠️ destructive** rename or delete sheets — reset fixtures a
 
 ---
 
+## `duplicate_sheet`
+
+### TC-S51: Duplicate within the same spreadsheet, default name ⚠️ destructive
+
+**Prompt**
+> "Duplicate the Sales sheet in {SPREADSHEET_ID}"
+
+**Checks**
+- New tab appears, named by Google's default (e.g. "Copy of Sales")
+- Data in the new tab matches Sales (6 rows, 4 columns)
+- Original Sales sheet unchanged
+- Response includes `sheetId`, `title`, `index`, `spreadsheetId`
+
+**Result (2026-07-10) ✅ PASS**
+`duplicate_sheet(spreadsheet_id, sheet="Sales")` → `{"sheetId":1766233601,"title":"Copy of Sales","index":1,...}`. `get_sheet_data` on "Copy of Sales" returned matching headers/rows. Deleted after verification.
+
+---
+
+### TC-S52: Duplicate with a custom name ⚠️ destructive
+
+**Prompt**
+> "Duplicate the Sales sheet in {SPREADSHEET_ID} and name the copy 'Sales Duplicate'"
+
+**Checks**
+- New tab is named 'Sales Duplicate', not Google's default
+- `newSheetName` was passed on the same `duplicateSheet` request (single API call, no follow-up rename)
+
+**Result (2026-07-10) ✅ PASS**
+`duplicate_sheet(spreadsheet_id, sheet="Sales", new_name="Sales Duplicate")` → title `"Sales Duplicate"`, confirmed via code that `newSheetName` is set on the same request body as `sourceSheetId`. Deleted after verification.
+
+---
+
+### TC-S53: Default position lands immediately after the source tab ⚠️ destructive
+
+**Prompt**
+> "Duplicate the Sales sheet in {SPREADSHEET_ID} without specifying a position, then list all sheets"
+
+**Checks**
+- The new tab appears immediately after 'Sales' in the `list_sheets` response order
+- 🔍 **Regression:** the Sheets API's own default for `duplicateSheet` places the copy at tab position 0 regardless of source position (confirmed via live QA on this tool) — the tool must compute and pass `insertSheetIndex` explicitly to land the copy after the source, matching Sheets UI's native "Duplicate" behavior
+
+**Result (2026-07-10) ✅ PASS**
+`duplicate_sheet(spreadsheet_id, sheet="Sales")` → index 1. `list_sheets` → `["Sales","Copy of Sales","Empty","Notes & Misc","BrandNew"]` — lands immediately after Sales, confirming the regression fix (`_get_sheet_index` + explicit `insertSheetIndex`). Deleted after verification.
+
+---
+
+### TC-S54: Explicit insert_index is honored ⚠️ destructive
+
+**Prompt**
+> "Duplicate the Sales sheet in {SPREADSHEET_ID}, placing the copy at tab position 0"
+
+**Checks**
+- The new tab is the first tab in the `list_sheets` response order
+- Confirms an explicit `insert_index` overrides the "after source" default
+
+**Result (2026-07-10) ✅ PASS**
+`duplicate_sheet(spreadsheet_id, sheet="Sales", insert_index=0)` → index 0. `list_sheets` → `["Copy of Sales","Sales",...]` — explicit index correctly overrides the default. Deleted after verification.
+
+---
+
+### TC-S55: Source sheet not found
+
+**Prompt**
+> "Duplicate a sheet called 'DoesNotExist' in {SPREADSHEET_ID}"
+
+**Checks**
+- Returns `{"error": ...}` before calling the duplicate API
+- Error references the missing sheet name
+
+**Result (2026-07-10) ✅ PASS**
+`duplicate_sheet(spreadsheet_id, sheet="DoesNotExist")` → `{"error": "Sheet 'DoesNotExist' not found"}`. No mutation, non-destructive.
+
+---
+
+### TC-S56: Cache invalidated after duplicate ⚠️ destructive
+
+**Prompt**
+> "Duplicate the Sales sheet in {SPREADSHEET_ID} as 'PostDuplicateCache', then immediately list all sheets"
+
+**Checks**
+- `list_sheets` includes 'PostDuplicateCache'
+- Confirms `cache.mark_dirty(spreadsheet_id)` fires after duplicate
+
+**Result (2026-07-10) ✅ PASS**
+`duplicate_sheet(spreadsheet_id, sheet="Sales", new_name="PostDuplicateCache")` succeeded; immediate `list_sheets` (no explicit `refresh_cache`) included `"PostDuplicateCache"`, confirming `mark_dirty` fired. Deleted after verification; fixture restored to `["Sales","Empty","Notes & Misc","BrandNew"]`.
+
+---
+
 ## `rename_sheet`
 
 ### TC-S11: Rename to a new name ⚠️ destructive

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/docs/roadmap.md

@@ -121,7 +121,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [ ] `create_named_range` / `create_bookmark` — anchor points for internal links ([#152](https://github.com/khuisman/mcp-gee-sweet/issues/152))
 - [ ] Rowspan emitter — AST `Cell.rowspan` field exists but emitter does not yet merge rows ([#195](https://github.com/khuisman/mcp-gee-sweet/issues/195))
 - [x] Warn/error on mixed text + nested table in same cell — shipped as the fuller `Cell.children: list[Run | Table]` ordered model, also fixing trailing-text-after-nested-table ordering ([#275](https://github.com/khuisman/mcp-gee-sweet/issues/275)) in the same PR (PR #276) ([#108](https://github.com/khuisman/mcp-gee-sweet/issues/108))
-- [ ] colspan/rowspan inside nested tables ([#109](https://github.com/khuisman/mcp-gee-sweet/issues/109))
+- [x] colspan/rowspan inside nested tables (PR #287) ([#109](https://github.com/khuisman/mcp-gee-sweet/issues/109))
 - [ ] `find_in_doc` — search doc text and return match locations, parallel to `find_in_spreadsheet`; removes the manual index math currently needed to retrofit links (or any style) onto text already in a doc, raised while fixing #248 ([#262](https://github.com/khuisman/mcp-gee-sweet/issues/262))
 
 **Drive**

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/docs/tools.md

@@ -2,7 +2,7 @@
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-92 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
+93 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
 
 ## Sheets — data
 
@@ -26,6 +26,7 @@
 |---|---|---|
 | `list_sheets` | List all sheets in a Google Spreadsheet. | `spreadsheet_id` |
 | `copy_sheet` | Copy a sheet from one spreadsheet to another. | `src_spreadsheet`, `src_sheet`, `dst_spreadsheet`, `dst_sheet` |
+| `duplicate_sheet` | Duplicate a sheet tab within the same spreadsheet. | `spreadsheet_id`, `sheet`, `new_name?`, `insert_index?` |
 | `rename_sheet` | Rename a sheet in a Google Spreadsheet. | `spreadsheet`, `sheet`, `new_name` |
 | `create_sheet` | Create a new sheet tab in an existing Google Spreadsheet. | `spreadsheet_id`, `title` |
 | `add_rows` | Add rows to a sheet in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `count`, `start_row?` |

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/src/mcp_gee_sweet/tools/sheets/helpers.py

@@ -106,3 +106,19 @@ def _get_sheet_id(
         return None
     except Exception:
         return None
+
+
+def _get_sheet_index(sheets_service: Any, spreadsheet_id: str, sheet_id: int) -> int | None:
+    """Return the current 0-based tab position of sheet_id, or None if not found."""
+    try:
+        spreadsheet = (
+            sheets_service.spreadsheets()
+            .get(spreadsheetId=spreadsheet_id, fields="sheets.properties(sheetId,index)")
+            .execute()
+        )
+        for sheet in spreadsheet.get("sheets", []):
+            if sheet["properties"]["sheetId"] == sheet_id:
+                return sheet["properties"]["index"]
+        return None
+    except Exception:
+        return None

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/src/mcp_gee_sweet/tools/sheets/structure.py

@@ -4,7 +4,7 @@ from mcp.server.fastmcp import Context
 from mcp.types import ToolAnnotations
 
 from ...cache import fetch_sheets
-from .helpers import _get_sheet_id, _parse_a1_notation
+from .helpers import _get_sheet_id, _get_sheet_index, _parse_a1_notation
 
 _VALID_CHART_TYPES = ["COLUMN", "BAR", "LINE", "AREA", "PIE", "SCATTER", "COMBO", "HISTOGRAM"]
 
@@ -124,6 +124,66 @@ def register(tool):
         lc.cache.mark_dirty(dst_spreadsheet)
         return result
 
+    @tool(annotations=ToolAnnotations(title="Duplicate Sheet", destructiveHint=True))
+    def duplicate_sheet(
+        spreadsheet_id: str,
+        sheet: str,
+        new_name: str | None = None,
+        insert_index: int | None = None,
+        ctx: Context = None,
+    ) -> dict[str, Any]:
+        """
+        Duplicate a sheet tab within the same spreadsheet.
+
+        Distinct from copy_sheet, which copies a sheet across spreadsheets.
+
+        Args:
+            spreadsheet_id: The ID of the spreadsheet
+            sheet: The name of the sheet to duplicate
+            new_name: Optional title for the new sheet. Defaults to Google's
+                auto-generated name (e.g. "Copy of Sheet1") if omitted.
+            insert_index: Optional 0-based tab position for the new sheet.
+                Defaults to immediately after the source sheet if omitted.
+
+        Returns:
+            Information about the newly created sheet
+        """
+        lc = ctx.request_context.lifespan_context
+        sheets_service = lc.sheets_service
+
+        sheet_id = _get_sheet_id(sheets_service, spreadsheet_id, sheet, lc.cache, lc.drive_service)
+        if sheet_id is None:
+            return {"error": f"Sheet '{sheet}' not found"}
+
+        duplicate_request: dict[str, Any] = {"sourceSheetId": sheet_id}
+        if insert_index is not None:
+            duplicate_request["insertSheetIndex"] = insert_index
+        else:
+            source_index = _get_sheet_index(sheets_service, spreadsheet_id, sheet_id)
+            if source_index is not None:
+                duplicate_request["insertSheetIndex"] = source_index + 1
+        if new_name is not None:
+            duplicate_request["newSheetName"] = new_name
+
+        result = (
+            sheets_service.spreadsheets()
+            .batchUpdate(
+                spreadsheetId=spreadsheet_id,
+                body={"requests": [{"duplicateSheet": duplicate_request}]},
+            )
+            .execute()
+        )
+
+        lc.cache.mark_dirty(spreadsheet_id)
+
+        new_sheet_props = result["replies"][0]["duplicateSheet"]["properties"]
+        return {
+            "sheetId": new_sheet_props["sheetId"],
+            "title": new_sheet_props["title"],
+            "index": new_sheet_props.get("index"),
+            "spreadsheetId": spreadsheet_id,
+        }
+
     @tool(annotations=ToolAnnotations(title="Rename Sheet", destructiveHint=True))
     def rename_sheet(
         spreadsheet: str, sheet: str, new_name: str, ctx: Context = None

{mcp_gee_sweet-0.7.0.dev84 → mcp_gee_sweet-0.7.0.dev87}/tests/sheets/test_structure.py

@@ -237,6 +237,158 @@ class TestCopySheet:
         assert not mock_sheets.spreadsheets.return_value.batchUpdate.called
 
 
+class TestDuplicateSheet:
+    def _sheets_service(self, sheet_id=0, source_index=0, reply_props=None):
+        mock = MagicMock()
+        mock.spreadsheets.return_value.get.return_value.execute.return_value = {
+            "sheets": [
+                {"properties": {"title": "Sheet1", "sheetId": sheet_id, "index": source_index}}
+            ]
+        }
+        mock.spreadsheets.return_value.batchUpdate.return_value.execute.return_value = {
+            "replies": [
+                {
+                    "duplicateSheet": {
+                        "properties": reply_props
+                        or {"sheetId": 99, "title": "Copy of Sheet1", "index": 1}
+                    }
+                }
+            ]
+        }
+        return mock
+
+    def _cache_with_sheet(self, title="Sheet1", sheet_id=0):
+        cache = MagicMock()
+        cache.get_sheets.return_value = [SheetInfo(title=title, sheet_id=sheet_id)]
+        return cache
+
+    def _request(self, svc):
+        body = svc.spreadsheets.return_value.batchUpdate.call_args.kwargs["body"]
+        return body["requests"][0]["duplicateSheet"]
+
+    def test_sends_duplicate_sheet_request_with_source_id(self):
+        svc = self._sheets_service(sheet_id=7, source_index=0)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        assert self._request(svc)["sourceSheetId"] == 7
+
+    def test_new_name_included_when_given(self):
+        svc = self._sheets_service(sheet_id=7)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](
+            spreadsheet_id="ss1", sheet="Sheet1", new_name="My Copy", ctx=ctx
+        )
+        assert self._request(svc)["newSheetName"] == "My Copy"
+
+    def test_insert_index_included_when_given(self):
+        svc = self._sheets_service(sheet_id=7)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](
+            spreadsheet_id="ss1", sheet="Sheet1", insert_index=3, ctx=ctx
+        )
+        assert self._request(svc)["insertSheetIndex"] == 3
+
+    def test_explicit_insert_index_skips_source_index_lookup(self):
+        """When the caller supplies insert_index, no extra API call is needed to
+        compute a default — the direct spreadsheets().get() (used only for that
+        lookup) must not be invoked."""
+        svc = self._sheets_service(sheet_id=7)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](
+            spreadsheet_id="ss1", sheet="Sheet1", insert_index=3, ctx=ctx
+        )
+        assert not svc.spreadsheets.return_value.get.called
+
+    def test_new_name_omitted_when_not_given(self):
+        svc = self._sheets_service(sheet_id=7)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        assert "newSheetName" not in self._request(svc)
+
+    def test_insert_index_defaults_to_immediately_after_source(self):
+        """Matches Sheets' native UI 'Duplicate' behavior: the copy lands right
+        after the source tab. The Sheets API's own default (observed via live
+        QA) is index 0 regardless of source position, so this must be computed
+        and passed explicitly rather than relying on the API's default."""
+        svc = self._sheets_service(sheet_id=7, source_index=2)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        assert self._request(svc)["insertSheetIndex"] == 3
+
+    def test_insert_index_omitted_when_source_index_lookup_fails(self):
+        svc = self._sheets_service(sheet_id=7)
+        svc.spreadsheets.return_value.get.return_value.execute.return_value = {"sheets": []}
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        assert "insertSheetIndex" not in self._request(svc)
+
+    def test_returns_new_sheet_info(self):
+        svc = self._sheets_service(
+            sheet_id=7, reply_props={"sheetId": 99, "title": "Copy of Sheet1", "index": 2}
+        )
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(sheet_id=7))
+        result = _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        assert result == {
+            "sheetId": 99,
+            "title": "Copy of Sheet1",
+            "index": 2,
+            "spreadsheetId": "ss1",
+        }
+
+    def test_returns_error_when_source_sheet_not_found(self):
+        svc = self._sheets_service(sheet_id=7)
+        ctx = _make_ctx(sheets_service=svc, cache=self._cache_with_sheet(title="Other", sheet_id=7))
+        result = _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Missing", ctx=ctx)
+        assert result == {"error": "Sheet 'Missing' not found"}
+        assert not svc.spreadsheets.return_value.batchUpdate.called
+
+    def test_marks_cache_dirty_on_success(self):
+        svc = self._sheets_service(sheet_id=7)
+        cache = self._cache_with_sheet(sheet_id=7)
+        ctx = _make_ctx(sheets_service=svc, cache=cache)
+        _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        cache.mark_dirty.assert_called_with("ss1")
+
+    def test_forwards_drive_service_to_get_sheet_id(self, monkeypatch):
+        """Regression: this call site omitted drive_service, reintroducing the
+        cache-poisoning bug fixed in #284 (modified_time silently disabled for
+        all subsequent readers of the spreadsheet)."""
+        svc = self._sheets_service(sheet_id=7)
+        cache = self._cache_with_sheet(sheet_id=7)
+        drive_svc = MagicMock()
+        ctx = _make_ctx(sheets_service=svc, cache=cache, drive_service=drive_svc)
+        mock_get_sheet_id = MagicMock(return_value=7)
+        monkeypatch.setattr(sheets_structure_module, "_get_sheet_id", mock_get_sheet_id)
+        _structure_tools["duplicate_sheet"](spreadsheet_id="ss1", sheet="Sheet1", ctx=ctx)
+        mock_get_sheet_id.assert_called_once_with(svc, "ss1", "Sheet1", cache, drive_svc)
+
+
+class TestGetSheetIdCallSitesForwardDriveService:
+    """Static regression guard: every _get_sheet_id() call in structure.py must
+    forward drive_service as its 5th argument.
+
+    PR #284 fixed cache poisoning caused by a missing drive_service (it silently
+    disables modifiedTime staleness checks for all readers of that spreadsheet).
+    duplicate_sheet reintroduced the bug by omitting the argument (caught in
+    review of PR #286) — this scans all call sites so a future tool can't drop
+    it again without a test failing.
+    """
+
+    def test_all_call_sites_pass_drive_service(self):
+        import inspect
+        import re
+
+        source = inspect.getsource(sheets_structure_module)
+        calls = re.findall(r"_get_sheet_id\(([^)]*)\)", source)
+        assert len(calls) >= 12, (
+            f"expected at least 12 _get_sheet_id call sites, found {len(calls)}"
+        )
+        for call_args in calls:
+            assert "drive_service" in call_args, (
+                f"_get_sheet_id call missing drive_service: {call_args}"
+            )
+
+
 class TestDeleteSheet:
     def _sheets_service(self, sheet_id=7):
         mock = MagicMock()