@gscdump/cli 1.4.0 → 1.4.1

package/dist/{_chunks → commands}/query.mjs

@@ -1,7 +1,8 @@
-import { loadConfig } from "./config.mjs";
-import { ALL_SEARCH_TYPES, exportToCSV, logger, parseSearchType } from "./utils.mjs";
-import { allTables, createCommandContext, inferTable } from "./context.mjs";
-import { gscErrorHandler } from "./error-handler.mjs";
+import { loadConfig } from "../config.mjs";
+import { ALL_SEARCH_TYPES, exportToCSV, logger, parseSearchType } from "../utils.mjs";
+import { allTables, inferTable } from "../local-store.mjs";
+import { createCommandContext } from "../context.mjs";
+import { gscErrorHandler } from "../error-handler.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";

package/dist/{_chunks → commands}/report.mjs

@@ -1,5 +1,5 @@
-import { logger } from "./utils.mjs";
-import { resolveAnalysisSource } from "./analysis-local.mjs";
+import { logger } from "../utils.mjs";
+import { resolveAnalysisSource } from "../analysis-local.mjs";
 import { defineCommand } from "citty";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
 import { err, ok, unwrapResult } from "gscdump/result";

package/dist/commands/rollups.mjs

@@ -0,0 +1,134 @@
+import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
+import { createCommandContext } from "../context.mjs";
+import { defineCommand } from "citty";
+import { INTENT_CLASSIFIER_VERSION, NORMALIZER_VERSION, classifyQueryIntent, encodeIntent, normalizeQuery } from "@gscdump/analysis";
+import { buildQueryDimRecords, createQueryDimStore } from "@gscdump/engine/entities";
+import { CANONICAL_ROLLUPS, DEFAULT_ROLLUPS, rebuildRollups } from "@gscdump/engine/rollups";
+async function buildSiteQueryDim(store, siteId) {
+	const ctx = {
+		userId: store.userId,
+		siteId
+	};
+	const entries = await store.engine.listLive({
+		userId: ctx.userId,
+		siteId,
+		table: "queries"
+	});
+	if (entries.length === 0) return 0;
+	const { rows } = await store.engine.runSQL({
+		ctx,
+		table: "queries",
+		fileSets: { FILES: {
+			table: "queries",
+			partitions: entries.map((e) => e.partition)
+		} },
+		sql: `SELECT DISTINCT query FROM read_parquet({{FILES}}, union_by_name = true) WHERE query IS NOT NULL`
+	});
+	const records = buildQueryDimRecords(rows.map((r) => String(r.query)), {
+		normalizeQuery,
+		normalizerVersion: NORMALIZER_VERSION,
+		classifyIntentCode: (q) => encodeIntent(classifyQueryIntent(q)),
+		intentVersion: INTENT_CLASSIFIER_VERSION
+	});
+	await createQueryDimStore({ dataSource: store.dataSource }).write(ctx, records, Date.now());
+	return records.length;
+}
+const rollupsCommand = defineCommand({
+	meta: {
+		name: "rollups",
+		description: "Manage post-sync rollups"
+	},
+	subCommands: { rebuild: defineCommand({
+		meta: {
+			name: "rebuild",
+			description: "Rebuild post-sync rollups (daily totals, weekly totals, top-N tables) for a site"
+		},
+		args: {
+			...OUTPUT_ARGS,
+			"site": {
+				type: "string",
+				alias: "s",
+				description: "Restrict to a single site (default: all sites with local data)"
+			},
+			"with-canonical": {
+				type: "boolean",
+				description: "Also build the opt-in canonical-primary rollups (query_canonical_variants, query_canonical_daily)",
+				default: false
+			}
+		},
+		async run({ args }) {
+			const { json } = applyOutputMode(args);
+			const defs = args["with-canonical"] ? [...DEFAULT_ROLLUPS, ...CANONICAL_ROLLUPS] : DEFAULT_ROLLUPS;
+			const store = (await createCommandContext({ needsStore: true })).store;
+			const explicitSiteId = args.site ? store.siteIdFor(String(args.site)) : void 0;
+			const allSiteIds = /* @__PURE__ */ new Set();
+			if (explicitSiteId) allSiteIds.add(explicitSiteId);
+			else {
+				const entries = await store.engine.listLive({ userId: store.userId });
+				for (const e of entries) if (e.siteId) allSiteIds.add(e.siteId);
+			}
+			if (allSiteIds.size === 0) {
+				if (json) console.log(JSON.stringify({
+					sites: [],
+					totalBytes: 0
+				}, null, 2));
+				else logger.warn("No sites with local data. Run `gscdump sync` first.");
+				return;
+			}
+			const summary = [];
+			let totalBytes = 0;
+			for (const siteId of allSiteIds) {
+				if (args["with-canonical"]) {
+					const dimRows = await buildSiteQueryDim(store, siteId);
+					if (!json) logger.info(`Built query dimension for [${siteId}] (${dimRows} distinct queries, normalizer v${NORMALIZER_VERSION})`);
+				}
+				logger.info(`Rebuilding rollups for [${siteId}] (${defs.length} rollups)`);
+				const results = await rebuildRollups({
+					engine: {
+						runSQL: (opts) => store.engine.runSQL(opts),
+						listPartitions: async ({ ctx, table, searchType }) => {
+							return (await store.engine.listLive({
+								userId: ctx.userId,
+								...ctx.siteId !== void 0 ? { siteId: ctx.siteId } : {},
+								table,
+								...searchType !== void 0 ? { searchType } : {}
+							})).map((e) => ({
+								partition: e.partition,
+								bytes: e.bytes
+							}));
+						}
+					},
+					dataSource: store.dataSource,
+					ctx: {
+						userId: store.userId,
+						siteId
+					},
+					defs
+				});
+				const site = {
+					siteId,
+					rollups: []
+				};
+				for (const r of results) {
+					totalBytes += r.bytes;
+					site.rollups.push({
+						id: r.id,
+						bytes: r.bytes,
+						objectKey: r.objectKey
+					});
+					if (!json) console.log(`  ${r.id.padEnd(20)} ${(r.bytes / 1024).toFixed(1).padStart(8)} KB  ${r.objectKey}`);
+				}
+				summary.push(site);
+			}
+			if (json) {
+				console.log(JSON.stringify({
+					sites: summary,
+					totalBytes
+				}, null, 2));
+				return;
+			}
+			logger.success(`Rebuilt rollups across ${allSiteIds.size} site(s) — total ${(totalBytes / 1024).toFixed(1)} KB`);
+		}
+	}) }
+});
+export { rollupsCommand };

package/dist/{_chunks → commands}/sitemaps.mjs

@@ -1,6 +1,6 @@
-import { OUTPUT_ARGS, applyOutputMode, logger, noSubcommandSelected } from "./utils.mjs";
-import { createCommandContext } from "./context.mjs";
-import { gscErrorHandler } from "./error-handler.mjs";
+import { OUTPUT_ARGS, applyOutputMode, logger, noSubcommandSelected } from "../utils.mjs";
+import { createCommandContext } from "../context.mjs";
+import { gscErrorHandler } from "../error-handler.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import { discoverSitemap, fetchSitemap, fetchSitemapUrls } from "gscdump";

package/dist/{_chunks → commands}/sites.mjs

@@ -1,6 +1,6 @@
-import { OUTPUT_ARGS, applyOutputMode, logger } from "./utils.mjs";
-import { createCommandContext } from "./context.mjs";
-import { gscErrorHandler } from "./error-handler.mjs";
+import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
+import { createCommandContext } from "../context.mjs";
+import { gscErrorHandler } from "../error-handler.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import { confirm, isCancel } from "@clack/prompts";

package/dist/commands/stats.mjs

@@ -0,0 +1,118 @@
+import { OUTPUT_ARGS, applyOutputMode, displayPath, formatAge, logger } from "../utils.mjs";
+import { allTables } from "../local-store.mjs";
+import { createCommandContext } from "../context.mjs";
+import process from "node:process";
+import { defineCommand } from "citty";
+import { filesystemStats } from "@gscdump/engine/filesystem";
+const statsCommand = defineCommand({
+	meta: {
+		name: "stats",
+		description: "Show row/byte counts per table and on-disk footprint"
+	},
+	args: {
+		...OUTPUT_ARGS,
+		site: {
+			type: "string",
+			description: "Limit to one site URL (sc-domain:example.com, https://example.com/, ...)"
+		}
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const store = (await createCommandContext({ needsStore: true })).store;
+		const allEntries = await store.engine.listAll({ userId: store.userId });
+		let siteId;
+		if (args.site) {
+			const known = new Set(allEntries.filter((entry) => entry.retiredAt === void 0 && entry.siteId !== void 0).map((entry) => entry.siteId));
+			const candidate = store.siteIdFor(args.site);
+			if (!known.has(candidate)) {
+				logger.error(`No local data for --site=${args.site}. Known site IDs: ${known.size === 0 ? "(none — run `gscdump sync` first)" : Array.from(known).join(", ")}`);
+				process.exit(1);
+			}
+			siteId = candidate;
+		}
+		const selectedEntries = siteId === void 0 ? allEntries : allEntries.filter((entry) => entry.siteId === siteId);
+		const perTable = allTables().map((table) => {
+			const all = selectedEntries.filter((entry) => entry.table === table);
+			return {
+				table,
+				live: all.filter((e) => e.retiredAt === void 0),
+				retired: all.filter((e) => e.retiredAt !== void 0)
+			};
+		});
+		const [watermarks, disk] = await Promise.all([store.engine.getWatermarks({
+			userId: store.userId,
+			siteId
+		}), filesystemStats(store.dataDir).catch(() => ({
+			files: 0,
+			bytes: 0
+		}))]);
+		if (json) {
+			const payload = {
+				dataDir: store.dataDir,
+				disk,
+				tables: perTable.map(({ table, live, retired }) => ({
+					table,
+					liveFiles: live.length,
+					liveRows: sumRows(live),
+					liveBytes: sumBytes(live),
+					retiredFiles: retired.length,
+					retiredBytes: sumBytes(retired),
+					watermarks: watermarks.filter((w) => w.table === table).map((w) => ({
+						siteId: w.siteId ?? null,
+						newestDateSynced: w.newestDateSynced,
+						oldestDateSynced: w.oldestDateSynced,
+						lastSyncAt: w.lastSyncAt
+					}))
+				}))
+			};
+			console.log(JSON.stringify(payload, null, 2));
+			return;
+		}
+		console.log();
+		console.log(`  \x1B[1m${displayPath(store.dataDir)}\x1B[0m`);
+		console.log(`  \x1B[90mDisk: ${disk.files} file(s), ${formatBytes(disk.bytes)}\x1B[0m`);
+		console.log();
+		const totalRows = perTable.reduce((acc, t) => acc + sumRows(t.live), 0);
+		const totalBytes = perTable.reduce((acc, t) => acc + sumBytes(t.live), 0);
+		const totalFiles = perTable.reduce((acc, t) => acc + t.live.length, 0);
+		const totalRetiredFiles = perTable.reduce((acc, t) => acc + t.retired.length, 0);
+		const totalRetiredBytes = perTable.reduce((acc, t) => acc + sumBytes(t.retired), 0);
+		for (const { table, live, retired } of perTable) {
+			const rows = sumRows(live).toLocaleString();
+			const bytes = formatBytes(sumBytes(live));
+			const retiredSuffix = retired.length > 0 ? ` \x1B[90m(+${retired.length} retired, ${formatBytes(sumBytes(retired))})\x1B[0m` : "";
+			console.log(`  ${table.padEnd(15)} \x1B[36m${String(live.length).padStart(4)}\x1B[0m files, ${rows.padStart(10)} rows, ${bytes}${retiredSuffix}`);
+		}
+		console.log();
+		console.log(`  \x1B[1mTotal:\x1B[0m ${totalFiles} files, ${totalRows.toLocaleString()} rows, ${formatBytes(totalBytes)} live`);
+		if (totalRetiredFiles > 0) console.log(`  \x1B[90mRetired: ${totalRetiredFiles} files, ${formatBytes(totalRetiredBytes)} awaiting GC\x1B[0m`);
+		if (watermarks.length > 0) {
+			console.log();
+			console.log(`  \x1B[1mSync watermarks:\x1B[0m`);
+			for (const w of sortWatermarks(watermarks)) {
+				const scope = w.siteId ? `${w.table}@${w.siteId}` : w.table;
+				console.log(`  ${scope.padEnd(24)} \x1B[36m${w.oldestDateSynced}\x1B[0m → \x1B[36m${w.newestDateSynced}\x1B[0m  \x1B[90m(last ${formatAge(w.lastSyncAt)})\x1B[0m`);
+			}
+		}
+		console.log();
+	}
+});
+function sortWatermarks(ws) {
+	return [...ws].sort((a, b) => {
+		if (a.table !== b.table) return a.table.localeCompare(b.table);
+		return (a.siteId ?? "").localeCompare(b.siteId ?? "");
+	});
+}
+function sumRows(entries) {
+	return entries.reduce((acc, e) => acc + e.rowCount, 0);
+}
+function sumBytes(entries) {
+	return entries.reduce((acc, e) => acc + e.bytes, 0);
+}
+function formatBytes(n) {
+	if (n < 1024) return `${n} B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+	if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+	return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+export { statsCommand };

package/dist/commands/store-purge.mjs

@@ -0,0 +1,93 @@
+import { OUTPUT_ARGS, applyOutputMode, logger } from "../utils.mjs";
+import { createCommandContext } from "../context.mjs";
+import process from "node:process";
+import { defineCommand } from "citty";
+import { confirm, isCancel } from "@clack/prompts";
+const rmSiteCommand = defineCommand({
+	meta: {
+		name: "rm-site",
+		description: "Delete every parquet, manifest, watermark, and sync-state record for a single site"
+	},
+	args: {
+		site: {
+			type: "positional",
+			required: true,
+			description: "Site URL (e.g. sc-domain:example.com)"
+		},
+		yes: {
+			type: "boolean",
+			alias: "y",
+			default: false,
+			description: "Skip confirmation prompt"
+		},
+		...OUTPUT_ARGS
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const store = (await createCommandContext({ needsStore: true })).store;
+		const siteId = store.siteIdFor(String(args.site));
+		if (!args.yes && !json) {
+			const ok = await confirm({
+				message: `Delete ALL local data for ${args.site}? This is irreversible.`,
+				initialValue: false
+			});
+			if (isCancel(ok) || !ok) {
+				logger.info("Cancelled");
+				process.exit(0);
+			}
+		}
+		const result = await store.engine.purgeTenant({
+			userId: store.userId,
+			siteId
+		});
+		if (json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		logger.success(`Removed local data for ${args.site}`);
+		console.log(`  Objects deleted:    ${result.objectsDeleted}`);
+		console.log(`  Manifest entries:   ${result.entriesRemoved}`);
+		console.log(`  Watermarks:         ${result.watermarksRemoved}`);
+		console.log(`  Sync states:        ${result.syncStatesRemoved}`);
+	}
+});
+const resetCommand = defineCommand({
+	meta: {
+		name: "reset",
+		description: "Wipe the entire local store (every site, every table). Irreversible."
+	},
+	args: {
+		yes: {
+			type: "boolean",
+			alias: "y",
+			default: false,
+			description: "Skip confirmation prompt"
+		},
+		...OUTPUT_ARGS
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const store = (await createCommandContext({ needsStore: true })).store;
+		if (!args.yes && !json) {
+			const ok = await confirm({
+				message: `Wipe the entire local store under ${store.dataDir}? This deletes data for ALL sites.`,
+				initialValue: false
+			});
+			if (isCancel(ok) || !ok) {
+				logger.info("Cancelled");
+				process.exit(0);
+			}
+		}
+		const result = await store.engine.purgeTenant({ userId: store.userId });
+		if (json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		logger.success("Local store reset");
+		console.log(`  Objects deleted:    ${result.objectsDeleted}`);
+		console.log(`  Manifest entries:   ${result.entriesRemoved}`);
+		console.log(`  Watermarks:         ${result.watermarksRemoved}`);
+		console.log(`  Sync states:        ${result.syncStatesRemoved}`);
+	}
+});
+export { resetCommand, rmSiteCommand };

package/dist/commands/store.mjs

@@ -0,0 +1,40 @@
+import { noSubcommandSelected } from "../utils.mjs";
+import { compactCommand } from "./compact.mjs";
+import { exportCommand } from "./export.mjs";
+import { gcCommand } from "./gc.mjs";
+import { rollupsCommand } from "./rollups.mjs";
+import { statsCommand } from "./stats.mjs";
+import { resetCommand, rmSiteCommand } from "./store-purge.mjs";
+import { defineCommand } from "citty";
+const storeCommand = defineCommand({
+	meta: {
+		name: "store",
+		description: "Manage the local DuckDB/Parquet store"
+	},
+	subCommands: {
+		"stats": statsCommand,
+		"compact": compactCommand,
+		"gc": gcCommand,
+		"export": exportCommand,
+		"rollups": rollupsCommand,
+		"rm-site": rmSiteCommand,
+		"reset": resetCommand
+	},
+	async run({ args }) {
+		if (!noSubcommandSelected("store", [
+			"stats",
+			"compact",
+			"gc",
+			"export",
+			"rollups",
+			"rm-site",
+			"reset"
+		])) return;
+		await statsCommand.run?.({
+			args,
+			cmd: statsCommand,
+			rawArgs: []
+		});
+	}
+});
+export { storeCommand };

package/dist/{_chunks → commands}/sync.mjs

@@ -1,5 +1,6 @@
-import { OUTPUT_ARGS, applyOutputMode, clearLine, displayPath, formatAge, logger, progressBar, runWithConcurrency } from "./utils.mjs";
-import { TABLE_DIMS, allTables, createCommandContext, createLocalStore, transformGscRow } from "./context.mjs";
+import { OUTPUT_ARGS, applyOutputMode, clearLine, displayPath, formatAge, logger, progressBar, runWithConcurrency } from "../utils.mjs";
+import { TABLE_DIMS, allTables, createLocalStore, transformGscRow } from "../local-store.mjs";
+import { createCommandContext } from "../context.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import { SearchTypes } from "gscdump/query";

package/dist/config.mjs

@@ -0,0 +1,43 @@
+import { useCliRuntime } from "./runtime.mjs";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+function setConfigDir(dir) {
+	useCliRuntime().configDir = dir;
+}
+function getConfigDir() {
+	return useCliRuntime().configDir;
+}
+function defaultDataDir() {
+	return path.join(os.homedir(), ".gscdump", "data");
+}
+function resolveDataDir(config) {
+	return expandTilde(config.dataDir ?? defaultDataDir());
+}
+function expandTilde(p) {
+	if (p === "~") return os.homedir();
+	if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+	return p;
+}
+async function loadConfig() {
+	return fs.readFile(path.join(getConfigDir(), "config.json"), "utf-8").then((data) => JSON.parse(data)).catch(() => ({}));
+}
+async function loadResolvedConfig() {
+	const config = await loadConfig();
+	return {
+		config,
+		dataDir: resolveDataDir(config)
+	};
+}
+async function saveConfig(config) {
+	const configDir = getConfigDir();
+	await fs.mkdir(configDir, {
+		recursive: true,
+		mode: 448
+	});
+	await fs.writeFile(path.join(configDir, "config.json"), JSON.stringify(config, null, 2), { mode: 384 });
+}
+function getConfigPath() {
+	return path.join(getConfigDir(), "config.json");
+}
+export { defaultDataDir, getConfigDir, getConfigPath, loadConfig, loadResolvedConfig, resolveDataDir, saveConfig, setConfigDir };

package/dist/{_chunks/context.mjs → context.mjs}

@@ -1,16 +1,10 @@
-import { __exportAll, loadResolvedConfig } from "./config.mjs";
+import { loadResolvedConfig } from "./config.mjs";
 import { logger } from "./utils.mjs";
 import { resolveAuth } from "./auth.mjs";
+import { createLocalStore } from "./local-store.mjs";
 import process from "node:process";
 import { cancel, isCancel, select } from "@clack/prompts";
 import { googleSearchConsole } from "gscdump";
-import { createNodeHarness } from "@gscdump/engine/node";
-import { TABLE_DIMS, transformGscRow } from "@gscdump/engine/ingest";
-import { allTables, inferTable } from "@gscdump/engine/schema";
-function createLocalStore(opts) {
-	return createNodeHarness(opts);
-}
-var context_exports = /* @__PURE__ */ __exportAll({ createCommandContext: () => createCommandContext });
 async function createCommandContext(opts = {}) {
 	const { needsAuth = false, needsStore = false, interactive = false, byok, fetchOptions } = opts;
 	const { config, dataDir } = await loadResolvedConfig();
@@ -66,4 +60,4 @@ async function createCommandContext(opts = {}) {
 		resolveSite
 	};
 }
-export { TABLE_DIMS, allTables, context_exports, createCommandContext, createLocalStore, inferTable, transformGscRow };
+export { createCommandContext };

package/dist/{_chunks/env-file.mjs → env-file.mjs}

@@ -1,7 +1,7 @@
-import { useCliRuntime } from "./config.mjs";
+import { useCliRuntime } from "./runtime.mjs";
+import path from "node:path";
 import process from "node:process";
 import fs from "node:fs";
-import path from "node:path";
 const ENV_LINE_RE = /^([^=]+)=(.*)$/;
 function parseEnvFile(envPath) {
 	let content;
@@ -50,4 +50,4 @@ function loadEnvFile(opts) {
 	}
 	return applied;
 }
-export { getAppliedEnvKeys, getLoadedEnvPath, loadEnvFromCwd, parseEnvFile };
+export { getAppliedEnvKeys, getLoadedEnvPath, loadEnvFile, loadEnvFromCwd, parseEnvFile };

package/dist/{_chunks/environment.mjs → environment.mjs}

@@ -1,4 +1,4 @@
-import { useCliRuntime } from "./config.mjs";
+import { useCliRuntime } from "./runtime.mjs";
 function resolveCliEnvironment(values = useCliRuntime().environment) {
 	return {
 		accessToken: values.GSC_ACCESS_TOKEN || values.GOOGLE_ACCESS_TOKEN,

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { CliRuntime, CreateCliRuntimeOptions, createCliRuntime } from "./runtime.mjs";
+export { type CliRuntime, type CreateCliRuntimeOptions, createCliRuntime };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { createCliRuntime } from "./runtime.mjs";
+export { createCliRuntime };

package/dist/local-store.mjs

@@ -0,0 +1,7 @@
+import { createNodeHarness } from "@gscdump/engine/node";
+import { TABLE_DIMS, transformGscRow } from "@gscdump/engine/ingest";
+import { allTables, inferTable } from "@gscdump/engine/schema";
+function createLocalStore(opts) {
+	return createNodeHarness(opts);
+}
+export { TABLE_DIMS, allTables, createLocalStore, inferTable, transformGscRow };

package/dist/mcp/errors.mjs

@@ -0,0 +1,85 @@
+import { isQueryError } from "gscdump/query";
+import { isAnalysisError } from "@gscdump/analysis/errors";
+import { isEngineError } from "@gscdump/engine/errors";
+const PERIODS = [
+	"7d",
+	"28d",
+	"30d",
+	"90d",
+	"180d",
+	"365d",
+	"mtd",
+	"ytd",
+	"custom"
+];
+const COMPARISONS = [
+	"none",
+	"prev-period",
+	"yoy"
+];
+const mcpHandlerErrors = {
+	unknownReport(id, available) {
+		return {
+			kind: "unknown-report",
+			id,
+			available,
+			message: `Unknown report id "${id}". Available: ${available.join(", ")}`
+		};
+	},
+	unknownPeriod(value) {
+		return {
+			kind: "unknown-period",
+			value,
+			supported: PERIODS,
+			message: `Unknown period "${value}". Supported: ${PERIODS.join(", ")}.`
+		};
+	},
+	unknownComparison(value) {
+		return {
+			kind: "unknown-comparison",
+			value,
+			supported: COMPARISONS,
+			message: `Unknown comparison "${value}". Supported: ${COMPARISONS.join(", ")}.`
+		};
+	},
+	noValidDimension() {
+		return {
+			kind: "no-valid-dimension",
+			message: "At least one valid dimension required"
+		};
+	}
+};
+function mcpHandlerErrorToException(error) {
+	const exception = new Error(error.message);
+	exception.mcpHandlerError = error;
+	return exception;
+}
+function enrichToolError(error) {
+	const query = asQueryError(error);
+	if (query) return /* @__PURE__ */ new Error(`[query:${query.kind}] ${query.message}`);
+	const analysis = asAnalysisError(error);
+	if (analysis) {
+		const cause = analysis.kind === "required-step-failed" ? asEngineError(analysis.cause) : null;
+		const tail = cause ? ` (engine:${cause.kind})` : "";
+		return /* @__PURE__ */ new Error(`[analysis:${analysis.kind}]${tail} ${analysis.message}`);
+	}
+	const engine = asEngineError(error);
+	if (engine) return /* @__PURE__ */ new Error(`[engine:${engine.kind}] ${engine.message}`);
+	return null;
+}
+function asQueryError(error) {
+	if (isQueryError(error)) return error;
+	const tagged = error?.queryError;
+	return isQueryError(tagged) ? tagged : null;
+}
+function asEngineError(error) {
+	if (isEngineError(error)) return error;
+	const tagged = error?.engineError;
+	return isEngineError(tagged) ? tagged : null;
+}
+function asAnalysisError(error) {
+	if (isAnalysisError(error)) return error;
+	const tagged = error?.analysisError;
+	return isAnalysisError(tagged) ? tagged : null;
+}
+export { enrichToolError, mcpHandlerErrorToException, mcpHandlerErrors };

package/dist/mcp/handlers/analytics.mjs

@@ -0,0 +1 @@
+export {};