gogcli-mcp-sheets 2.5.0 → 2.6.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-    "version": "2.5.0"
+    "version": "2.6.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Sheets)",
       "source": "./",
       "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-      "version": "2.5.0",
+      "version": "2.6.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-sheets",
   "displayName": "gogcli (Sheets)",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -72,6 +72,8 @@ Plus 5 auth tools and 8 base Sheets tools (get, update, append, clear, metadata,
 | `gog_sheets_notes` | Read cell notes |
 | `gog_sheets_update_note` | Add or update cell notes |
 | `gog_sheets_links` | List hyperlinks in a range |
+| `gog_sheets_set_links` | Set =HYPERLINK() cells in one call (batch) |
+| `gog_sheets_snapshot` | Back up a whole spreadsheet before a risky edit |
 
 ## License
 

package/SKILL.md

@@ -51,6 +51,8 @@ Extended Google Sheets MCP server via [gogcli](https://github.com/openclaw/gogcl
 | `gog_sheets_notes` | Read cell notes |
 | `gog_sheets_update_note` | Add or update cell notes |
 | `gog_sheets_links` | List hyperlinks in a range |
+| `gog_sheets_set_links` | Set =HYPERLINK() cells in one call (batch) |
+| `gog_sheets_snapshot` | Back up a whole spreadsheet before a risky edit |
 | `gog_sheets_named_ranges_list` | List named ranges |
 | `gog_sheets_named_ranges_get` | Get a named range |
 | `gog_sheets_named_ranges_add` | Create a named range |

package/dist/index.js

@@ -31399,7 +31399,7 @@ function registerSheetsTools(server2) {
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.5.0" : "0.0.0";
+var VERSION = true ? "2.6.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31794,6 +31794,27 @@ ${result.content[0].text}` }] };
   }, async ({ spreadsheetId, range, account }) => {
     return runOrDiagnose(["sheets", "links", spreadsheetId, range], { account });
   });
+  server2.registerTool("gog_sheets_links_set", {
+    description: "Set cell hyperlinks in a Google Sheet. Three modes: (1) single link \u2014 pass cell + url (+ optional text); (2) multi-link cell \u2014 pass cell + runsJson, a JSON array of rich-text runs (a run with an empty uri is plain text); (3) batch \u2014 pass cellsJson, a JSON array of {cell,url,text} or {cell,runs:[...]} objects written in one request.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      cell: external_exports.string().optional().describe("Target cell in A1 notation (e.g. Sheet1!B2). Used by single-link and runsJson modes; omit for batch (cellsJson)."),
+      url: external_exports.string().optional().describe("Hyperlink URL for single-link mode"),
+      text: external_exports.string().optional().describe("Display text for single-link mode (defaults to the URL when omitted)"),
+      runsJson: external_exports.string().optional().describe('Multi-link cell: JSON array of runs, e.g. [{"text":"Act A","uri":"https://a"},{"text":" / "},{"text":"Act B","uri":"https://b"}]. A run with an empty uri is plain text.'),
+      cellsJson: external_exports.string().optional().describe("Batch: JSON array of {cell,url,text} or {cell,runs:[{text,uri}]} objects, written in one request."),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, cell, url: url2, text, runsJson, cellsJson, account }) => {
+    const args = ["sheets", "links", "set", spreadsheetId];
+    if (cell) args.push(cell);
+    if (url2) args.push(url2);
+    if (text) args.push(text);
+    if (runsJson) args.push(`--runs-json=${runsJson}`);
+    if (cellsJson) args.push(`--cells-json=${cellsJson}`);
+    return runOrDiagnose(args, { account });
+  });
   server2.registerTool("gog_sheets_named_ranges_list", {
     description: "List all named ranges in a spreadsheet.",
     annotations: { readOnlyHint: true },
@@ -32016,15 +32037,51 @@ ${result.content[0].text}` }] };
     return runOrDiagnose(["sheets", "table", "clear", spreadsheetId, tableId], { account });
   });
   server2.registerTool("gog_sheets_table_delete", {
-    description: "Delete a table by its table ID.",
+    description: "Delete a Google Sheets table. WARNING: the underlying `gog`/Sheets behaviour is that deleting a table also DESTROYS every cell value in the table range \u2014 not just the table styling/columns. By default this tool prevents that data loss by emulating the Sheets UI's \"Convert to range\": it reads the table's cells (values AND formulas) first, deletes the table, then restores the data into the now-plain range. Formatting, banding, and data-validation dropdowns are still lost (gog cannot round-trip those yet). Set keep_data=false to delete the table AND wipe its cell data (the raw destructive behaviour). To preserve everything, snapshot the whole spreadsheet first with gog_sheets_snapshot.",
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
       tableId: external_exports.string().describe("Table ID to delete"),
+      keep_data: external_exports.boolean().optional().describe(
+        `Default true: preserve the table's cell values and formulas (read \u2192 delete \u2192 restore), emulating "Convert to range". Set false to delete the table AND its data.`
+      ),
       account: accountParam
     }
-  }, async ({ spreadsheetId, tableId, account }) => {
-    return runOrDiagnose(["sheets", "table", "delete", spreadsheetId, tableId], { account });
+  }, async ({ spreadsheetId, tableId, keep_data = true, account }) => {
+    if (!keep_data) {
+      return runOrDiagnose(["sheets", "table", "delete", spreadsheetId, tableId, "--discard-data", "--force"], { account });
+    }
+    let range;
+    let values;
+    try {
+      const parsed = JSON.parse(await run(["sheets", "table", "get", spreadsheetId, tableId], { account }));
+      range = parsed.table?.a1;
+      if (!range) throw new Error(`could not determine the table's range (no "a1" in table get output) for table ${tableId}`);
+      const read = JSON.parse(await run(["sheets", "get", spreadsheetId, range, "--render=FORMULA"], { account }));
+      values = read.values ?? [];
+    } catch (err) {
+      return diagnose(err);
+    }
+    try {
+      await run(["sheets", "table", "delete", spreadsheetId, tableId, "--discard-data", "--force"], { account });
+    } catch (err) {
+      return diagnose(err);
+    }
+    if (values.length > 0) {
+      try {
+        await run(["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`], { account });
+      } catch (err) {
+        return toText(
+          `Table ${tableId} was deleted, but restoring its data FAILED \u2014 re-apply the values below manually.
+
+Range: ${range}
+Values: ${JSON.stringify(values)}
+
+${toError(err).content[0].text}`
+        );
+      }
+    }
+    return toText(`Deleted table ${tableId} and preserved ${values.length} row(s) of data (values + formulas) in ${range}.`);
   });
   server2.registerTool("gog_sheets_banding_list", {
     description: "List alternating-color banded ranges. Optionally scope to a single sheet.",
@@ -32130,6 +32187,19 @@ ${result.content[0].text}` }] };
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_sheets_snapshot", {
+    description: "Make a backup copy of an entire spreadsheet \u2014 a one-call safety snapshot to take BEFORE a risky or destructive edit (table delete, bulk clear, large rewrite). Returns the new copy's file ID and URL; if the edit goes wrong, restore by copying the backup back or sharing it. The copy is independent \u2014 later edits to the original do not affect it.",
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID to back up"),
+      name: external_exports.string().describe('Name for the backup copy, e.g. "Budget \u2014 backup before table delete"'),
+      parent: external_exports.string().optional().describe("Destination folder ID for the copy (default: same location as the original)"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, name, parent, account }) => {
+    const args = ["drive", "copy", spreadsheetId, name];
+    if (parent) args.push(`--parent=${parent}`);
+    return runOrDiagnose(args, { account });
+  });
 }
 
 // src/index.ts

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -180,6 +180,10 @@
       "name": "gog_sheets_links",
       "description": "List hyperlinks in a range."
     },
+    {
+      "name": "gog_sheets_links_set",
+      "description": "Set native cell hyperlinks: single link, multi-link rich-text cell (runsJson), or batch (cellsJson)."
+    },
     {
       "name": "gog_sheets_named_ranges_list",
       "description": "List all named ranges in a spreadsheet."
@@ -254,7 +258,11 @@
     },
     {
       "name": "gog_sheets_table_delete",
-      "description": "Delete a table by table ID."
+      "description": "Delete a Google Sheets table. By default preserves the table's cell values and formulas (emulates \"Convert to range\"); set keep_data=false to also wipe the data."
+    },
+    {
+      "name": "gog_sheets_snapshot",
+      "description": "Make a backup copy of an entire spreadsheet before a risky/destructive edit. Returns the copy's file ID and URL."
     },
     {
       "name": "gog_sheets_banding_list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-sheets",
   "description": "Extended Google Sheets MCP server via gogcli — all base tools plus full Sheets support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp-sheets"
   },
-  "version": "2.5.0",
+  "version": "2.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-sheets",
-      "version": "2.5.0",
+      "version": "2.6.0",
       "transport": {
         "type": "stdio"
       },

package/src/tools/sheets-extra.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, run, diagnose, toText, toError } from '../../../gogcli-mcp/src/lib.js';
 
 // Convert a CSS-style hex color ("#FFF5D9", "#FD9", "FFF5D9") to the
 // {red, green, blue} 0-1 float triple that Sheets API CellFormat expects.
@@ -440,6 +440,31 @@ export function registerExtraSheetsTools(server: McpServer): void {
     return runOrDiagnose(['sheets', 'links', spreadsheetId, range], { account });
   });
 
+  server.registerTool('gog_sheets_links_set', {
+    description:
+      'Set cell hyperlinks in a Google Sheet. Three modes: (1) single link — pass cell + url (+ optional text); ' +
+      '(2) multi-link cell — pass cell + runsJson, a JSON array of rich-text runs (a run with an empty uri is plain text); ' +
+      '(3) batch — pass cellsJson, a JSON array of {cell,url,text} or {cell,runs:[...]} objects written in one request.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      cell: z.string().optional().describe('Target cell in A1 notation (e.g. Sheet1!B2). Used by single-link and runsJson modes; omit for batch (cellsJson).'),
+      url: z.string().optional().describe('Hyperlink URL for single-link mode'),
+      text: z.string().optional().describe('Display text for single-link mode (defaults to the URL when omitted)'),
+      runsJson: z.string().optional().describe('Multi-link cell: JSON array of runs, e.g. [{"text":"Act A","uri":"https://a"},{"text":" / "},{"text":"Act B","uri":"https://b"}]. A run with an empty uri is plain text.'),
+      cellsJson: z.string().optional().describe('Batch: JSON array of {cell,url,text} or {cell,runs:[{text,uri}]} objects, written in one request.'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, cell, url, text, runsJson, cellsJson, account }) => {
+    const args = ['sheets', 'links', 'set', spreadsheetId];
+    if (cell) args.push(cell);
+    if (url) args.push(url);
+    if (text) args.push(text);
+    if (runsJson) args.push(`--runs-json=${runsJson}`);
+    if (cellsJson) args.push(`--cells-json=${cellsJson}`);
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_sheets_named_ranges_list', {
     description: 'List all named ranges in a spreadsheet.',
     annotations: { readOnlyHint: true },
@@ -683,15 +708,70 @@ export function registerExtraSheetsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_sheets_table_delete', {
-    description: 'Delete a table by its table ID.',
+    description:
+      'Delete a Google Sheets table. WARNING: the underlying `gog`/Sheets behaviour is that deleting a table also DESTROYS every cell value in the table range — not just the table styling/columns. ' +
+      'By default this tool prevents that data loss by emulating the Sheets UI\'s "Convert to range": it reads the table\'s cells (values AND formulas) first, deletes the table, then restores the data into the now-plain range. ' +
+      'Formatting, banding, and data-validation dropdowns are still lost (gog cannot round-trip those yet). ' +
+      'Set keep_data=false to delete the table AND wipe its cell data (the raw destructive behaviour). To preserve everything, snapshot the whole spreadsheet first with gog_sheets_snapshot.',
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       tableId: z.string().describe('Table ID to delete'),
+      keep_data: z.boolean().optional().describe(
+        'Default true: preserve the table\'s cell values and formulas (read → delete → restore), emulating "Convert to range". Set false to delete the table AND its data.',
+      ),
       account: accountParam,
     },
-  }, async ({ spreadsheetId, tableId, account }) => {
-    return runOrDiagnose(['sheets', 'table', 'delete', spreadsheetId, tableId], { account });
+  }, async ({ spreadsheetId, tableId, keep_data = true, account }) => {
+    if (!keep_data) {
+      // Raw destructive delete: removes the table and its cell data. gog ≥ 0.23
+      // requires --discard-data to confirm the cell wipe (--force only skips the
+      // interactive confirmation; it does not authorize the data loss).
+      return runOrDiagnose(['sheets', 'table', 'delete', spreadsheetId, tableId, '--discard-data', '--force'], { account });
+    }
+
+    // keep_data: emulate "Convert to range". Read the full table range with
+    // formulas intact, then delete, then write the data back. If we can't read
+    // the data first, refuse to delete — losing the backup is the whole risk.
+    let range: string;
+    let values: unknown[][];
+    try {
+      // `gog sheets table get` wraps the table under a top-level "table" key.
+      const parsed = JSON.parse(await run(['sheets', 'table', 'get', spreadsheetId, tableId], { account }));
+      range = parsed.table?.a1;
+      if (!range) throw new Error(`could not determine the table's range (no "a1" in table get output) for table ${tableId}`);
+      const read = JSON.parse(await run(['sheets', 'get', spreadsheetId, range, '--render=FORMULA'], { account }));
+      values = read.values ?? [];
+    } catch (err) {
+      return diagnose(err);
+    }
+
+    try {
+      // We have already backed up the cells above, so --discard-data (required
+      // by gog ≥ 0.23) is the intended path here — we re-write the data right
+      // after.
+      await run(['sheets', 'table', 'delete', spreadsheetId, tableId, '--discard-data', '--force'], { account });
+    } catch (err) {
+      // Table not deleted; cell data is untouched.
+      return diagnose(err);
+    }
+
+    if (values.length > 0) {
+      try {
+        await run(['sheets', 'update', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`], { account });
+      } catch (err) {
+        // The table is already gone but the restore write failed. Hand the
+        // read-back data straight back so it can be re-applied manually rather
+        // than silently lost.
+        return toText(
+          `Table ${tableId} was deleted, but restoring its data FAILED — re-apply the values below manually.\n\n` +
+          `Range: ${range}\nValues: ${JSON.stringify(values)}\n\n` +
+          `${toError(err).content[0].text}`,
+        );
+      }
+    }
+
+    return toText(`Deleted table ${tableId} and preserved ${values.length} row(s) of data (values + formulas) in ${range}.`);
   });
 
   // ---- Banding / alternating colors (gog 0.19.0) ----
@@ -798,4 +878,21 @@ export function registerExtraSheetsTools(server: McpServer): void {
     if (all) args.push('--all');
     return runOrDiagnose(args, { account });
   });
+
+  server.registerTool('gog_sheets_snapshot', {
+    description:
+      'Make a backup copy of an entire spreadsheet — a one-call safety snapshot to take BEFORE a risky or destructive edit (table delete, bulk clear, large rewrite). ' +
+      'Returns the new copy\'s file ID and URL; if the edit goes wrong, restore by copying the backup back or sharing it. The copy is independent — later edits to the original do not affect it.',
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID to back up'),
+      name: z.string().describe('Name for the backup copy, e.g. "Budget — backup before table delete"'),
+      parent: z.string().optional().describe('Destination folder ID for the copy (default: same location as the original)'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, name, parent, account }) => {
+    const args = ['drive', 'copy', spreadsheetId, name];
+    if (parent) args.push(`--parent=${parent}`);
+    return runOrDiagnose(args, { account });
+  });
+
 }

package/tests/tools/sheets-extra.test.ts

@@ -8,6 +8,8 @@ vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   return {
     ...actual,
     runOrDiagnose: vi.fn(),
+    run: vi.fn(),
+    diagnose: vi.fn(),
   };
 });
 
@@ -684,6 +686,39 @@ describe('gog_sheets_links', () => {
   });
 });
 
+// gog 0.23.0
+describe('gog_sheets_links_set', () => {
+  it('sets a single-cell hyperlink with cell/url/text positionals', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_links_set')!({ spreadsheetId: 'sid', cell: 'A1', url: 'https://x.com', text: 'Link' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'links', 'set', 'sid', 'A1', 'https://x.com', 'Link'],
+      { account: undefined },
+    );
+  });
+
+  it('sets a multi-link cell with --runs-json', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_links_set')!({ spreadsheetId: 'sid', cell: 'B2', runsJson: '[{"text":"A","uri":"https://a"}]' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'links', 'set', 'sid', 'B2', '--runs-json=[{"text":"A","uri":"https://a"}]'],
+      { account: undefined },
+    );
+  });
+
+  it('sets batch hyperlinks with --cells-json', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_links_set')!({ spreadsheetId: 'sid', cellsJson: '[{"cell":"A1","url":"https://a"}]' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'links', 'set', 'sid', '--cells-json=[{"cell":"A1","url":"https://a"}]'],
+      { account: undefined },
+    );
+  });
+});
+
 // 18. named-ranges list
 describe('gog_sheets_named_ranges_list', () => {
   it('calls runOrDiagnose with correct args', async () => {
@@ -980,11 +1015,82 @@ describe('gog_sheets_table_clear', () => {
 
 // 35. table delete
 describe('gog_sheets_table_delete', () => {
-  it('calls runOrDiagnose with correct args', async () => {
+  it('keep_data=false deletes table (and data) directly with --discard-data --force', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
-    await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'table', 'delete', 'sid', 't1'], { account: undefined });
+    await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1', keep_data: false });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'table', 'delete', 'sid', 't1', '--discard-data', '--force'], { account: undefined });
+    expect(lib.run).not.toHaveBeenCalled();
+  });
+
+  it('keep_data (default) reads formulas, deletes, then restores the data', async () => {
+    vi.mocked(lib.run)
+      .mockResolvedValueOnce('{"table":{"a1":"Sheet1!A1:C2"}}')                     // table get
+      .mockResolvedValueOnce('{"values":[["Name","City","N"],["A","NYC","=1+1"]]}') // get --render=FORMULA
+      .mockResolvedValueOnce('{"deleted":{"tableId":"t1"}}')               // table delete
+      .mockResolvedValueOnce('{"updatedRows":2}');                         // update restore
+    const handlers = setupHandlers();
+    const res = await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1', account: 'a@b.com' });
+    expect(lib.run).toHaveBeenNthCalledWith(1, ['sheets', 'table', 'get', 'sid', 't1'], { account: 'a@b.com' });
+    expect(lib.run).toHaveBeenNthCalledWith(2, ['sheets', 'get', 'sid', 'Sheet1!A1:C2', '--render=FORMULA'], { account: 'a@b.com' });
+    expect(lib.run).toHaveBeenNthCalledWith(3, ['sheets', 'table', 'delete', 'sid', 't1', '--discard-data', '--force'], { account: 'a@b.com' });
+    expect(lib.run).toHaveBeenNthCalledWith(4, ['sheets', 'update', 'sid', 'Sheet1!A1:C2', '--values-json=[["Name","City","N"],["A","NYC","=1+1"]]'], { account: 'a@b.com' });
+    expect(res.content[0].text).toContain('2 row');
+    expect(res.content[0].text).toContain('Sheet1!A1:C2');
+  });
+
+  it('keep_data with an empty table skips the restore write', async () => {
+    vi.mocked(lib.run)
+      .mockResolvedValueOnce('{"table":{"a1":"Sheet1!A1:C1"}}')   // table get
+      .mockResolvedValueOnce('{}')                        // get --render=FORMULA, no values key
+      .mockResolvedValueOnce('{"deleted":{}}');           // table delete
+    const handlers = setupHandlers();
+    const res = await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1' });
+    expect(lib.run).toHaveBeenCalledTimes(3); // no update call
+    expect(res.content[0].text).toContain('0 row');
+  });
+
+  it('aborts without deleting when the table has no a1 range', async () => {
+    vi.mocked(lib.run).mockResolvedValueOnce('{"name":"Repro"}'); // table get, no a1
+    vi.mocked(lib.diagnose).mockResolvedValue(toText('diagnosed'));
+    const handlers = setupHandlers();
+    const res = await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1' });
+    expect(lib.run).toHaveBeenCalledTimes(1); // only the read, no delete
+    expect(res.content[0].text).toBe('diagnosed');
+  });
+
+  it('aborts without deleting when the pre-delete read fails', async () => {
+    vi.mocked(lib.run).mockRejectedValueOnce(new Error('read boom')); // table get throws
+    vi.mocked(lib.diagnose).mockResolvedValue(toText('diagnosed read'));
+    const handlers = setupHandlers();
+    const res = await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1' });
+    expect(lib.run).toHaveBeenCalledTimes(1);
+    expect(res.content[0].text).toBe('diagnosed read');
+  });
+
+  it('diagnoses a delete failure leaving the data intact', async () => {
+    vi.mocked(lib.run)
+      .mockResolvedValueOnce('{"table":{"a1":"Sheet1!A1:C2"}}')
+      .mockResolvedValueOnce('{"values":[["A"]]}')
+      .mockRejectedValueOnce(new Error('delete boom')); // table delete throws
+    vi.mocked(lib.diagnose).mockResolvedValue(toText('diagnosed delete'));
+    const handlers = setupHandlers();
+    const res = await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1' });
+    expect(res.content[0].text).toBe('diagnosed delete');
+  });
+
+  it('surfaces the read-back values when restore fails after deletion', async () => {
+    vi.mocked(lib.run)
+      .mockResolvedValueOnce('{"table":{"a1":"Sheet1!A1:C2"}}')
+      .mockResolvedValueOnce('{"values":[["keepme"]]}')
+      .mockResolvedValueOnce('{"deleted":{}}')
+      .mockRejectedValueOnce(new Error('restore boom')); // update throws
+    const handlers = setupHandlers();
+    const res = await handlers.get('gog_sheets_table_delete')!({ spreadsheetId: 'sid', tableId: 't1' });
+    const text = res.content[0].text;
+    expect(text).toContain('restoring its data FAILED');
+    expect(text).toContain('keepme'); // the data is handed back for manual recovery
+    expect(text).toContain('restore boom');
   });
 });
 
@@ -1146,3 +1252,20 @@ describe('gog_sheets_conditional_format_clear', () => {
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'conditional-format', 'clear', 'sid', '--sheet=Data', '--index=2'], { account: undefined });
   });
 });
+
+// 49. snapshot (backup before destructive edits)
+describe('gog_sheets_snapshot', () => {
+  it('copies the spreadsheet to a named backup', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_snapshot')!({ spreadsheetId: 'sid', name: 'Backup A' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'copy', 'sid', 'Backup A'], { account: undefined });
+  });
+
+  it('includes --parent and forwards account', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_snapshot')!({ spreadsheetId: 'sid', name: 'Backup A', parent: 'folder1', account: 'a@b.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'copy', 'sid', 'Backup A', '--parent=folder1'], { account: 'a@b.com' });
+  });
+});