gogcli-mcp 2.21.0 → 2.22.0

package/tests/google-probe.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { readGoogleProbe } from '../src/google-probe.js';
+
+/**
+ * REVIEW DEFECT: "the probe could not run" was filed as "Google refused".
+ *
+ * The runner collapses every non-healthy outcome into `ok:false`, and BOTH
+ * connector call sites used to branch on `ok === true` alone. Three of the
+ * runner's causes are facts about the probe, not about Google — it timed out, it
+ * could not be run (`gog` missing from PATH, `credentials.json` missing from the
+ * volume), or its output could not be parsed — and each of those became an
+ * error-level `connect.google-unhealthy` / `refusal.google-unhealthy`, whose
+ * documented meaning is "Google was asked and refused". An operator grepping
+ * event names would close the incident on evidence nobody gathered.
+ *
+ * The runner now states `measured` explicitly. This module is the ONE place that
+ * reads it, precisely because the defect was two call sites making the same
+ * judgement separately.
+ */
+describe('readGoogleProbe', () => {
+  it('reads a healthy answer as ok', () => {
+    expect(readGoogleProbe({ ok: true, measured: true })).toEqual({ kind: 'ok' });
+  });
+
+  it('reads a measured refusal as unhealthy, carrying the runner’s cause', () => {
+    expect(readGoogleProbe({ ok: false, measured: true, error: 'invalid_grant: …' })).toEqual({
+      kind: 'unhealthy',
+      reason: 'invalid_grant: …',
+    });
+  });
+
+  it('says so plainly when a measured refusal names no cause', () => {
+    const verdict = readGoogleProbe({ ok: false, measured: true });
+    expect(verdict.kind).toBe('unhealthy');
+    expect(verdict.reason).toMatch(/no cause/i);
+  });
+
+  it('reads measured:false as UNMEASURED however loudly the cause reads', () => {
+    // The regression under test. Every one of these used to be `unhealthy`.
+    for (const error of [
+      'the Google probe timed out before gog answered',
+      'the Google probe could not be run',
+      'gog auth list --check returned unrecognized output',
+      'gog did not report token validity',
+      'gog reported an account it explicitly did not check',
+    ]) {
+      expect(readGoogleProbe({ ok: false, measured: false, error })).toEqual({
+        kind: 'unmeasured',
+        reason: error,
+      });
+    }
+  });
+
+  it('refuses to claim HEALTH from a runner that never said it measured', () => {
+    // The row this table was missing, and the last place `ok` outranked
+    // `measured`. A bare `ok:true` used to return {kind:'ok'}, which on the
+    // refusal path is `refusal.google-ok` — the record documented as "the one
+    // record that means we cannot explain this", logged at error level, and
+    // held up as the only evidence that could justify automatic recovery on the
+    // hosted path. Raising it from a measurement nobody took is this branch's
+    // founding defect surviving in the module written to delete it. `ok:true`
+    // is not self-licensing: it is a health claim, and a health claim needs a
+    // measurement behind it — exactly what the runner's README asserts when it
+    // says `ok:true` always travels with `measured:true`.
+    const verdict = readGoogleProbe({ ok: true });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toMatch(/did not report whether/i);
+  });
+
+  it('carries the runner’s cause when a bare ok:true also names one', () => {
+    const verdict = readGoogleProbe({ ok: true, error: 'something went wrong' });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toContain('something went wrong');
+  });
+
+  it('never claims health from an incoherent ok:true + measured:false', () => {
+    // `measured` is read FIRST, so the field that can only under-claim wins.
+    const verdict = readGoogleProbe({ ok: true, measured: false });
+    expect(verdict.kind).toBe('unmeasured');
+  });
+
+  it('describes an unmeasured answer that names no cause', () => {
+    const verdict = readGoogleProbe({ ok: false, measured: false });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toMatch(/could not measure/i);
+  });
+
+  it('refuses to claim ill health from a runner that never said it measured', () => {
+    // Silence is not a measurement. An `ok:false` with no `measured` field is
+    // read as unmeasured — under-claiming, the only safe direction.
+    const verdict = readGoogleProbe({ ok: false, error: 'something went wrong' });
+    expect(verdict.kind).toBe('unmeasured');
+    expect(verdict.reason).toContain('something went wrong');
+    expect(verdict.reason).toMatch(/did not report whether/i);
+  });
+
+  it('reads a body with no fields at all, and a null body, as unmeasured', () => {
+    expect(readGoogleProbe({}).kind).toBe('unmeasured');
+    expect(readGoogleProbe(null).kind).toBe('unmeasured');
+    expect(readGoogleProbe(undefined).kind).toBe('unmeasured');
+    expect(readGoogleProbe('a proxy error page').kind).toBe('unmeasured');
+  });
+
+  it('ignores non-boolean field types rather than trusting them', () => {
+    // JSON from a proxy, or a future runner, may put anything here.
+    expect(readGoogleProbe({ ok: 'true', measured: 'true' }).kind).toBe('unmeasured');
+    expect(readGoogleProbe({ ok: 1, measured: 1 }).kind).toBe('unmeasured');
+  });
+
+  it('never carries a non-string cause into a log line', () => {
+    const verdict = readGoogleProbe({ ok: false, measured: true, error: { nested: 'object' } });
+    expect(verdict.kind).toBe('unhealthy');
+    expect(typeof verdict.reason).toBe('string');
+    expect(verdict.reason).toMatch(/no cause/i);
+  });
+});

package/tests/google-token.test.ts

@@ -129,6 +129,13 @@ describe('makeAccessTokenSource', () => {
     );
     const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-dead' })!;
     await expect(source()).rejects.toThrow(/expired or been revoked|re-?enrol|re-?authoriz/i);
+    // The literal token, not just the prose. tools/utils.ts picks the richer
+    // INVALID_GRANT_HINT (7-day Testing-mode cause + the headless re-auth pair)
+    // by matching `invalid_grant`; a message that only DESCRIBES the failure
+    // earns the generic "authentication may have expired" advice instead, which
+    // is what this mint used to get while the identical failure reported by gog
+    // got the specific guidance.
+    await expect(source()).rejects.toThrow(/invalid_grant/);
   });
 
   it('does not cache a failure, so a transient outage is not sticky', async () => {
@@ -277,10 +284,24 @@ describe('makeAccessTokenSource', () => {
   });
 
   it('does not let two different credentials share one in-flight exchange', async () => {
-    const fetchMock = vi
-      .fn()
-      .mockResolvedValueOnce(tokenResponse('ya29.alice'))
-      .mockResolvedValueOnce(tokenResponse('ya29.bob'));
+    // Answers are keyed off the REQUEST's refresh_token, never off call order.
+    //
+    // `mockResolvedValueOnce` twice would assign alice's token to whichever
+    // exchange reaches fetch first, and that is not the order the sources were
+    // called in: each one awaits `crypto.subtle.digest` (via the cache key)
+    // before it reaches fetch, and two digest promises are not guaranteed to
+    // settle in the order they were started. Measured against this very source,
+    // bob's request went first in 4 of 400 races (~1%), which is exactly the
+    // rate at which an order-keyed mock hands alice bob's token and reddens CI
+    // for a reason that has nothing to do with the behaviour under test.
+    //
+    // Keying off the body also makes the assertion say what it means: the point
+    // is that each credential got ITS OWN token, which is a claim about
+    // pairing, not about sequence.
+    const fetchMock = vi.fn(async (_url: string, init: { body: string }) => {
+      const refreshToken = new URLSearchParams(init.body).get('refresh_token');
+      return tokenResponse(refreshToken === 'rt-alice' ? 'ya29.alice' : 'ya29.bob');
+    });
     vi.stubGlobal('fetch', fetchMock);
     const alice = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-alice' })!;
     const bob = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-bob' })!;
@@ -302,3 +323,103 @@ describe('makeAccessTokenSource', () => {
     );
   });
 });
+
+/**
+ * A token Google has REJECTED must leave the cache.
+ *
+ * The cache's only read guard is time-based (`expiresAt - EXPIRY_MARGIN_MS >
+ * Date.now()`), so before this existed a token Google answered 401 to was
+ * re-served for the rest of its nominal hour — every call in that window failed
+ * identically, retrying changed nothing, and only reconnecting (a fresh isolate
+ * with an empty cache) helped.
+ *
+ * The eviction is deliberately NOT `clearAccessTokenCache()`. That is a test
+ * seam which drops EVERY credential; using it here would mean one caller's dead
+ * token forced a re-mint on every other caller sharing the isolate — a new bug
+ * in the same shape as the ones this module was built to avoid.
+ */
+describe('invalidate', () => {
+  it('evicts the rejected token so the next call mints a fresh one', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(tokenResponse('ya29.first'))
+      .mockResolvedValueOnce(tokenResponse('ya29.second'));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    expect(await source()).toBe('ya29.first');
+    expect(await source()).toBe('ya29.first');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // True: something was actually dropped, so a retry has a chance of using a
+    // DIFFERENT token. That answer is what the caller's retry decision hangs on.
+    expect(await source.invalidate('ya29.first')).toBe(true);
+
+    expect(await source()).toBe('ya29.second');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('evicts only the credential whose token was rejected', async () => {
+    // The multi-tenant property. A Worker isolate serves many callers; one
+    // caller meeting a dead token must not cost everyone else a re-mint.
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(tokenResponse('ya29.alice'))
+      .mockResolvedValueOnce(tokenResponse('ya29.bob'));
+    vi.stubGlobal('fetch', fetchMock);
+    const alice = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-alice' })!;
+    const bob = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-bob' })!;
+
+    expect(await alice()).toBe('ya29.alice');
+    expect(await bob()).toBe('ya29.bob');
+    expect(await alice.invalidate('ya29.alice')).toBe(true);
+
+    // Bob's entry is untouched — still served from cache, no third exchange.
+    expect(await bob()).toBe('ya29.bob');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores a rejection naming a token that is no longer the cached one', async () => {
+    // The ABA case. Caller A sends token T; while A is in flight, B refreshes
+    // the entry to T2; A comes back with "T was rejected". Dropping T2 there
+    // would make the next call mint a third token for nothing, and two callers
+    // could keep evicting each other's work indefinitely.
+    const fetchMock = vi.fn(async () => tokenResponse('ya29.current'));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    expect(await source()).toBe('ya29.current');
+    expect(await source.invalidate('ya29.superseded')).toBe(false);
+    expect(await source()).toBe('ya29.current');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports nothing evicted when the credential has no cached token at all', async () => {
+    vi.stubGlobal('fetch', vi.fn());
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    expect(await source.invalidate('ya29.never-minted')).toBe(false);
+  });
+
+  it('offers no eviction at all for a directly-supplied token, which cannot be re-minted', async () => {
+    // The #230 path stores an ACCESS token, so there is nothing to mint from:
+    // reading again returns the identical string.
+    //
+    // The ABSENCE of the method is the signal, not a `false` return. A source
+    // that answers false is indistinguishable from a mintable one whose token a
+    // concurrent caller already replaced, and the connector logs those two as
+    // different causes — so a source that attached an always-false `invalidate`
+    // made the auth log blame concurrency for "nothing here can mint a
+    // replacement", which is the one case where re-authorizing IS the repair.
+    const source = makeAccessTokenSource({ GOG_ACCESS_TOKEN: 'ya29.direct' })!;
+    expect(source.invalidate).toBeUndefined();
+    expect(await source()).toBe('ya29.direct');
+  });
+
+  it('offers no eviction for a source that cannot mint at all', async () => {
+    // GOG_REFRESH_TOKEN without an OAuth client: the source exists only to fail
+    // loudly on first use, so there is never a cached token behind it.
+    const source = makeAccessTokenSource({ GOG_REFRESH_TOKEN: 'rt-1', GOG_CLIENT_ID: 'cid' })!;
+    expect(source.invalidate).toBeUndefined();
+    await expect(source()).rejects.toThrow(/GOG_CLIENT_SECRET/);
+  });
+});

package/tests/runner.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { EventEmitter } from 'node:events';
 import { spawn as mockedSpawn } from 'node:child_process';
-import { run, runBinary, runExecutor } from '../src/runner.js';
+import { run, runBinary, runExecutor, RunnerTransportError, isRunnerTransportError } from '../src/runner.js';
 import type { Spawner, GogExecutor } from '../src/runner.js';
 
 // The real spawn is dynamically imported inside runner's default executor.
@@ -763,6 +763,26 @@ describe('run executor seam', () => {
     }
   });
 
+  // run() re-wraps every thrown error to redact secrets from its message. That
+  // rewrap must not cost a RunnerTransportError its TYPE: the type is the only
+  // thing that tells diagnose() the failure was the connector's transport and
+  // not the caller's Google credential, and a bare Error puts it straight back
+  // to guessing from prose.
+  it('preserves a RunnerTransportError through the redacting rewrap', async () => {
+    const executor = vi.fn(async () => {
+      throw new RunnerTransportError('runner key mismatch; saw 1//0eLEAKED-REFRESH end', 'transport-auth', 401);
+    }) as unknown as GogExecutor;
+    const err = await runExecutor
+      .run({ executor }, () => run(['gmail', 'get', 'm1']))
+      .catch((e: unknown) => e);
+    expect(isRunnerTransportError(err)).toBe(true);
+    expect((err as RunnerTransportError).kind).toBe('transport-auth');
+    expect((err as RunnerTransportError).status).toBe(401);
+    // and it is still redacted
+    expect((err as Error).message).not.toContain('1//0eLEAKED-REFRESH');
+    expect((err as Error).message).toContain('[REDACTED]');
+  });
+
   it('options.spawner takes precedence over an injected ALS executor', async () => {
     const spawner = makeSpawner(0, '{"via":"spawner"}');
     const executor = vi.fn(async () => '{"via":"executor"}') as unknown as GogExecutor;

package/tests/timestamps.test.ts

@@ -316,3 +316,55 @@ describe('normalizeTimestamps', () => {
     expect(out.date).toMatch(/[+-]\d{2}:\d{2}$/);
   });
 });
+
+// gog 0.35.0 (#946) adds `internalDateIso` to Gmail message AND thread
+// listings: Gmail's own internalDate rendered RFC3339 with a real offset. It is
+// separately sourced from the neighbouring `date` (a naive reconstruction of
+// the sender's Date header), so the two can legitimately disagree — but only
+// `internalDateIso` carries its own zone, which makes it the field a machine
+// consumer should read.
+describe('internalDateIso (gog >= 0.35.0 Gmail listings)', () => {
+  it('gains a display sibling and survives a DISPLAY_TZ unlike its own offset', () => {
+    const payload = JSON.stringify({
+      messages: [{ id: 'm1', date: '2026-07-28 03:36', internalDateIso: '2026-07-28T03:36:12-04:00' }],
+    });
+    const pt = JSON.parse(normalizeTimestamps(payload, 'America/Los_Angeles', 'UTC'));
+    const row = pt.messages[0];
+    // Re-rendered in the display zone, same instant, offset still explicit.
+    expect(row.internalDateIso).toBe('2026-07-28T00:36:12-07:00');
+    expect(Date.parse(row.internalDateIso)).toBe(Date.parse('2026-07-28T03:36:12-04:00'));
+    expect(row.internalDateIsoDisplay).toContain('Tue, Jul 28');
+    expect(isNaiveTimestamp(row.internalDateIso)).toBe(false);
+  });
+
+  it('keeps sub-second precision when gog emits milliseconds', () => {
+    const out = JSON.parse(normalizeTimestamps(
+      JSON.stringify({ internalDateIso: '2026-07-28T03:36:12.250-04:00' }), ET,
+    ));
+    expect(out.internalDateIso).toBe('2026-07-28T03:36:12.250-04:00');
+    expect(out.internalDateIsoDisplay).toContain('Tue, Jul 28');
+  });
+
+  // The trap: `date` is gog re-formatting the sender header into GOG_TIMEZONE
+  // with no offset, so the wrapper has to re-read it in that zone. Only
+  // `internalDateIso` is self-describing, and the two are allowed to disagree.
+  it('is trusted verbatim while the naive sibling is read in GOG_TIMEZONE', () => {
+    const out = JSON.parse(normalizeTimestamps(JSON.stringify({
+      date: '2026-07-28 03:36',
+      internalDateIso: '2026-07-27T23:36:12-04:00',
+    }), ET, 'UTC'));
+    expect(out.internalDateIso).toBe('2026-07-27T23:36:12-04:00');
+    expect(out.date).toBe('2026-07-27T23:36:00-04:00');
+    expect(out.dateDisplay).toContain('Jul 27');
+    expect(out.internalDateIsoDisplay).toContain('Jul 27');
+  });
+
+  // A thread listing carries the same field (gmail_thread_search_helpers.go).
+  it('normalizes the field on thread listings too', () => {
+    const out = JSON.parse(normalizeTimestamps(
+      JSON.stringify({ threads: [{ id: 't1', internalDateIso: '2026-07-28T03:36:12Z' }] }), ET,
+    ));
+    expect(out.threads[0].internalDateIso).toBe('2026-07-27T23:36:12-04:00');
+    expect(out.threads[0].internalDateIsoDisplay).toContain('Mon, Jul 27');
+  });
+});

package/tests/tools/auth-401-context.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { diagnose } from '../../src/tools/utils.js';
+
+/**
+ * `401` is a status code, but it is also just a number, and gog's output is
+ * full of numbers that are row indices, ranges and counts. The pattern used to
+ * be a bare `\b401\b`, so "row 401 is outside the sheet grid" — a pure Sheets
+ * range error — told the caller to re-authorize a healthy Google account.
+ *
+ * That is the same defect this PR exists to remove, reached from gog's stderr
+ * instead of the runner's status line: a caller is sent to do a manual,
+ * account-wide re-auth that cannot possibly fix their problem.
+ *
+ * So a 401 now has to look like a STATUS, not like an integer.
+ */
+const reauth = async (msg: string) => {
+  const r = await diagnose(new Error(msg));
+  return /Use gog_auth_add to re-authorize the account/i.test(r.content.map((c: any) => c.text).join('\n'));
+};
+
+describe('401 must look like a status, not any integer', () => {
+  it.each([
+    ['row 401 is outside the sheet grid'],
+    ['wrote 401 rows'],
+    ['A401:B401 exceeds grid limits'],
+    ['deleted 401 messages'],
+    ['sheet has 401 columns'],
+  ])('does NOT claim an auth failure for: %s', async (msg) => {
+    expect(await reauth(msg)).toBe(false);
+  });
+
+  it.each([
+    ['googleapi: Error 401: Invalid Credentials, authError'],
+    ['HTTP 401 Unauthorized'],
+    ['request failed with status 401'],
+    ['unexpected status code 401'],
+    ['401 Unauthorized'],
+    ['server responded 401: token rejected'],
+  ])('still DOES claim an auth failure for: %s', async (msg) => {
+    expect(await reauth(msg)).toBe(true);
+  });
+});

package/tests/tools/auth-401-shapes.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { diagnose } from '../../src/tools/utils.js';
+
+/**
+ * #246: making 401 "look like a status" (#245 follow-up) required a separator
+ * between the status word and the number. `\s*[:=]?\s*` cannot cross an opening
+ * paren or a JSON quote, so the CANONICAL shape gog emits for a Google auth
+ * failure stopped matching entirely:
+ *
+ *   Google API error (401 authError): Invalid Credentials
+ *
+ * That shape is hard-coded in connector-runtime.ts as /Google API error \(401\b/
+ * and used as the fixture across auth-log and connector-runtime tests. Losing it
+ * is strictly worse than the `row 401` false positive that motivated the change:
+ * a false positive sends someone on a pointless re-auth, but this leaves a REAL
+ * dead credential with no hint at all.
+ */
+const reauth = async (msg: string) => {
+  const r = await diagnose(new Error(msg));
+  return /Use gog_auth_add to re-authorize the account/i.test(r.content.map((c: any) => c.text).join('\n'));
+};
+
+describe('401 shapes that ARE auth failures', () => {
+  it.each([
+    ['Google API error (401 authError): Invalid Credentials'],   // the canonical gog shape
+    ['Google API error (401): Invalid Credentials'],
+    ['{"code": 401, "message": "Invalid Credentials"}'],          // JSON body
+    ['{"status":401}'],
+    ['googleapi: Error 401: Invalid Credentials, authError'],
+    ['HTTP 401 Unauthorized'],
+    ['request failed with status 401'],
+    ['unexpected status code 401'],
+    ['response=401'],
+  ])('claims an auth failure for: %s', async (msg) => {
+    expect(await reauth(msg)).toBe(true);
+  });
+});
+
+describe('401 shapes that are NOT auth failures', () => {
+  it.each([
+    ['row 401 is outside the sheet grid'],
+    ['wrote 401 rows'],
+    ['A401:B401 exceeds grid limits'],
+    ['deleted 401 messages'],
+    ['sheet has 401 columns'],
+    ['error: could not write row 401'],   // status word present, but far from the number
+  ])('stays silent for: %s', async (msg) => {
+    expect(await reauth(msg)).toBe(false);
+  });
+});

package/tests/tools/auth.test.ts

@@ -69,6 +69,20 @@ describe('gog_auth_status', () => {
     const result = await harness.callTool('gog_auth_status', {});
     expect(result.content[0].text).toBe('Error: Status failed');
   });
+
+  it('does not present itself as a health check', async () => {
+    // `gog auth status` prints the keyring backend and where the credential
+    // files live. It contacts nothing. Named "status" next to a connector whose
+    // UI says "connected", it reads as the answer to "is my auth OK?" — which is
+    // the question only gog_auth_health can answer.
+    const harness = await setupHandlers();
+    const { tools } = await harness.client.listTools();
+    const desc = tools.find((t) => t.name === 'gog_auth_status')!.description!;
+
+    expect(desc).toMatch(/does not contact Google/i);
+    expect(desc).toContain('gog_auth_health');
+    await harness.close();
+  });
 });
 
 describe('gog_auth_services', () => {
@@ -127,6 +141,20 @@ describe('gog_auth_add', () => {
 });
 
 describe('gog_auth_health', () => {
+  it('names itself as the only live measurement of the Google layer', async () => {
+    // DEFECT 1's wording half: the hosted connector's "connected" / "refreshed"
+    // is an OAuth refresh inside OAUTH_KV that contacts neither Fly nor Google.
+    // Nothing in this repo can change that word, so the tool that DOES measure
+    // has to say that it is the one that does.
+    const harness = await setupHandlers();
+    const { tools } = await harness.client.listTools();
+    const desc = tools.find((t) => t.name === 'gog_auth_health')!.description!;
+
+    expect(desc).toMatch(/connected|refreshed/i);
+    expect(desc).toMatch(/only|nothing else/i);
+    await harness.close();
+  });
+
   const CHECK_JSON = JSON.stringify({
     accounts: [
       { email: 'chris.c.hall@gmail.com', created_at: '2026-07-17T15:08:39Z', valid: true },

package/tests/tools/utils.test.ts

@@ -1,8 +1,17 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as runner from '../../src/runner.js';
 import { runOrDiagnose, pushPaginationFlags, formatAccountList, formatAuthHealth } from '../../src/tools/utils.js';
-
-vi.mock('../../src/runner.js');
+import { RunnerTransportError } from '../../src/connector-runtime.js';
+
+// PARTIAL mock: only `run` is stubbed. A full automock would also replace
+// `RunnerTransportError` and `isRunnerTransportError`, and diagnose()'s whole
+// point is that it classifies the REAL class structurally — an automocked
+// brand check answers undefined for everything and the tests below would pass
+// while proving nothing.
+vi.mock('../../src/runner.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof runner>()),
+  run: vi.fn(),
+}));
 
 beforeEach(() => vi.clearAllMocks());
 
@@ -455,3 +464,47 @@ describe('formatAuthHealth', () => {
     expect(formatAuthHealth('{"foo":1}', NOW)).toBe('{"foo":1}');
   });
 });
+
+// The connector's own transport failing is NOT the Google credential failing.
+// diagnose() must recognise that structurally, from the error's type, because
+// the runner's prose ("unauthorized") is indistinguishable from Google's.
+describe('diagnose: runner-authored transport failures', () => {
+  it('blames the runner key, not the Google account, for a transport-auth failure', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(
+        new RunnerTransportError('gog-runner rejected the bearer token; GOG_RUNNER_KEY vs RUNNER_KEY', 'transport-auth', 401),
+      )
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    const text = result.content[0].text as string;
+    expect(text).not.toContain('gog_auth_add');
+    expect(text).not.toMatch(/re-authorize the account/i);
+    expect(text).toContain('GOG_RUNNER_KEY');
+    expect(text).toContain('RUNNER_KEY');
+  });
+
+  it('lets the TYPE beat the prose: runner words that read like Google words get no re-auth hint', async () => {
+    // The regression this whole change exists to prevent. A runner-authored
+    // failure whose text happens to contain every Google auth signal must still
+    // not produce Google auth advice — the request never reached Google.
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(
+        new RunnerTransportError('unauthorized: 401 invalid_grant, token has been expired or revoked', 'transport-request', 400),
+      )
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    const text = result.content[0].text as string;
+    expect(text).not.toContain('gog_auth_add');
+    expect(text).not.toContain('often transient');
+  });
+
+  it('advises a retry for a retryable transport failure', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new RunnerTransportError('gog-runner is restarting; retry this call.', 'transport-retryable', 503))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    const text = result.content[0].text as string;
+    expect(text).toContain('often transient');
+    expect(text).not.toContain('gog_auth_add');
+  });
+});

package/tests/worker.test.ts

@@ -80,16 +80,41 @@ describe('gogcli Cloudflare connector — OAuth surface', () => {
   }
 
   it('GET /authorize renders the gogcli login page with the connector-key field', async () => {
-    // No `client_id` query param: the login page renders without needing a
-    // registered OAuth client, which is all we verify here.
-    // `redirect_uri` IS required, though — do not remove it. workers-oauth-provider
-    // 0.8.x calls validateRedirectUriScheme() unconditionally from parseAuthRequest,
-    // and it rejects any value with no scheme — including the empty string an ABSENT
-    // `redirect_uri` becomes ("Invalid redirect URI"). client_id stays omitted, so no
-    // client lookup happens and the assertion below is unchanged.
+    // `/authorize` is only reachable for a REGISTERED client, so the request has
+    // to be preceded by a real dynamic client registration.
+    //
+    // It did not always: workers-oauth-provider 0.8.x parsed the request without
+    // a `client_id` (it only called validateRedirectUriScheme unconditionally,
+    // which is why `redirect_uri` was already here). 0.10.x moved the
+    // `client_id is required` check and the client lookup ahead of everything
+    // else in parseAuthRequest, so the old URL now throws before the login page
+    // is ever rendered — an AuthorizationError from inside the library, not from
+    // any code in this repo. Registering first is the fix, and it exercises the
+    // path a real client actually takes.
+    const redirectUri = 'https://example.com/callback';
+    const registration = await SELF.fetch('https://example.com/register', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        client_name: 'worker test client',
+        redirect_uris: [redirectUri],
+        token_endpoint_auth_method: 'none',
+      }),
+    });
+    expect(registration.status).toBe(201);
+    const { client_id: clientId } = (await registration.json()) as { client_id: string };
+    expect(clientId).toBeTruthy();
+
+    // PKCE is mandatory for a public client (`token_endpoint_auth_method: none`)
+    // on the authorization-code flow, and the provider enforces it during the
+    // same parse. The challenge is never redeemed here — this test stops at the
+    // rendered page — so any well-formed S256 value will do.
+    const codeChallenge = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
     const res = await SELF.fetch(
       'https://example.com/authorize?response_type=code&state=abc' +
-        `&redirect_uri=${encodeURIComponent('https://example.com/callback')}`,
+        `&client_id=${encodeURIComponent(clientId)}` +
+        `&redirect_uri=${encodeURIComponent(redirectUri)}` +
+        `&code_challenge=${codeChallenge}&code_challenge_method=S256`,
     );
     expect(res.status).toBe(200);
     expect(res.headers.get('content-type')).toContain('text/html');