@gscdump/cli 3.5.0 → 3.6.0

package/dist/bing-hosted.mjs

@@ -0,0 +1,121 @@
+import { getCloudAccount } from "./auth-state.mjs";
+import { logger } from "./utils.mjs";
+import { writeBingDump } from "./bing-data.mjs";
+import { createGscdumpV1Client } from "@gscdump/sdk/v1";
+function hostedBingClient(state) {
+	return createGscdumpV1Client({
+		apiRoot: state.apiRoot,
+		credential: state.apiKey
+	});
+}
+async function listHostedBingSites(state) {
+	return loadHostedBingConnections(state, (await getCloudAccount(state)).sites, { tolerateFailures: true });
+}
+async function loadHostedBingConnections(state, sites, options = {}) {
+	const client = hostedBingClient(state);
+	return (await Promise.all(sites.map(async (site) => {
+		const connection = await client.getSiteBingConnection({ params: { siteId: site.siteId } }, { signal: AbortSignal.timeout(3e4) }).then((response) => response.data).catch((error) => {
+			if (!options.tolerateFailures) throw error;
+			const detail = error instanceof Error ? error.message : "Bing connection request failed.";
+			logger.warn(`Bing connection for ${site.siteUrl} is unavailable: ${detail}`);
+			return null;
+		});
+		return connection && {
+			siteId: site.siteId,
+			siteUrl: site.siteUrl,
+			connection
+		};
+	}))).filter((site) => site !== null);
+}
+async function resolveHostedBingSites(state, input) {
+	if (Boolean(input.site) === Boolean(input.allSites)) throw new Error("Choose --site or --all-sites.");
+	const account = await getCloudAccount(state);
+	const exact = account.sites.filter((site) => site.siteId === input.site || site.siteUrl === input.site);
+	const normalize = (value) => URL.parse(value.startsWith("sc-domain:") ? `https://${value.slice(10)}/` : value)?.toString();
+	const requested = input.allSites ? account.sites : exact.length ? exact : account.sites.filter((site) => normalize(site.siteUrl) === normalize(input.site) && normalize(input.site) !== void 0);
+	if (requested.length === 0) throw new Error("No matching Bing site. Run `gscdump bing sites`.");
+	if (!input.allSites && requested.length > 1) throw new Error("Multiple Bing sites match. Use a site ID from `gscdump bing sites`.");
+	const connections = await loadHostedBingConnections(state, requested, { tolerateFailures: Boolean(input.allSites) });
+	const selected = input.allSites ? connections.filter((site) => site.connection._tag === "connected") : connections;
+	if (selected.length === 0) throw new Error("No matching Bing site. Run `gscdump bing sites`.");
+	if (input.requireConnected !== false && selected.some((site) => site.connection._tag !== "connected")) throw new Error("Bing is not connected. Run `gscdump bing login --site SITE_ID`.");
+	return selected;
+}
+async function dumpHostedBingSite(state, site, outDir, options) {
+	if (options.datasets.includes("crawl-issues")) throw new Error("Bing crawl issues require local authentication. Use --mode local.");
+	const endDate = options.end ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const startDate = options.start ?? (/* @__PURE__ */ new Date(Date.parse(endDate) - 316224e5)).toISOString().slice(0, 10);
+	if (Date.parse(endDate) - Date.parse(startDate) > 316224e5) throw new Error("Hosted Bing exports support at most 366 days. Use a shorter --start and --end range.");
+	const client = hostedBingClient(state);
+	const results = [];
+	let remoteSiteUrl;
+	for (const dataset of options.datasets) {
+		if (dataset === "crawl-issues") continue;
+		let offset = 0;
+		let first;
+		const rows = [];
+		while (true) {
+			if (offset > 1e5) throw new Error("Bing pagination reached the API limit. Export a shorter date range.");
+			const { data } = await client.getSiteBingData({
+				params: { siteId: site.siteId },
+				query: {
+					dataset,
+					startDate,
+					endDate,
+					limit: 500,
+					offset
+				}
+			}, { signal: AbortSignal.timeout(3e4) });
+			if (data.dataset !== dataset) throw new Error("The hosted API returned a different Bing dataset.");
+			if (data.sync._tag !== "ready") throw new Error(`Bing ${dataset} data is ${data.sync._tag}. Retry after the hosted sync succeeds.`);
+			if (remoteSiteUrl && data.siteUrl !== remoteSiteUrl) throw new Error("The Bing connection changed during export. Retry the dump.");
+			remoteSiteUrl = data.siteUrl;
+			if (first && (data.sync.observedAt !== first.observedAt || data.pagination.total !== first.total)) throw new Error("The Bing dataset changed during export. Retry the dump.");
+			first ??= {
+				observedAt: data.sync.observedAt,
+				total: data.pagination.total
+			};
+			if (data.pagination.offset !== offset || data.pagination.hasMore && data.rows.length === 0 || (data.pagination.hasMore ? offset + data.rows.length >= first.total : offset + data.rows.length !== first.total)) throw new Error("The hosted API returned inconsistent Bing pagination. Retry the dump.");
+			rows.push(...data.dataset === "keywords" ? data.rows.map(({ keyword, ...row }) => ({
+				...row,
+				query: keyword
+			})) : data.rows);
+			if (!data.pagination.hasMore) {
+				results.push({
+					dataset,
+					rows,
+					sync: data.sync,
+					semantics: data.semantics
+				});
+				break;
+			}
+			offset += data.rows.length;
+		}
+	}
+	return writeBingDump(remoteSiteUrl ?? site.siteUrl, outDir, options.format, results);
+}
+async function inspectHostedBingUrl(state, siteId, url) {
+	const client = hostedBingClient(state);
+	let offset = 0;
+	while (true) {
+		const { data } = await client.listSiteBingIndexingEvidence({
+			params: { siteId },
+			query: {
+				limit: 500,
+				offset
+			}
+		}, { signal: AbortSignal.timeout(3e4) });
+		const evidence = data.indexingEvidence.find((row) => row.url === url);
+		if (evidence) return evidence;
+		if (!data.pagination.hasMore) return {
+			_tag: "unknown",
+			searchEngine: "bing",
+			url,
+			reason: "not-observed",
+			observedAt: null
+		};
+		if (data.pagination.offset !== offset || data.indexingEvidence.length === 0) throw new Error("The hosted API returned inconsistent Bing evidence pagination.");
+		offset += data.indexingEvidence.length;
+	}
+}
+export { dumpHostedBingSite, hostedBingClient, inspectHostedBingUrl, listHostedBingSites, resolveHostedBingSites };

package/dist/cli.d.mts

@@ -1,10 +1,10 @@
 import { CliRuntime, CreateCliRuntimeOptions, createCliRuntime } from "./runtime.mjs";
-declare const main: import("citty").CommandDef<import("citty").ArgsDef>;
-interface RunCliOptions {
+export declare const main: import("citty").CommandDef<import("citty").ArgsDef>;
+export interface RunCliOptions {
   rawArgs?: string[];
   loadEnv?: boolean;
   environment?: Record<string, string | undefined>;
   runtime?: CliRuntime;
 }
-declare function runCli(opts?: RunCliOptions): Promise<void>;
-export { type CliRuntime, type CreateCliRuntimeOptions, RunCliOptions, createCliRuntime, main, runCli };
+export declare function runCli(opts?: RunCliOptions): Promise<void>;
+export { type CliRuntime, type CreateCliRuntimeOptions, createCliRuntime };

package/dist/cli.mjs

@@ -1,14 +1,16 @@
+import { createCliRuntime, runWithCliRuntime, useCliRuntime } from "./runtime.mjs";
+import { parseAuthMode } from "./auth-state.mjs";
 import { CLI_SUBCOMMANDS } from "./command-registry.mjs";
-import { createCliRuntime, runWithCliRuntime } from "./runtime.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
 import { applyProfileFromCli } from "./commands/profile-selection.mjs";
 import { loadEnvFromCwd } from "./env-file.mjs";
-import { VERSION, configureColor, showSplash, withConfiguredOutput } from "./utils.mjs";
+import { terminalOutputOptions } from "./render/terminal.mjs";
+import { VERSION, setNoColor, showSplash, withConfiguredOutput } from "./utils.mjs";
 import process from "node:process";
 import { defineCommand, runMain } from "citty";
 function shouldShowSplash(rawArgs) {
 	if (!process.stdout.isTTY) return false;
-	if (rawArgs.includes("mcp")) return false;
+	if (rawArgs[0] !== "init" && rawArgs[0] !== "auth") return false;
 	for (const flag of [
 		"--json",
 		"--quiet",
@@ -22,13 +24,10 @@ function shouldShowSplash(rawArgs) {
 }
 function prepareCliArgs(input) {
 	const rawArgs = [...input];
+	useCliRuntime().authModeOverride = parseAuthMode(pluckArgValue(rawArgs, "--mode") ?? void 0);
 	const env = resolveCliEnvironment();
-	configureColor({
-		noColor: rawArgs.includes("--no-color") || env.noColor,
-		forceColor: env.forceColor,
-		stderrIsTTY: Boolean(process.stderr.isTTY)
-	});
-	const profile = pluckArgValue(rawArgs, "--profile");
+	setNoColor(!terminalOutputOptions().color);
+	const profile = pluckArgValue(rawArgs, "--profile", true);
 	const configDir = pluckArgValue(rawArgs, "--config-dir") ?? env.configDir ?? null;
 	applyProfileFromCli({
 		configDir,
@@ -41,21 +40,21 @@ function prepareCliArgs(input) {
 	}
 	return rawArgs;
 }
-function pluckArgValue(argv, flag) {
+function pluckArgValue(argv, flag, allowQueryTiming = false) {
+	let value = null;
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i];
-		if (a === flag && i + 1 < argv.length) {
-			const v = argv[i + 1];
-			argv.splice(i, 2);
-			return v;
-		}
-		if (a.startsWith(`${flag}=`)) {
-			const v = a.slice(flag.length + 1);
-			argv.splice(i, 1);
-			return v;
-		}
+		if (a === "--") break;
+		if (a !== flag && !a.startsWith(`${flag}=`)) continue;
+		const inline = a !== flag;
+		const next = inline ? a.slice(flag.length + 1) : argv[i + 1];
+		if (!inline && allowQueryTiming && argv.includes("query") && argv.indexOf("query") < i && (next === void 0 || next.startsWith("-"))) continue;
+		if (!next || !inline && next.startsWith("-")) throw new Error(`${flag} requires a value. Use ${flag}=VALUE.`);
+		value = next;
+		argv.splice(i, inline ? 1 : 2);
+		i--;
 	}
-	return null;
+	return value;
 }
 const main = defineCommand({
 	meta: {

package/dist/cloud-google.mjs

@@ -0,0 +1,92 @@
+import { cloudRequest } from "./auth-state.mjs";
+import { googleSearchConsole } from "gscdump/client";
+import { ofetch } from "ofetch";
+function createCloudGoogleClient(state, fetchOptions) {
+	const request = async (input, init) => {
+		const url = new URL(String(input));
+		if (url.origin !== "https://searchconsole.googleapis.com") throw new Error("Google indexing and Site Verification require local authentication. Use --mode local.");
+		const method = init?.method ?? "GET";
+		const signal = init?.signal;
+		const body = typeof init?.body === "string" ? JSON.parse(init.body) : {};
+		const post = (route, data) => cloudRequest(state, `/cli/gsc/${route}`, {
+			method: "POST",
+			body: JSON.stringify(data),
+			signal
+		});
+		let result;
+		if (url.pathname === "/webmasters/v3/sites" && method === "GET") result = { siteEntry: await cloudRequest(state, "/cli/gsc/sites", { signal }) };
+		else if (url.pathname === "/v1/urlInspection/index:inspect" && method === "POST") result = await post("inspect", {
+			siteUrl: body.siteUrl,
+			urls: [body.inspectionUrl],
+			languageCode: body.languageCode,
+			raw: true
+		});
+		else {
+			const match = url.pathname.match(/^\/webmasters\/v3\/sites\/([^/]+)(?:\/(searchAnalytics\/query|sitemaps)(?:\/([^/]+))?)?$/);
+			if (!match) throw new Error("This Google operation requires local authentication. Use --mode local.");
+			const siteUrl = decodeURIComponent(match[1]);
+			if (match[2] === "searchAnalytics/query" && method === "POST") {
+				const { type, ...query } = body;
+				result = await post("query", {
+					...query,
+					siteUrl,
+					searchType: type,
+					raw: true
+				});
+			} else if (match[2] === "sitemaps") {
+				if (match[3]) {
+					const action = method === "GET" ? "get" : method === "PUT" ? "submit" : method === "DELETE" ? "delete" : null;
+					if (!action) throw new Error("This sitemap operation requires local authentication. Use --mode local.");
+					const response = await post("sitemaps", {
+						siteUrl,
+						sitemapUrl: decodeURIComponent(match[3]),
+						action
+					});
+					result = action === "get" ? response : void 0;
+				} else if (method === "GET") {
+					const query = new URLSearchParams({
+						siteUrl,
+						raw: "true"
+					});
+					const sitemapIndex = url.searchParams.get("sitemapIndex");
+					if (sitemapIndex) query.set("sitemapIndex", sitemapIndex);
+					result = { sitemap: (await cloudRequest(state, `/cli/gsc/sitemaps?${query}`, { signal })).sitemaps };
+				} else throw new Error("This sitemap operation requires local authentication. Use --mode local.");
+			} else if (!match[2]) {
+				const action = method === "GET" ? "get" : method === "PUT" ? "add" : method === "DELETE" ? "remove" : null;
+				if (!action) throw new Error("This Site operation requires local authentication. Use --mode local.");
+				const response = await post("sites", {
+					siteUrl,
+					action
+				});
+				result = action === "get" ? response : void 0;
+			} else throw new Error("This Google operation requires local authentication. Use --mode local.");
+		}
+		return result === void 0 ? new Response(null, { status: 204 }) : Response.json(result);
+	};
+	const fetchHosted = (input, init) => request(input, init).catch((error) => {
+		if (error && typeof error === "object" && "response" in error && error.response instanceof Response) return error.response;
+		throw error;
+	});
+	return googleSearchConsole("", { fetch: ofetch.create({
+		...fetchOptions,
+		retry: fetchOptions?.retry ?? 3,
+		timeout: fetchOptions?.timeout ?? 3e4,
+		async onRequest(context) {
+			if (new URL(String(context.request)).origin !== "https://searchconsole.googleapis.com") throw new Error("Google indexing and Site Verification require local authentication. Use --mode local.");
+			const hooks = fetchOptions?.onRequest;
+			for (const hook of hooks ? Array.isArray(hooks) ? hooks : [hooks] : []) await hook(context);
+		},
+		retryDelay: fetchOptions?.retryDelay ?? (({ response }) => {
+			const header = response?.headers.get("retry-after");
+			if (header) {
+				const seconds = Number(header);
+				if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+				const date = Date.parse(header);
+				if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+			}
+			return 1e3;
+		})
+	}, { fetch: fetchHosted }) });
+}
+export { createCloudGoogleClient };

package/dist/command-meta.mjs

@@ -80,4 +80,16 @@ const mcpCommandMeta = {
 	name: "mcp",
 	description: "Start MCP server for AI assistants"
 };
-export { analyzeCommandMeta, authCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, storeCommandMeta, syncCommandMeta };
+const skillCommandMeta = {
+	name: "skill",
+	description: "Install the packaged coding agent skill"
+};
+const papercutCommandMeta = {
+	name: "papercut",
+	description: "Report a CLI problem to gscdump.com (anonymous, sanitized)"
+};
+const bingCommandMeta = {
+	name: "bing",
+	description: "Authenticate Bing, list sites, dump data, and read Indexing Evidence"
+};
+export { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, papercutCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, skillCommandMeta, storeCommandMeta, syncCommandMeta };

package/dist/command-registry.mjs

@@ -1,4 +1,4 @@
-import { analyzeCommandMeta, authCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, storeCommandMeta, syncCommandMeta } from "./command-meta.mjs";
+import { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, papercutCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, skillCommandMeta, storeCommandMeta, syncCommandMeta } from "./command-meta.mjs";
 function resolveValue(value) {
 	return typeof value === "function" ? value() : value;
 }
@@ -32,6 +32,7 @@ function shallowCommand(meta, load) {
 	};
 }
 const CLI_SUBCOMMANDS = {
+	bing: shallowCommand(bingCommandMeta, () => import("./commands/bing.mjs").then((module) => module.bingCommand)),
 	init: shallowCommand(initCommandMeta, () => import("./commands/init.mjs").then((module) => module.initCommand)),
 	dump: shallowCommand(dumpCommandMeta, () => import("./commands/dump.mjs").then((module) => module.dumpCommand)),
 	query: shallowCommand(queryCommandMeta, () => import("./commands/query.mjs").then((module) => module.queryCommand)),
@@ -51,6 +52,8 @@ const CLI_SUBCOMMANDS = {
 	config: shallowCommand(configCommandMeta, () => import("./commands/config.mjs").then((module) => module.configCommand)),
 	profile: shallowCommand(profileCommandMeta, () => import("./commands/profile.mjs").then((module) => module.profileCommand)),
 	doctor: shallowCommand(doctorCommandMeta, () => import("./commands/doctor.mjs").then((module) => module.doctorCommand)),
-	mcp: shallowCommand(mcpCommandMeta, () => import("./commands/mcp.mjs").then((module) => module.mcpCommand))
+	mcp: shallowCommand(mcpCommandMeta, () => import("./commands/mcp.mjs").then((module) => module.mcpCommand)),
+	skill: shallowCommand(skillCommandMeta, () => import("./commands/skill.mjs").then((module) => module.skillCommand)),
+	papercut: shallowCommand(papercutCommandMeta, () => import("./commands/papercut.mjs").then((module) => module.papercutCommand))
 };
 export { CLI_SUBCOMMANDS };

package/dist/commands/analyze.mjs

@@ -1,9 +1,12 @@
 import { analyzeCommandMeta } from "../command-meta.mjs";
-import { logger, toCSV } from "../utils.mjs";
+import { terminalOutputOptions } from "../render/terminal.mjs";
+import { logger, parseIntegerOption, toCSV } from "../utils.mjs";
 import { gscErrorHandler } from "../error-handler.mjs";
 import { resolveAnalysisSource } from "../analysis-local.mjs";
+import { renderAnalysis } from "../render/analysis.mjs";
 import { defineCommand } from "citty";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
+import { periodOf } from "@gscdump/engine/period";
 const ANALYSIS_TOOLS = defaultAnalyzerRegistry.listAnalyzerIds();
 const TOOL_EXTRA_ARGS = {
 	brand: { "brand-terms": {
@@ -62,7 +65,7 @@ function buildParams(tool, args) {
 		type: tool,
 		startDate: args.start ? String(args.start) : void 0,
 		endDate: args.end ? String(args.end) : void 0,
-		limit: args.limit ? Number(args.limit) : void 0
+		limit: parseIntegerOption(args.limit, "--limit")
 	};
 	if (args["brand-terms"]) params.brandTerms = String(args["brand-terms"]).split(",").map((t) => t.trim()).filter(Boolean);
 	if (args["prev-start"]) params.prevStartDate = String(args["prev-start"]);
@@ -70,8 +73,10 @@ function buildParams(tool, args) {
 	if (args.dimension) params.dimension = String(args.dimension);
 	if (args.metric) params.metric = String(args.metric);
 	if (args["cluster-by"]) params.clusterBy = String(args["cluster-by"]);
-	if (args.weeks) params.weeks = Number(args.weeks);
-	if (args["min-weeks"]) params.minWeeksWithData = Number(args["min-weeks"]);
+	const weeks = parseIntegerOption(args.weeks, "--weeks");
+	const minWeeks = parseIntegerOption(args["min-weeks"], "--min-weeks");
+	if (weeks !== void 0) params.weeks = weeks;
+	if (minWeeks !== void 0) params.minWeeksWithData = minWeeks;
 	return params;
 }
 function makeToolCommand(tool) {
@@ -120,190 +125,42 @@ function makeToolCommand(tool) {
 			...extraArgs
 		},
 		async run({ args }) {
-			const { format, runAnalysis } = await resolveAnalysisSource({
+			if (!args.json && ![
+				"table",
+				"json",
+				"csv"
+			].includes(args.format ?? "table")) throw new Error("Invalid --format. Use table, json, or csv.");
+			const params = buildParams(tool, args);
+			const { format, runAnalysis, siteUrl } = await resolveAnalysisSource({
 				site: args.site,
 				live: !!args.live,
 				json: !!args.json,
 				format: args.format
 			});
-			logger.info(`Running ${tool} analysis...`);
-			const result = await runAnalysis(buildParams(tool, args)).catch(gscErrorHandler);
+			logger.debug(`Running ${tool} analysis...`);
+			const result = await runAnalysis(params).catch(gscErrorHandler);
 			if (format === "json") {
 				console.log(JSON.stringify(result, null, 2));
 				return;
 			}
-			renderResults(result.results, result.results.length, format);
-		}
-	});
-}
-const SPARK_CHARS = [
-	"▁",
-	"▂",
-	"▃",
-	"▄",
-	"▅",
-	"▆",
-	"▇",
-	"█"
-];
-const SPARK_GAP = "·";
-const PERCENT_COLS = {
-	growthRatio: "ratio_to_pct",
-	brandShare: "direct",
-	topNConcentration: "direct",
-	declinePercent: "direct",
-	ctr: "direct",
-	share: "direct",
-	vsAverage: "ratio_to_pct",
-	clicksChangePercent: "scaled",
-	impressionsChangePercent: "scaled"
-};
-function formatPct(val, style) {
-	const pct = style === "ratio_to_pct" ? (val - 1) * 100 : style === "direct" ? val * 100 : val;
-	if (!Number.isFinite(pct)) return "";
-	return `${pct > 0 ? "+" : ""}${pct.toFixed(0)}%`;
-}
-function isTimeSeries(arr) {
-	if (arr.length === 0) return false;
-	const first = arr[0];
-	if (typeof first !== "object" || first === null) return false;
-	const keys = Object.keys(first);
-	const hasBucket = keys.includes("week") || keys.includes("date") || keys.includes("month");
-	const hasMetric = keys.includes("clicks") || keys.includes("impressions") || keys.includes("value");
-	return hasBucket && hasMetric;
-}
-function pickBucketKey(first) {
-	if ("week" in first) return "week";
-	if ("date" in first) return "date";
-	return "month";
-}
-function pickMetricKey(first) {
-	if ("clicks" in first) return "clicks";
-	if ("impressions" in first) return "impressions";
-	return "value";
-}
-function computeAlignedSparklines(results, col) {
-	const allBuckets = /* @__PURE__ */ new Set();
-	const perRow = [];
-	let bucketKey = "week";
-	let metricKey = "clicks";
-	for (const r of results) {
-		const arr = r[col];
-		if (!Array.isArray(arr) || !isTimeSeries(arr)) {
-			perRow.push(null);
-			continue;
-		}
-		const first = arr[0];
-		bucketKey = pickBucketKey(first);
-		metricKey = pickMetricKey(first);
-		const m = /* @__PURE__ */ new Map();
-		for (const item of arr) {
-			const rec = item;
-			const key = String(rec[bucketKey]);
-			const val = Number(rec[metricKey] ?? 0);
-			allBuckets.add(key);
-			m.set(key, val);
-		}
-		perRow.push(m);
-	}
-	const sorted = [...allBuckets].sort();
-	return perRow.map((m) => {
-		if (!m) return "";
-		const values = sorted.map((b) => m.has(b) ? m.get(b) : null);
-		const nonNull = values.filter((v) => v != null);
-		if (nonNull.length === 0) return SPARK_GAP.repeat(values.length);
-		const min = Math.min(...nonNull);
-		const range = Math.max(...nonNull) - min;
-		return values.map((v) => {
-			if (v == null) return SPARK_GAP;
-			if (range === 0) return SPARK_CHARS[0];
-			const idx = Math.round((v - min) / range * (SPARK_CHARS.length - 1));
-			return SPARK_CHARS[idx];
-		}).join("");
-	});
-}
-function classifyCol(col, values) {
-	const firstNonNull = values.find((v) => v != null);
-	if (firstNonNull == null) return "text";
-	if (Array.isArray(firstNonNull) && isTimeSeries(firstNonNull)) return "series";
-	if (col in PERCENT_COLS && values.every((v) => v == null || typeof v === "number")) return "pct";
-	if (values.every((v) => v == null || typeof v === "number")) return values.some((v) => typeof v === "number" && !Number.isInteger(v)) ? "float" : "int";
-	return "text";
-}
-function formatCellKinded(val, col, kind) {
-	if (val == null) return "";
-	if (kind === "int") return typeof val === "number" ? String(val) : String(val);
-	if (kind === "float") return typeof val === "number" ? val.toFixed(2) : String(val);
-	if (kind === "pct") return typeof val === "number" ? formatPct(val, PERCENT_COLS[col]) : String(val);
-	if (Array.isArray(val)) return `[${val.length} item${val.length === 1 ? "" : "s"}]`;
-	if (typeof val === "object") return JSON.stringify(val);
-	return String(val);
-}
-function computeRowSeriesSparkline(results) {
-	if (results.length < 2) return null;
-	const first = results[0];
-	const bucketKey = "week" in first ? "week" : "date" in first ? "date" : "month" in first ? "month" : null;
-	if (!bucketKey) return null;
-	const metricKey = "value" in first ? "value" : "clicks" in first ? "clicks" : "impressions" in first ? "impressions" : null;
-	if (!metricKey) return null;
-	for (const r of results) if (!(bucketKey in r) || !(metricKey in r)) return null;
-	const values = [...results].sort((a, b) => String(a[bucketKey]).localeCompare(String(b[bucketKey]))).map((r) => Number(r[metricKey] ?? 0));
-	const nonNull = values.filter((v) => Number.isFinite(v));
-	if (nonNull.length === 0) return null;
-	const min = Math.min(...nonNull);
-	const range = Math.max(...nonNull) - min;
-	return {
-		spark: values.map((v) => {
-			if (range === 0) return SPARK_CHARS[0];
-			const idx = Math.round((v - min) / range * (SPARK_CHARS.length - 1));
-			return SPARK_CHARS[idx];
-		}).join(""),
-		label: `${results.length} ${bucketKey}${results.length === 1 ? "" : "s"} of ${metricKey}`
-	};
-}
-function renderResults(results, total, format) {
-	if (format === "csv" && results.length > 0) {
-		const cols = Object.keys(results[0]);
-		console.log(toCSV(results, cols));
-		return;
-	}
-	if (results.length === 0) {
-		logger.warn("No results found");
-		return;
-	}
-	const cols = Object.keys(results[0]);
-	const kinds = cols.map((c) => classifyCol(c, results.map((r) => r[c])));
-	const sparklineByCol = {};
-	cols.forEach((c, i) => {
-		if (kinds[i] === "series") sparklineByCol[c] = computeAlignedSparklines(results, c);
-	});
-	const cellText = (row, rowIdx, colIdx) => {
-		const c = cols[colIdx];
-		const k = kinds[colIdx];
-		if (k === "series") return sparklineByCol[c][rowIdx];
-		return formatCellKinded(row[c], c, k);
-	};
-	const widths = cols.map((c, i) => {
-		let w = c.length;
-		const limit = Math.min(results.length, 20);
-		for (let j = 0; j < limit; j++) {
-			const len = cellText(results[j], j, i).length;
-			if (len > w) w = len;
+			if (format === "csv") {
+				console.log(toCSV(result.results, Object.keys(result.results[0] ?? {})));
+				return;
+			}
+			const period = periodOf(params);
+			console.log(renderAnalysis(result, {
+				id: tool,
+				site: siteUrl,
+				start: period.startDate,
+				end: period.endDate,
+				...params.prevStartDate && params.prevEndDate ? { previous: {
+					start: params.prevStartDate,
+					end: params.prevEndDate
+				} } : {},
+				metric: params.metric
+			}, terminalOutputOptions()));
 		}
-		return w;
 	});
-	console.log();
-	console.log(`  ${cols.map((c, i) => c.padEnd(widths[i])).join("  ")}`);
-	console.log(`  ${cols.map((_, i) => "─".repeat(widths[i])).join("  ")}`);
-	for (let r = 0; r < results.length; r++) console.log(`  ${cols.map((_, i) => cellText(results[r], r, i).padEnd(widths[i])).join("  ")}`);
-	const rowSeriesSparkline = computeRowSeriesSparkline(results);
-	if (rowSeriesSparkline) {
-		console.log();
-		console.log(`  trend: ${rowSeriesSparkline.spark}  (${rowSeriesSparkline.label})`);
-	}
-	console.log();
-	logger.success(`${results.length} results`);
-	if (total > results.length) logger.info(`Total: ${total} (showing ${results.length})`);
 }
 const listCommand = defineCommand({
 	meta: {