@gscdump/cli 0.37.3 → 0.37.4

package/bin/gscdump.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import('../dist/cli.mjs').then(({ runCli }) => runCli())

package/dist/_chunks/analysis-local.mjs

@@ -0,0 +1,88 @@
+import { logger } from "./utils.mjs";
+import { createCommandContext, createLocalStore } from "./context.mjs";
+import { LocalStoreUnsupportedError } from "./error-handler.mjs";
+import process from "node:process";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
+import { AnalyzerCapabilityError, createEngineQuerySource, runAnalyzerFromSource } from "@gscdump/analysis";
+import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
+import { err, ok, unwrapResult } from "gscdump/result";
+import { decodeSiteId, normalizeSiteUrl } from "gscdump/tenant";
+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 runAnalysisResult(source, params, mode) {
+	return runAnalyzerFromSource(source, params, defaultAnalyzerRegistry).then(ok).catch((e) => {
+		if (e instanceof AnalyzerCapabilityError) return err(new LocalStoreUnsupportedError(params.type, mode));
+		throw e;
+	});
+}
+function makeRunAnalysis(source, mode) {
+	return async (params) => unwrapResult(await runAnalysisResult(source, params, mode), (e) => e);
+}
+async function resolveAnalysisSource(args) {
+	const isLive = !!args.live;
+	const format = args.json ? "json" : args.format ? String(args.format) : "table";
+	if (!isLive) {
+		const { config, dataDir } = await createCommandContext();
+		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)
+			}
+		});
+		return {
+			source,
+			siteUrl,
+			format,
+			isLive,
+			runAnalysis: makeRunAnalysis(source, "local")
+		};
+	}
+	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
+	});
+	return {
+		source,
+		siteUrl,
+		format,
+		isLive,
+		runAnalysis: makeRunAnalysis(source, "live")
+	};
+}
+export { resolveAnalysisSource };

package/dist/_chunks/analyze.mjs

@@ -0,0 +1,332 @@
+import { logger, toCSV } from "./utils.mjs";
+import { gscErrorHandler } from "./error-handler.mjs";
+import { resolveAnalysisSource } from "./analysis-local.mjs";
+import { defineCommand } from "citty";
+import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
+const ANALYSIS_TOOLS = defaultAnalyzerRegistry.listAnalyzerIds();
+const TOOL_EXTRA_ARGS = {
+	brand: { "brand-terms": {
+		type: "string",
+		description: "Comma-separated brand terms (required)"
+	} },
+	movers: {
+		"prev-start": {
+			type: "string",
+			description: "Previous period start date (required)"
+		},
+		"prev-end": {
+			type: "string",
+			description: "Previous period end date (required)"
+		}
+	},
+	decay: {
+		"prev-start": {
+			type: "string",
+			description: "Previous period start date (required)"
+		},
+		"prev-end": {
+			type: "string",
+			description: "Previous period end date (required)"
+		}
+	},
+	concentration: { dimension: {
+		type: "string",
+		description: "Dimension: pages or keywords (default: pages)"
+	} },
+	seasonality: { metric: {
+		type: "string",
+		description: "Metric: clicks or impressions (default: clicks)"
+	} },
+	clustering: { "cluster-by": {
+		type: "string",
+		description: "Cluster by: prefix, intent, or both (default: both)"
+	} },
+	trends: {
+		"dimension": {
+			type: "string",
+			description: "Dimension: pages or keywords (default: pages)"
+		},
+		"weeks": {
+			type: "string",
+			description: "Rolling window size in weeks (default: 28)"
+		},
+		"min-weeks": {
+			type: "string",
+			description: "Minimum weeks with data to include an entity (default: weeks/4)"
+		}
+	}
+};
+function buildParams(tool, args) {
+	const params = {
+		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
+	};
+	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"]);
+	if (args["prev-end"]) params.prevEndDate = String(args["prev-end"]);
+	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"]);
+	return params;
+}
+function makeToolCommand(tool) {
+	const extraArgs = TOOL_EXTRA_ARGS[tool] || {};
+	return defineCommand({
+		meta: {
+			name: tool,
+			description: `Run ${tool} analysis`
+		},
+		args: {
+			site: {
+				type: "string",
+				alias: "s",
+				description: "Site URL"
+			},
+			start: {
+				type: "string",
+				description: "Start date (YYYY-MM-DD)"
+			},
+			end: {
+				type: "string",
+				description: "End date (YYYY-MM-DD)"
+			},
+			limit: {
+				type: "string",
+				alias: "l",
+				default: "100",
+				description: "Max results"
+			},
+			format: {
+				type: "string",
+				alias: "f",
+				default: "table",
+				description: "Output: table, json, csv"
+			},
+			json: {
+				type: "boolean",
+				default: false,
+				description: "Output as JSON"
+			},
+			live: {
+				type: "boolean",
+				default: false,
+				description: "Force live GSC API; bypass local Parquet store"
+			},
+			...extraArgs
+		},
+		async run({ args }) {
+			const { format, runAnalysis } = 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);
+			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];
+			return SPARK_CHARS[Math.round((v - min) / range * (SPARK_CHARS.length - 1))];
+		}).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];
+			return SPARK_CHARS[Math.round((v - min) / range * (SPARK_CHARS.length - 1))];
+		}).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;
+		}
+		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 analyzeCommand = defineCommand({
+	meta: {
+		name: "analyze",
+		description: "SEO analysis tools"
+	},
+	subCommands: {
+		list: defineCommand({
+			meta: {
+				name: "list",
+				description: "List available analyzer ids"
+			},
+			args: { json: {
+				type: "boolean",
+				default: false,
+				description: "Output as JSON"
+			} },
+			async run({ args }) {
+				if (args.json) {
+					console.log(JSON.stringify(ANALYSIS_TOOLS, null, 2));
+					return;
+				}
+				for (const id of ANALYSIS_TOOLS) console.log(id);
+			}
+		}),
+		...Object.fromEntries(ANALYSIS_TOOLS.map((tool) => [tool, makeToolCommand(tool)]))
+	}
+});
+export { analyzeCommand };