@gscdump/cli 4.8.0 → 5.1.0

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";

package/dist/commands/profile.mjs

@@ -1,5 +1,5 @@
-import { profileCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.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";

package/dist/commands/query.mjs

@@ -1,9 +1,10 @@
-import { queryCommandMeta } from "../command-meta.mjs";
 import { useCliRuntime } from "../runtime.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";
@@ -12,14 +13,13 @@ import { renderTable } from "../render/layout.mjs";
 import { asRecord, columnsFor } from "../render/analysis.mjs";
 import { resolveHostedSite } from "../hosted-site.mjs";
 import { FILTER_DIMS, filterDimensions, parseFilterArgs, toLiveFilter, toLocalFilter } from "../filters.mjs";
-import { queryHostedRows } from "../hosted-query.mjs";
 import { renderQuery } from "../render/query.mjs";
 import { openSqlViews, referencedTables } from "../sql-views.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
 import { and, between, country, date, device, gsc, hour, page, query, searchAppearance } from "gscdump/query";
-import { getLatestGscDate } from "gscdump/dates";
+import { getLatestGscDate, toIsoDate } from "gscdump/dates";
 import { cancel, isCancel, multiselect, text } from "@clack/prompts";
 import { collectSpans } from "@gscdump/engine/profile";
 import { inferDataset, isDatasetResolvable } from "gscdump/query/plan";
@@ -215,6 +215,7 @@ const queryCommand = defineCommand({
 			logger.error("Invalid --format. Use table, json, or csv.");
 			process.exit(1);
 		}
+		setJsonOutput(format === "json");
 		if (args.sql || args.schema) {
 			await runSqlMode({
 				mode: args.schema ? { kind: "schema" } : {
@@ -341,7 +342,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 +406,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...`);
@@ -431,7 +431,7 @@ const queryCommand = defineCommand({
 					end: endDate
 				},
 				total: result.rows.length,
-				data: result.rows,
+				data: result.rows.map(withIsoDate),
 				meta: { source: "local" }
 			},
 			format,
@@ -547,7 +547,14 @@ function buildLocalState(dimNames, startDate, endDate, rowLimit, dimensionFilter
 	const dims = dimNames.map((d) => DIM_COLUMNS[d]).filter((c) => Boolean(c));
 	const dateFilter = between(date, startDate, endDate);
 	const filter = dimensionFilter ? and(dateFilter, dimensionFilter) : dateFilter;
-	return gsc.select(...dims).where(filter).limit(rowLimit).getState();
+	const builder = gsc.select(...dims).where(filter);
+	return (dimNames.includes("date") ? builder.orderBy(date, "asc") : builder).limit(rowLimit).getState();
+}
+function withIsoDate(row) {
+	return typeof row.date === "number" ? {
+		...row,
+		date: toIsoDate(new Date(row.date))
+	} : row;
 }
 async function runSqlMode(opts) {
 	const ctx = await createCommandContext({ needsStore: true });
@@ -588,7 +595,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);
 			}
 		}
 	}

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,8 +1,8 @@
 import { sitemapsCommandMeta } from "../command-meta.mjs";
-import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption } from "../utils.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 { discoverLiveSitemap, loadSitemapUrls } from "../sitemap.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import { fetchSitemap } from "gscdump/sites";
@@ -59,12 +59,12 @@ const listCommand = defineCommand({
 			logger.warn("No sitemaps found");
 			return;
 		}
-		logger.success(`Found ${sitemaps.length} sitemaps:`);
+		logger.success(`Found ${plural(sitemaps.length, "sitemap", "sitemaps")}:`);
 		console.log();
 		for (const sm of sitemaps) {
 			const pending = sm.isPending ? " \x1B[33m(pending)\x1B[0m" : "";
-			const errors = sm.errors ? ` \x1B[31m${sm.errors} errors\x1B[0m` : "";
-			const warnings = sm.warnings ? ` \x1B[33m${sm.warnings} warnings\x1B[0m` : "";
+			const errors = sm.errors ? ` \x1B[31m${plural(sm.errors, "error", "errors")}\x1B[0m` : "";
+			const warnings = sm.warnings ? ` \x1B[33m${plural(sm.warnings, "warning", "warnings")}\x1B[0m` : "";
 			const submitted = sm.lastSubmitted ? ` \x1B[90msubmitted ${sm.lastSubmitted}\x1B[0m` : "";
 			console.log(`  ${sm.path}${pending}${errors}${warnings}${submitted}`);
 		}

package/dist/commands/sites.mjs

@@ -1,6 +1,6 @@
+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 } from "../utils.mjs";
+import { OUTPUT_ARGS, applyOutputMode, logger, plural } from "../utils.mjs";
 import { createCommandContext, formatSiteResolution } from "../context.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
@@ -362,7 +362,7 @@ const verifyListCommand = defineCommand({
 			logger.warn("No verified WebResources found");
 			return;
 		}
-		logger.success(`${resources.length} verified WebResources:`);
+		logger.success(`${plural(resources.length, "verified WebResource", "verified WebResources")}:`);
 		console.log();
 		for (const r of resources) {
 			const id = r.id ?? "?";
@@ -422,7 +422,7 @@ 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}`);
+	if (args["with-sitemaps"] || args["owner-only"]) throw localModeRequired("--with-sitemaps and --owner-only read Search Console permissions.");
 	const { sites } = await getHostedAccount(authentication);
 	if (args.json) {
 		console.log(JSON.stringify(sites.map((site) => ({
@@ -438,10 +438,10 @@ 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))}`);
 		return;
 	}
-	logger.success(`Found ${sites.length} hosted sites:`);
+	logger.success(`Found ${plural(sites.length, "hosted Site", "hosted Sites")}:`);
 	console.log();
 	for (const site of sites) console.log(`  ${site.siteUrl} \x1B[90m(${site.siteId})\x1B[0m  hosted sync ${formatHostedSync(site)}`);
 }
@@ -470,10 +470,10 @@ async function runListSites(args) {
 			return;
 		}
 		if (sites.length === 0) {
-			logger.warn(ownerOnly ? "No owned sites found" : "No verified sites found");
+			logger.warn(ownerOnly ? "No owned Sites found" : "No verified Sites found");
 			return;
 		}
-		logger.success(`Found ${sites.length} ${ownerOnly ? "owned" : "verified"} sites:`);
+		logger.success(`Found ${ownerOnly ? plural(sites.length, "owned Site", "owned Sites") : plural(sites.length, "verified Site", "verified Sites")}:`);
 		console.log();
 		for (const site of sites) {
 			const perm = site.permissionLevel === "siteOwner" ? "\x1B[32m" : "\x1B[90m";
@@ -492,10 +492,10 @@ async function runListSites(args) {
 		return;
 	}
 	if (sites.length === 0) {
-		logger.warn(ownerOnly ? "No owned sites found" : "No verified sites found");
+		logger.warn(ownerOnly ? "No owned Sites found" : "No verified Sites found");
 		return;
 	}
-	logger.success(`Found ${sites.length} ${ownerOnly ? "owned " : ""}sites:`);
+	logger.success(`Found ${ownerOnly ? plural(sites.length, "owned Site", "owned Sites") : plural(sites.length, "Site", "Sites")}:`);
 	console.log();
 	for (const site of sites) {
 		const perm = site.permissionLevel === "siteOwner" ? "\x1B[32m" : "\x1B[90m";

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/coverage.mjs

@@ -1,4 +1,5 @@
 import { quotaLedgerPath, quotaStatus, readLedgerState } from "./quota-ledger.mjs";
+import { plural } from "./utils.mjs";
 import { INSPECTION_QPD_PER_PROPERTY } from "./inspection-record.mjs";
 import { inspectionCandidates, loadInspectionState } from "./local-entities.mjs";
 import { datesForJob, jobWindowStart } from "./sync-plan.mjs";
@@ -117,9 +118,6 @@ function hasSyncedDays(states, table, searchType) {
 function n(value) {
 	return value.toLocaleString("en-US");
 }
-function plural(count, one, many) {
-	return `${n(count)} ${count === 1 ? one : many}`;
-}
 function clock(at) {
 	return new Date(at).toLocaleString("en-US", {
 		hour: "numeric",

package/dist/environment.mjs

@@ -23,8 +23,4 @@ function pickCliEnvironmentValue(names, values = useCliRuntime().environment) {
 	}
 	return null;
 }
-function applyCliEnvironment(updates, values = useCliRuntime().environment) {
-	for (const [key, value] of Object.entries(updates)) if (value === void 0) delete values[key];
-	else values[key] = value;
-}
-export { applyCliEnvironment, pickCliEnvironmentValue, resolveCliEnvironment };
+export { pickCliEnvironmentValue, resolveCliEnvironment };

package/dist/error-handler.mjs

@@ -1,11 +1,12 @@
+import { 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) {
@@ -103,19 +104,39 @@ const DEFECT_ERRORS = /* @__PURE__ */ new Set([
 	"EvalError",
 	"URIError"
 ]);
+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
 	};
+	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;
 		return {
@@ -136,13 +157,17 @@ function describeCliError(error) {
 		hint: error.mode === "local" ? "Pass --live to run against the GSC API." : "",
 		showAuthSources: false
 	};
+	const refusal = recordReadRefusalOf(error);
+	if (refusal) {
+		const text = describeRecordReadRefusal(refusal);
+		return {
+			kind: "expected",
+			...text,
+			showAuthSources: false,
+			stop: recordReadStop(refusal, text)
+		};
+	}
 	const classified = classifyError(error);
-	if (classified.message === HOSTED_KEY_REJECTED) return {
-		kind: "expected",
-		message: classified.message,
-		hint: "",
-		showAuthSources: false
-	};
 	return {
 		kind: "expected",
 		message: classified.message.replace(PARAM_NAME_RE, (name) => flagForParam(name)),
@@ -152,6 +177,7 @@ function describeCliError(error) {
 }
 async function reportCliError(error, options) {
 	const report = describeCliError(error);
+	if (options.json && (report.kind === "stop" || report.kind === "expected") && report.stop) (options.writeStdout ?? ((value) => console.log(value)))(JSON.stringify({ error: report.stop }, null, 2));
 	const red = (text) => options.color ? `\x1B[31m${text}\x1B[0m` : text;
 	const lines = [];
 	switch (report.kind) {
@@ -172,4 +198,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, reportCliError };

package/dist/hosted-query.mjs

@@ -28,4 +28,26 @@ async function queryHostedRows(client, siteId, state) {
 	}
 	return rows;
 }
-export { queryHostedRows };
+function describeRecordReadRefusal(refusal) {
+	const running = refusal.syncStatus === "syncing" || refusal.syncStatus === "pending";
+	if (refusal.reason === "record_not_ready") return {
+		message: "The Site's record is not readable yet.",
+		hint: refusal.syncStatus === "synced" && refusal.lastSyncAt !== void 0 ? `Sync finished at ${utcMinute(refusal.lastSyncAt)}. gscdump prepares the record for reads after Sync. Try again in a few minutes.` : running ? "Sync is still running. Run `gscdump sites` to see its progress, then try again when it finishes." : "Try again in a few minutes. Run `gscdump sites` to see the Sync state."
+	};
+	return {
+		message: `The Site's record does not hold ${refusal.missingStart === refusal.missingEnd ? refusal.missingStart : `${refusal.missingStart} to ${refusal.missingEnd}`}.`,
+		hint: rangeHint(refusal, running)
+	};
+}
+function rangeHint(refusal, running) {
+	const { oldestDateSynced: oldest, newestDateSynced: newest } = refusal;
+	const synced = oldest !== void 0 && newest !== void 0;
+	if (synced && refusal.missingStart >= oldest && refusal.missingEnd <= newest) return "Sync covers these days, but the record does not hold them yet. Pick an earlier end date with --end, or try again later.";
+	const covers = synced ? `Sync covers ${oldest} to ${newest}. ` : "";
+	if (running) return `${covers}Sync is still running. Try again when it finishes.`;
+	return synced ? `${covers}Pick dates in that range with --start and --end.` : "Run `gscdump sites` to see the Sync state.";
+}
+function utcMinute(unixSeconds) {
+	return `${(/* @__PURE__ */ new Date(unixSeconds * 1e3)).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+export { describeRecordReadRefusal, queryHostedRows };

package/dist/hosted-site.mjs

@@ -1,8 +1,7 @@
-import { getHostedAccount, hostedCredential, parseAuthentication, resolveAuthentication } from "./auth-state.mjs";
+import { stopError } from "./stop.mjs";
+import { connectSiteStep, getHostedAccount, hostedCredential, parseAuthentication, resolveAuthentication, siteManagerOf } from "./auth-state.mjs";
 import { loadConfig } from "./config.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
-import { logger } from "./utils.mjs";
-import process from "node:process";
 import { createGscdumpV1Client } from "@gscdump/sdk/v1";
 const HOSTED_ARGS = {
 	"site": {
@@ -57,35 +56,56 @@ function matchHostedSite(sites, target) {
 		sites: [...sites]
 	};
 }
-function describeMatchFailure(match) {
-	if (match.kind === "ambiguous") return `Multiple hosted Sites match "${match.target}": ${match.matches.map((site) => site.siteUrl).join(", ")}. Pass the exact Site URL with --site.`;
-	if (match.sites.length === 0) return "Your hosted account has no Sites. Add a Site at https://gscdump.com.";
-	const available = `Hosted Sites: ${match.sites.map((site) => site.siteUrl).join(", ")}.`;
-	return match.target ? `No hosted Site matches "${match.target}". ${available}` : `Pass --site. ${available}`;
+function noSitesStop(manager) {
+	return {
+		code: "NO_SITES",
+		message: `Your hosted record has no Sites. ${connectSiteStep(manager)} Then run the command again.`,
+		nextCommand: null
+	};
 }
-function fail(message) {
-	logger.error(message);
-	process.exit(1);
+function siteMatchStop(match, manager) {
+	const nextCommand = "gscdump sites --json";
+	if (match.kind === "ambiguous") return {
+		code: "SITE_AMBIGUOUS",
+		message: `Multiple hosted Sites match "${match.target}": ${match.matches.map((site) => site.siteUrl).join(", ")}. Pass the exact Site URL with --site.`,
+		nextCommand
+	};
+	if (match.sites.length === 0) return noSitesStop(manager);
+	const available = `Hosted Sites: ${match.sites.map((site) => site.siteUrl).join(", ")}.`;
+	return match.target ? {
+		code: "SITE_NOT_FOUND",
+		message: `No hosted Site matches "${match.target}". ${available}`,
+		nextCommand
+	} : {
+		code: "SITE_REQUIRED",
+		message: `Pass --site. ${available}`,
+		nextCommand
+	};
 }
 async function resolveHostedSite(args, command) {
-	if (args._?.length) fail(`\`gscdump ${command.name}\` does not accept a positional Site ID. Pass --site instead.`);
+	if (args._?.length) throw new Error(`\`gscdump ${command.name}\` does not accept a positional Site ID. Pass --site instead.`);
 	const environment = resolveCliEnvironment().values;
 	const authentication = args["api-key"] ? parseAuthentication({
 		_tag: "Hosted",
 		apiKey: args["api-key"],
 		apiRoot: String(args["api-root"] || environment.GSCDUMP_API_ROOT || "https://gscdump.com/api")
 	}) : await resolveAuthentication();
-	if (authentication._tag !== "Hosted") fail(`\`gscdump ${command.name}\` reads the hosted record, so it needs Hosted mode. Run \`gscdump auth login --mode hosted\`, or pass --api-key. In Local mode, ${command.localAlternative}.`);
-	if (args["api-root"] && String(args["api-root"]).replace(/\/+$/, "") !== authentication.apiRoot) fail("The API root changed. Pass --api-key for the new API root.");
+	if (authentication._tag !== "Hosted") throw stopError({
+		code: "HOSTED_MODE_REQUIRED",
+		message: `\`gscdump ${command.name}\` reads the hosted record, so it needs Hosted mode. Run \`gscdump auth login --mode hosted\`, or pass --api-key. In Local mode, ${command.localAlternative}.`,
+		nextCommand: "gscdump auth login --mode hosted"
+	});
+	if (args["api-root"] && String(args["api-root"]).replace(/\/+$/, "") !== authentication.apiRoot) throw new Error("The API root changed. Pass --api-key for the new API root.");
 	const target = args.site ? String(args.site) : (await loadConfig()).defaultSite;
 	const match = matchHostedSite((await getHostedAccount(authentication)).sites, target);
-	if (match.kind !== "found") fail(describeMatchFailure(match));
+	if (match.kind !== "found") throw stopError(siteMatchStop(match, siteManagerOf(authentication)));
 	return {
 		client: createGscdumpV1Client({
 			apiRoot: authentication.apiRoot,
 			credential: hostedCredential(authentication)
 		}),
-		site: match.site
+		site: match.site,
+		authentication
 	};
 }
-export { HOSTED_ARGS, matchHostedSite, resolveHostedSite };
+export { HOSTED_ARGS, matchHostedSite, noSitesStop, resolveHostedSite, siteMatchStop };

package/dist/mcp/errors.mjs

@@ -1,9 +1,9 @@
 import { resolveBYOK, resolveServiceAccount } from "../auth.mjs";
 import { COMPARISON_FLAGS, PERIOD_FLAGS } from "../window.mjs";
+import { isQueryError } from "gscdump/query";
 import { isAnalysisError } from "@gscdump/analysis/errors";
 import { isEngineError } from "@gscdump/engine/errors";
 import { classifyError } from "gscdump/errors";
-import { isQueryError } from "gscdump/query";
 const PERIODS = PERIOD_FLAGS;
 const COMPARISONS = COMPARISON_FLAGS;
 const mcpHandlerErrors = {

package/dist/mcp/types.mjs

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { SearchTypes } from "gscdump/query";
+import "gscdump/dates";
 const periodSchema = z.object({
 	start: z.string().describe("Start date (YYYY-MM-DD)"),
 	end: z.string().describe("End date (YYYY-MM-DD)")

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "4.8.0";
+var version = "5.1.0";
 export { version };

package/dist/render/query.mjs

@@ -21,7 +21,7 @@ function renderQuery(input, options) {
 		if (clicks !== -1) columns[clicks] = barColumn(input.rows, "clicks", options);
 	}
 	return [
-		...textLines(`${parseGscSiteUrl(input.site).hostname} / query`, options, "accent"),
+		...textLines(`${parseGscSiteUrl(input.site).hostname} / ${input.dimensions.join(", ")}`, options, "accent"),
 		...textLines(`${input.start} to ${input.end}`, options, "muted"),
 		"",
 		...renderTable(input.rows, columns, options)

package/dist/route.mjs

@@ -1,3 +1,4 @@
+import { stopError } from "./stop.mjs";
 import { probeAuth } from "./auth.mjs";
 import { listStoreSites } from "./store-sites.mjs";
 import { formatSiteResolution, siteArg } from "./context.mjs";
@@ -199,11 +200,8 @@ function stopCode(route) {
 		case "partial": return "STORE_RANGE_NOT_COVERED";
 	}
 }
-function routeStopError(route, message) {
-	return Object.assign(new Error(message), {
-		name: "RouteStopError",
-		routeStop: route
-	});
+function routeStopError(route, details) {
+	return Object.assign(stopError(details, "RouteStopError"), { routeStop: route });
 }
 async function needCoverage(needs, states) {
 	const reader = syncStateCoverageReader(states);
@@ -299,9 +297,7 @@ function describeStop(route, req, auth) {
 		} } : {}
 	};
 }
-function stopAtRoute(route, req, auth, opts) {
-	const details = describeStop(route, req, auth);
-	if (opts.json) console.log(JSON.stringify({ error: details }, null, 2));
-	throw routeStopError(route, details.message);
+function stopAtRoute(route, req, auth) {
+	throw routeStopError(route, describeStop(route, req, auth));
 }
 export { decideRoute, describeStop, liveCommand, liveNote, needCoverage, readRouteState, readSiteStates, resolveReadSite, routeMessage, routeStopError, stopAtRoute, stopCode, syncCommandFor };

package/dist/runtime.d.mts

@@ -7,6 +7,8 @@ export interface CliRuntime {
   configDir: string;
   configDirOverridden: boolean;
   environment: CliEnvironmentSource;
+  /** The command writes JSON to stdout. A stop then prints its JSON form there too. */
+  jsonOutput: boolean;
   logger: ConsolaInstance;
   quiet: boolean;
   rawArgs: string[];

package/dist/runtime.mjs

@@ -21,6 +21,7 @@ function createCliRuntime(opts = {}) {
 		configDir: opts.configDir ?? path.join(os.homedir(), ".config", "gscdump"),
 		configDirOverridden: false,
 		environment: opts.environment ?? process.env,
+		jsonOutput: false,
 		logger: baseLogger.withTag("gscdump"),
 		quiet: false,
 		rawArgs: [...opts.rawArgs ?? process.argv.slice(2)]

package/dist/stop.mjs

@@ -0,0 +1,10 @@
+function stopError(details, name = "StopError") {
+	return Object.assign(new Error(details.message), {
+		name,
+		stopDetails: details
+	});
+}
+function stopDetailsOf(error) {
+	return error instanceof Error ? error.stopDetails : void 0;
+}
+export { stopDetailsOf, stopError };

package/dist/sync-plan.mjs

@@ -1,5 +1,5 @@
-import { addDays, getDateRange } from "gscdump/dates";
 import { searchTypeSupportsDimensions, searchTypeSupportsQueries } from "@gscdump/contracts";
+import { addDays, getDateRange } from "gscdump/dates";
 const TABLE_NEEDS = {
 	pages: {
 		queries: false,

package/dist/utils.mjs

@@ -2,8 +2,8 @@ import { useCliRuntime } from "./runtime.mjs";
 import { version } from "./package.mjs";
 import process from "node:process";
 import fs from "node:fs/promises";
-import { SearchTypes } from "gscdump/query";
 import os from "node:os";
+import { SearchTypes } from "gscdump/query";
 import { Buffer } from "node:buffer";
 import { MAX_FETCH_BUDGET } from "@gscdump/engine/analysis-types";
 const ALL_SEARCH_TYPES = Object.values(SearchTypes);
@@ -40,10 +40,14 @@ const OUTPUT_ARGS = {
 		description: "Suppress info/success output"
 	}
 };
+function setJsonOutput(json) {
+	useCliRuntime().jsonOutput = json;
+}
 function applyOutputMode(args) {
 	const json = Boolean(args.json);
 	const quiet = json || Boolean(args.quiet);
 	setQuiet(quiet);
+	setJsonOutput(json);
 	return {
 		json,
 		quiet
@@ -148,14 +152,14 @@ function clearLine() {
 	process.stdout.write("\r\x1B[K");
 }
 function displayPath(absPath) {
-	const cwd = process.cwd();
 	const home = os.homedir();
-	if (absPath === cwd) return ".";
-	if (absPath.startsWith(`${cwd}/`)) return absPath.slice(cwd.length + 1);
 	if (absPath === home) return "~";
 	if (absPath.startsWith(`${home}/`)) return `~/${absPath.slice(home.length + 1)}`;
 	return absPath;
 }
+function plural(count, one, many) {
+	return `${count.toLocaleString("en-US")} ${count === 1 ? one : many}`;
+}
 function formatAge(ms) {
 	const delta = Date.now() - ms;
 	if (delta < 6e4) return "just now";
@@ -193,4 +197,4 @@ async function readUrlList(input) {
 	for await (const chunk of process.stdin) chunks.push(chunk);
 	return parseUrlLines(Buffer.concat(chunks).toString("utf-8"));
 }
-export { ALL_SEARCH_TYPES, OUTPUT_ARGS, VERSION, applyOutputMode, clearLine, color, cyan, dim, displayPath, formatAge, isColorEnabled, logger, parseFetchBudget, parseIntegerOption, parseNameList, parseSearchType, progressBar, readUrlList, red, runWithConcurrency, setNoColor, setQuiet, showSplash, toCSV, withConfiguredOutput };
+export { ALL_SEARCH_TYPES, OUTPUT_ARGS, VERSION, applyOutputMode, clearLine, color, cyan, dim, displayPath, formatAge, isColorEnabled, logger, parseFetchBudget, parseIntegerOption, parseNameList, parseSearchType, plural, progressBar, readUrlList, red, runWithConcurrency, setJsonOutput, setNoColor, setQuiet, showSplash, toCSV, withConfiguredOutput };