@gscdump/cli 0.8.2 → 0.9.0

package/dist/_chunks/libs/node-fetch-native.mjs

@@ -1,6 +1,6 @@
 import { n as __require, t as __exportAll } from "../rolldown-runtime.mjs";
-import http from "node:http";
 import { basename } from "node:path";
+import http from "node:http";
 import https from "node:https";
 import st from "node:zlib";
 import me, { PassThrough, pipeline } from "node:stream";

package/dist/index.mjs

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
 import { t as __exportAll } from "./_chunks/rolldown-runtime.mjs";
-import { t as ofetch } from "./_chunks/libs/ofetch.mjs";
 import { a as loadConfig, c as setConfigDir, i as getConfigPath, n as defaultDataDir, o as resolveDataDir, r as getConfigDir, s as saveConfig } from "./_chunks/config.mjs";
+import { t as ofetch } from "./_chunks/libs/ofetch.mjs";
 import process from "node:process";
 import { defineCommand, runMain } from "citty";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
+import fs, { readFile, readdir, rm } from "node:fs/promises";
+import path, { join } from "node:path";
 import { AnalyzerCapabilityError, analyzeFromSource, createEngineQuerySource } from "@gscdump/analysis";
 import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
+import { decodeSiteId, normalizeSiteUrl } from "gscdump/tenant";
+import os from "node:os";
 import { cancel, confirm, isCancel, multiselect, select, text } from "@clack/prompts";
 import { addSite, batchInspectUrls, batchRequestIndexing, createAuth, daysAgo, deleteSite, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitesWithSitemaps, formatErrorForCli, getDateRange, getIndexingMetadata, getVerificationToken, getVerifiedSite, googleSearchConsole, listVerifiedSites, progressBar, requestIndexing, runSequentialBatch, siteUrlToVerificationSite, unverifySite, verificationMethodsFor, verifySite } from "gscdump";
-import fs, { readFile, rm } from "node:fs/promises";
 import { createServer } from "node:http";
-import path from "node:path";
 import { JWT, OAuth2Client } from "google-auth-library";
 import { Buffer } from "node:buffer";
 import fs$1 from "node:fs";
-import os from "node:os";
 import { createConsola } from "consola";
 import { createNodeHarness } from "@gscdump/engine-duckdb-node";
 import { TABLE_DIMS, transformGscRow } from "@gscdump/engine/ingest";
@@ -26,48 +27,11 @@ import { createEmptyTypesStore, createIndexingMetadataStore, createInspectionSto
 import { createGscMcpServer } from "@gscdump/mcp/server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SearchTypes, and, between, contains, country, date, device, eq, gsc, notRegex, page, query, regex, searchAppearance } from "gscdump/query";
+import { defaultReportRegistry, dryRunReport, formatReport, runReport } from "@gscdump/analysis/report";
+import { resolveWindow } from "@gscdump/engine/period";
 import { inferLegacyTier } from "@gscdump/engine";
 import { DEFAULT_ROLLUPS, rebuildRollups } from "@gscdump/analysis/rollups";
 import { filesystemStats } from "@gscdump/engine/filesystem";
-var LocalStoreUnsupportedError = class extends Error {
-	constructor(tool) {
-		super(`analysis "${tool}" is not yet implemented against the local Parquet store`);
-		this.name = "LocalStoreUnsupportedError";
-	}
-};
-var LocalStoreEmptyError = class extends Error {
-	constructor(siteUrl) {
-		super(`no local data synced for ${siteUrl} (run \`gscdump sync\` first)`);
-		this.name = "LocalStoreEmptyError";
-	}
-};
-async function hasLocalData(store, siteUrl) {
-	return (await store.engine.listLive({
-		userId: store.userId,
-		siteId: store.siteIdFor(siteUrl)
-	})).length > 0;
-}
-async function runLocalAnalysis(store, siteUrl, params) {
-	return analyzeFromSource(createEngineQuerySource({
-		engine: store.engine,
-		ctx: {
-			userId: store.userId,
-			siteId: store.siteIdFor(siteUrl)
-		}
-	}), params, defaultAnalyzerRegistry).catch((e) => {
-		if (e instanceof AnalyzerCapabilityError) throw new LocalStoreUnsupportedError(params.type);
-		throw e;
-	});
-}
-async function runLiveAnalysis(client, siteUrl, params) {
-	return analyzeFromSource(createGscApiQuerySource({
-		client,
-		siteUrl
-	}), params, defaultAnalyzerRegistry).catch((e) => {
-		if (e instanceof AnalyzerCapabilityError) throw new LocalStoreUnsupportedError(params.type);
-		throw e;
-	});
-}
 const ENV_LINE_RE$1 = /^([^=]+)=(.*)$/;
 function parseEnvFile(envPath) {
 	let content;
@@ -110,7 +74,7 @@ function loadEnvFromCwd() {
 	}
 	return applied;
 }
-const VERSION = "0.8.2";
+const VERSION = "0.9.0";
 const baseLogger = createConsola({
 	stdout: process.stderr,
 	stderr: process.stderr
@@ -735,6 +699,92 @@ async function gscErrorHandler(error) {
 	console.error();
 	process.exit(1);
 }
+var LocalStoreUnsupportedError = class extends Error {
+	constructor(tool) {
+		super(`analysis "${tool}" is not yet implemented against the local Parquet store`);
+		this.name = "LocalStoreUnsupportedError";
+	}
+};
+async function hasLocalData(store, siteUrl) {
+	return (await store.engine.listLive({
+		userId: store.userId,
+		siteId: store.siteIdFor(siteUrl)
+	})).length > 0;
+}
+async function listLocalSites(dataDir, userId = "local") {
+	return readdir(join(dataDir, `u_${userId}`), { withFileTypes: true }).then((entries) => entries.filter((e) => e.isDirectory() && (e.name.startsWith("d_") || e.name.startsWith("h_"))).map((e) => decodeSiteId(e.name))).catch(() => []);
+}
+function pickLocalSite(siteUrls, hint) {
+	if (siteUrls.length === 0) return null;
+	if (!hint) return siteUrls.length === 1 ? siteUrls[0] : null;
+	const normalized = normalizeSiteUrl(hint);
+	const exact = siteUrls.find((s) => s === normalized || s === hint);
+	if (exact) return exact;
+	return siteUrls.find((s) => s.includes(hint) || hint.includes(s)) ?? null;
+}
+async function resolveAnalysisSource(args) {
+	const isLive = !!args.live;
+	const format = args.json ? "json" : args.format ? String(args.format) : "table";
+	if (!isLive) {
+		const config = await loadConfig();
+		const dataDir = resolveDataDir(config);
+		const store = createLocalStore({ dataDir });
+		const siteHint = args.site ? String(args.site) : config.defaultSite;
+		const localSites = await listLocalSites(dataDir, store.userId);
+		const siteUrl = pickLocalSite(localSites, siteHint);
+		if (!siteUrl) {
+			if (localSites.length === 0) logger.error(`No local data found in ${dataDir}. Run \`gscdump sync\` first, or pass --live.`);
+			else logger.error(`Could not resolve site${siteHint ? ` from "${siteHint}"` : ""}. Local sites: ${localSites.join(", ")}`);
+			process.exit(1);
+		}
+		if (!await hasLocalData(store, siteUrl).catch(() => false)) {
+			logger.error(`No local data for ${siteUrl}. Run \`gscdump sync\` first, or pass --live.`);
+			process.exit(1);
+		}
+		const source = createEngineQuerySource({
+			engine: store.engine,
+			ctx: {
+				userId: store.userId,
+				siteId: store.siteIdFor(siteUrl)
+			}
+		});
+		const runAnalysis = (params) => analyzeFromSource(source, params, defaultAnalyzerRegistry).catch((e) => {
+			if (e instanceof AnalyzerCapabilityError) {
+				logger.error(`${new LocalStoreUnsupportedError(params.type).message}. Pass --live to run against the GSC API.`);
+				process.exit(1);
+			}
+			logger.error(`Local analysis failed: ${e.message}`);
+			process.exit(1);
+		});
+		return {
+			source,
+			siteUrl,
+			format,
+			isLive,
+			runAnalysis
+		};
+	}
+	const ctx = await createCommandContext({
+		needsAuth: true,
+		needsStore: false
+	});
+	const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+	const source = createGscApiQuerySource({
+		client: ctx.client,
+		siteUrl
+	});
+	const runAnalysis = (params) => analyzeFromSource(source, params, defaultAnalyzerRegistry).catch((e) => {
+		if (e instanceof AnalyzerCapabilityError) throw new LocalStoreUnsupportedError(params.type);
+		return gscErrorHandler(e);
+	});
+	return {
+		source,
+		siteUrl,
+		format,
+		isLive,
+		runAnalysis
+	};
+}
 const ANALYSIS_TOOLS = defaultAnalyzerRegistry.listAnalyzerIds();
 const TOOL_EXTRA_ARGS = {
 	brand: { "brand-terms": {
@@ -851,40 +901,14 @@ function makeToolCommand(tool) {
 			...extraArgs
 		},
 		async run({ args }) {
-			const ctx = await createCommandContext({
-				needsAuth: true,
-				needsStore: !args.live
+			const { format, runAnalysis } = await resolveAnalysisSource({
+				site: args.site,
+				live: !!args.live,
+				json: !!args.json,
+				format: args.format
 			});
-			const siteUrl = await ctx.resolveSite(args.site);
 			logger.info(`Running ${tool} analysis...`);
-			const params = buildParams(tool, args);
-			const format = args.json ? "json" : String(args.format);
-			if (!args.live) {
-				const store = ctx.store;
-				if (!await hasLocalData(store, siteUrl).catch(() => false)) {
-					logger.error(`No local data for ${siteUrl}. Run \`gscdump sync\` first, or pass --live.`);
-					process.exit(1);
-				}
-				const localResult = await runLocalAnalysis(store, siteUrl, params).catch((e) => {
-					if (e instanceof LocalStoreUnsupportedError) {
-						logger.error(`${e.message}. Pass --live to run against the GSC API.`);
-						process.exit(1);
-					}
-					if (e instanceof LocalStoreEmptyError) {
-						logger.error(`${e.message}`);
-						process.exit(1);
-					}
-					logger.error(`Local analysis failed: ${e.message}`);
-					process.exit(1);
-				});
-				if (format === "json") {
-					console.log(JSON.stringify(localResult, null, 2));
-					return;
-				}
-				renderResults(localResult.results, localResult.results.length, format);
-				return;
-			}
-			const result = await runLiveAnalysis(ctx.client, siteUrl, params).catch(gscErrorHandler);
+			const result = await runAnalysis(buildParams(tool, args));
 			if (format === "json") {
 				console.log(JSON.stringify(result, null, 2));
 				return;
@@ -3966,6 +3990,222 @@ async function writeOutput(opts) {
 function isKnownTable$1(name) {
 	return allTables().includes(name);
 }
+const REPORT_IDS = defaultReportRegistry.listReportIds();
+const PERIOD_ALIASES = {
+	"7d": "last-7d",
+	"28d": "last-28d",
+	"30d": "last-30d",
+	"90d": "last-90d",
+	"180d": "last-180d",
+	"365d": "last-365d",
+	"last-7d": "last-7d",
+	"last-28d": "last-28d",
+	"last-30d": "last-30d",
+	"last-90d": "last-90d",
+	"last-180d": "last-180d",
+	"last-365d": "last-365d",
+	"mtd": "mtd",
+	"ytd": "ytd",
+	"custom": "custom"
+};
+const COMPARISON_ALIASES = {
+	"none": "none",
+	"prev": "prev-period",
+	"prev-period": "prev-period",
+	"prior": "prev-period",
+	"prior-period": "prev-period",
+	"yoy": "yoy"
+};
+function resolvePeriod(input, fallback) {
+	if (!input) return 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;
+}
+function resolveComparison(input, fallback) {
+	if (!input) return fallback;
+	const mode = COMPARISON_ALIASES[input.toLowerCase()];
+	if (!mode) throw new Error(`Unknown --vs "${input}". Supported: none, prev-period, yoy.`);
+	return mode;
+}
+function reportArgsToCitty(spec) {
+	const out = {};
+	for (const [key, def] of Object.entries(spec)) out[key] = {
+		type: def.type === "boolean" ? "boolean" : "string",
+		description: def.description,
+		default: def.default == null ? void 0 : String(def.default),
+		alias: def.alias,
+		required: def.required
+	};
+	return out;
+}
+function buildReportParams(report, args) {
+	const params = {};
+	for (const [key, def] of Object.entries(report.argsSpec)) {
+		const raw = args[key];
+		if (raw == null || raw === "") continue;
+		if (def.type === "number") {
+			const n = Number(raw);
+			if (Number.isFinite(n)) params[toCamel(key)] = n;
+		} else if (def.type === "boolean") params[toCamel(key)] = !!raw;
+		else params[toCamel(key)] = raw;
+	}
+	return params;
+}
+function toCamel(kebab) {
+	return kebab.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function makeReportCommand(report) {
+	const reportArgs = reportArgsToCitty(report.argsSpec);
+	return defineCommand({
+		meta: {
+			name: report.id,
+			description: report.description
+		},
+		args: {
+			"site": {
+				type: "string",
+				alias: "s",
+				description: "Site URL"
+			},
+			"period": {
+				type: "string",
+				description: "Window: 7d|28d|90d|mtd|ytd|custom",
+				default: presetToFlag(report.defaultPeriod)
+			},
+			"vs": {
+				type: "string",
+				description: "Comparison: none|prev-period|yoy",
+				default: report.defaultComparison
+			},
+			"start": {
+				type: "string",
+				description: "Custom start date (YYYY-MM-DD)"
+			},
+			"end": {
+				type: "string",
+				description: "Custom end date (YYYY-MM-DD)"
+			},
+			"prev-start": {
+				type: "string",
+				description: "Override comparison start"
+			},
+			"prev-end": {
+				type: "string",
+				description: "Override comparison end"
+			},
+			"live": {
+				type: "boolean",
+				default: false,
+				description: "Force live GSC API; bypass local store"
+			},
+			"json": {
+				type: "boolean",
+				default: false,
+				description: "Emit full ReportResult JSON"
+			},
+			"explain": {
+				type: "boolean",
+				default: false,
+				description: "Print plan steps + window without executing"
+			},
+			"dry-run": {
+				type: "boolean",
+				default: false,
+				description: "Alias for --explain"
+			},
+			...reportArgs
+		},
+		async run({ args }) {
+			const preset = resolvePeriod(args.period, report.defaultPeriod);
+			const comparison = resolveComparison(args.vs, report.defaultComparison);
+			const window = resolveWindow({
+				preset,
+				comparison,
+				start: args.start,
+				end: args.end
+			});
+			if (args["prev-start"] && args["prev-end"]) window.comparison = {
+				start: String(args["prev-start"]),
+				end: String(args["prev-end"])
+			};
+			const params = buildReportParams(report, args);
+			if (args.explain || args["dry-run"]) {
+				const dry = await dryRunReport(report, {
+					site: args.site ? String(args.site) : "(unresolved)",
+					window,
+					params,
+					registryVersion: defaultReportRegistry.version
+				});
+				console.log(JSON.stringify({
+					id: report.id,
+					window,
+					comparison,
+					plan: dry.steps
+				}, null, 2));
+				return;
+			}
+			const { source, siteUrl } = await resolveAnalysisSource({
+				site: args.site,
+				live: !!args.live,
+				json: !!args.json
+			});
+			const result = await runReport(report, {
+				source,
+				analyzers: defaultAnalyzerRegistry,
+				ctx: {
+					site: siteUrl,
+					window,
+					params,
+					registryVersion: defaultReportRegistry.version
+				}
+			});
+			if (args.json) {
+				console.log(JSON.stringify(result, null, 2));
+				return;
+			}
+			console.log(formatReport(result));
+			if (result.meta.degraded) logger.warn(`degraded: ${result.meta.steps.filter((s) => s.status === "error").map((s) => `${s.key}(${s.error})`).join(", ")}`);
+		}
+	});
+}
+function presetToFlag(preset) {
+	if (preset === "mtd" || preset === "ytd" || preset === "custom") return preset;
+	return preset.replace(/^last-/, "");
+}
+const reportCommand = defineCommand({
+	meta: {
+		name: "report",
+		description: "Run an intent-keyed report (composes analyzers into bounded sections)"
+	},
+	subCommands: {
+		list: defineCommand({
+			meta: {
+				name: "list",
+				description: "List available report ids"
+			},
+			args: { json: {
+				type: "boolean",
+				default: false,
+				description: "Output as JSON"
+			} },
+			async run({ args }) {
+				const reports = defaultReportRegistry.listReports().map((r) => ({
+					id: r.id,
+					description: r.description,
+					defaultPeriod: r.defaultPeriod,
+					defaultComparison: r.defaultComparison
+				}));
+				if (args.json) {
+					console.log(JSON.stringify(reports, null, 2));
+					return;
+				}
+				for (const r of reports) console.log(`${r.id.padEnd(16)} ${r.description}`);
+			}
+		}),
+		...Object.fromEntries(REPORT_IDS.map((id) => [id, makeReportCommand(defaultReportRegistry.getReport(id))]))
+	}
+});
 const sitemapsCommand = defineCommand({
 	meta: {
 		name: "sitemaps",
@@ -5819,6 +6059,7 @@ runMain(defineCommand({
 		indexing: indexingCommand,
 		entities: entitiesCommand,
 		analyze: analyzeCommand,
+		report: reportCommand,
 		auth: authCommand,
 		config: configCommand,
 		profile: profileCommand,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "CLI for Google Search Console - dump, query, and run MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -41,12 +41,12 @@
     "consola": "^3.4.2",
     "google-auth-library": "^10.6.2",
     "open": "^11.0.0",
-    "@gscdump/engine-duckdb-node": "0.8.2",
-    "@gscdump/engine": "0.8.2",
-    "@gscdump/engine-gsc-api": "0.8.2",
-    "@gscdump/mcp": "0.8.2",
-    "@gscdump/analysis": "0.8.2",
-    "gscdump": "0.8.2"
+    "@gscdump/engine": "0.9.0",
+    "@gscdump/engine-duckdb-node": "0.9.0",
+    "@gscdump/analysis": "0.9.0",
+    "@gscdump/engine-gsc-api": "0.9.0",
+    "@gscdump/mcp": "0.9.0",
+    "gscdump": "0.9.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "1.5.1-r.2",