gsc-axi 0.1.0 → 0.1.1

package/package.json

@@ -1,20 +1,42 @@
 {
   "name": "gsc-axi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AXI-compliant Google Search Console CLI — search performance, URL inspection, and sitemaps with token-efficient TOON output",
-  "keywords": ["axi", "google-search-console", "gsc", "seo", "agent", "cli", "toon"],
+  "keywords": [
+    "axi",
+    "google-search-console",
+    "gsc",
+    "seo",
+    "agent",
+    "cli",
+    "toon"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/radityasurya/gsc-axi.git"
   },
   "homepage": "https://github.com/radityasurya/gsc-axi#readme",
-  "bugs": { "url": "https://github.com/radityasurya/gsc-axi/issues" },
+  "bugs": {
+    "url": "https://github.com/radityasurya/gsc-axi/issues"
+  },
   "license": "MIT",
   "type": "module",
-  "bin": { "gsc-axi": "bin/gsc-axi.js" },
-  "exports": { ".": "./src/cli.js" },
-  "files": ["bin", "src", "skills", "README.md", "LICENSE"],
-  "engines": { "node": ">=20" },
+  "bin": {
+    "gsc-axi": "bin/gsc-axi.js"
+  },
+  "exports": {
+    ".": "./src/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "test": "node --test",
     "build:skill": "node scripts/build-skill.mjs",

package/src/api.js

@@ -108,22 +108,28 @@ async function exchange(body, fetchImpl, context) {
   return payload.access_token;
 }
 
-let cached;
+// Keyed by scope: a token minted for the read scope cannot perform a write, and
+// `sitemaps submit` reads the existing list before it PUTs. Caching one token
+// for the process meant the write reused the read-only one and Google answered
+// "Request had insufficient authentication scopes".
+const cached = new Map();
+
 export async function accessToken(options = {}) {
   const { env = process.env, write = false, fetchImpl = fetch } = options;
-  if (cached) return cached;
+  const scope = write ? WRITE_SCOPE : READ_SCOPE;
+  if (cached.has(scope)) return cached.get(scope);
   if (!hasCredentials(env)) {
     throw new AxiError("No Google credentials in the environment", "AUTH_REQUIRED", CREDENTIAL_HELP);
   }
-  const scope = write ? WRITE_SCOPE : READ_SCOPE;
-  cached = env.GOOGLE_APPLICATION_CREDENTIALS
+  const token = env.GOOGLE_APPLICATION_CREDENTIALS
     ? await serviceAccountToken(env.GOOGLE_APPLICATION_CREDENTIALS, scope, fetchImpl)
     : await refreshTokenGrant(env, fetchImpl);
-  return cached;
+  cached.set(scope, token);
+  return token;
 }
 
 export function resetTokenCache() {
-  cached = undefined;
+  cached.clear();
 }
 
 function apiError(status, payload, path) {
@@ -137,6 +143,16 @@ function apiError(status, payload, path) {
     ]);
   }
   if (status === 403) {
+    // Google returns 403 for two unrelated causes; sending someone to the
+    // property's user list when the problem is the token's scope wastes the
+    // one piece of information the error actually carried.
+    if (/insufficient (authentication )?scope/i.test(message)) {
+      return new AxiError(message, "AUTH_ERROR", [
+        "The token was minted for read-only access but this command writes",
+        "An OAuth refresh token granted `webmasters.readonly` cannot submit sitemaps",
+        "Use a service account, or re-consent with the `webmasters` scope",
+      ]);
+    }
     return new AxiError(message, "AUTH_ERROR", [
       "This account has no access to that property",
       "Add it as a user in Search Console: Settings -> Users and permissions",

package/src/commands/index-tools.js

@@ -53,6 +53,9 @@ export async function sitesCommand(argv) {
   };
 }
 
+const verdict = (block) =>
+  block?.verdict && block.verdict !== "VERDICT_UNSPECIFIED" ? block.verdict : undefined;
+
 /** The inspection payload nests three verdicts an agent has to act on. */
 function inspection(result) {
   const index = result?.indexStatusResult ?? {};
@@ -66,8 +69,10 @@ function inspection(result) {
       ? { your_canonical: index.userCanonical }
       : {}),
     ...(index.robotsTxtState ? { robots: index.robotsTxtState } : {}),
-    ...(result?.mobileUsabilityResult?.verdict ? { mobile: result.mobileUsabilityResult.verdict } : {}),
-    ...(result?.richResultsResult?.verdict ? { rich_results: result.richResultsResult.verdict } : {}),
+    // VERDICT_UNSPECIFIED is Google's "no data for this check" — printing it
+    // implies a result was returned when none was.
+    ...(verdict(result?.mobileUsabilityResult) ? { mobile: verdict(result.mobileUsabilityResult) } : {}),
+    ...(verdict(result?.richResultsResult) ? { rich_results: verdict(result.richResultsResult) } : {}),
   };
 }
 
@@ -88,12 +93,15 @@ export async function inspectCommand(argv) {
     url,
     site,
     ...result,
-    help: result.indexed
-      ? []
-      : [
-          "A NEUTRAL or FAIL verdict means Google has not indexed this URL",
-          `Run \`${BIN} sitemaps\` to check the sitemap covering it was read`,
-        ],
+    // AXI §9: a detail view that fully answers the question takes no suggestions.
+    ...(result.indexed
+      ? {}
+      : {
+          help: [
+            "A NEUTRAL or FAIL verdict means Google has not indexed this URL",
+            `Run \`${BIN} sitemaps\` to check the sitemap covering it was read`,
+          ],
+        }),
   };
 }
 
@@ -119,8 +127,9 @@ async function sitemapsList(argv) {
       type: entry.type ?? "-",
       submitted: String(entry.lastSubmitted ?? "").slice(0, 10),
       last_read: String(entry.lastDownloaded ?? "").slice(0, 10) || "never",
-      errors: entry.errors ?? 0,
-      warnings: entry.warnings ?? 0,
+      // Google returns these as strings; numbers render bare and compare right.
+      errors: Number(entry.errors ?? 0),
+      warnings: Number(entry.warnings ?? 0),
       pending: Boolean(entry.isPending),
     })),
   };

package/src/commands/performance.js

@@ -168,12 +168,21 @@ export async function performanceCommand(argv) {
     count: `${rows.length} shown`,
     [`by_${dimension}`]: rows.map((entry) => row(entry, [dimension])),
     help: [
-      `Run \`${BIN} performance --by page\` for the pages behind these`,
+      // Suggesting the view the agent is already looking at is noise (§9).
+      ...(dimension === "page"
+        ? [`Run \`${BIN} performance --by query\` for the queries earning these`]
+        : [`Run \`${BIN} performance --by page\` for the pages behind these`]),
       `Run \`${BIN} opportunities\` for queries ranking 4-20`,
     ],
   };
 }
 
+/** Lower average position is better; unchanged within 0.05 is "flat". */
+function direction(now, before) {
+  if (Math.abs(now - before) < 0.05) return "flat";
+  return now < before ? "better" : "worse";
+}
+
 function delta(now, before) {
   if (!before) return now ? "+100%" : "0%";
   const change = ((now - before) / before) * 100;
@@ -195,7 +204,9 @@ export async function compareCommand(argv) {
     clicks: `${current.clicks} (${delta(current.clicks, prior.clicks)})`,
     impressions: `${current.impressions} (${delta(current.impressions, prior.impressions)})`,
     ctr: `${(current.ctr * 100).toFixed(1)}% (was ${(prior.ctr * 100).toFixed(1)}%)`,
-    position: `${current.position.toFixed(1)} (was ${prior.position.toFixed(1)})`,
+    // Position is the one metric where a bigger number is worse, so say so
+    // rather than leaving a reader to infer it from the direction.
+    position: `${current.position.toFixed(1)} (was ${prior.position.toFixed(1)}, ${direction(current.position, prior.position)})`,
   };
 
   if (!values.by) {