@gscdump/cli 5.8.0 → 5.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Google Search Console CLI and MCP server.
 
-Choose [Local or Hosted mode](../../docs/gscdump-cli/guides/1.start/2.choose-access.md) before login. Local mode calls Google with your own credentials: a service account or an OAuth client. Hosted mode opens gscdump.com, saves a CLI session, and reads your hosted record. Explicit `indexing inspect --yes` requests spend URL Inspections through the platform.
+Choose [Local or Hosted mode](../../docs/gscdump-cli/guides/1.start/2.choose-access.md) before login. Local mode calls Google with your own credentials: a service account or an OAuth client. Hosted mode opens gscdump.com, saves a CLI session, and reads your hosted record. Explicit `indexing inspect --yes` requests spend URL Inspections through the platform. `sitemaps inspect --engine google` reads one Sitemap live through the platform. It uses Google's API quota, without spending URL Inspections. Bing Sitemap inspection reads dated stored evidence.
 
 ```bash
 npm install -g @gscdump/cli

package/dist/commands/sitemaps.mjs

@@ -3,8 +3,10 @@ import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, plural } from
 import { createCommandContext } from "../context.mjs";
 import { HOSTED_ARGS, resolveHostedSite } from "../hosted-site.mjs";
 import { discoverLiveSitemap, loadSitemapUrls } from "../sitemap.mjs";
+import process from "node:process";
 import { defineCommand } from "citty";
 import { fetchSitemap } from "gscdump/sites";
+import { sitemapInspectQueryV1Schema } from "@gscdump/contracts/v1";
 const HOSTED_SITEMAP_ALTERNATIVE = "read a live sitemap with `gscdump sitemaps urls <sitemap-url>`";
 function hostedSitemapSite(args, name) {
 	return resolveHostedSite(args, {
@@ -260,6 +262,53 @@ const urlsCommand = defineCommand({
 		for (const u of urls) console.log(u);
 	}
 });
+const inspectCommand = defineCommand({
+	meta: {
+		name: "inspect",
+		description: "Read provider evidence for one exact Sitemap URL (hosted)"
+	},
+	args: {
+		...OUTPUT_ARGS,
+		...HOSTED_ARGS,
+		url: {
+			type: "positional",
+			required: true,
+			description: "Exact Sitemap URL"
+		},
+		engine: {
+			type: "string",
+			default: "google",
+			description: "Search Engine: google or bing"
+		}
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const query = sitemapInspectQueryV1Schema.parse({
+			searchEngine: args.engine,
+			url: args.url
+		});
+		const { client, site } = await hostedSitemapSite({
+			...args,
+			_: []
+		}, "inspect");
+		const { data } = await client.inspectSiteSitemap({
+			params: { siteId: site.siteId },
+			query
+		});
+		if (data.state._tag === "unavailable") process.exitCode = 1;
+		if (json) {
+			console.log(JSON.stringify(data, null, 2));
+			return;
+		}
+		console.log(`${data.searchEngine}: ${data.sitemapUrl}`);
+		console.log(`Evidence: ${data.state._tag}`);
+		if (data.capture._tag === "captured") console.log(`Capture: ${data.capture.capturedAt} (${data.capture.source})`);
+		if (data.state._tag === "unavailable") console.log(`Reason: ${data.state.reason}`);
+		if (data.state._tag === "listed") {
+			for (const [key, value] of Object.entries(data.state)) if (key !== "_tag") console.log(`${key}: ${value ?? "unknown"}`);
+		}
+	}
+});
 const currentCommand = defineCommand({
 	meta: {
 		name: "current",
@@ -436,6 +485,7 @@ const sitemapsCommand = defineCommand({
 		discover: discoverCommand,
 		urls: urlsCommand,
 		current: currentCommand,
+		inspect: inspectCommand,
 		history: historyCommand,
 		membership: membershipCommand,
 		lastmod: lastmodCommand,

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "5.8.0";
+var version = "5.9.0";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,16 +44,16 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@duckdb/node-api": "1.5.5-r.5",
-    "@gscdump/analysis": "^5.8.0",
-    "@gscdump/contracts": "^5.8.0",
-    "@gscdump/engine": "^5.8.0",
-    "@gscdump/engine-gsc-api": "^5.8.0",
-    "@gscdump/sdk": "^5.8.0",
+    "@gscdump/analysis": "^5.9.0",
+    "@gscdump/contracts": "^5.9.0",
+    "@gscdump/engine": "^5.9.0",
+    "@gscdump/engine-gsc-api": "^5.9.0",
+    "@gscdump/sdk": "^5.9.0",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^5.8.0",
+    "gscdump": "^5.9.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -72,7 +72,7 @@ gscdump query --site example.com -d page -f json
 ```
 
 Hosted mode can run only these commands: `sites`, `query`, `sitemaps current`, `sitemaps history`, `sitemaps membership`,
-`sitemaps lastmod`, `sitemaps export`, `indexing urls`, `indexing inspect --yes`, `indexing summary`, `indexing watch list|add|remove`,
+`sitemaps lastmod`, `sitemaps export`, `sitemaps inspect`, `indexing urls`, `indexing inspect --yes`, `indexing summary`, `indexing watch list|add|remove`,
 and the `bing` commands `login --site`, `sites`, `status`, `dump`, `inspect`, and `verify`.
 Direct Google commands need Local mode: `sync`, `inspect`, `query --live`, `analyze --live`, `report --live`,
 `sites add|get|delete|verify*`, `sitemaps list|get|submit|delete`, `indexing submit|remove|status|batch`, `entities`, and `mcp`.
@@ -468,6 +468,22 @@ gscdump indexing urls --site example.com --status not_indexed --all --format csv
 - Pages hold 100 rows by default and 500 at most. Use `--offset` for the next page, or `--all` for every page.
 - With local authentication, the command fails. Pipe `gscdump sitemaps urls <sitemap-url>` into `gscdump inspect --site <site>` instead.
 
+## Inspect one Sitemap (hosted)
+
+```sh
+gscdump sitemaps inspect https://example.com/sitemap-old.xml --site example.com --engine google --json
+gscdump sitemaps inspect https://example.com/sitemap-old.xml --site example.com --engine bing --json
+```
+
+Google reads that exact Sitemap from Search Console during the request.
+That read uses Google's API quota, without spending URL Inspections.
+Bing reads its stored provider list. Quote `capture.capturedAt` and `capture.source` with the answer.
+`listed` carries provider dates, flags, and counts. A null date means the provider supplied no date.
+`missing` means that exact Sitemap was absent at Capture time.
+`unavailable` means gscdump could not establish the evidence. The command exits with code 1.
+The command never submits a Sitemap or inspects URLs inside it.
+For Hosted MCP, use `inspect-sitemap` at `https://gscdump.com/mcp`.
+
 ## Read the coverage ladder (hosted)
 
 ```sh