@lanes-sh/link 0.1.0

package/src/providers/google/shared/setup.ts

@@ -0,0 +1,80 @@
+import { GOOGLE_APP } from './oauth.ts';
+
+/**
+ * The walkthrough every Google provider prints before asking for anything.
+ *
+ * Google requires a pre-registered OAuth client — even for Google's own MCP
+ * servers. That is their policy and no architecture avoids it, but it does not
+ * follow that *you* have to be the one to register it: since ADR-028 the client
+ * Lanes operates is the default, and this walkthrough is what `--own-client`
+ * opts into. It stays complete, because the people who need it — an
+ * organisation that forbids third-party clients, a Workspace "Internal" app —
+ * need all of it.
+ *
+ * Gmail and Drive share the `google` app, which is why `oauth_apps` exists:
+ * every connection of a vendor authorises against the same registered client,
+ * and declaring that entry is also how a profile says it has one of its own.
+ */
+export const googleSetup = (
+  product: string,
+  scopes: readonly string[],
+  options: { preview?: boolean; apis?: readonly string[] } = {},
+) => {
+  // Which APIs to enable is per product, not global: telling someone connecting
+  // Gmail to enable Sheets is advice to grant more than they asked for. Sheets
+  // and Docs name Drive as well, because their `identity` block reads
+  // `drive/v3/about` — with the Drive API disabled, connecting succeeds and then
+  // fails to label the connection.
+  const apis =
+    options.apis ??
+    (options.preview
+      ? [
+          'gmail.googleapis.com',
+          'gmailmcp.googleapis.com',
+          'drive.googleapis.com',
+          'drivemcp.googleapis.com',
+        ]
+      : ['gmail.googleapis.com', 'drive.googleapis.com']);
+
+  return {
+    summary: `${product} signs in with Google. By default it authorises against the OAuth client Lanes operates, so there is nothing to register and no client secret on this machine — the code is exchanged for a token by the Lanes API, which holds that secret. Pass --own-client to register a client of your own instead; the steps below are that path, asked once per profile and then covering every Google account you connect.`,
+    docs: 'docs/detailed/setup/google.md',
+    docs_url: 'https://console.cloud.google.com/auth',
+    steps: [
+      ...(options.preview
+        ? [
+            'ENROL IN THE WORKSPACE DEVELOPER PREVIEW FIRST — https://developers.google.com/workspace/preview\n       This provider proxies Google\'s MCP server, which is gated behind it. Without enrolment everything below still succeeds — consent is granted, the tool list is returned — and then every single call answers "The caller does not have permission". Enrolment needs a Google Workspace account; a personal @gmail.com cannot enrol, and should use the plain "' +
+              product.toLowerCase() +
+              '" provider instead, which talks to the REST API and has no gate.',
+          ]
+        : []),
+      'Create or pick a project at https://console.cloud.google.com',
+      `Enable the APIs:\n       gcloud services enable ${apis.join(' ')} --project=YOUR_PROJECT${
+        options.preview
+          ? '\n       Note there are TWO per product for the MCP path: the service itself and its separate MCP API. Enabling only one produces a 403 whose explanation is buried in the response body.'
+          : ''
+      }\n       Without gcloud: APIs & Services → Library, and search for each by name.`,
+      'The rest is under Google Auth Platform — https://console.cloud.google.com/auth — in this order:',
+      '  BRANDING — app name and a support email. Seen by nobody but you.',
+      '  AUDIENCE — User type: EXTERNAL (even with a Workspace domain: "Internal" admits only that one domain, so a mix of personal and Workspace accounts needs External). Add every account you will connect under "Test users". LEAVE the status as "Testing".',
+      `  DATA ACCESS — where scopes live now. Add:\n       ${scopes.join('\n       ')}\n       Note drive.file is filed under "sensitive" rather than "restricted", so it appears in a different section of that page.`,
+      '  CLIENTS — Create OAuth client → type: DESKTOP APP. Google\'s docs say "Web application" with a redirect URI for Claude or Antigravity, because they assume the agent host runs the OAuth. Here the CLI does, on a loopback port — which is also why this stays Desktop even when the server runs on Cloud Run.',
+      'Copy the client ID and secret — you are asked for them next.',
+      'Not publishing is deliberate: these are restricted scopes, and publishing them means Google verification with a CASA assessment taking months. Testing needs none. The cost is that refresh tokens expire after 7 days, so expect to re-run "lanes link connect" weekly — "lanes link doctor" says which are stale.',
+    ],
+    prompts: [
+      {
+        key: 'client_id',
+        label: 'Google OAuth client ID',
+        secret: false,
+        credential_ref: `${GOOGLE_APP}/client_id`,
+      },
+      {
+        key: 'client_secret',
+        label: 'Google OAuth client secret',
+        secret: true,
+        credential_ref: `${GOOGLE_APP}/client_secret`,
+      },
+    ],
+  };
+};

package/src/providers/google/sheets/hints.ts

@@ -0,0 +1,45 @@
+/**
+ * Where the Sheets surface stops, and what continues it.
+ *
+ * Two gaps, both of which read as missing features rather than as boundaries.
+ *
+ * There is no `spreadsheets.create` here and there will not be: its request
+ * body is a whole `Spreadsheet`, which generates a 1,133 KB input schema
+ * against a 64 KB budget — the argument is in `specs/vendor.ts`. Creating the
+ * file belongs to Drive. Nothing in a tool list says so, and "sheet has no
+ * create" is the reasonable conclusion from reading one.
+ *
+ * And `batchUpdate` is the whole structural-edit surface behind a single
+ * `requests` argument that has to stay opaque, because inlining Google's
+ * `Request` union costs 2,469 KB. Opaque means the tool cannot enumerate what
+ * it does, so the common cases are named here instead.
+ */
+export const SHEETS_HINTS: Record<string, string> = {
+  'spreadsheets.batchUpdate': [
+    'This is the structural-edit surface: adding, renaming, reordering, and deleting tabs,',
+    'plus formatting, frozen rows, filters, and charts.',
+    'The `requests` array takes Google\'s `Request` objects — `addSheet` to create a tab,',
+    '`updateSheetProperties` to rename one, `deleteSheet` to remove it,',
+    '`repeatCell` to format a range. Its structure is omitted from this schema because',
+    'inlining the full union costs megabytes; the shapes are at',
+    'https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request.',
+    'To change cell *values* rather than structure, use the `values_*` tools instead.',
+    'To create a whole new spreadsheet file, use `drive_files_create` with',
+    '`mimeType: "application/vnd.google-apps.spreadsheet"` — there is no create tool here.',
+  ].join(' '),
+
+  // On the read too, because "how do I make one" is asked while looking at the
+  // tool that reads one, and this is the only other tool named `spreadsheets.*`
+  // that an agent scanning the list is likely to open.
+  'spreadsheets.get': [
+    'Reads an existing spreadsheet. To create one, use `drive_files_create` with',
+    '`mimeType: "application/vnd.google-apps.spreadsheet"`, then write into it with the',
+    '`values_*` tools — this provider edits spreadsheets but does not create the file.',
+  ].join(' '),
+
+  'spreadsheets.sheets.copyTo': [
+    'Copies one tab into a *different* spreadsheet. To duplicate a tab within the same',
+    'file use `batchUpdate` with a `duplicateSheet` request, and to copy the whole file',
+    'use `drive_files_copy`.',
+  ].join(' '),
+};

package/src/providers/google/sheets/index.ts

@@ -0,0 +1,70 @@
+import { defineProvider } from '#connectivity';
+import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { SHEETS_HINTS } from './hints.ts';
+import { SHEETS_REDACT } from './redact.ts';
+
+/**
+ * Sheets, because Drive cannot edit a spreadsheet.
+ *
+ * Drive holds the file and exports a rendering of it; nothing in Drive writes a
+ * cell. The nearest thing would be `files.update` with media, which replaces the
+ * whole file through import conversion and discards formulas, formatting, tabs,
+ * and comments in the process. Cell-level editing exists in exactly one place.
+ *
+ * Note the `base_url`: Sheets carries its version in the path
+ * (`/v4/spreadsheets/...`), where Drive carries it in the host. Copying Drive's
+ * shape here yields `/v4/v4/...` and a 404 on every call.
+ */
+
+/**
+ * Editing a file someone already has, and why that costs a broad scope.
+ *
+ * `drive.readonly` and `drive.file` are held already and between them nearly
+ * cover this: reads of any spreadsheet accept `drive.readonly`, and every Sheets
+ * write accepts `drive.file`. But `drive.file` means *files this app created* —
+ * its other half, files the user picks, arrives through the Google Picker, and
+ * there is no picker on an MCP endpoint. So under those two scopes an agent can
+ * build a spreadsheet and maintain it forever, and cannot touch the one someone
+ * made in the browser last week. That second case is the request.
+ *
+ * `spreadsheets` is the only scope that reaches it, and it is the `gmail.modify`
+ * argument again, arriving at the same answer for the same reason: there is no
+ * narrower grant that does the job, so the choice is this or the feature. It is
+ * marked broad in `../shared/scopes.ts` and should stay marked. What bounds it is
+ * what bounds Gmail — the token is wide, the tool surface is eight operations,
+ * and `lanes link policy deny` narrows that further.
+ *
+ * `drive.readonly` stays alongside it. `spreadsheets` alone cannot answer
+ * `drive/v3/about`, which is how the connection gets labelled with an address.
+ */
+const SHEETS_SCOPES = [
+  'https://www.googleapis.com/auth/drive.readonly',
+  'https://www.googleapis.com/auth/drive.file',
+  'https://www.googleapis.com/auth/spreadsheets',
+];
+
+export const sheets = defineProvider({
+  id: 'sheets',
+  name: 'Google Sheets',
+  description:
+    'Read and edit spreadsheet cells — ranges, appends, and structural changes like tabs, formatting, and frozen rows — via the Sheets REST API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://sheets.googleapis.com',
+    openapi: specPath('sheets.v4.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: SHEETS_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  identity: DRIVE_IDENTITY,
+  setup: googleSetup('Sheets', SHEETS_SCOPES, {
+    apis: ['sheets.googleapis.com', 'drive.googleapis.com'],
+  }),
+  redact: SHEETS_REDACT,
+  hints: SHEETS_HINTS,
+});

package/src/providers/google/sheets/redact.ts

@@ -0,0 +1,45 @@
+/**
+ * Identifiers and shape, never contents.
+ *
+ * The split is cleaner here than it was for mail. `values` and `data` hold the
+ * cells themselves, and `requests` holds the text of a structural edit — that is
+ * the spreadsheet, and withholding it is the whole point of the default. What is
+ * kept is where and how: which file, which range, and which write mode, without
+ * which a write log records that a spreadsheet changed and not where.
+ *
+ * Reads are listed too, unlike Gmail's block. Gmail withholds its reads because
+ * `q` is a search query and the question is the sensitive part; a Sheets read
+ * carries no query, only a file id and an A1 range, so there is nothing there to
+ * protect. A range does embed a tab name, which is the user's word — that is the
+ * one judgement call, made in favour of an audit log that can distinguish
+ * reading a cell from reading the sheet.
+ *
+ * The two writes take `pathRange`, not `range`. A `ValueRange` body carries a
+ * `range` of its own, so the generator prefixes both with where they came from,
+ * and the plain name matches neither. This block said `range` until the
+ * argument-name check in `cli/tools.test.ts` was written — which meant the one
+ * thing these entries exist to record, *where* the sheet was written, was the
+ * one thing being withheld. The reads keep the plain name because they have no
+ * body to collide with.
+ */
+export const SHEETS_REDACT: Record<string, string[]> = {
+  'spreadsheets.get': ['spreadsheetId', 'ranges', 'includeGridData'],
+  'spreadsheets.values.get': ['spreadsheetId', 'range', 'majorDimension'],
+  'spreadsheets.values.batchGet': ['spreadsheetId', 'ranges', 'majorDimension'],
+  'spreadsheets.values.update': ['spreadsheetId', 'pathRange', 'valueInputOption'],
+  'spreadsheets.values.batchUpdate': ['spreadsheetId'],
+  'spreadsheets.values.append': [
+    'spreadsheetId',
+    'pathRange',
+    'valueInputOption',
+    'insertDataOption',
+  ],
+  'spreadsheets.values.clear': ['spreadsheetId', 'range'],
+  'spreadsheets.values.batchClear': ['spreadsheetId', 'ranges'],
+  // Every argument, because every argument is an identifier: this operation
+  // carries no cell contents at all, and the destination file is the one fact
+  // an audit log must not lose — a tab copied into the wrong workbook is the
+  // failure worth being able to trace.
+  'spreadsheets.sheets.copyTo': ['spreadsheetId', 'sheetId', 'destinationSpreadsheetId'],
+  'spreadsheets.batchUpdate': ['spreadsheetId'],
+};