seo 0.2.5 → 0.2.6

package/dist/mcp.d.ts

@@ -65,7 +65,9 @@ declare function executeReport(id: string, params?: Record<string, unknown>): Pr
 declare function runReport(id: string, params?: Record<string, unknown>): Promise<ToolResult>;
 //#endregion
 //#region packages/mcp/src/index.d.ts
-declare function createServer(): McpServer;
+declare function createServer(options?: {
+  telemetry?: boolean;
+}): McpServer;
 declare function startMcpServer(opts?: {
   test?: boolean;
 }): Promise<void>;

package/dist/mcp.js

@@ -1,8 +1,8 @@
 import { createRequire as __seoCreateRequire } from 'node:module'; const require = __seoCreateRequire(import.meta.url);
-import { n as load, t as version } from "./package-BF_XgK7-.js";
+import { n as load, t as version } from "./package-B9-D646K.js";
 import { Headers, fetch as fetch$1 } from "undici";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { arch, homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import lockfile from "proper-lockfile";
@@ -149,6 +149,7 @@ function resolveSeoCliPaths(input = {}) {
 		configFile: join(configDir, "config.json"),
 		tokensFile: join(configDir, "tokens.json"),
 		oauthClientFile: join(configDir, "oauth-client.json"),
+		telemetryStateFile: join(configDir, "telemetry.json"),
 		cacheDbFile: join(cacheDir, "cache.db")
 	};
 }
@@ -25882,6 +25883,317 @@ new LocalCredentialsProvider();
 //#endregion
 //#region packages/core/dist/version.js
 const SEO_VERSION = version;
+const TELEMETRY_TIMEOUT_MS = 2e3;
+const TELEMETRY_REPORTS = [
+	"affected-urls",
+	"agent-readiness",
+	"ai-readiness",
+	"ai-referrals",
+	"ai-search-scorecard",
+	"audit-page",
+	"audit-urls",
+	"cannibalisation",
+	"community-intent",
+	"compare-crawls",
+	"content-optimization",
+	"crawl-diff",
+	"site-crawl",
+	"ctr-underperformers",
+	"decaying-pages",
+	"setup-check",
+	"entity-readiness",
+	"explain-crawl-issue",
+	"geo-gaps",
+	"crawl-report",
+	"index-coverage",
+	"index-coverage-plan",
+	"index-monitor",
+	"index-watch",
+	"internal-links",
+	"link-recovery",
+	"crawl-history",
+	"crawler-rules",
+	"llms-txt-audit",
+	"generate-llms-txt",
+	"measure-change",
+	"monthly-report",
+	"okf-build",
+	"okf-validate",
+	"page-opportunities",
+	"performance-audit",
+	"pseo-audit",
+	"query-clusters",
+	"quick-wins",
+	"redirect-trace",
+	"narrative-report",
+	"second-page",
+	"segment-impact",
+	"striking-distance",
+	"seo-to-ai-query",
+	"top-fixes",
+	"traffic-anomaly",
+	"update-correlation",
+	"search-performance-overview",
+	"monthly-action-plan",
+	"refresh-priorities",
+	"technical-watch",
+	"update-postmortem"
+];
+const RETENTION_MILESTONES = [
+	{
+		days: 1,
+		event: "active_d1"
+	},
+	{
+		days: 7,
+		event: "active_d7"
+	},
+	{
+		days: 30,
+		event: "active_d30"
+	}
+];
+const CI_ENVIRONMENT_KEYS = [
+	"GITHUB_ACTIONS",
+	"GITLAB_CI",
+	"CIRCLECI",
+	"TRAVIS",
+	"BUILDKITE",
+	"JENKINS_URL",
+	"TEAMCITY_VERSION",
+	"TF_BUILD",
+	"BITBUCKET_BUILD_NUMBER",
+	"CODEBUILD_BUILD_ID"
+];
+const TELEMETRY_NOTICE = `SEO Skill collects anonymous usage data to improve the tool (event name,
+report id, version, agent, OS, architecture, Node major, and install week;
+never URLs, report data, or identifiers of any kind).
+Docs: https://seoskill.dev/telemetry
+Disable: seo telemetry disable (or set DO_NOT_TRACK=1)\n`;
+function optionEnv(options) {
+	return options.env ?? process.env;
+}
+function optionNow(options) {
+	return options.now ?? /* @__PURE__ */ new Date();
+}
+function optionStateFile(options) {
+	return options.stateFile ?? getSeoCliPaths().telemetryStateFile;
+}
+function isEnvEnabled(value) {
+	return value === "1" || value?.toLowerCase() === "true";
+}
+function isTelemetryCi(env = process.env) {
+	return env.NODE_ENV === "test" || Boolean(env.NODE_TEST_CONTEXT) || isEnvEnabled(env.CI) || CI_ENVIRONMENT_KEYS.some((key) => Boolean(env[key]));
+}
+function environmentDisableReason(env) {
+	if (isTelemetryCi(env)) return "ci";
+	if (isEnvEnabled(env.DO_NOT_TRACK)) return "do_not_track";
+	if (isEnvEnabled(env.SEOSKILL_TELEMETRY_DISABLED) || isEnvEnabled(env.SEO_TELEMETRY_DISABLED)) return "environment";
+}
+function isTelemetryMilestone(value) {
+	return typeof value === "string" && [
+		"first_run",
+		"setup_complete",
+		"first_audit_complete",
+		"active_d1",
+		"active_d7",
+		"active_d30"
+	].includes(value);
+}
+function isTelemetryReport(value) {
+	return typeof value === "string" && TELEMETRY_REPORTS.includes(value);
+}
+function isValidCohort(value) {
+	return typeof value === "string" && /^\d{4}-W(?:0[1-9]|[1-4]\d|5[0-3])$/.test(value);
+}
+function isTelemetryState(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const state = value;
+	return typeof state.telemetryEnabled === "boolean" && typeof state.firstRunAt === "string" && Number.isFinite(Date.parse(state.firstRunAt)) && isValidCohort(state.cohort) && Array.isArray(state.sentMilestones) && state.sentMilestones.every(isTelemetryMilestone);
+}
+function readState(path) {
+	if (!existsSync(path)) return { kind: "missing" };
+	const value = readJsonFile(path);
+	return isTelemetryState(value) ? {
+		kind: "valid",
+		state: value
+	} : { kind: "invalid" };
+}
+function writeState(path, state) {
+	writeJsonAtomic(path, state, 384);
+}
+function isoWeek(date) {
+	const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+	const day = utc.getUTCDay() || 7;
+	utc.setUTCDate(utc.getUTCDate() + 4 - day);
+	const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+	const week = Math.ceil(((utc.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+	return `${utc.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+function newState(options, enabled = true) {
+	const now = optionNow(options);
+	return {
+		telemetryEnabled: enabled,
+		firstRunAt: now.toISOString(),
+		cohort: isoWeek(now),
+		sentMilestones: []
+	};
+}
+function detectTelemetryAgent(input = {}) {
+	const env = input.env ?? process.env;
+	const clientName = input.clientName?.toLowerCase() ?? "";
+	if (clientName.includes("claude")) return "claude-code";
+	if (clientName.includes("cursor")) return "cursor";
+	if (clientName.includes("codex")) return "codex";
+	if (input.clientName) return "unknown";
+	if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude-code";
+	if (env.CURSOR_AGENT || env.CURSOR_TRACE_ID || env.CURSOR_SESSION_ID) return "cursor";
+	if (env.CODEX_HOME || env.CODEX_THREAD_ID || env.CODEX_SANDBOX) return "codex";
+	return "cli";
+}
+function telemetryAgent(options) {
+	return options.agent ?? detectTelemetryAgent({
+		clientName: options.clientName,
+		env: optionEnv(options)
+	});
+}
+function nodeMajor(version) {
+	return version.replace(/^v/, "").split(".")[0] || "unknown";
+}
+function buildTelemetryPayload(event, state, fields = {}, options = {}) {
+	return {
+		event,
+		version: options.version ?? SEO_VERSION,
+		agent: telemetryAgent(options),
+		os: options.processPlatform ?? platform(),
+		arch: options.processArch ?? arch(),
+		node: nodeMajor(options.nodeVersion ?? process.version),
+		cohort: state.cohort,
+		schema: 1,
+		...fields.errorCategory ? { errorCategory: fields.errorCategory } : {},
+		...fields.report ? { report: fields.report } : {}
+	};
+}
+function dispatchTelemetry(payload, options) {
+	const fetchTelemetry = options.fetch ?? globalThis.fetch;
+	try {
+		fetchTelemetry(options.endpoint ?? "https://seoskill.dev/api/t", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(TELEMETRY_TIMEOUT_MS)
+		}).catch(() => void 0);
+	} catch {}
+}
+function statusFromState(options) {
+	const stateFile = optionStateFile(options);
+	const envReason = environmentDisableReason(optionEnv(options));
+	const stored = readState(stateFile);
+	if (envReason) return {
+		enabled: false,
+		reason: envReason,
+		stateFile,
+		...stored.kind === "valid" ? { state: stored.state } : {}
+	};
+	if (stored.kind === "invalid") return {
+		enabled: false,
+		reason: "invalid_state",
+		stateFile
+	};
+	if (stored.kind === "valid" && !stored.state.telemetryEnabled) return {
+		enabled: false,
+		reason: "local_setting",
+		stateFile,
+		state: stored.state
+	};
+	return {
+		enabled: true,
+		stateFile,
+		...stored.kind === "valid" ? { state: stored.state } : {}
+	};
+}
+function enabledState(options) {
+	const status = statusFromState(options);
+	return status.enabled ? status.state : void 0;
+}
+function initializeTelemetry(options = {}) {
+	const initialStatus = statusFromState(options);
+	if (!initialStatus.enabled) return initialStatus;
+	const stateFile = initialStatus.stateFile;
+	const state = initialStatus.state ?? newState(options);
+	const events = [];
+	if (!state.sentMilestones.includes("first_run")) {
+		try {
+			(options.notice ?? ((message) => process.stderr.write(message)))(TELEMETRY_NOTICE);
+		} catch {
+			return {
+				enabled: false,
+				reason: "invalid_state",
+				stateFile
+			};
+		}
+		state.sentMilestones.push("first_run");
+		events.push("first_run");
+	}
+	const daysSinceFirstRun = (optionNow(options).getTime() - Date.parse(state.firstRunAt)) / 864e5;
+	for (const milestone of RETENTION_MILESTONES) if (daysSinceFirstRun >= milestone.days && !state.sentMilestones.includes(milestone.event)) {
+		state.sentMilestones.push(milestone.event);
+		events.push(milestone.event);
+	}
+	try {
+		writeState(stateFile, state);
+	} catch {
+		return {
+			enabled: false,
+			reason: "invalid_state",
+			stateFile
+		};
+	}
+	for (const event of events) dispatchTelemetry(buildTelemetryPayload(event, state, {}, options), options);
+	return {
+		enabled: true,
+		stateFile,
+		state
+	};
+}
+function sendEvent(event, fields, options) {
+	const state = enabledState(options);
+	if (!state) return;
+	dispatchTelemetry(buildTelemetryPayload(event, state, fields, options), options);
+}
+function trackTelemetryReportStart(report, options = {}) {
+	if (!isTelemetryReport(report)) return;
+	sendEvent("audit_start", { report }, options);
+}
+function trackTelemetryReportComplete(report, options = {}) {
+	if (!isTelemetryReport(report)) return;
+	const state = enabledState(options);
+	if (!state) return;
+	dispatchTelemetry(buildTelemetryPayload("audit_complete", state, { report }, options), options);
+	if (state.sentMilestones.includes("first_audit_complete")) return;
+	state.sentMilestones.push("first_audit_complete");
+	try {
+		writeState(optionStateFile(options), state);
+	} catch {
+		return;
+	}
+	dispatchTelemetry(buildTelemetryPayload("first_audit_complete", state, { report }, options), options);
+}
+function trackTelemetryReportFailed(report, errorCategory, options = {}) {
+	if (!isTelemetryReport(report)) return;
+	sendEvent("audit_failed", {
+		errorCategory,
+		report
+	}, options);
+}
+function telemetryErrorCategory(error) {
+	if (error instanceof Error && error.name === "AbortError") return "crawl_timeout";
+	const code = error && typeof error === "object" && "code" in error ? String(error.code) : void 0;
+	if (code === "ACCESS_DENIED" || code === "AUTH_CONFIG_REQUIRED" || code === "AUTH_EXPIRED" || code === "AUTH_REQUIRED") return "auth";
+	if (code === "INVALID_INPUT" || code === "PROPERTY_NOT_FOUND") return "config";
+	if (code === "OPTIONAL_PROVIDER_UNAVAILABLE" || code === "PROVIDER_UNAVAILABLE" || code === "RATE_LIMITED") return "network";
+	return "unknown";
+}
 //#endregion
 //#region packages/mcp/src/input-schemas.ts
 const calendarDateSchema = z$1.iso.date("Use a YYYY-MM-DD date.");
@@ -30053,7 +30365,8 @@ async function runReport(id, params = {}) {
 //#endregion
 //#region packages/mcp/src/discovery-tools.ts
 const openOutputSchema = z$1.looseObject({});
-function registerDiscoveryTools(server) {
+const reportIds = new Set(listReports().map((report) => report.id));
+function registerDiscoveryTools(server, options = {}) {
 	server.registerTool("seo_list_reports", {
 		description: "List compact SEO report ids, names, and purposes, optionally by category",
 		inputSchema: { category: z$1.enum(REPORT_CATEGORIES).optional() },
@@ -30097,17 +30410,31 @@ function registerDiscoveryTools(server) {
 		outputSchema: openOutputSchema,
 		annotations: { destructiveHint: false }
 	}, async ({ id, params }) => {
-		return runReport(id, params);
+		const telemetry = reportIds.has(id) ? options.telemetry?.() : void 0;
+		if (telemetry) trackTelemetryReportStart(id, telemetry);
+		try {
+			const result = await runReport(id, params);
+			if (telemetry) if (result.isError) trackTelemetryReportFailed(id, telemetryErrorCategory(result.structuredContent?.error), telemetry);
+			else trackTelemetryReportComplete(id, telemetry);
+			return result;
+		} catch (error) {
+			if (telemetry) trackTelemetryReportFailed(id, telemetryErrorCategory(error), telemetry);
+			throw error;
+		}
 	});
 }
 //#endregion
 //#region packages/mcp/src/index.ts
-function createServer() {
+function createServer(options = {}) {
 	const server = new McpServer({
 		name: "seo",
 		version: SEO_VERSION
 	}, { capabilities: { logging: {} } });
-	registerDiscoveryTools(server);
+	const telemetryOptions = () => ({ clientName: server.server.getClientVersion()?.name });
+	registerDiscoveryTools(server, { telemetry: options.telemetry === false ? void 0 : telemetryOptions });
+	if (options.telemetry !== false) server.server.oninitialized = () => {
+		initializeTelemetry(telemetryOptions());
+	};
 	return server;
 }
 async function startMcpServer(opts = {}) {