gogcli-mcp-docs 2.21.0 → 2.21.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-docs",
   "displayName": "gogcli (Docs)",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -31140,6 +31140,21 @@ import { delimiter, join } from "node:path";
 function isGogFileArg(arg) {
   return typeof arg !== "string";
 }
+var RUNNER_TRANSPORT_BRAND = /* @__PURE__ */ Symbol.for("gogcli.RunnerTransportError");
+var RunnerTransportError = class extends Error {
+  kind;
+  status;
+  constructor(message, kind, status) {
+    super(message);
+    this.name = "RunnerTransportError";
+    this.kind = kind;
+    this.status = status;
+    Object.defineProperty(this, RUNNER_TRANSPORT_BRAND, { value: true });
+  }
+};
+function isRunnerTransportError(err) {
+  return err instanceof Error && err[RUNNER_TRANSPORT_BRAND] === true;
+}
 var runExecutor = new AsyncLocalStorage();
 var defaultExecutor;
 function setDefaultGogExecutor(executor) {
@@ -31320,7 +31335,11 @@ async function run(args, options = {}) {
     }
     return redact(output);
   } catch (err) {
-    throw new Error(redact(err instanceof Error ? err.message : String(err)));
+    const message = redact(err instanceof Error ? err.message : String(err));
+    if (isRunnerTransportError(err)) {
+      throw new RunnerTransportError(message, err.kind, err.status);
+    }
+    throw new Error(message);
   }
 }
 
@@ -31584,7 +31603,7 @@ function registerRunTool(server, options) {
 function errorText(err) {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
-var DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+var DEFINITE_AUTH_PATTERN = /\b(?:unauthorized|invalid_grant)\b|\b(?:error|status|code|http|responded|response)["']?[\s:=(,]{0,4}401\b/i;
 var STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
 var AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, "i");
 var INVALID_GRANT_PATTERN = /invalid_grant|token has been expired or revoked/i;
@@ -31594,6 +31613,14 @@ var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-aut
 var INVALID_GRANT_HINT = '\n\nThe stored refresh token was rejected (invalid_grant): it has expired or been revoked, so the whole account is signed out and re-authorization is required. The most common cause is the 7-day refresh-token limit Google applies to OAuth apps whose consent screen is still in "Testing" mode. Re-authorize with gog_auth_add (opens a browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless). To stop this recurring, publish the OAuth consent screen to "In production" in the Google Cloud project that owns the OAuth client. Ask the user if they would like to re-authenticate.';
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
 var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+var RUNNER_TRANSPORT_AUTH_HINT = "\n\nThis is the CONNECTOR's own transport auth failing, not your Google sign-in. The gog-runner backend rejected the bearer token this server sent, so the request never reached gog and no Google credential was checked \u2014 the Google account is not the problem and re-authorizing it cannot fix this. An operator must make the Worker secret GOG_RUNNER_KEY equal RUNNER_KEY on the Fly app (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY), then retry.";
+var RUNNER_TRANSPORT_HINTS = {
+  "transport-auth": RUNNER_TRANSPORT_AUTH_HINT,
+  // The request itself was malformed, so the runner will refuse it identically
+  // every time. Nothing to advise beyond the message the runner already gave.
+  "transport-request": "",
+  "transport-retryable": TRANSIENT_HINT
+};
 function formatAccountList(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -31606,11 +31633,12 @@ function formatAccountList(raw) {
 }
 async function diagnose(err) {
   const errText = errorText(err);
+  const transportHint = isRunnerTransportError(err) ? RUNNER_TRANSPORT_HINTS[err.kind] : void 0;
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
   const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
   const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
-  const hint = isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
+  const hint = transportHint ?? (isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "");
   try {
     const accounts = formatAccountList(await run(["auth", "list"]));
     return errorResult(`${errText}
@@ -31904,7 +31932,25 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.21.0" : "0.0.0";
+var VERSION = true ? "2.21.1" : "0.0.0";
+
+// ../gogcli-mcp/src/auth-log.ts
+var FAILURES = /* @__PURE__ */ new Set([
+  "token.mint-failed",
+  "grant.dead",
+  "replay.failed",
+  "runner.auth-failed"
+]);
+var PREFIX = "gog-auth ";
+var TAG_CHARS = 12;
+function credentialTag(cacheKeyHash) {
+  return cacheKeyHash.slice(0, TAG_CHARS);
+}
+function logAuthTransition(event, context) {
+  const record2 = JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), event, ...context });
+  const write = FAILURES.has(event) ? console.error : console.warn;
+  write(PREFIX + redactSecrets2(record2));
+}
 
 // ../gogcli-mcp/src/google-token.ts
 var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
@@ -31931,22 +31977,73 @@ function makeAccessTokenSource(env) {
       );
     };
   }
-  return async () => {
-    const key = await cacheKey(refreshToken, clientId);
-    const hit = cache.get(key);
-    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return hit.accessToken;
-    let pending = inFlight.get(key);
+  let keyPromise;
+  const key = () => keyPromise ??= cacheKey(refreshToken, clientId);
+  const logCacheHits = parseBoolEnv("GOG_AUTH_LOG_CACHE_HITS", { env });
+  const read = async () => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) {
+      if (logCacheHits) logAuthTransition("token.cache-hit", { credential: credentialTag(k) });
+      return hit.accessToken;
+    }
+    let pending = inFlight.get(k);
     if (!pending) {
       pending = exchange(refreshToken, clientId, clientSecret).then((minted2) => {
-        cache.set(key, minted2);
+        cache.set(k, minted2);
+        logAuthTransition("token.minted", {
+          credential: credentialTag(k),
+          reason: `valid for ${Math.round((minted2.expiresAt - Date.now()) / 1e3)}s`
+        });
         return minted2;
-      }).finally(() => inFlight.delete(key));
-      inFlight.set(key, pending);
+      }).catch((err) => {
+        logAuthTransition(err.grantDead ? "grant.dead" : "token.mint-failed", {
+          credential: credentialTag(k),
+          reason: err.message
+        });
+        throw err;
+      }).finally(() => inFlight.delete(k));
+      inFlight.set(k, pending);
     }
     const minted = await pending;
     return minted.accessToken;
   };
+  const invalidate = async (rejected) => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (!hit || hit.accessToken !== rejected) {
+      logAuthTransition("token.evict-noop", {
+        credential: credentialTag(k),
+        reason: hit ? "a concurrent caller had already replaced this credential\u2019s token" : "no token was cached for this credential"
+      });
+      return false;
+    }
+    cache.delete(k);
+    logAuthTransition("token.evicted", {
+      credential: credentialTag(k),
+      reason: "Google rejected this access token; the next read will mint a new one"
+    });
+    return true;
+  };
+  return Object.assign(read, {
+    invalidate,
+    credentialId: async () => credentialTag(await key())
+  });
 }
+var TokenExchangeError = class extends Error {
+  /**
+   * The REFRESH token is dead (Google's `invalid_grant`), not merely the access
+   * token. Carried as a flag rather than re-read from the message, because
+   * inferring the author of a failure from prose several authors can produce is
+   * precisely the mistake this branch exists to undo. `instanceof` is safe: the
+   * class is thrown and caught inside this one module.
+   */
+  grantDead;
+  constructor(message, grantDead) {
+    super(message);
+    this.grantDead = grantDead;
+  }
+};
 async function exchange(refreshToken, clientId, clientSecret) {
   let res;
   try {
@@ -31961,23 +32058,29 @@ async function exchange(refreshToken, clientId, clientSecret) {
       }).toString()
     });
   } catch (err) {
-    throw new Error(
-      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`
+    throw new TokenExchangeError(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+      false
     );
   }
   const body = await res.json().catch(() => ({}));
   if (!res.ok) {
     if (body.error === "invalid_grant") {
-      throw new Error(
-        'the stored refresh token has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.'
+      throw new TokenExchangeError(
+        'the stored refresh token was rejected (invalid_grant): it has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.',
+        true
       );
     }
-    throw new Error(
-      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`
+    throw new TokenExchangeError(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`,
+      false
     );
   }
   if (!body.access_token) {
-    throw new Error("the access token could not be refreshed: Google returned no access_token");
+    throw new TokenExchangeError(
+      "the access token could not be refreshed: Google returned no access_token",
+      false
+    );
   }
   const expiresInMs = (body.expires_in ?? 3600) * 1e3;
   return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
@@ -31986,54 +32089,218 @@ async function exchange(refreshToken, clientId, clientSecret) {
 // ../gogcli-mcp/src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
+var MIN_REPLAY_BUDGET_MS = 1e3;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
+var RUNNER_BAD_REQUEST = 400;
+var RUNNER_BAD_KEY = 401;
+var GogFailedError = class extends Error {
+  /** gog's stderr alone, with no echoed argv mixed in. */
+  stderr;
+  constructor(message, stderr) {
+    super(message);
+    this.stderr = stderr;
+  }
+};
+var GOOGLE_TOKEN_REJECTED_PATTERN = /Google API error \(401\b|invalid[ _]authentication[ _]credentials|\bACCESS_TOKEN_EXPIRED\b|\binvalid_token\b/i;
+var REFRESH_TOKEN_DEAD_PATTERN = /\binvalid_grant\b/i;
+var READ_ONLY_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "cat",
+  "describe",
+  "get",
+  "info",
+  "list",
+  "list-slides",
+  "ls",
+  "metadata",
+  "read-slide",
+  "search",
+  "services",
+  "status",
+  "structure"
+]);
+function gogTarget(args) {
+  const words = args.filter((arg) => typeof arg === "string");
+  let service;
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    if (word.startsWith("-")) {
+      if (word === "--account") i += 1;
+      continue;
+    }
+    if (service === void 0) {
+      service = word;
+      continue;
+    }
+    return { service, subcommand: word };
+  }
+  return { service };
+}
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt) {
+  if (!(err instanceof GogFailedError)) return void 0;
+  const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
+  if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
+  const { service, subcommand } = gogTarget(args);
+  const credential = await readAccessToken?.credentialId?.();
+  const where = { credential, service };
+  if (grantDead) {
+    logAuthTransition("grant.dead", {
+      ...where,
+      reason: "gog reported invalid_grant: the stored refresh token is dead, so no token can be minted and this account must be re-authorized"
+    });
+    return void 0;
+  }
+  if (!used) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
+    });
+    return void 0;
+  }
+  if (!readAccessToken?.invalidate) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "this token source cannot mint a replacement, so a replay would resend the rejected token"
+    });
+    return void 0;
+  }
+  const evicted = await readAccessToken.invalidate(used);
+  if (subcommand === void 0 || !READ_ONLY_SUBCOMMANDS.has(subcommand)) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `not replayable: '${subcommand ?? "(none)"}' is not a known read-only subcommand and a write could double-apply`
+    });
+    return void 0;
+  }
+  if (!evicted) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the rejected token was already superseded, so the cache holds the token a replay would send"
+    });
+    return void 0;
+  }
+  const fresh = await readAccessToken();
+  if (!fresh) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the token source produced no token after eviction; replaying without one would act as the backend"
+    });
+    return void 0;
+  }
+  const budgetMs = deadlineAt - Date.now();
+  if (budgetMs < MIN_REPLAY_BUDGET_MS) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `only ${budgetMs}ms of the call\u2019s deadline remained, so a replay could only time out; the rejected token was evicted, so the next call mints a fresh one`
+    });
+    return void 0;
+  }
+  return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
+}
 function makeFlyExecutor(endpoint, key, readAccessToken) {
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     const accessToken = await readAccessToken?.();
-    let res;
+    const deadlineAt = Date.now() + deadlineMs;
     try {
-      res = await fetch(endpoint + "/run", {
-        method: "POST",
-        headers: {
-          Authorization: "Bearer " + key,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
-        signal: AbortSignal.timeout(deadlineMs)
-      });
+      return await attempt(endpoint, key, args, accessToken, deadlineMs);
     } catch (err) {
-      const name = err instanceof Error ? err.name : "";
-      if (name === "TimeoutError" || name === "AbortError") {
-        throw new Error(
-          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`
-        );
+      const replay = await remintAfterGoogleRejection(
+        err,
+        accessToken,
+        args,
+        readAccessToken,
+        deadlineAt
+      );
+      if (replay === void 0) throw err;
+      const where = { credential: replay.credential, service: replay.service, endpoint };
+      logAuthTransition("replay.attempted", {
+        ...where,
+        reason: "Google rejected the access token; replaying this read once with a freshly minted one"
+      });
+      try {
+        const stdout = await attempt(endpoint, key, args, replay.token, replay.budgetMs);
+        logAuthTransition("replay.succeeded", where);
+        return stdout;
+      } catch (replayErr) {
+        logAuthTransition("replay.failed", { ...where, reason: String(replayErr) });
+        if (replayErr instanceof GogFailedError && GOOGLE_TOKEN_REJECTED_PATTERN.test(replayErr.stderr)) {
+          await replay.invalidate(replay.token);
+        }
+        throw replayErr;
       }
-      throw err;
     }
-    if (!res.ok) {
-      const body = await res.json().catch(() => null);
-      const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
+  };
+}
+async function attempt(endpoint, key, args, accessToken, deadlineMs) {
+  let res;
+  try {
+    res = await fetch(endpoint + "/run", {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + key,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
+      signal: AbortSignal.timeout(deadlineMs)
+    });
+  } catch (err) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw new RunnerTransportError(
+        `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`,
+        "transport-retryable"
+      );
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
 ${body.stderr}` : body.error : "";
-      if (res.status === RUNNER_GOG_FAILED) {
-        throw new Error(detail || "gog failed on the runner (no detail supplied)");
-      }
-      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
-        throw new Error(
-          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`
-        );
-      }
-      if (detail) {
-        throw new Error(detail);
-      }
-      throw new Error(
-        `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`
+    if (res.status === RUNNER_GOG_FAILED) {
+      throw new GogFailedError(
+        detail || "gog failed on the runner (no detail supplied)",
+        typeof body?.stderr === "string" ? body.stderr : ""
       );
     }
-    const { stdout } = await res.json();
-    return stdout;
-  };
+    if (res.status === RUNNER_BAD_KEY) {
+      logAuthTransition("runner.auth-failed", {
+        service: gogTarget(args).service,
+        endpoint,
+        reason: "the gog-runner rejected the connector\u2019s bearer token, so gog never ran and no Google credential was read; GOG_RUNNER_KEY does not match the Fly app\u2019s RUNNER_KEY"
+      });
+      throw new RunnerTransportError(
+        "gog-runner rejected the connector's bearer token, so the request never reached gog and no Google credential was involved. The Worker secret GOG_RUNNER_KEY no longer matches RUNNER_KEY on the Fly app; set them to the same value (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY) and retry.",
+        "transport-auth",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_BAD_REQUEST) {
+      throw new RunnerTransportError(
+        detail || "gog-runner rejected the request (no detail supplied)",
+        "transport-request",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+      throw new RunnerTransportError(
+        `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`,
+        "transport-retryable",
+        res.status
+      );
+    }
+    if (detail) {
+      throw new Error(detail);
+    }
+    throw new RunnerTransportError(
+      `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`,
+      "transport-retryable",
+      res.status
+    );
+  }
+  const { stdout } = await res.json();
+  return stdout;
 }
 
 // ../gogcli-mcp/src/remote-runner.ts

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/package.json

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

package/server.json

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