@gscdump/cli 5.0.0 → 5.2.0

package/dist/commands/indexing.mjs

@@ -1,3 +1,4 @@
+import { commandLineError } from "../stop.mjs";
 import { indexingCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, readUrlList } from "../utils.mjs";
 import { createCommandContext } from "../context.mjs";
@@ -5,7 +6,6 @@ import { loadSitemapUrls } from "../sitemap.mjs";
 import { indexingSummaryCommand } from "./indexing-summary.mjs";
 import { indexingUrlsCommand } from "./indexing-urls.mjs";
 import { indexingWatchCommand } from "./indexing-watch.mjs";
-import process from "node:process";
 import { defineCommand } from "citty";
 import { batchRequestIndexing, getIndexingMetadata, requestIndexing, runSequentialBatch } from "gscdump/indexing";
 const RETRIES_ARG = { retries: {
@@ -16,10 +16,7 @@ async function resolveUrlSource(args) {
 	const fromSitemap = args["from-sitemap"];
 	if (fromSitemap) {
 		const result = await loadSitemapUrls(String(fromSitemap));
-		if (result._tag === "error") {
-			logger.error(`Sitemap fetch failed: ${result.message}`);
-			process.exit(1);
-		}
+		if (result._tag === "error") throw new Error(`Sitemap fetch failed: ${result.message}`);
 		if (!result.value.complete) logger.warn("Sitemap walk was incomplete; indexing only the URLs that were read");
 		return result.value.urls;
 	}
@@ -214,20 +211,10 @@ const batchCommand = defineCommand({
 		const delayMs = parseIntegerOption(args["delay-ms"], "--delay-ms", 0) ?? 100;
 		const concurrency = parseIntegerOption(args.concurrency, "--concurrency") ?? 1;
 		const urls = await resolveUrlSource(args);
-		if (urls.length === 0) {
-			logger.error("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
-			process.exit(1);
-		}
+		if (urls.length === 0) throw commandLineError("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
 		const type = String(args.type);
-		if (type !== "URL_UPDATED" && type !== "URL_DELETED") {
-			logger.error(`Invalid --type: ${type}. Use URL_UPDATED or URL_DELETED.`);
-			process.exit(1);
-		}
-		if (urls.length > INDEXING_DAILY_QUOTA && !args.yes && !args.json) {
-			logger.warn(`Submitting ${urls.length} URLs but the Indexing API daily quota is ${INDEXING_DAILY_QUOTA}/day.`);
-			logger.warn(`Excess submissions will fail with quota errors. Pass --yes to proceed anyway.`);
-			process.exit(1);
-		}
+		if (type !== "URL_UPDATED" && type !== "URL_DELETED") throw commandLineError(`Invalid --type: ${type}. Use URL_UPDATED or URL_DELETED.`);
+		if (urls.length > INDEXING_DAILY_QUOTA && !args.yes && !args.json) throw commandLineError(`Submitting ${urls.length} URLs but the Indexing API daily quota is ${INDEXING_DAILY_QUOTA}/day. Excess submissions will fail with quota errors. Pass --yes to proceed anyway.`);
 		if (urls.length > INDEXING_DAILY_QUOTA && !args.json && !args.quiet) logger.warn(`Proceeding with ${urls.length} URLs (over the ${INDEXING_DAILY_QUOTA}/day quota). Excess will fail.`);
 		const ctx = await createCommandContext({
 			needsAuth: true,
@@ -290,10 +277,7 @@ const batchStatusCommand = defineCommand({
 		const delayMs = parseIntegerOption(args["delay-ms"], "--delay-ms", 0) ?? 100;
 		const concurrency = parseIntegerOption(args.concurrency, "--concurrency") ?? 1;
 		const urls = await resolveUrlSource(args);
-		if (urls.length === 0) {
-			logger.error("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
-			process.exit(1);
-		}
+		if (urls.length === 0) throw commandLineError("No URLs provided. Pass URLs as args, --file, --from-sitemap, or stdin.");
 		const ctx = await createCommandContext({
 			needsAuth: true,
 			fetchOptions: { retry }

package/dist/commands/init.mjs

@@ -1,6 +1,6 @@
-import { initCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
 import { saveAuthentication } from "../auth-state.mjs";
+import { initCommandMeta } from "../command-meta.mjs";
 import { defaultDataDir, loadConfig, saveConfig } from "../config.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
 import { ACCESS_NOT_SET_UP, getAuth, loadTokens, resolveBYOK, resolveServiceAccount } from "../auth.mjs";
@@ -100,10 +100,7 @@ const initCommand = defineCommand({
 			return;
 		}
 		if (!canPrompt()) {
-			if (!await loadTokens()) {
-				logger.error(`Init cannot prompt without a terminal.\n${ACCESS_NOT_SET_UP}`);
-				process.exit(1);
-			}
+			if (!await loadTokens()) throw new Error(`Init cannot prompt without a terminal.\n${ACCESS_NOT_SET_UP}`);
 			await saveConfig({
 				...config,
 				dataDir: config.dataDir ?? defaultDataDir()
@@ -114,7 +111,7 @@ const initCommand = defineCommand({
 			return;
 		}
 		console.log();
-		console.log("  \x1B[1mWelcome to GSCDump!\x1B[0m");
+		console.log("  \x1B[1mWelcome to gscdump\x1B[0m");
 		console.log("  \x1B[90mGoogle Search Console data extraction CLI\x1B[0m");
 		console.log();
 		const dataDir = args.store ? await promptDataDir(config.dataDir) : void 0;

package/dist/commands/mcp.mjs

@@ -1,5 +1,5 @@
-import { mcpCommandMeta } from "../command-meta.mjs";
 import { runWithCliRuntime, useCliRuntime } from "../runtime.mjs";
+import { mcpCommandMeta } from "../command-meta.mjs";
 import { VERSION } from "../utils.mjs";
 import { probeAuth } from "../auth.mjs";
 import { createCommandContext } from "../context.mjs";

package/dist/commands/papercut.mjs

@@ -1,5 +1,5 @@
-import { papercutCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
+import { papercutCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
 import { buildPapercutBody, resolvePapercutUrl, submitPapercut } from "../papercut.mjs";
 import process from "node:process";
@@ -62,10 +62,7 @@ const papercutCommand = defineCommand({
 			fetch: globalThis.fetch,
 			url
 		});
-		if (result._tag === "Err") {
-			logger.error(result.message);
-			process.exit(1);
-		}
+		if (result._tag === "Err") throw new Error(result.message);
 		if (json) {
 			console.log(JSON.stringify(result.receipt));
 			return;

package/dist/commands/profile.mjs

@@ -1,5 +1,6 @@
-import { profileCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.mjs";
+import { commandLineError } from "../stop.mjs";
+import { profileCommandMeta } from "../command-meta.mjs";
 import { getConfigDir, setConfigDir } from "../config.mjs";
 import { resolveCliEnvironment } from "../environment.mjs";
 import { ACTIVE_MARKER, PROFILES_DIR, ROOT_DIR, getProfileDir, readActiveMarkerSync } from "./profile-selection.mjs";
@@ -100,10 +101,7 @@ const pathCmd = defineCommand({
 	} },
 	async run({ args }) {
 		const name = args.name ? String(args.name) : resolveActiveProfile();
-		if (!name) {
-			logger.error("No profile specified and none active (set --profile, GSCDUMP_PROFILE, or run `gscdump profile use <name>`)");
-			process.exit(1);
-		}
+		if (!name) throw commandLineError("No profile specified and none active (set --profile, GSCDUMP_PROFILE, or run `gscdump profile use <name>`)");
 		console.log(getProfileDir(name));
 	}
 });
@@ -135,11 +133,7 @@ const useCmd = defineCommand({
 		applyOutputMode(args);
 		const name = String(args.name);
 		const dir = getProfileDir(name);
-		if (!await fs.stat(dir).then(() => true).catch(() => false)) {
-			logger.error(`Profile not found: ${name}`);
-			logger.info(`Create it with: gscdump profile create ${name}`);
-			process.exit(1);
-		}
+		if (!await fs.stat(dir).then(() => true).catch(() => false)) throw new Error(`Profile not found: ${name}. Create it with: gscdump profile create ${name}`);
 		await setActiveProfile(name);
 		logger.success(`Active profile: ${name}`);
 	}
@@ -207,10 +201,7 @@ const deleteCmd = defineCommand({
 		applyOutputMode(args);
 		const name = String(args.name);
 		const dir = getProfileDir(name);
-		if (!await fs.stat(dir).then(() => true).catch(() => false)) {
-			logger.error(`Profile not found: ${name}`);
-			process.exit(1);
-		}
+		if (!await fs.stat(dir).then(() => true).catch(() => false)) throw new Error(`Profile not found: ${name}`);
 		if (!args.yes) {
 			const ok = await confirm({
 				message: `Delete profile "${name}" at ${dir}? Tokens and config will be lost.`,

package/dist/commands/query.mjs

@@ -1,10 +1,11 @@
-import { queryCommandMeta } from "../command-meta.mjs";
-import { queryHostedRows } from "../hosted-query.mjs";
 import { useCliRuntime } from "../runtime.mjs";
+import { commandLineError } from "../stop.mjs";
 import { resolveAuthentication } from "../auth-state.mjs";
+import { queryCommandMeta } from "../command-meta.mjs";
 import { loadConfig } from "../config.mjs";
+import { queryHostedRows } from "../hosted-query.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
-import { ALL_SEARCH_TYPES, logger, parseSearchType, toCSV } from "../utils.mjs";
+import { ALL_SEARCH_TYPES, logger, parseSearchType, setJsonOutput, toCSV } from "../utils.mjs";
 import { allTables } from "../local-store.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import { decideRoute, describeStop, liveNote, readRouteState, readSiteStates, resolveReadSite, stopAtRoute } from "../route.mjs";
@@ -211,10 +212,8 @@ const queryCommand = defineCommand({
 	async run({ args }) {
 		const ctxConfig = await loadConfig();
 		const format = args.format ?? ctxConfig.defaultFormat ?? "json";
-		if (format !== "json" && format !== "csv" && format !== "table") {
-			logger.error("Invalid --format. Use table, json, or csv.");
-			process.exit(1);
-		}
+		if (format !== "json" && format !== "csv" && format !== "table") throw commandLineError("Invalid --format. Use table, json, or csv.");
+		setJsonOutput(format === "json");
 		if (args.sql || args.schema) {
 			await runSqlMode({
 				mode: args.schema ? { kind: "schema" } : {
@@ -233,31 +232,19 @@ const queryCommand = defineCommand({
 		const dimNames = await resolveDimensions(args);
 		const windowFlags = await promptRange(args);
 		const invalidWindow = checkWindowFlags(windowFlags);
-		if (invalidWindow) {
-			logger.error(invalidWindow.message);
-			process.exit(1);
-		}
+		if (invalidWindow) throw commandLineError(invalidWindow.message);
 		await promptFilters(args);
 		const limitArg = String(args.limit ?? ctxConfig.defaultLimit ?? 1e3);
 		const rowLimit = Number(limitArg);
-		if (!POSITIVE_INTEGER_RE.test(limitArg) || !Number.isSafeInteger(rowLimit) || rowLimit < 1) {
-			logger.error("Invalid --limit. Use a positive safe integer, such as --limit 1000.");
-			process.exit(1);
-		}
+		if (!POSITIVE_INTEGER_RE.test(limitArg) || !Number.isSafeInteger(rowLimit) || rowLimit < 1) throw commandLineError("Invalid --limit. Use a positive safe integer, such as --limit 1000.");
 		const filters = parseFilterArgs(args);
 		const searchType = parseSearchType(args.type ?? ctxConfig.defaultSearchType, "--type");
 		const localSearchType = searchType ?? "web";
 		const dataState = args["data-state"] ? String(args["data-state"]) : ctxConfig.defaultDataState;
 		const aggregationType = args["aggregation-type"] ? String(args["aggregation-type"]) : void 0;
 		const filterDims = filterDimensions(filters);
-		if (dataState && !DATA_STATES.includes(dataState)) {
-			logger.error(`Invalid --data-state: ${dataState}. Allowed: ${DATA_STATES.join(", ")}`);
-			process.exit(1);
-		}
-		if (aggregationType && !AGGREGATION_TYPES.includes(aggregationType)) {
-			logger.error(`Invalid --aggregation-type: ${aggregationType}. Allowed: ${AGGREGATION_TYPES.join(", ")}`);
-			process.exit(1);
-		}
+		if (dataState && !DATA_STATES.includes(dataState)) throw commandLineError(`Invalid --data-state: ${dataState}. Allowed: ${DATA_STATES.join(", ")}`);
+		if (aggregationType && !AGGREGATION_TYPES.includes(aggregationType)) throw commandLineError(`Invalid --aggregation-type: ${aggregationType}. Allowed: ${AGGREGATION_TYPES.join(", ")}`);
 		const forceLive = Boolean(args.live);
 		if (!forceLive && (await resolveAuthentication())._tag === "Hosted") {
 			if (dataState || aggregationType) logger.warn("--data-state / --aggregation-type are ignored without --live");
@@ -341,7 +328,6 @@ const queryCommand = defineCommand({
 			auth
 		});
 		const route = decideRoute(req, routeState);
-		const json = format === "json";
 		if (route.kind === "live") {
 			const live = await connect();
 			const siteUrl = site ?? await live.resolveSite(void 0);
@@ -406,7 +392,7 @@ const queryCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, routeState.auth, { json });
+		if (route.kind === "syncing" || route.kind === "prompt") stopAtRoute(route, req, routeState.auth);
 		if (dataState || aggregationType) logger.warn("--data-state / --aggregation-type are ignored without --live");
 		const siteUrl = site;
 		if (!args.quiet) logger.debug(`Querying ${siteUrl} from local Parquet store...`);
@@ -417,10 +403,7 @@ const queryCommand = defineCommand({
 			table,
 			searchType: localSearchType,
 			...probe ? { profiler: probe.profiler } : {}
-		}, state).catch((e) => {
-			logger.error(`Query failed: ${e.message}`);
-			process.exit(1);
-		});
+		}, state);
 		if (probe) logProfile(probe.spans);
 		await writeOutput({
 			output: {
@@ -443,10 +426,7 @@ const queryCommand = defineCommand({
 async function resolveDimensions(args) {
 	if (args.dimensions != null) {
 		const dimensions = String(args.dimensions).split(",").map((d) => d.trim());
-		if (dimensions.some((d) => !DIMENSIONS.includes(d))) {
-			logger.error(`Invalid --dimensions. Use a comma-separated list from: ${DIMENSIONS.join(", ")}.`);
-			process.exit(1);
-		}
+		if (dimensions.some((d) => !DIMENSIONS.includes(d))) throw commandLineError(`Invalid --dimensions. Use a comma-separated list from: ${DIMENSIONS.join(", ")}.`);
 		return [...new Set(dimensions)];
 	}
 	if (args.interactive) {
@@ -500,10 +480,7 @@ async function promptRange(args) {
 }
 function windowOrExit(flags, anchor) {
 	const window = parseWindowFlags(flags, DEFAULT_WINDOW, anchor);
-	if (!window.ok) {
-		logger.error(window.error.message);
-		process.exit(1);
-	}
+	if (!window.ok) throw commandLineError(window.error.message);
 	return window.value;
 }
 async function promptFilters(args) {
@@ -595,7 +572,7 @@ async function runSqlMode(opts) {
 			});
 			if (route.kind === "syncing" || route.kind === "prompt") {
 				views.close();
-				stopAtRoute(route, req, routeState.auth, { json: opts.format === "json" });
+				stopAtRoute(route, req, routeState.auth);
 			}
 		}
 	}
@@ -620,8 +597,7 @@ async function runSql(views, sql) {
 	for (const warning of warnings) logger.warn(warning);
 	return {
 		...await views.run(sql).catch((e) => {
-			logger.error(`SQL failed: ${e.message}`);
-			process.exit(1);
+			throw new Error(`SQL failed: ${e.message}`, { cause: e });
 		}),
 		warnings
 	};

package/dist/commands/report.mjs

@@ -1,6 +1,6 @@
 import { reportCommandMeta } from "../command-meta.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
-import { logger, parseFetchBudget } from "../utils.mjs";
+import { logger, parseFetchBudget, setJsonOutput } from "../utils.mjs";
 import { COMPARISON_FLAGS, PERIOD_FLAGS, parseWindowFlags, windowFlagErrorToException } from "../window.mjs";
 import { analysisNeeds, analyzerSources, analyzerTables, resolveAnalysisSource } from "../analysis-local.mjs";
 import { renderCliReport } from "../render/report.mjs";
@@ -127,6 +127,7 @@ function makeReportCommand(report) {
 			...reportArgs
 		},
 		async run({ args }) {
+			setJsonOutput(Boolean(args.json));
 			const flags = windowFlags(args);
 			const params = buildReportParams(report, args);
 			const fetchBudget = parseFetchBudget(args["fetch-budget"]);
@@ -158,7 +159,6 @@ function makeReportCommand(report) {
 			const { source, siteUrl, anchor, isLive } = await resolveAnalysisSource({
 				site: args.site,
 				live: !!args.live,
-				json: !!args.json,
 				label: `report ${report.id}`,
 				types: provisional.map((step) => step.type),
 				sources: reportSources(provisional),

package/dist/commands/sitemaps.mjs

@@ -1,9 +1,8 @@
 import { sitemapsCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, plural } from "../utils.mjs";
 import { createCommandContext } from "../context.mjs";
-import { discoverLiveSitemap, loadSitemapUrls } from "../sitemap.mjs";
 import { HOSTED_ARGS, resolveHostedSite } from "../hosted-site.mjs";
-import process from "node:process";
+import { discoverLiveSitemap, loadSitemapUrls } from "../sitemap.mjs";
 import { defineCommand } from "citty";
 import { fetchSitemap } from "gscdump/sites";
 const HOSTED_SITEMAP_ALTERNATIVE = "read a live sitemap with `gscdump sitemaps urls <sitemap-url>`";
@@ -207,14 +206,8 @@ const discoverCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		if (discovery._tag === "incomplete") {
-			logger.error(`Sitemap discovery was incomplete: ${discovery.failures[0] ?? "unknown failure"}`);
-			process.exit(1);
-		}
-		if (!url) {
-			logger.warn(`No sitemap discovered for ${domain}`);
-			process.exit(1);
-		}
+		if (discovery._tag === "incomplete") throw new Error(`Sitemap discovery was incomplete: ${discovery.failures[0] ?? "unknown failure"}`);
+		if (!url) throw new Error(`No sitemap discovered for ${domain}`);
 		logger.success(`Discovered sitemap: ${url}`);
 	}
 });

package/dist/commands/sites.mjs

@@ -1,5 +1,6 @@
+import { commandLineError } from "../stop.mjs";
+import { connectSiteStep, formatHostedSync, getHostedAccount, localModeRequired, resolveAuthentication, siteManagerOf } from "../auth-state.mjs";
 import { sitesCommandMeta } from "../command-meta.mjs";
-import { LOCAL_MODE_REQUIRED, formatHostedSync, getHostedAccount, resolveAuthentication } from "../auth-state.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, plural } from "../utils.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import process from "node:process";
@@ -20,16 +21,10 @@ function pickDefaultMethod(siteUrl) {
 }
 function validateMethod(siteUrl, method) {
 	const upper = method.toUpperCase();
-	if (!ALL_METHODS.includes(upper)) {
-		logger.error(`Invalid --method: ${method}. Valid: ${ALL_METHODS.join(", ")}`);
-		process.exit(1);
-	}
+	if (!ALL_METHODS.includes(upper)) throw commandLineError(`Invalid --method: ${method}. Valid: ${ALL_METHODS.join(", ")}`);
 	const site = siteUrlToVerificationSite(siteUrl);
 	const allowed = verificationMethodsFor(site);
-	if (!allowed.includes(upper)) {
-		logger.error(`Method ${upper} not valid for ${site.type === "INET_DOMAIN" ? "domain" : "URL-prefix"} property "${siteUrl}". Valid: ${allowed.join(", ")}`);
-		process.exit(1);
-	}
+	if (!allowed.includes(upper)) throw commandLineError(`Method ${upper} not valid for ${site.type === "INET_DOMAIN" ? "domain" : "URL-prefix"} property "${siteUrl}". Valid: ${allowed.join(", ")}`);
 	return upper;
 }
 function printPlacementInstructions(method, siteUrl, token) {
@@ -422,8 +417,8 @@ const LIST_ARGS = {
 	}
 };
 async function runListHostedSites(args, authentication) {
-	if (args["with-sitemaps"] || args["owner-only"]) throw new Error(`--with-sitemaps and --owner-only read Search Console permissions.\n${LOCAL_MODE_REQUIRED}`);
-	const { sites } = await getHostedAccount(authentication);
+	if (args["with-sitemaps"] || args["owner-only"]) throw localModeRequired("--with-sitemaps and --owner-only read Search Console permissions.");
+	const { sites, issuer } = await getHostedAccount(authentication);
 	if (args.json) {
 		console.log(JSON.stringify(sites.map((site) => ({
 			siteId: site.siteId,
@@ -438,7 +433,7 @@ async function runListHostedSites(args, authentication) {
 		return;
 	}
 	if (sites.length === 0) {
-		logger.warn("Your hosted record has no Sites. Connect a Site at https://gscdump.com/app/onboarding?step=connect-sites.");
+		logger.warn(`Your hosted record has no Sites. ${connectSiteStep(siteManagerOf(authentication, issuer))}`);
 		return;
 	}
 	logger.success(`Found ${plural(sites.length, "hosted Site", "hosted Sites")}:`);

package/dist/commands/skill.mjs

@@ -33,10 +33,7 @@ const installCommand = defineCommand({
 			homeDirectory: os.homedir(),
 			target: args.target
 		});
-		if (result._tag === "Err") {
-			logger.error(result.message);
-			process.exit(1);
-		}
+		if (result._tag === "Err") throw new Error(result.message);
 		if (json) {
 			console.log(JSON.stringify(result.installation));
 			return;

package/dist/commands/sync.mjs

@@ -395,10 +395,7 @@ const syncCommand = defineCommand({
 				siteUrls.push(siteUrl);
 				continue;
 			}
-			if (!args["all-sites"]) {
-				logger.error(formatSiteIdCollision(claim.error));
-				process.exit(1);
-			}
+			if (!args["all-sites"]) throw new Error(formatSiteIdCollision(claim.error));
 			logger.warn(`Skipped ${siteUrl}. ${formatSiteIdCollision(claim.error)}`);
 		}
 		const latest = getLatestGscDate();
@@ -416,10 +413,7 @@ const syncCommand = defineCommand({
 				now: Date.now(),
 				isAlive: isProcessAlive
 			});
-			if (existing.kind === "running") {
-				logger.error(`Another sync is running (pid ${existing.record.pid}, ${existing.record.done}/${existing.record.planned} days). Wait for it to finish, or run \`gscdump sync --status\`.`);
-				process.exit(1);
-			}
+			if (existing.kind === "running") throw new Error(`Another sync is running (pid ${existing.record.pid}, ${existing.record.done}/${existing.record.planned} days). Wait for it to finish, or run \`gscdump sync --status\`.`);
 		}
 		const ledger = await openQuotaLedger({ dataDir: store.dataDir });
 		const pacer = createRequestPacer({

package/dist/config.mjs

@@ -2,8 +2,8 @@ import { useCliRuntime } from "./runtime.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { SearchTypes } from "gscdump/query";
 import os from "node:os";
+import { SearchTypes } from "gscdump/query";
 function setConfigDir(dir) {
 	useCliRuntime().configDir = dir;
 }

package/dist/context.mjs

@@ -1,6 +1,6 @@
-import { openQuotaLedger, quotaFetchOptions } from "./quota-ledger.mjs";
-import { LOCAL_MODE_REQUIRED, resolveAuthentication } from "./auth-state.mjs";
+import { localModeRequired, resolveAuthentication } from "./auth-state.mjs";
 import { loadResolvedConfig } from "./config.mjs";
+import { openQuotaLedger, quotaFetchOptions } from "./quota-ledger.mjs";
 import { resolveAuth } from "./auth.mjs";
 import { createLocalStore } from "./local-store.mjs";
 import { listStoreSites } from "./store-sites.mjs";
@@ -12,7 +12,7 @@ const FULL_SITE_URL_RE = /^(?:sc-domain:|https?:\/\/)/i;
 async function createCommandContext(opts = {}) {
 	const { needsAuth = false, needsStore = false, interactive = false, byok, quota = true } = opts;
 	const { config, dataDir } = await loadResolvedConfig();
-	if (needsAuth && (await resolveAuthentication())._tag === "Hosted") throw new Error(LOCAL_MODE_REQUIRED);
+	if (needsAuth && (await resolveAuthentication())._tag === "Hosted") throw localModeRequired();
 	const fetchOptions = needsAuth && quota ? quotaFetchOptions(await openQuotaLedger({ dataDir }), opts.fetchOptions) : opts.fetchOptions;
 	const auth = needsAuth ? await resolveAuth({
 		interactive,

package/dist/error-handler.mjs

@@ -1,13 +1,13 @@
+import { HOSTED_SESSION_EXPIRED, isSessionExpiredError } from "./hosted-session.mjs";
+import { isUserStop, stopDetailsOf } from "./stop.mjs";
 import { isUsageError } from "./command-registry.mjs";
 import { describeRecordReadRefusal } from "./hosted-query.mjs";
 import { quotaStopOf } from "./quota-ledger.mjs";
+import { isQueryError } from "gscdump/query";
 import { isAnalysisError } from "@gscdump/analysis/errors";
 import { parseRecordReadRefusal } from "@gscdump/contracts";
 import { isEngineError } from "@gscdump/engine/errors";
 import { classifyError } from "gscdump/errors";
-import { isQueryError } from "gscdump/query";
-const HOSTED_KEY_REJECTED_REASON = "gscdump.com rejected the API key";
-const HOSTED_KEY_REJECTED = `${HOSTED_KEY_REJECTED_REASON}. Run \`gscdump auth login --mode hosted --api-key KEY\` with a valid key.`;
 const QUOTA_MESSAGE_RE = /quota|rate\s*limit/i;
 const ANSI_RE = /\x1B\[[0-9;]*m/g;
 function suggestionForGscError(error) {
@@ -109,18 +109,44 @@ function recordReadRefusalOf(error) {
 	if (!(error instanceof Error) || error.name !== "GscdumpV1Error") return null;
 	return parseRecordReadRefusal(error.details);
 }
+function recordReadStop(refusal, text) {
+	return {
+		code: refusal.reason === "record_not_ready" ? "RECORD_NOT_READY" : "RANGE_NOT_SYNCED",
+		message: text.hint ? `${text.message} ${text.hint}` : text.message,
+		nextCommand: null
+	};
+}
 function describeCliError(error) {
 	if (isUsageError(error)) return {
 		kind: "usage",
 		message: error.message
 	};
+	const stop = stopDetailsOf(error);
 	if (error instanceof Error && error.routeStop !== void 0) return {
 		kind: "stop",
-		message: error.message
+		message: error.message,
+		...stop ? { stop } : {}
 	};
 	if (error instanceof Error && quotaStopOf(error)) return {
 		kind: "stop",
-		message: error.message
+		message: error.message,
+		stop: {
+			code: "QUOTA_USED_UP",
+			message: error.message,
+			nextCommand: null
+		}
+	};
+	if (isUserStop(error) && stop) return {
+		kind: "stop",
+		message: stop.message,
+		stop
+	};
+	if (error instanceof Error && stop) return {
+		kind: "expected",
+		message: error.message,
+		hint: "",
+		showAuthSources: false,
+		stop
 	};
 	if (error instanceof TypeError && error.message === "fetch failed") {
 		const cause = error.cause;
@@ -142,19 +168,24 @@ function describeCliError(error) {
 		hint: error.mode === "local" ? "Pass --live to run against the GSC API." : "",
 		showAuthSources: false
 	};
-	const refusal = recordReadRefusalOf(error);
-	if (refusal) return {
+	if (isSessionExpiredError(error)) return {
 		kind: "expected",
-		...describeRecordReadRefusal(refusal),
-		showAuthSources: false
-	};
-	const classified = classifyError(error);
-	if (classified.message === HOSTED_KEY_REJECTED) return {
-		kind: "expected",
-		message: classified.message,
+		message: HOSTED_SESSION_EXPIRED.message,
 		hint: "",
-		showAuthSources: false
+		showAuthSources: false,
+		stop: HOSTED_SESSION_EXPIRED
 	};
+	const refusal = recordReadRefusalOf(error);
+	if (refusal) {
+		const text = describeRecordReadRefusal(refusal);
+		return {
+			kind: "expected",
+			...text,
+			showAuthSources: false,
+			stop: recordReadStop(refusal, text)
+		};
+	}
+	const classified = classifyError(error);
 	return {
 		kind: "expected",
 		message: classified.message.replace(PARAM_NAME_RE, (name) => flagForParam(name)),
@@ -162,8 +193,33 @@ function describeCliError(error) {
 		showAuthSources: classified.kind === "auth-expired" || classified.kind === "permission-denied" || isAuthError(error)
 	};
 }
+function jsonErrorOf(report) {
+	switch (report.kind) {
+		case "usage": return {
+			code: "USAGE",
+			message: report.message,
+			nextCommand: null
+		};
+		case "stop": return report.stop ?? {
+			code: "FAILED",
+			message: report.message,
+			nextCommand: null
+		};
+		case "expected": return report.stop ?? {
+			code: "FAILED",
+			message: report.hint ? `${report.message} ${report.hint}` : report.message,
+			nextCommand: null
+		};
+		case "defect": return {
+			code: "UNEXPECTED",
+			message: report.message,
+			nextCommand: null
+		};
+	}
+}
 async function reportCliError(error, options) {
 	const report = describeCliError(error);
+	if (options.json) (options.writeStdout ?? ((value) => console.log(value)))(JSON.stringify({ error: jsonErrorOf(report) }, null, 2));
 	const red = (text) => options.color ? `\x1B[31m${text}\x1B[0m` : text;
 	const lines = [];
 	switch (report.kind) {
@@ -184,4 +240,4 @@ async function reportCliError(error, options) {
 	const text = lines.join("\n");
 	(options.write ?? ((value) => console.error(value)))(options.color ? text : text.replace(ANSI_RE, ""));
 }
-export { HOSTED_KEY_REJECTED, HOSTED_KEY_REJECTED_REASON, LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, reportCliError };
+export { LocalStoreUnsupportedError, describeCliError, flagForParam, isAuthError, jsonErrorOf, reportCliError };

package/dist/hosted-auth.mjs

@@ -1,3 +1,4 @@
+import { userStopError } from "./stop.mjs";
 import { z } from "zod";
 const ORIGIN = "https://gscdump.com";
 const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal("pending") }), z.object({
@@ -5,6 +6,12 @@ const pollSchema = z.discriminatedUnion("status", [z.object({ status: z.literal(
 	sessionId: z.string().regex(/^[a-f0-9]{64}$/)
 })]);
 const HOSTED_LOGIN_FAILURE = "Hosted login failed. Run `gscdump auth login --mode hosted` to try again.";
+const LOGIN_CANCELLED = {
+	code: "LOGIN_CANCELLED",
+	message: "Login cancelled in the browser.",
+	nextCommand: "gscdump auth login --mode hosted"
+};
+const loginCancelledBodySchema = z.object({ data: z.object({ details: z.object({ reason: z.literal("login_cancelled") }) }) });
 async function requestJson(request, route, init = {}) {
 	const response = await request(`${ORIGIN}/api/cli/auth/${route}`, {
 		...init,
@@ -13,6 +20,7 @@ async function requestJson(request, route, init = {}) {
 	});
 	if (!response.ok) {
 		if (response.status === 429 || response.status >= 500) throw new Error("gscdump.com login is temporarily unavailable. Try again later.");
+		if (response.status === 403 && loginCancelledBodySchema.safeParse(await response.json().catch(() => null)).success) throw userStopError(LOGIN_CANCELLED);
 		throw new Error(HOSTED_LOGIN_FAILURE);
 	}
 	return response.json();
@@ -31,4 +39,4 @@ async function loginWithHostedSession(deps) {
 	}
 	throw new Error("Authorization expired. Run `gscdump auth login --mode hosted` to try again.");
 }
-export { loginWithHostedSession };
+export { LOGIN_CANCELLED, loginWithHostedSession };

package/dist/hosted-session.mjs

@@ -0,0 +1,17 @@
+import { z } from "zod";
+const sessionExpiredDetailsSchema = z.object({ reason: z.literal("session_expired") });
+const sessionExpiredBodySchema = z.union([z.object({ data: z.object({ details: sessionExpiredDetailsSchema }) }), z.object({ error: z.object({ details: sessionExpiredDetailsSchema }) })]);
+const HOSTED_SESSION_EXPIRED = {
+	code: "HOSTED_CREDENTIALS_REJECTED",
+	message: "Your gscdump.com session expired. Run `gscdump auth login --mode hosted`.",
+	nextCommand: "gscdump auth login --mode hosted"
+};
+function isSessionExpiredBody(body) {
+	return sessionExpiredBodySchema.safeParse(body).success;
+}
+function isSessionExpiredError(error) {
+	if (!(error instanceof Error) || error.name !== "GscdumpV1Error") return false;
+	const { status, details } = error;
+	return status === 401 && sessionExpiredDetailsSchema.safeParse(details).success;
+}
+export { HOSTED_SESSION_EXPIRED, isSessionExpiredBody, isSessionExpiredError };