runline 0.11.6 → 0.13.0

package/dist/plugins/googleSheets/src/index.js

@@ -22,14 +22,57 @@
  *   sheet.deleteDimension   — drop N rows or columns starting at an index
  *   sheet.batchUpdate       — raw passthrough to spreadsheets:batchUpdate
  *
+ *   chart.add / chart.update / chart.delete
+ *   namedRange.add / namedRange.delete
+ *   protectedRange.add / protectedRange.delete
+ *   conditionalFormat.add / conditionalFormat.delete
+ *   dataValidation.set
+ *
  * Features: auto-column-add on update/upsert, multi-row
  * batchUpdate, RAW vs USER_ENTERED value input, appending via
  * values:append or PUT at lastRow+1, keepFirstRow on clear.
  * Filtering is intentionally the caller's job — `read` returns
  * raw rows / objects and callers post-filter.
  */
+import * as t from "typebox";
 import { googleAccessToken } from "../../_shared/googleAuth.js";
+import { Id, JsonValue, NonEmptyString, NonNegativeInteger, PositiveInteger, RawGoogleObject, StringArray, stringEnum, } from "../../_shared/googleSchemas.js";
 const ROW_NUMBER = "row_number";
+const sheetReferenceSchema = t.Union([NonEmptyString, NonNegativeInteger]);
+const cellValueSchema = t.Union([
+    t.String(),
+    t.Number(),
+    t.Boolean(),
+    t.Null(),
+]);
+const objectRowSchema = t.Record(t.String(), JsonValue);
+const rowsSchema = t.Union([
+    t.Array(t.Array(cellValueSchema)),
+    t.Array(objectRowSchema),
+]);
+const valueInputOptionSchema = stringEnum(["RAW", "USER_ENTERED"]);
+const handlingExtraDataSchema = stringEnum([
+    "ignore",
+    "error",
+    "insertInNewColumn",
+]);
+const initialSheetSchema = t.Object({
+    title: NonEmptyString,
+    sheetId: t.Optional(NonNegativeInteger),
+    index: t.Optional(NonNegativeInteger),
+    sheetType: t.Optional(stringEnum(["GRID", "OBJECT", "DATA_SOURCE"])),
+    hidden: t.Optional(t.Boolean()),
+    rightToLeft: t.Optional(t.Boolean()),
+    gridProperties: t.Optional(t.Object({
+        rowCount: t.Optional(PositiveInteger),
+        columnCount: t.Optional(PositiveInteger),
+        frozenRowCount: t.Optional(NonNegativeInteger),
+        frozenColumnCount: t.Optional(NonNegativeInteger),
+        hideGridlines: t.Optional(t.Boolean()),
+        rowGroupControlAfter: t.Optional(t.Boolean()),
+        columnGroupControlAfter: t.Optional(t.Boolean()),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
 // ─── Auth ────────────────────────────────────────────────────────
 async function accessToken(ctx) {
     return googleAccessToken(ctx, "googleSheets", SCOPES);
@@ -60,7 +103,8 @@ async function sheetsRequest(ctx, method, path, body, qs, baseOverride) {
         },
     };
     if (body && Object.keys(body).length > 0) {
-        init.headers["Content-Type"] = "application/json";
+        init.headers["Content-Type"] =
+            "application/json";
         init.body = JSON.stringify(body);
     }
     const res = await fetch(url.toString(), init);
@@ -322,7 +366,13 @@ function a1RangeToGridRange(a1, sheetId) {
     const startRow = parseInt(m[2], 10) - 1;
     const endCol = columnLetterToNumber(m[3]);
     const endRow = parseInt(m[4], 10);
-    return { sheetId, startRowIndex: startRow, endRowIndex: endRow, startColumnIndex: startCol, endColumnIndex: endCol };
+    return {
+        sheetId,
+        startRowIndex: startRow,
+        endRowIndex: endRow,
+        startColumnIndex: startCol,
+        endColumnIndex: endCol,
+    };
 }
 export default function googleSheets(rl) {
     rl.setName("googleSheets");
@@ -408,21 +458,14 @@ export default function googleSheets(rl) {
     });
     // ── Spreadsheet ───────────────────────────────────────
     rl.registerAction("spreadsheet.create", {
+        access: "write",
         description: "Create a new spreadsheet",
-        inputSchema: {
-            title: { type: "string", required: true },
-            sheets: {
-                type: "array",
-                required: false,
-                description: "[{title, hidden?}] — initial sheet tabs",
-            },
-            locale: { type: "string", required: false, description: "e.g. en_US" },
-            autoRecalc: {
-                type: "string",
-                required: false,
-                description: "ON_CHANGE | MINUTE | HOUR",
-            },
-        },
+        inputSchema: t.Object({
+            title: NonEmptyString,
+            sheets: t.Optional(t.Array(initialSheetSchema)),
+            locale: t.Optional(NonEmptyString),
+            autoRecalc: t.Optional(stringEnum(["ON_CHANGE", "MINUTE", "HOUR"])),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const body = {
@@ -441,17 +484,14 @@ export default function googleSheets(rl) {
         },
     });
     rl.registerAction("spreadsheet.get", {
+        access: "read",
         description: "Get spreadsheet metadata (sheets, properties, optional grid data)",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            includeGridData: { type: "boolean", required: false },
-            ranges: {
-                type: "array",
-                required: false,
-                description: "Limit the response to specific A1 ranges",
-            },
-            fields: { type: "string", required: false },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            includeGridData: t.Optional(t.Boolean()),
+            ranges: t.Optional(StringArray),
+            fields: t.Optional(NonEmptyString),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const qs = {};
@@ -465,8 +505,9 @@ export default function googleSheets(rl) {
         },
     });
     rl.registerAction("spreadsheet.delete", {
+        access: "write",
         description: "Delete a spreadsheet (via Drive API — requires drive.file scope)",
-        inputSchema: { spreadsheetId: { type: "string", required: true } },
+        inputSchema: t.Object({ spreadsheetId: Id }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             await sheetsRequest(ctx, "DELETE", `/drive/v3/files/${p.spreadsheetId}`, undefined, undefined, "https://www.googleapis.com");
@@ -475,24 +516,26 @@ export default function googleSheets(rl) {
     });
     // ── Sheet tabs ────────────────────────────────────────
     rl.registerAction("sheet.listTabs", {
+        access: "read",
         description: "List sheet tabs in a spreadsheet",
-        inputSchema: { spreadsheetId: { type: "string", required: true } },
+        inputSchema: t.Object({ spreadsheetId: Id }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return getSheetProperties(ctx, p.spreadsheetId);
         },
     });
     rl.registerAction("sheet.addTab", {
+        access: "write",
         description: "Add a new sheet tab",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            title: { type: "string", required: true },
-            index: { type: "number", required: false, description: "Position within the spreadsheet" },
-            sheetId: { type: "number", required: false, description: "Custom tab ID (non-negative)" },
-            hidden: { type: "boolean", required: false },
-            rightToLeft: { type: "boolean", required: false },
-            tabColor: { type: "string", required: false, description: "Hex RGB (e.g. #0aa55c)" },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            title: NonEmptyString,
+            index: t.Optional(NonNegativeInteger),
+            sheetId: t.Optional(NonNegativeInteger),
+            hidden: t.Optional(t.Boolean()),
+            rightToLeft: t.Optional(t.Boolean()),
+            tabColor: t.Optional(t.String({ pattern: "^#?[0-9a-fA-F]{6}$" })),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const properties = { title: p.title };
@@ -514,15 +557,12 @@ export default function googleSheets(rl) {
         },
     });
     rl.registerAction("sheet.deleteTab", {
+        access: "write",
         description: "Delete a sheet tab",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: {
-                type: "string",
-                required: true,
-                description: "Tab title or numeric sheetId",
-            },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
@@ -534,41 +574,22 @@ export default function googleSheets(rl) {
     });
     // ── Read ──────────────────────────────────────────────
     rl.registerAction("sheet.read", {
+        access: "read",
         description: "Read values from a range. Returns a 2D array by default; set `asObjects=true` to pair rows with a header row and return objects.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            range: {
-                type: "string",
-                required: true,
-                description: "Sheet tab name, or full A1 range (e.g. 'Sheet1!A1:C10')",
-            },
-            asObjects: { type: "boolean", required: false },
-            headerRow: {
-                type: "number",
-                required: false,
-                description: "1-indexed header row (default: 1, used with asObjects)",
-            },
-            dataStartRow: {
-                type: "number",
-                required: false,
-                description: "1-indexed first data row (default: headerRow + 1)",
-            },
-            valueRenderOption: {
-                type: "string",
-                required: false,
-                description: "FORMATTED_VALUE (default) | UNFORMATTED_VALUE | FORMULA",
-            },
-            dateTimeRenderOption: {
-                type: "string",
-                required: false,
-                description: "FORMATTED_STRING (default) | SERIAL_NUMBER",
-            },
-            includeRowNumber: {
-                type: "boolean",
-                required: false,
-                description: "Attach `row_number` to each object (asObjects only)",
-            },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            range: NonEmptyString,
+            asObjects: t.Optional(t.Boolean()),
+            headerRow: t.Optional(PositiveInteger),
+            dataStartRow: t.Optional(PositiveInteger),
+            valueRenderOption: t.Optional(stringEnum([
+                "FORMATTED_VALUE",
+                "UNFORMATTED_VALUE",
+                "FORMULA",
+            ])),
+            dateTimeRenderOption: t.Optional(stringEnum(["FORMATTED_STRING", "SERIAL_NUMBER"])),
+            includeRowNumber: t.Optional(t.Boolean()),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const rows = await getValues(ctx, p.spreadsheetId, p.range, p.valueRenderOption ?? "FORMATTED_VALUE", p.dateTimeRenderOption ?? "FORMATTED_STRING");
@@ -590,40 +611,17 @@ export default function googleSheets(rl) {
     });
     // ── Append ────────────────────────────────────────────
     rl.registerAction("sheet.append", {
+        access: "write",
         description: "Append rows to the bottom. Pass `rows` as arrays (matching columns) or objects (keyed by header names; extra keys become new columns by default).",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: {
-                type: "string",
-                required: true,
-                description: "Tab name or numeric sheetId",
-            },
-            rows: {
-                type: "array",
-                required: true,
-                description: "Array of arrays, or array of objects",
-            },
-            headerRow: {
-                type: "number",
-                required: false,
-                description: "1-indexed header row (default: 1, used when rows are objects)",
-            },
-            valueInputOption: {
-                type: "string",
-                required: false,
-                description: "USER_ENTERED (default) | RAW",
-            },
-            handlingExtraData: {
-                type: "string",
-                required: false,
-                description: "insertInNewColumn (default) | ignore | error",
-            },
-            useAppend: {
-                type: "boolean",
-                required: false,
-                description: "Use values:append (safer w/ formulas but rewrites filters) instead of PUT at lastRow+1",
-            },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            rows: rowsSchema,
+            headerRow: t.Optional(PositiveInteger),
+            valueInputOption: t.Optional(valueInputOptionSchema),
+            handlingExtraData: t.Optional(handlingExtraDataSchema),
+            useAppend: t.Optional(t.Boolean()),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const spreadsheetId = p.spreadsheetId;
@@ -684,39 +682,37 @@ export default function googleSheets(rl) {
     });
     // ── Update ────────────────────────────────────────────
     rl.registerAction("sheet.update", {
+        access: "write",
         description: "Update rows matched by a key column (or by the synthetic 'row_number' field). Rows are objects; undefined/null values are skipped.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            rows: { type: "array", required: true, description: "Array of objects" },
-            matchKey: {
-                type: "string",
-                required: true,
-                description: "Column name to match on, or 'row_number'",
-            },
-            headerRow: { type: "number", required: false, description: "1-indexed (default: 1)" },
-            dataStartRow: { type: "number", required: false },
-            valueInputOption: { type: "string", required: false },
-            handlingExtraData: { type: "string", required: false },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            rows: t.Array(objectRowSchema),
+            matchKey: NonEmptyString,
+            headerRow: t.Optional(PositiveInteger),
+            dataStartRow: t.Optional(PositiveInteger),
+            valueInputOption: t.Optional(valueInputOptionSchema),
+            handlingExtraData: t.Optional(handlingExtraDataSchema),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return runUpdateOrUpsert(ctx, p, false);
         },
     });
     rl.registerAction("sheet.appendOrUpdate", {
+        access: "write",
         description: "Upsert rows. Rows whose match value is found are updated in place; rows with a missing or unknown match value are appended.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            rows: { type: "array", required: true, description: "Array of objects" },
-            matchKey: { type: "string", required: true },
-            headerRow: { type: "number", required: false },
-            dataStartRow: { type: "number", required: false },
-            valueInputOption: { type: "string", required: false },
-            handlingExtraData: { type: "string", required: false },
-            useAppend: { type: "boolean", required: false },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            rows: t.Array(objectRowSchema),
+            matchKey: NonEmptyString,
+            headerRow: t.Optional(PositiveInteger),
+            dataStartRow: t.Optional(PositiveInteger),
+            valueInputOption: t.Optional(valueInputOptionSchema),
+            handlingExtraData: t.Optional(handlingExtraDataSchema),
+            useAppend: t.Optional(t.Boolean()),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return runUpdateOrUpsert(ctx, p, true);
@@ -724,26 +720,72 @@ export default function googleSheets(rl) {
     });
     // ── Clear ─────────────────────────────────────────────
     rl.registerAction("sheet.clear", {
+        access: "write",
         description: "Clear values from a sheet. Modes: wholeSheet (optional keepFirstRow) | rows | columns | range.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            mode: {
-                type: "string",
-                required: false,
-                description: "wholeSheet (default) | rows | columns | range",
-            },
-            startRow: { type: "number", required: false, description: "1-indexed, for mode=rows" },
-            rowCount: { type: "number", required: false, description: "for mode=rows" },
-            startColumn: { type: "string", required: false, description: "A1 letter, for mode=columns" },
-            columnCount: { type: "number", required: false, description: "for mode=columns" },
-            range: { type: "string", required: false, description: "A1 region, for mode=range" },
-            keepFirstRow: {
-                type: "boolean",
-                required: false,
-                description: "mode=wholeSheet only — preserve row 1",
-            },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            mode: t.Optional(stringEnum(["wholeSheet", "rows", "columns", "range"])),
+            startRow: t.Optional(PositiveInteger),
+            rowCount: t.Optional(PositiveInteger),
+            startColumn: t.Optional(t.String({ pattern: "^[A-Za-z]+$" })),
+            columnCount: t.Optional(PositiveInteger),
+            range: t.Optional(NonEmptyString),
+            keepFirstRow: t.Optional(t.Boolean()),
+        }, {
+            additionalProperties: false,
+            oneOf: [
+                {
+                    properties: { mode: { const: "wholeSheet" } },
+                    not: {
+                        anyOf: [
+                            { required: ["startRow"] },
+                            { required: ["rowCount"] },
+                            { required: ["startColumn"] },
+                            { required: ["columnCount"] },
+                            { required: ["range"] },
+                        ],
+                    },
+                },
+                {
+                    properties: { mode: { const: "rows" } },
+                    required: ["mode"],
+                    not: {
+                        anyOf: [
+                            { required: ["startColumn"] },
+                            { required: ["columnCount"] },
+                            { required: ["range"] },
+                            { required: ["keepFirstRow"] },
+                        ],
+                    },
+                },
+                {
+                    properties: { mode: { const: "columns" } },
+                    required: ["mode"],
+                    not: {
+                        anyOf: [
+                            { required: ["startRow"] },
+                            { required: ["rowCount"] },
+                            { required: ["range"] },
+                            { required: ["keepFirstRow"] },
+                        ],
+                    },
+                },
+                {
+                    properties: { mode: { const: "range" } },
+                    required: ["mode", "range"],
+                    not: {
+                        anyOf: [
+                            { required: ["startRow"] },
+                            { required: ["rowCount"] },
+                            { required: ["startColumn"] },
+                            { required: ["columnCount"] },
+                            { required: ["keepFirstRow"] },
+                        ],
+                    },
+                },
+            ],
+        }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetName = typeof p.sheet === "number"
@@ -768,7 +810,9 @@ export default function googleSheets(rl) {
             }
             else if (mode === "range") {
                 const region = String(p.range ?? "");
-                range = region.includes("!") ? `${sheetName}!${region.split("!")[1]}` : `${sheetName}!${region}`;
+                range = region.includes("!")
+                    ? `${sheetName}!${region.split("!")[1]}`
+                    : `${sheetName}!${region}`;
             }
             else {
                 range = sheetName;
@@ -786,18 +830,15 @@ export default function googleSheets(rl) {
     });
     // ── Delete rows/columns ───────────────────────────────
     rl.registerAction("sheet.deleteDimension", {
+        access: "write",
         description: "Delete a range of rows or columns",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            dimension: { type: "string", required: true, description: "ROWS | COLUMNS" },
-            startIndex: {
-                type: "number",
-                required: true,
-                description: "1-indexed (row number) or column letter position",
-            },
-            count: { type: "number", required: false, description: "How many to delete (default: 1)" },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            dimension: stringEnum(["ROWS", "COLUMNS"]),
+            startIndex: PositiveInteger,
+            count: t.Optional(PositiveInteger),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
@@ -820,114 +861,155 @@ export default function googleSheets(rl) {
     });
     // ── Raw batchUpdate ───────────────────────────────────
     rl.registerAction("sheet.batchUpdate", {
+        access: "write",
         description: "Raw passthrough to spreadsheets:batchUpdate for anything this plugin doesn't expose directly (formatting, merges, conditional rules, …).",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            requests: { type: "array", required: true },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            requests: t.Array(RawGoogleObject, { minItems: 1 }),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return spreadsheetBatchUpdate(ctx, p.spreadsheetId, p.requests);
         },
     });
-}
-/**
- * Shared implementation for `sheet.update` and `sheet.appendOrUpdate`.
- * Reads current headers + the key column, decides per row whether
- * it's an update or an append, issues one `values:batchUpdate` for
- * the updates, and (in upsert mode) falls through to the append
- * path for the rest.
- */
-async function runUpdateOrUpsert(ctx, p, upsert) {
-    const spreadsheetId = p.spreadsheetId;
-    const sheetIdOrName = p.sheet;
-    const rows = p.rows;
-    if (!Array.isArray(rows) || rows.length === 0) {
-        return { updated: 0, appended: 0 };
-    }
-    const matchKey = p.matchKey;
-    if (!matchKey)
-        throw new Error("googleSheets: matchKey is required");
-    const valueInputOption = p.valueInputOption ?? "USER_ENTERED";
-    const allProps = await getSheetProperties(ctx, spreadsheetId);
-    const prop = allProps.find((s) => s.title === sheetIdOrName || String(s.sheetId) === String(sheetIdOrName));
-    if (!prop)
-        throw new Error(`googleSheets: sheet "${sheetIdOrName}" not found`);
-    const sheetName = prop.title;
-    const sheetId = prop.sheetId;
-    const headerRowIdx = Math.max(1, p.headerRow ?? 1) - 1;
-    const dataStartRowIdx = Math.max(headerRowIdx + 1, (p.dataStartRow ?? headerRowIdx + 2) - 1);
-    const handlingExtraData = p.handlingExtraData ?? "insertInNewColumn";
-    // Headers come from FORMATTED_VALUE (cosmetic strings). The match
-    // column needs UNFORMATTED_VALUE so "1,234" in input matches 1234
-    // on the sheet (issue a second fetch with UNFORMATTED_VALUE).
-    const sheetData = await getValues(ctx, spreadsheetId, sheetName, "FORMATTED_VALUE");
-    let headers = sheetData[headerRowIdx] ?? [];
-    let keyColumnValues = [];
-    if (matchKey !== ROW_NUMBER) {
-        const idx = headers.indexOf(matchKey);
-        if (idx === -1) {
-            if (!upsert)
-                throw new Error(`googleSheets: match column "${matchKey}" not found`);
+    /**
+     * Shared implementation for `sheet.update` and `sheet.appendOrUpdate`.
+     * Reads current headers + the key column, decides per row whether
+     * it's an update or an append, issues one `values:batchUpdate` for
+     * the updates, and (in upsert mode) falls through to the append
+     * path for the rest.
+     */
+    async function runUpdateOrUpsert(ctx, p, upsert) {
+        const spreadsheetId = p.spreadsheetId;
+        const sheetIdOrName = p.sheet;
+        const rows = p.rows;
+        if (!Array.isArray(rows) || rows.length === 0) {
+            return { updated: 0, appended: 0 };
         }
-        else {
-            const unformatted = await getValues(ctx, spreadsheetId, sheetName, "UNFORMATTED_VALUE");
-            keyColumnValues = unformatted.slice(dataStartRowIdx).map((r) => String(r[idx] ?? ""));
+        const matchKey = p.matchKey;
+        if (!matchKey)
+            throw new Error("googleSheets: matchKey is required");
+        const valueInputOption = p.valueInputOption ?? "USER_ENTERED";
+        const allProps = await getSheetProperties(ctx, spreadsheetId);
+        const prop = allProps.find((s) => s.title === sheetIdOrName ||
+            String(s.sheetId) === String(sheetIdOrName));
+        if (!prop)
+            throw new Error(`googleSheets: sheet "${sheetIdOrName}" not found`);
+        const sheetName = prop.title;
+        const sheetId = prop.sheetId;
+        const headerRowIdx = Math.max(1, p.headerRow ?? 1) - 1;
+        const dataStartRowIdx = Math.max(headerRowIdx + 1, (p.dataStartRow ?? headerRowIdx + 2) - 1);
+        const handlingExtraData = p.handlingExtraData ??
+            "insertInNewColumn";
+        // Headers come from FORMATTED_VALUE (cosmetic strings). The match
+        // column needs UNFORMATTED_VALUE so "1,234" in input matches 1234
+        // on the sheet (issue a second fetch with UNFORMATTED_VALUE).
+        const sheetData = await getValues(ctx, spreadsheetId, sheetName, "FORMATTED_VALUE");
+        let headers = sheetData[headerRowIdx] ?? [];
+        let keyColumnValues = [];
+        if (matchKey !== ROW_NUMBER) {
+            const idx = headers.indexOf(matchKey);
+            if (idx === -1) {
+                if (!upsert)
+                    throw new Error(`googleSheets: match column "${matchKey}" not found`);
+            }
+            else {
+                const unformatted = await getValues(ctx, spreadsheetId, sheetName, "UNFORMATTED_VALUE");
+                keyColumnValues = unformatted
+                    .slice(dataStartRowIdx)
+                    .map((r) => String(r[idx] ?? ""));
+            }
         }
-    }
-    const prepared = prepareUpdateOrUpsert(rows, headers, keyColumnValues, dataStartRowIdx, matchKey, { upsert, handlingExtraData });
-    // If we added new columns, extend the header row on the sheet first.
-    if (prepared.newColumns.length > 0) {
-        headers = [...headers, ...prepared.newColumns];
-        await sheetsRequest(ctx, "PUT", `/v4/spreadsheets/${spreadsheetId}/values/${encodeA1(`${sheetName}!${headerRowIdx + 1}:${headerRowIdx + 1}`)}`, {
-            range: `${sheetName}!${headerRowIdx + 1}:${headerRowIdx + 1}`,
-            values: [headers],
-        }, { valueInputOption });
-    }
-    // Qualify update ranges with the sheet name (prepareUpdateOrUpsert
-    // returned bare A1 cells like "C5").
-    const updateData = prepared.updateData.map((d) => ({
-        range: `${sheetName}!${d.range}`,
-        values: d.values,
-    }));
-    if (updateData.length > 0) {
-        await batchValuesUpdate(ctx, spreadsheetId, updateData, valueInputOption);
-    }
-    if (upsert && prepared.appendData.length > 0) {
-        const values = objectsToRows(prepared.appendData, headers);
-        if (p.useAppend) {
-            await sheetsRequest(ctx, "POST", `/v4/spreadsheets/${spreadsheetId}/values/${encodeA1(sheetName)}:append`, { range: sheetName, values }, { valueInputOption, insertDataOption: "INSERT_ROWS" });
+        const prepared = prepareUpdateOrUpsert(rows, headers, keyColumnValues, dataStartRowIdx, matchKey, { upsert, handlingExtraData });
+        // If we added new columns, extend the header row on the sheet first.
+        if (prepared.newColumns.length > 0) {
+            headers = [...headers, ...prepared.newColumns];
+            await sheetsRequest(ctx, "PUT", `/v4/spreadsheets/${spreadsheetId}/values/${encodeA1(`${sheetName}!${headerRowIdx + 1}:${headerRowIdx + 1}`)}`, {
+                range: `${sheetName}!${headerRowIdx + 1}:${headerRowIdx + 1}`,
+                values: [headers],
+            }, { valueInputOption });
         }
-        else {
-            const lastRow = sheetData.length;
-            await appendEmptyRow(ctx, spreadsheetId, sheetId);
-            const targetRange = `${sheetName}!${lastRow + 1}:${lastRow + values.length}`;
-            await sheetsRequest(ctx, "PUT", `/v4/spreadsheets/${spreadsheetId}/values/${encodeA1(targetRange)}`, { range: targetRange, values }, { valueInputOption });
+        // Qualify update ranges with the sheet name (prepareUpdateOrUpsert
+        // returned bare A1 cells like "C5").
+        const updateData = prepared.updateData.map((d) => ({
+            range: `${sheetName}!${d.range}`,
+            values: d.values,
+        }));
+        if (updateData.length > 0) {
+            await batchValuesUpdate(ctx, spreadsheetId, updateData, valueInputOption);
         }
+        if (upsert && prepared.appendData.length > 0) {
+            const values = objectsToRows(prepared.appendData, headers);
+            if (p.useAppend) {
+                await sheetsRequest(ctx, "POST", `/v4/spreadsheets/${spreadsheetId}/values/${encodeA1(sheetName)}:append`, { range: sheetName, values }, { valueInputOption, insertDataOption: "INSERT_ROWS" });
+            }
+            else {
+                const lastRow = sheetData.length;
+                await appendEmptyRow(ctx, spreadsheetId, sheetId);
+                const targetRange = `${sheetName}!${lastRow + 1}:${lastRow + values.length}`;
+                await sheetsRequest(ctx, "PUT", `/v4/spreadsheets/${spreadsheetId}/values/${encodeA1(targetRange)}`, { range: targetRange, values }, { valueInputOption });
+            }
+        }
+        return {
+            updated: prepared.updateData.length,
+            appended: prepared.appendData.length,
+            newColumns: prepared.newColumns,
+        };
     }
-    return {
-        updated: prepared.updateData.length,
-        appended: prepared.appendData.length,
-        newColumns: prepared.newColumns,
-    };
     // ─── Charts ─────────────────────────────────────────────────────
     rl.registerAction("chart.add", {
+        access: "write",
         description: "Embed a chart on a sheet. Minimal signature: type ('COLUMN'|'BAR'|'LINE'|'AREA'|'PIE'|'SCATTER'|'COMBO'), data source (sheet name + A1 range), and target anchor cell. For full control pass a raw `chartSpec` object instead.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            title: { type: "string", required: false },
-            type: { type: "string", required: false, description: "Basic chart type. Default COLUMN. Ignored when `chartSpec` is provided." },
-            sourceSheet: { type: "string", required: false, description: "Sheet name holding the source range. Ignored when `chartSpec` is provided." },
-            sourceRange: { type: "string", required: false, description: "A1 range on `sourceSheet`, e.g. 'A1:D20'. Ignored when `chartSpec` is provided." },
-            legendPosition: { type: "string", required: false, description: "BOTTOM_LEGEND | TOP_LEGEND | RIGHT_LEGEND | LEFT_LEGEND | NO_LEGEND. Default BOTTOM_LEGEND." },
-            stackedType: { type: "string", required: false, description: "STACKED | PERCENT_STACKED — for COLUMN/BAR/AREA." },
-            anchorSheet: { type: "string", required: true, description: "Sheet to place the chart on." },
-            anchorRow: { type: "number", required: false, default: 0 },
-            anchorColumn: { type: "number", required: false, default: 0 },
-            widthPx: { type: "number", required: false, default: 600 },
-            heightPx: { type: "number", required: false, default: 371 },
-            chartSpec: { type: "object", required: false, description: "Raw ChartSpec object; bypasses the simple type+source builder." },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            title: t.Optional(t.String()),
+            type: t.Optional(stringEnum([
+                "COLUMN",
+                "BAR",
+                "LINE",
+                "AREA",
+                "PIE",
+                "SCATTER",
+                "COMBO",
+            ])),
+            sourceSheet: t.Optional(sheetReferenceSchema),
+            sourceRange: t.Optional(NonEmptyString),
+            legendPosition: t.Optional(stringEnum([
+                "BOTTOM_LEGEND",
+                "TOP_LEGEND",
+                "RIGHT_LEGEND",
+                "LEFT_LEGEND",
+                "NO_LEGEND",
+            ])),
+            stackedType: t.Optional(stringEnum(["STACKED", "PERCENT_STACKED"])),
+            anchorSheet: sheetReferenceSchema,
+            anchorRow: t.Optional(NonNegativeInteger),
+            anchorColumn: t.Optional(NonNegativeInteger),
+            widthPx: t.Optional(PositiveInteger),
+            heightPx: t.Optional(PositiveInteger),
+            chartSpec: t.Optional(RawGoogleObject),
+        }, {
+            additionalProperties: false,
+            oneOf: [
+                {
+                    required: ["chartSpec"],
+                    not: {
+                        anyOf: [
+                            { required: ["title"] },
+                            { required: ["type"] },
+                            { required: ["sourceSheet"] },
+                            { required: ["sourceRange"] },
+                            { required: ["legendPosition"] },
+                            { required: ["stackedType"] },
+                        ],
+                    },
+                },
+                {
+                    required: ["sourceSheet", "sourceRange"],
+                    not: { required: ["chartSpec"] },
+                },
+            ],
+        }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const spreadsheetId = p.spreadsheetId;
@@ -946,14 +1028,41 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
                         legendPosition: p.legendPosition ?? "BOTTOM_LEGEND",
                         stackedType: p.stackedType,
                         headerCount: 1,
-                        domains: [{ domain: { sourceRange: { sources: [{
-                                                sheetId: grid.sheetId, startRowIndex: grid.startRowIndex, endRowIndex: grid.endRowIndex,
-                                                startColumnIndex: grid.startColumnIndex, endColumnIndex: grid.startColumnIndex + 1,
-                                            }] } } }],
-                        series: [{ series: { sourceRange: { sources: [{
-                                                sheetId: grid.sheetId, startRowIndex: grid.startRowIndex, endRowIndex: grid.endRowIndex,
-                                                startColumnIndex: grid.startColumnIndex + 1, endColumnIndex: grid.endColumnIndex,
-                                            }] } }, targetAxis: "LEFT_AXIS" }],
+                        domains: [
+                            {
+                                domain: {
+                                    sourceRange: {
+                                        sources: [
+                                            {
+                                                sheetId: grid.sheetId,
+                                                startRowIndex: grid.startRowIndex,
+                                                endRowIndex: grid.endRowIndex,
+                                                startColumnIndex: grid.startColumnIndex,
+                                                endColumnIndex: grid.startColumnIndex + 1,
+                                            },
+                                        ],
+                                    },
+                                },
+                            },
+                        ],
+                        series: [
+                            {
+                                series: {
+                                    sourceRange: {
+                                        sources: [
+                                            {
+                                                sheetId: grid.sheetId,
+                                                startRowIndex: grid.startRowIndex,
+                                                endRowIndex: grid.endRowIndex,
+                                                startColumnIndex: grid.startColumnIndex + 1,
+                                                endColumnIndex: grid.endColumnIndex,
+                                            },
+                                        ],
+                                    },
+                                },
+                                targetAxis: "LEFT_AXIS",
+                            },
+                        ],
                     },
                 };
             }
@@ -963,7 +1072,11 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
                         spec,
                         position: {
                             overlayPosition: {
-                                anchorCell: { sheetId: anchorSheetId, rowIndex: p.anchorRow ?? 0, columnIndex: p.anchorColumn ?? 0 },
+                                anchorCell: {
+                                    sheetId: anchorSheetId,
+                                    rowIndex: p.anchorRow ?? 0,
+                                    columnIndex: p.anchorColumn ?? 0,
+                                },
                                 widthPixels: p.widthPx ?? 600,
                                 heightPixels: p.heightPx ?? 371,
                             },
@@ -975,13 +1088,14 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
         },
     });
     rl.registerAction("chart.update", {
+        access: "write",
         description: "Update an existing chart's spec by chartId.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            chartId: { type: "number", required: true },
-            chartSpec: { type: "object", required: true },
-            fields: { type: "string", required: false, default: "*" },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            chartId: NonNegativeInteger,
+            chartSpec: RawGoogleObject,
+            fields: t.Optional(NonEmptyString),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [
@@ -996,11 +1110,12 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
         },
     });
     rl.registerAction("chart.delete", {
+        access: "write",
         description: "Delete a chart by its embedded-object id.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            chartId: { type: "number", required: true },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            chartId: NonNegativeInteger,
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [
@@ -1010,13 +1125,14 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
     });
     // ─── Named ranges ───────────────────────────────────────────────
     rl.registerAction("namedRange.add", {
+        access: "write",
         description: "Create a named range on a sheet (so formulas can reference it by name).",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            name: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            range: { type: "string", required: true, description: "A1 range on `sheet`, e.g. 'A1:D20'." },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            name: NonEmptyString,
+            sheet: sheetReferenceSchema,
+            range: NonEmptyString,
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
@@ -1027,11 +1143,12 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
         },
     });
     rl.registerAction("namedRange.delete", {
+        access: "write",
         description: "Delete a named range by its id.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            namedRangeId: { type: "string", required: true },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            namedRangeId: Id,
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [
@@ -1041,19 +1158,23 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
     });
     // ─── Protected ranges ───────────────────────────────────────────
     rl.registerAction("protectedRange.add", {
+        access: "write",
         description: "Protect a range from edits. Pass `editorEmails` to restrict who can still edit; without it, only the sheet owner can edit.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            range: { type: "string", required: false, description: "A1 range. Omit to protect the whole sheet." },
-            description: { type: "string", required: false },
-            warningOnly: { type: "boolean", required: false, description: "When true, edits are allowed but show a warning." },
-            editorEmails: { type: "array", required: false },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            range: t.Optional(NonEmptyString),
+            description: t.Optional(t.String()),
+            warningOnly: t.Optional(t.Boolean()),
+            editorEmails: t.Optional(t.Array(NonEmptyString)),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
-            const protectedRange = { description: p.description, warningOnly: p.warningOnly };
+            const protectedRange = {
+                description: p.description,
+                warningOnly: p.warningOnly,
+            };
             if (p.range)
                 protectedRange.range = a1RangeToGridRange(p.range, sheetId);
             else
@@ -1067,11 +1188,12 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
         },
     });
     rl.registerAction("protectedRange.delete", {
+        access: "write",
         description: "Delete a protected range by its id.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            protectedRangeId: { type: "number", required: true },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            protectedRangeId: NonNegativeInteger,
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [
@@ -1081,22 +1203,39 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
     });
     // ─── Conditional formatting ─────────────────────────────────────
     rl.registerAction("conditionalFormat.add", {
+        access: "write",
         description: "Add a single-condition conditional-format rule. For complex rules pass a raw `rule` object instead of the simple builder.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            range: { type: "string", required: true },
-            condition: {
-                type: "object",
-                required: false,
-                description: "BooleanCondition, e.g. { type: 'NUMBER_GREATER', values: [{ userEnteredValue: '100' }] }.",
-            },
-            backgroundColorHex: { type: "string", required: false },
-            foregroundColorHex: { type: "string", required: false },
-            bold: { type: "boolean", required: false },
-            italic: { type: "boolean", required: false },
-            rule: { type: "object", required: false, description: "Raw ConditionalFormatRule; bypasses the simple builder." },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            range: NonEmptyString,
+            condition: t.Optional(RawGoogleObject),
+            backgroundColorHex: t.Optional(t.String({ pattern: "^#?[0-9a-fA-F]{6}$" })),
+            foregroundColorHex: t.Optional(t.String({ pattern: "^#?[0-9a-fA-F]{6}$" })),
+            bold: t.Optional(t.Boolean()),
+            italic: t.Optional(t.Boolean()),
+            rule: t.Optional(RawGoogleObject),
+        }, {
+            additionalProperties: false,
+            oneOf: [
+                {
+                    required: ["rule"],
+                    not: {
+                        anyOf: [
+                            { required: ["condition"] },
+                            { required: ["backgroundColorHex"] },
+                            { required: ["foregroundColorHex"] },
+                            { required: ["bold"] },
+                            { required: ["italic"] },
+                        ],
+                    },
+                },
+                {
+                    required: ["condition"],
+                    not: { required: ["rule"] },
+                },
+            ],
+        }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
@@ -1118,18 +1257,24 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
                         ts.italic = p.italic;
                     fmt.textFormat = ts;
                 }
-                rule = { ranges: [grid], booleanRule: { condition: p.condition, format: fmt } };
+                rule = {
+                    ranges: [grid],
+                    booleanRule: { condition: p.condition, format: fmt },
+                };
             }
-            return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [{ addConditionalFormatRule: { rule, index: 0 } }]);
+            return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [
+                { addConditionalFormatRule: { rule, index: 0 } },
+            ]);
         },
     });
     rl.registerAction("conditionalFormat.delete", {
+        access: "write",
         description: "Delete a conditional-format rule by its index within the sheet's rule list.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            index: { type: "number", required: true },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            index: NonNegativeInteger,
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
@@ -1140,18 +1285,54 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
     });
     // ─── Data validation ────────────────────────────────────────────
     rl.registerAction("dataValidation.set", {
+        access: "write",
         description: "Apply a data-validation rule to a range. Pass either `condition` (BooleanCondition) or `oneOfList` (array of values for ONE_OF_LIST). Use `clear: true` to remove validation.",
-        inputSchema: {
-            spreadsheetId: { type: "string", required: true },
-            sheet: { type: "string", required: true },
-            range: { type: "string", required: true },
-            condition: { type: "object", required: false },
-            oneOfList: { type: "array", required: false },
-            showCustomUi: { type: "boolean", required: false, default: true },
-            strict: { type: "boolean", required: false, default: true },
-            inputMessage: { type: "string", required: false },
-            clear: { type: "boolean", required: false },
-        },
+        inputSchema: t.Object({
+            spreadsheetId: Id,
+            sheet: sheetReferenceSchema,
+            range: NonEmptyString,
+            condition: t.Optional(RawGoogleObject),
+            oneOfList: t.Optional(t.Array(JsonValue, { minItems: 1 })),
+            showCustomUi: t.Optional(t.Boolean()),
+            strict: t.Optional(t.Boolean()),
+            inputMessage: t.Optional(t.String()),
+            clear: t.Optional(t.Boolean()),
+        }, {
+            additionalProperties: false,
+            oneOf: [
+                {
+                    required: ["condition"],
+                    not: {
+                        anyOf: [
+                            { required: ["oneOfList"] },
+                            { required: ["clear"] },
+                        ],
+                    },
+                },
+                {
+                    required: ["oneOfList"],
+                    not: {
+                        anyOf: [
+                            { required: ["condition"] },
+                            { required: ["clear"] },
+                        ],
+                    },
+                },
+                {
+                    properties: { clear: { const: true } },
+                    required: ["clear"],
+                    not: {
+                        anyOf: [
+                            { required: ["condition"] },
+                            { required: ["oneOfList"] },
+                            { required: ["showCustomUi"] },
+                            { required: ["strict"] },
+                            { required: ["inputMessage"] },
+                        ],
+                    },
+                },
+            ],
+        }),
         async execute(input, ctx) {
             const p = (input ?? {});
             const sheetId = await resolveSheetId(ctx, p.spreadsheetId, p.sheet);
@@ -1162,12 +1343,19 @@ async function runUpdateOrUpsert(ctx, p, upsert) {
                 if (!cond && Array.isArray(p.oneOfList)) {
                     cond = {
                         type: "ONE_OF_LIST",
-                        values: p.oneOfList.map((v) => ({ userEnteredValue: String(v) })),
+                        values: p.oneOfList.map((v) => ({
+                            userEnteredValue: String(v),
+                        })),
                     };
                 }
                 if (!cond)
                     throw new Error("googleSheets.dataValidation.set: pass condition or oneOfList, or set clear=true");
-                rule = { condition: cond, strict: p.strict ?? true, showCustomUi: p.showCustomUi ?? true, inputMessage: p.inputMessage };
+                rule = {
+                    condition: cond,
+                    strict: p.strict ?? true,
+                    showCustomUi: p.showCustomUi ?? true,
+                    inputMessage: p.inputMessage,
+                };
             }
             return spreadsheetBatchUpdate(ctx, p.spreadsheetId, [
                 { setDataValidation: { range: grid, rule: rule ?? undefined } },