@gscdump/cli 0.25.14 → 0.26.1

package/dist/index.mjs

@@ -7,6 +7,7 @@ import path, { join } from "node:path";
 import { AnalyzerCapabilityError, createEngineQuerySource, runAnalyzerFromSource } from "@gscdump/analysis";
 import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
 import { addSite, batchInspectUrls, batchRequestIndexing, createAuth, daysAgo, decodeSiteId, deleteSite, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitesWithSitemaps, formatErrorForCli, getDateRange, getIndexingMetadata, getVerificationToken, getVerifiedSite, googleSearchConsole, listVerifiedSites, normalizeSiteUrl, progressBar, requestIndexing, runSequentialBatch, siteUrlToVerificationSite, unverifySite, verificationMethodsFor, verifySite } from "gscdump";
+import { err, ok, unwrapResult } from "gscdump/result";
 import os from "node:os";
 import { cancel, confirm, isCancel, multiselect, select, text } from "@clack/prompts";
 import { createServer } from "node:http";
@@ -15,10 +16,12 @@ import { ofetch } from "ofetch";
 import fs$1 from "node:fs";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { createConsola } from "consola";
-import { SearchTypes, and, between, contains, country, date, device, eq, gsc, hour, notRegex, page, query, regex, searchAppearance } from "gscdump/query";
+import { SearchTypes, and, between, contains, country, date, device, eq, gsc, hour, isQueryError, notRegex, page, query, regex, searchAppearance } from "gscdump/query";
 import { createNodeHarness } from "@gscdump/engine/node";
 import { TABLE_DIMS, transformGscRow } from "@gscdump/engine/ingest";
 import { allTables, inferTable } from "@gscdump/engine/schema";
+import { isAnalysisError } from "@gscdump/analysis/errors";
+import { isEngineError } from "@gscdump/engine/errors";
 import { DuckDBInstance } from "@duckdb/node-api";
 import { sqlEscape } from "@gscdump/engine/sql";
 import { createEmptyTypesStore, createIndexingMetadataStore, createInspectionStore, createSitemapStore } from "@gscdump/engine/entities";
@@ -122,7 +125,7 @@ function loadEnvFromCwd() {
 	}
 	return applied;
 }
-var version = "0.25.14";
+var version = "0.26.1";
 const ALL_SEARCH_TYPES$1 = Object.values(SearchTypes);
 const VERSION = version;
 function noSubcommandSelected(parent, subNames) {
@@ -293,20 +296,34 @@ function exportToCSV(output) {
 	])}`);
 	return sections.join("\n\n");
 }
+function authErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.authError = error;
+	return exception;
+}
 const SCOPES = [
 	"https://www.googleapis.com/auth/webmasters",
 	"https://www.googleapis.com/auth/indexing",
 	"https://www.googleapis.com/auth/siteverification"
 ];
-async function loadServiceAccount(jsonPath) {
+async function loadServiceAccountResult(jsonPath) {
 	const raw = await fs.readFile(jsonPath, "utf-8");
 	const key = JSON.parse(raw);
-	if (key.type !== "service_account") throw new Error(`${jsonPath} is not a service-account key (type=${key.type})`);
-	return new JWT({
+	if (key.type !== "service_account") return err({
+		kind: "not-service-account",
+		path: jsonPath,
+		accountType: key.type,
+		message: `${jsonPath} is not a service-account key (type=${key.type})`
+	});
+	return ok(new JWT({
 		email: key.client_email,
 		key: key.private_key,
 		scopes: SCOPES
-	});
+	}));
+}
+async function loadServiceAccount(jsonPath) {
+	return unwrapResult(await loadServiceAccountResult(jsonPath), authErrorToException);
 }
 async function resolveServiceAccount(opts = {}) {
 	let p = opts.path || process.env.GSC_SERVICE_ACCOUNT_JSON || process.env.GOOGLE_APPLICATION_CREDENTIALS;
@@ -315,15 +332,24 @@ async function resolveServiceAccount(opts = {}) {
 	return loadServiceAccount(p);
 }
 async function authenticateDeviceCode(credentials) {
+	return unwrapResult(await authenticateDeviceCodeResult(credentials), authErrorToException);
+}
+async function authenticateDeviceCodeResult(credentials) {
 	const init = await ofetch("https://oauth2.googleapis.com/device/code", {
 		method: "POST",
 		body: new URLSearchParams({
 			client_id: credentials.clientId,
 			scope: SCOPES.join(" ")
 		})
-	}).catch((e) => {
-		throw new Error(`Device-code request failed: ${e.message}`);
-	});
+	}).then(ok).catch((e) => err({
+		kind: "device-code-request-failed",
+		message: `Device-code request failed: ${e.message}`,
+		cause: e
+	}));
+	if (!init.ok) return init;
+	return pollDeviceCode(credentials, init.value);
+}
+async function pollDeviceCode(credentials, init) {
 	console.log();
 	console.log(`  \x1B[1mDevice-code OAuth\x1B[0m`);
 	console.log(`  1. On any device, open: \x1B[36m${init.verification_url}\x1B[0m`);
@@ -344,17 +370,30 @@ async function authenticateDeviceCode(credentials) {
 				grant_type: "urn:ietf:params:oauth:grant-type:device_code"
 			})
 		}).catch((e) => e?.data ?? { error: "request_failed" });
-		if (res.access_token) return {
+		if (res.access_token) return ok({
 			access_token: res.access_token,
 			refresh_token: res.refresh_token,
 			expiry_date: res.expires_in ? Date.now() + res.expires_in * 1e3 : void 0
-		};
+		});
 		if (res.error === "authorization_pending" || res.error === "slow_down") continue;
-		if (res.error === "access_denied") throw new Error("User denied authorization.");
-		if (res.error === "expired_token") throw new Error("Device code expired. Re-run `gscdump auth login --no-browser`.");
-		if (res.error) throw new Error(`Device-code poll failed: ${res.error_description || res.error}`);
+		if (res.error === "access_denied") return err({
+			kind: "device-code-denied",
+			message: "User denied authorization."
+		});
+		if (res.error === "expired_token") return err({
+			kind: "device-code-expired",
+			message: "Device code expired. Re-run `gscdump auth login --no-browser`."
+		});
+		if (res.error) return err({
+			kind: "device-code-failed",
+			reason: res.error,
+			message: `Device-code poll failed: ${res.error_description || res.error}`
+		});
 	}
-	throw new Error("Device-code flow timed out.");
+	return err({
+		kind: "device-code-timed-out",
+		message: "Device-code flow timed out."
+	});
 }
 function resolveBYOK(opts = {}) {
 	const accessToken = opts.accessToken || process.env.GSC_ACCESS_TOKEN || process.env.GOOGLE_ACCESS_TOKEN;
@@ -780,6 +819,54 @@ async function createCommandContext(opts = {}) {
 		resolveSite
 	};
 }
+function extractQueryError(error) {
+	if (isQueryError(error)) return error;
+	const tagged = error.queryError;
+	return isQueryError(tagged) ? tagged : null;
+}
+function extractEngineError(error) {
+	if (isEngineError(error)) return error;
+	const tagged = error.engineError;
+	return isEngineError(tagged) ? tagged : null;
+}
+function extractAnalysisError(error) {
+	if (isAnalysisError(error)) return error;
+	const tagged = error.analysisError;
+	return isAnalysisError(tagged) ? tagged : null;
+}
+function suggestionForTypedError(error) {
+	const query = extractQueryError(error);
+	if (query) switch (query.kind) {
+		case "unresolvable-dataset": return "This breakdown spans separate stored tables. Re-run with --live to compute it from the GSC API.";
+		case "unsupported-capability": return `The local engine lacks the "${query.capability}" capability for ${query.context}. Re-run with --live.`;
+		case "missing-date-range": return "Add a date range, e.g. --start YYYY-MM-DD --end YYYY-MM-DD.";
+		case "invalid-row-limit":
+		case "invalid-start-row":
+		case "invalid-data-state":
+		case "invalid-aggregation-type":
+		case "invalid-builder-state": return "";
+	}
+	const analysis = extractAnalysisError(error);
+	if (analysis) switch (analysis.kind) {
+		case "missing-report-param": return `Report "${analysis.report}" needs --${analysis.param}.`;
+		case "missing-comparison-window": return `Report "${analysis.report}" is a comparison report; pass --vs prev-period (or --vs yoy).`;
+		case "missing-brand-terms": return "Pass --brand-terms to segment branded vs non-branded queries.";
+		case "unknown-report": return `Unknown report. Available: ${analysis.available.join(", ")}.`;
+		case "unknown-analyzer": return "Run `gscdump report list` to see available reports/analyzers.";
+		case "required-step-failed": return suggestionForTypedError(analysis.cause);
+	}
+	const engine = extractEngineError(error);
+	if (engine) switch (engine.kind) {
+		case "attached-table-missing": return `Local store is missing table(s): ${engine.missing.join(", ")}. Run \`gscdump sync\` first, or pass --live.`;
+		case "analyzer-not-found":
+		case "analyzer-capability-missing": return "This analysis is not available for the chosen source. Re-run with --live.";
+		case "invalid-year-month":
+		case "invalid-snapshot-filename":
+		case "invalid-schema-identifier": return "The local store appears corrupt. Re-run `gscdump sync` to rebuild it.";
+		default: return "";
+	}
+	return "";
+}
 var LocalStoreUnsupportedError = class extends Error {
 	tool;
 	mode;
@@ -799,6 +886,11 @@ async function gscErrorHandler(error) {
 		process.exit(1);
 	}
 	console.error(formatErrorForCli(error));
+	const typedHint = suggestionForTypedError(error);
+	if (typedHint) {
+		console.error();
+		console.error(typedHint);
+	}
 	if (isAuthError(error)) {
 		console.error();
 		console.error(await formatAuthProvenance());
@@ -823,12 +915,15 @@ function pickLocalSite(siteUrls, hint) {
 	if (exact) return exact;
 	return siteUrls.find((s) => s.includes(hint) || hint.includes(s)) ?? null;
 }
-function makeRunAnalysis(source, mode) {
-	return (params) => runAnalyzerFromSource(source, params, defaultAnalyzerRegistry).catch((e) => {
-		if (e instanceof AnalyzerCapabilityError) throw new LocalStoreUnsupportedError(params.type, mode);
+async function runAnalysisResult(source, params, mode) {
+	return runAnalyzerFromSource(source, params, defaultAnalyzerRegistry).then(ok).catch((e) => {
+		if (e instanceof AnalyzerCapabilityError) return err(new LocalStoreUnsupportedError(params.type, mode));
 		throw e;
 	});
 }
+function makeRunAnalysis(source, mode) {
+	return async (params) => unwrapResult(await runAnalysisResult(source, params, mode), (e) => e);
+}
 async function resolveAnalysisSource(args) {
 	const isLive = !!args.live;
 	const format = args.json ? "json" : args.format ? String(args.format) : "table";
@@ -3748,17 +3843,10 @@ async function probeReachable(url) {
 	}).then(() => true).catch(() => false);
 }
 async function requestIndexing$1(input, ctx) {
-	return requestIndexing(ctx.client, input.url, { type: input.type || "URL_UPDATED" }).catch((e) => ({
-		url: input.url,
-		type: input.type || "URL_UPDATED",
-		error: e.message
-	}));
+	return requestIndexing(ctx.client, input.url, { type: input.type || "URL_UPDATED" });
 }
 async function getIndexingStatus(input, ctx) {
-	return getIndexingMetadata(ctx.client, input.url).catch((e) => ({
-		url: input.url,
-		error: e.message
-	}));
+	return getIndexingMetadata(ctx.client, input.url);
 }
 async function batchRequestIndexing$1(input, ctx) {
 	const results = await batchRequestIndexing(ctx.client, input.urls, {
@@ -3779,6 +3867,87 @@ async function batchInspectUrls$1(input, ctx) {
 		notIndexed: results.filter((r) => !r.isIndexed).length
 	};
 }
+const PERIODS = [
+	"7d",
+	"28d",
+	"30d",
+	"90d",
+	"180d",
+	"365d",
+	"mtd",
+	"ytd",
+	"custom"
+];
+const COMPARISONS = [
+	"none",
+	"prev-period",
+	"yoy"
+];
+const mcpHandlerErrors = {
+	unknownReport(id, available) {
+		return {
+			kind: "unknown-report",
+			id,
+			available,
+			message: `Unknown report id "${id}". Available: ${available.join(", ")}`
+		};
+	},
+	unknownPeriod(value) {
+		return {
+			kind: "unknown-period",
+			value,
+			supported: PERIODS,
+			message: `Unknown period "${value}". Supported: ${PERIODS.join(", ")}.`
+		};
+	},
+	unknownComparison(value) {
+		return {
+			kind: "unknown-comparison",
+			value,
+			supported: COMPARISONS,
+			message: `Unknown comparison "${value}". Supported: ${COMPARISONS.join(", ")}.`
+		};
+	},
+	noValidDimension() {
+		return {
+			kind: "no-valid-dimension",
+			message: "At least one valid dimension required"
+		};
+	}
+};
+function mcpHandlerErrorToException(error) {
+	const exception = new Error(error.message);
+	exception.mcpHandlerError = error;
+	return exception;
+}
+function enrichToolError(error) {
+	const query = asQueryError(error);
+	if (query) return /* @__PURE__ */ new Error(`[query:${query.kind}] ${query.message}`);
+	const analysis = asAnalysisError(error);
+	if (analysis) {
+		const cause = analysis.kind === "required-step-failed" ? asEngineError(analysis.cause) : null;
+		const tail = cause ? ` (engine:${cause.kind})` : "";
+		return /* @__PURE__ */ new Error(`[analysis:${analysis.kind}]${tail} ${analysis.message}`);
+	}
+	const engine = asEngineError(error);
+	if (engine) return /* @__PURE__ */ new Error(`[engine:${engine.kind}] ${engine.message}`);
+	return null;
+}
+function asQueryError(error) {
+	if (isQueryError(error)) return error;
+	const tagged = error?.queryError;
+	return isQueryError(tagged) ? tagged : null;
+}
+function asEngineError(error) {
+	if (isEngineError(error)) return error;
+	const tagged = error?.engineError;
+	return isEngineError(tagged) ? tagged : null;
+}
+function asAnalysisError(error) {
+	if (isAnalysisError(error)) return error;
+	const tagged = error?.analysisError;
+	return isAnalysisError(tagged) ? tagged : null;
+}
 const PERIOD_ALIASES$1 = {
 	"7d": "last-7d",
 	"28d": "last-28d",
@@ -3806,13 +3975,13 @@ function listReports() {
 		argsSpec: r.argsSpec
 	}));
 }
-async function runReportHandler(input, ctx) {
+async function runReportHandlerResult(input, ctx) {
 	const report = defaultReportRegistry.getReport(input.id);
-	if (!report) throw new Error(`Unknown report id "${input.id}". Available: ${defaultReportRegistry.listReportIds().join(", ")}`);
+	if (!report) return err(mcpHandlerErrors.unknownReport(input.id, defaultReportRegistry.listReportIds()));
 	const preset = input.period ? PERIOD_ALIASES$1[input.period.toLowerCase()] ?? null : report.defaultPeriod;
-	if (!preset) throw new Error(`Unknown period "${input.period}". Supported: 7d, 28d, 30d, 90d, 180d, 365d, mtd, ytd, custom.`);
+	if (!preset) return err(mcpHandlerErrors.unknownPeriod(input.period ?? ""));
 	const comparison = input.comparison ? COMPARISON_ALIASES$1[input.comparison.toLowerCase()] ?? null : report.defaultComparison;
-	if (!comparison) throw new Error(`Unknown comparison "${input.comparison}". Supported: none, prev-period, yoy.`);
+	if (!comparison) return err(mcpHandlerErrors.unknownComparison(input.comparison ?? ""));
 	const window = resolveWindow({
 		preset,
 		comparison,
@@ -3825,7 +3994,7 @@ async function runReportHandler(input, ctx) {
 	};
 	const params = {};
 	if (input.maxFindings != null) params.maxFindings = input.maxFindings;
-	return runReport(report, {
+	return ok(await runReport(report, {
 		source: createGscApiQuerySource({
 			client: ctx.client,
 			siteUrl: input.siteUrl
@@ -3837,7 +4006,12 @@ async function runReportHandler(input, ctx) {
 			params,
 			registryVersion: defaultReportRegistry.version
 		}
-	});
+	}));
+}
+async function runReportHandler(input, ctx) {
+	return unwrapResult(await runReportHandlerResult(input, ctx).catch((thrown) => {
+		throw enrichToolError(thrown) ?? thrown;
+	}), mcpHandlerErrorToException);
 }
 async function listSitesWithSitemaps(_input, ctx) {
 	return fetchSitesWithSitemaps(ctx.client);
@@ -4867,6 +5041,11 @@ async function writeOutput(opts) {
 function isKnownTable$1(name) {
 	return allTables().includes(name);
 }
+function reportFlagErrorToException(error) {
+	const exception = new Error(error.message);
+	exception.reportFlagError = error;
+	return exception;
+}
 const REPORT_IDS = defaultReportRegistry.listReportIds();
 const PERIOD_ALIASES = {
 	"7d": "last-7d",
@@ -4893,17 +5072,31 @@ const COMPARISON_ALIASES = {
 	"prior-period": "prev-period",
 	"yoy": "yoy"
 };
-function resolvePeriod(input, fallback) {
-	if (!input) return fallback;
+function resolvePeriodResult(input, fallback) {
+	if (!input) return ok(fallback);
 	const preset = PERIOD_ALIASES[input.toLowerCase()];
-	if (!preset) throw new Error(`Unknown --period "${input}". Supported: 7d, 28d, 30d, 90d, 180d, 365d, mtd, ytd, custom.`);
-	return preset;
+	if (!preset) return err({
+		kind: "unknown-period",
+		value: input,
+		message: `Unknown --period "${input}". Supported: 7d, 28d, 30d, 90d, 180d, 365d, mtd, ytd, custom.`
+	});
+	return ok(preset);
 }
-function resolveComparison(input, fallback) {
-	if (!input) return fallback;
+function resolvePeriod(input, fallback) {
+	return unwrapResult(resolvePeriodResult(input, fallback), reportFlagErrorToException);
+}
+function resolveComparisonResult(input, fallback) {
+	if (!input) return ok(fallback);
 	const mode = COMPARISON_ALIASES[input.toLowerCase()];
-	if (!mode) throw new Error(`Unknown --vs "${input}". Supported: none, prev-period, yoy.`);
-	return mode;
+	if (!mode) return err({
+		kind: "unknown-comparison",
+		value: input,
+		message: `Unknown --vs "${input}". Supported: none, prev-period, yoy.`
+	});
+	return ok(mode);
+}
+function resolveComparison(input, fallback) {
+	return unwrapResult(resolveComparisonResult(input, fallback), reportFlagErrorToException);
 }
 function reportArgsToCitty(spec) {
 	const out = {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "0.25.14",
+  "version": "0.26.1",
   "description": "CLI for Google Search Console - dump, query, and run MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -35,18 +35,18 @@
     "dist"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.5.0",
+    "@clack/prompts": "^1.5.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
-    "google-auth-library": "^10.6.2",
+    "google-auth-library": "^10.7.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.0",
     "zod": "^4.4.3",
-    "@gscdump/analysis": "0.25.14",
-    "@gscdump/engine": "0.25.14",
-    "@gscdump/engine-gsc-api": "0.25.14",
-    "gscdump": "0.25.14"
+    "gscdump": "0.26.1",
+    "@gscdump/engine-gsc-api": "0.26.1",
+    "@gscdump/analysis": "0.26.1",
+    "@gscdump/engine": "0.26.1"
   },
   "devDependencies": {
     "@duckdb/node-api": "1.5.1-r.2",