@gscdump/cli 0.37.2 → 0.37.4

package/dist/_chunks/report.mjs

@@ -0,0 +1,243 @@
+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";
+import { defaultReportRegistry, dryRunReport, formatReport, runReport } from "@gscdump/analysis/report";
+import { resolveWindow } from "@gscdump/engine/period";
+function reportFlagErrorToException(error) {
+	const exception = new Error(error.message);
+	exception.reportFlagError = error;
+	return exception;
+}
+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 resolvePeriodResult(input, fallback) {
+	if (!input) return ok(fallback);
+	const preset = PERIOD_ALIASES[input.toLowerCase()];
+	if (!preset) return err({
+		kind: "unknown-period",
+		value: input,
+		message: `Unknown --period "${input}". Supported: 7d, 28d, 30d, 90d, 180d, 365d, mtd, ytd, custom.`
+	});
+	return ok(preset);
+}
+function resolvePeriod(input, fallback) {
+	return unwrapResult(resolvePeriodResult(input, fallback), reportFlagErrorToException);
+}
+function resolveComparisonResult(input, fallback) {
+	if (!input) return ok(fallback);
+	const mode = COMPARISON_ALIASES[input.toLowerCase()];
+	if (!mode) return err({
+		kind: "unknown-comparison",
+		value: input,
+		message: `Unknown --vs "${input}". Supported: none, prev-period, yoy.`
+	});
+	return ok(mode);
+}
+function resolveComparison(input, fallback) {
+	return unwrapResult(resolveComparisonResult(input, fallback), reportFlagErrorToException);
+}
+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))]))
+	}
+});
+export { reportCommand };

package/dist/_chunks/sitemaps.mjs

@@ -0,0 +1,274 @@
+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/api";
+const listCommand = defineCommand({
+	meta: {
+		name: "list",
+		description: "List sitemaps for a site"
+	},
+	args: {
+		...OUTPUT_ARGS,
+		site: {
+			type: "string",
+			alias: "s",
+			description: "Site URL (e.g., sc-domain:example.com or https://example.com/)"
+		},
+		pending: {
+			type: "boolean",
+			default: false,
+			description: "Show only sitemaps with isPending=true"
+		},
+		errored: {
+			type: "boolean",
+			default: false,
+			description: "Show only sitemaps with errors > 0"
+		}
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const ctx = await createCommandContext({ needsAuth: true });
+		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+		let sitemaps = (await ctx.client.sitemaps.list(siteUrl).catch(gscErrorHandler)).map((sm) => ({
+			path: sm.path,
+			type: sm.type || void 0,
+			isPending: sm.isPending || false,
+			errors: Number(sm.errors) || 0,
+			warnings: Number(sm.warnings) || 0,
+			lastDownloaded: sm.lastDownloaded || null,
+			lastSubmitted: sm.lastSubmitted || null
+		}));
+		if (args.pending) sitemaps = sitemaps.filter((sm) => sm.isPending);
+		if (args.errored) sitemaps = sitemaps.filter((sm) => sm.errors > 0);
+		if (json) {
+			console.log(JSON.stringify(sitemaps, null, 2));
+			return;
+		}
+		if (sitemaps.length === 0) {
+			logger.warn("No sitemaps found");
+			return;
+		}
+		logger.success(`Found ${sitemaps.length} 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 submitted = sm.lastSubmitted ? ` \x1B[90msubmitted ${sm.lastSubmitted}\x1B[0m` : "";
+			console.log(`  ${sm.path}${pending}${errors}${warnings}${submitted}`);
+		}
+	}
+});
+const sitemapsCommand = defineCommand({
+	meta: {
+		name: "sitemaps",
+		description: "Manage sitemaps"
+	},
+	subCommands: {
+		list: listCommand,
+		get: defineCommand({
+			meta: {
+				name: "get",
+				description: "Get details for a specific sitemap"
+			},
+			args: {
+				...OUTPUT_ARGS,
+				site: {
+					type: "string",
+					alias: "s",
+					description: "Site URL (defaults to config.defaultSite or prompt)"
+				},
+				url: {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL"
+				}
+			},
+			async run({ args }) {
+				const { json } = applyOutputMode(args);
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				const client = ctx.client;
+				const sitemap = await fetchSitemap(client, siteUrl, args.url).catch(gscErrorHandler);
+				if (json) {
+					console.log(JSON.stringify(sitemap, null, 2));
+					return;
+				}
+				console.log();
+				console.log(`  \x1B[1mPath:\x1B[0m ${sitemap.path}`);
+				console.log(`  \x1B[1mType:\x1B[0m ${sitemap.type || "sitemap"}`);
+				console.log(`  \x1B[1mLast Submitted:\x1B[0m ${sitemap.lastSubmitted || "N/A"}`);
+				console.log(`  \x1B[1mLast Downloaded:\x1B[0m ${sitemap.lastDownloaded || "N/A"}`);
+				console.log(`  \x1B[1mPending:\x1B[0m ${sitemap.isPending ? "Yes" : "No"}`);
+				console.log(`  \x1B[1mErrors:\x1B[0m ${sitemap.errors || 0}`);
+				console.log(`  \x1B[1mWarnings:\x1B[0m ${sitemap.warnings || 0}`);
+				if (sitemap.contents?.length) {
+					console.log();
+					console.log("  \x1B[1mContents:\x1B[0m");
+					for (const c of sitemap.contents) console.log(`    ${c.type}: ${c.submitted} submitted, ${c.indexed} indexed`);
+				}
+			}
+		}),
+		submit: defineCommand({
+			meta: {
+				name: "submit",
+				description: "Submit a sitemap to GSC"
+			},
+			args: {
+				...OUTPUT_ARGS,
+				site: {
+					type: "string",
+					alias: "s",
+					description: "Site URL (defaults to config.defaultSite or prompt)"
+				},
+				url: {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL to submit"
+				}
+			},
+			async run({ args }) {
+				const { json } = applyOutputMode(args);
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				await ctx.client.sitemaps.submit(siteUrl, args.url).catch(gscErrorHandler);
+				if (json) {
+					console.log(JSON.stringify({
+						siteUrl,
+						feedpath: args.url,
+						status: "submitted"
+					}, null, 2));
+					return;
+				}
+				logger.success(`Submitted sitemap: ${args.url}`);
+			}
+		}),
+		delete: defineCommand({
+			meta: {
+				name: "delete",
+				description: "Delete a sitemap from GSC"
+			},
+			args: {
+				...OUTPUT_ARGS,
+				site: {
+					type: "string",
+					alias: "s",
+					description: "Site URL (defaults to config.defaultSite or prompt)"
+				},
+				url: {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL to delete"
+				}
+			},
+			async run({ args }) {
+				const { json } = applyOutputMode(args);
+				const ctx = await createCommandContext({ needsAuth: true });
+				const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+				await ctx.client.sitemaps.delete(siteUrl, args.url).catch(gscErrorHandler);
+				if (json) {
+					console.log(JSON.stringify({
+						siteUrl,
+						feedpath: args.url,
+						status: "deleted"
+					}, null, 2));
+					return;
+				}
+				logger.success(`Deleted sitemap: ${args.url}`);
+			}
+		}),
+		discover: defineCommand({
+			meta: {
+				name: "discover",
+				description: "Probe a domain's robots.txt + common paths for an advertised sitemap (no auth needed)"
+			},
+			args: {
+				...OUTPUT_ARGS,
+				domain: {
+					type: "positional",
+					required: true,
+					description: "Domain (e.g., example.com)"
+				}
+			},
+			async run({ args }) {
+				const { json } = applyOutputMode(args);
+				const domain = String(args.domain).replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+				const url = await discoverSitemap(domain).catch(() => null);
+				if (json) {
+					console.log(JSON.stringify({
+						domain,
+						sitemap: url
+					}, null, 2));
+					return;
+				}
+				if (!url) {
+					logger.warn(`No sitemap discovered for ${domain}`);
+					process.exit(1);
+				}
+				logger.success(`Discovered sitemap: ${url}`);
+			}
+		}),
+		urls: defineCommand({
+			meta: {
+				name: "urls",
+				description: "Fetch a sitemap (or sitemap index) and dump its <loc> URLs (no auth needed)"
+			},
+			args: {
+				...OUTPUT_ARGS,
+				"url": {
+					type: "positional",
+					required: true,
+					description: "Sitemap URL (index files are followed)"
+				},
+				"limit": {
+					type: "string",
+					alias: "l",
+					description: "Stop after N URLs across all nested sitemaps"
+				},
+				"max-depth": {
+					type: "string",
+					description: "Max sitemap-index nesting depth (default: 3)"
+				}
+			},
+			async run({ args }) {
+				const { json } = applyOutputMode(args);
+				const limit = args.limit ? Number.parseInt(String(args.limit), 10) : void 0;
+				const maxDepth = args["max-depth"] ? Number.parseInt(String(args["max-depth"]), 10) : void 0;
+				const urls = await fetchSitemapUrls(String(args.url), {
+					limit,
+					maxDepth
+				}).catch((e) => {
+					logger.error(`Sitemap fetch failed: ${e.message}`);
+					process.exit(1);
+				});
+				if (json) {
+					console.log(JSON.stringify({
+						sitemap: args.url,
+						count: urls.length,
+						urls
+					}, null, 2));
+					return;
+				}
+				for (const u of urls) console.log(u);
+			}
+		})
+	},
+	async run({ args }) {
+		if (!noSubcommandSelected("sitemaps", [
+			"list",
+			"get",
+			"submit",
+			"delete",
+			"discover",
+			"urls"
+		])) return;
+		await listCommand.run?.({
+			args,
+			cmd: listCommand,
+			rawArgs: []
+		});
+	}
+});
+export { sitemapsCommand };