create-better-t-stack 3.40.5 → 3.41.0

package/README.md

@@ -128,6 +128,9 @@ This CLI collects anonymous usage data to help improve the tool. The data collec
 - CLI version
 - Node.js version
 - Platform (OS)
+- How the CLI was driven (prompts, flags, `--yes`, JSON, the programmatic API, or the MCP server)
+
+Separately, a small number of anonymous diagnostic events are sent for failures (stage and error class, never full messages or paths), cancelled prompts, other commands such as `add` and `history`, slow runs, and MCP tool usage. See the [analytics documentation](https://better-t-stack.dev/docs/analytics) for the exact list.
 
 **Telemetry is enabled by default in published versions** to help us understand usage patterns and improve the tool.
 
@@ -143,6 +146,8 @@ BTS_TELEMETRY_DISABLED=1 npx create-better-t-stack
 export BTS_TELEMETRY_DISABLED=1
 ```
 
+The CLI also honors the cross-tool `DO_NOT_TRACK=1` convention (https://consoledonottrack.com), and `--disable-analytics` skips telemetry for a single run.
+
 ## Examples
 
 Create a project with default configuration:

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli, v as types_exports, y as getLatestCLIVersion } from "./src-E3yd8mxg.mjs";
+import { A as setProcessMode, S as getLatestCLIVersion, b as scrubReason, i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli, v as durationBucket, x as types_exports, y as reportDiagnostic } from "./src-NAkPN6DN.mjs";
 import z from "zod";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 //#region src/mcp.ts
 const ToolResponseSchema = z.object({
 	ok: z.boolean(),
@@ -58,6 +58,44 @@ function formatToolError(cause) {
 		isError: true
 	};
 }
+const reportedSessions = /* @__PURE__ */ new WeakSet();
+/** One session event per connection, sent when the client identity is first known. */
+function reportMcpSession(server) {
+	if (reportedSessions.has(server)) return;
+	reportedSessions.add(server);
+	const client = server.server.getClientVersion();
+	reportDiagnostic("mcp_session", {
+		client: client?.name ?? "unknown",
+		clientVersion: client?.version ?? "unknown"
+	});
+}
+/**
+* Times every tool call and reports the outcome. Diagnostics are fire-and-forget here
+* because the server process is long-lived and must not add latency to tool results.
+*/
+function instrumentTool(server, tool, handler, isOptedOut) {
+	return async (...args) => {
+		if (isOptedOut?.(...args)) return handler(...args);
+		reportMcpSession(server);
+		const startTime = Date.now();
+		const result = await handler(...args);
+		const ok = !("isError" in result);
+		reportDiagnostic("mcp_tool", {
+			tool,
+			ok,
+			duration: durationBucket(Date.now() - startTime)
+		});
+		if (!ok) reportDiagnostic("mcp_tool_error", {
+			tool,
+			error: "ToolError",
+			reason: scrubReason(result.structuredContent.error)
+		});
+		return result;
+	};
+}
+function isCreateOptedOut(input) {
+	return input.disableAnalytics === true;
+}
 function getProjectToolAnnotations() {
 	return {
 		destructiveHint: true,
@@ -128,10 +166,14 @@ function getStackGuidance() {
 	};
 }
 function createBtsMcpServer() {
+	setProcessMode("mcp");
 	const server = new McpServer({
 		name: "create-better-t-stack",
 		version: getLatestCLIVersion()
-	}, { capabilities: { logging: {} } });
+	}, { cacheHints: { "tools/list": {
+		ttlMs: 3600 * 1e3,
+		cacheScope: "public"
+	} } });
 	server.registerTool("bts_get_stack_guidance", {
 		title: "Get Better T Stack MCP Guidance",
 		description: "Read MCP-specific guidance for choosing valid Better T Stack configurations. Use this before planning when user intent is ambiguous. This explains the full explicit config required by MCP project creation, plus important field semantics and ambiguity rules.",
@@ -143,13 +185,13 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async () => {
+	}, instrumentTool(server, "bts_get_stack_guidance", async () => {
 		try {
 			return formatToolSuccess(getStackGuidance());
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	server.registerTool("bts_get_schema", {
 		title: "Get Better T Stack Schemas",
 		description: "Inspect Better T Stack CLI and input schemas so agents can plan valid create/add requests. Use this together with bts_get_stack_guidance before creating a project if any part of the request is ambiguous.",
@@ -162,13 +204,13 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async ({ name }) => {
+	}, instrumentTool(server, "bts_get_schema", async ({ name }) => {
 		try {
 			return formatToolSuccess(getSchemaResult(name ?? "all"));
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	server.registerTool("bts_plan_project", {
 		title: "Plan Better T Stack Project",
 		description: "Validate and preview a Better T Stack project creation without writing files or provisioning resources. Always use this before bts_create_project. This tool requires an explicit full stack config rather than a partial payload with inferred defaults.",
@@ -181,7 +223,7 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_plan_project", async (input) => {
 		try {
 			const result = await create(input.projectName, {
 				...input,
@@ -200,7 +242,7 @@ function createBtsMcpServer() {
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}, isCreateOptedOut));
 	server.registerTool("bts_create_project", {
 		title: "Create Better T Stack Project",
 		description: "Create a Better T Stack project on disk using the same silent programmatic flow as the CLI JSON API. Call this only after bts_plan_project succeeds and the plan clearly matches the user's intent. This tool requires an explicit full stack config.",
@@ -210,19 +252,19 @@ function createBtsMcpServer() {
 			title: "Create Better T Stack Project",
 			...getProjectToolAnnotations()
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_create_project", async (input) => {
 		try {
 			if (input.install) return formatToolError(getMcpInstallTimeoutMessage(input.packageManager));
 			const result = await create(input.projectName, {
 				...input,
-				disableAnalytics: true
+				disableAnalytics: input.disableAnalytics ?? false
 			});
 			if (result.isErr()) return formatToolError(result.error);
 			return formatToolSuccess(result.value);
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}, isCreateOptedOut));
 	server.registerTool("bts_plan_addons", {
 		title: "Plan Better T Stack Project Additions",
 		description: "Validate and preview addon installation or workspace package scaffolding for an existing Better T Stack project without writing files. Always use this before bts_add_addons.",
@@ -235,7 +277,7 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_plan_addons", async (input) => {
 		try {
 			const result = await add({
 				...input,
@@ -246,7 +288,7 @@ function createBtsMcpServer() {
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	server.registerTool("bts_add_addons", {
 		title: "Apply Better T Stack Project Additions",
 		description: "Install addons or scaffold a workspace package in an existing Better T Stack project using the same silent flow as add-json. Call this only after bts_plan_addons succeeds and the planned changes match the user's intent.",
@@ -258,7 +300,7 @@ function createBtsMcpServer() {
 			idempotentHint: false,
 			openWorldHint: true
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_add_addons", async (input) => {
 		try {
 			const result = await add(input);
 			if (!result?.success) return formatToolError(result?.error ?? "Failed to update project");
@@ -266,13 +308,11 @@ function createBtsMcpServer() {
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	return server;
 }
-async function startBtsMcpServer() {
-	const server = createBtsMcpServer();
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
+function startBtsMcpServer() {
+	return serveStdio(() => createBtsMcpServer());
 }
 //#endregion
 //#region src/cli.ts

package/dist/index.d.mts

@@ -12,9 +12,12 @@ declare const UserCancelledError_base: import("better-result").TaggedErrorClass<
  */
 declare class UserCancelledError extends UserCancelledError_base<{
   message: string;
+  /** Name of the prompt that was open when the user cancelled, when known. */
+  prompt?: string;
 }> {
   constructor(args?: {
     message?: string;
+    prompt?: string;
   });
 }
 declare const CLIError_base: import("better-result").TaggedErrorClass<"CLIError">;

package/dist/index.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { C as DirectoryConflictError, E as ValidationError, S as DatabaseSetupError, T as UserCancelledError, _ as ProjectLauncherSchema, a as TEMPLATE_COUNT, b as CLIError, c as builder, d as createVirtual, f as docs, g as sponsors, h as router, i as SchemaNameSchema, l as create, m as getSchemaResult, n as GeneratorError, o as VirtualFileSystem, p as generate, r as Result, s as add, t as EMBEDDED_TEMPLATES, u as createBtsCli, w as ProjectCreationError, x as CompatibilityError } from "./src-E3yd8mxg.mjs";
+import { C as CLIError, D as ProjectCreationError, E as DirectoryConflictError, O as UserCancelledError, T as DatabaseSetupError, _ as ProjectLauncherSchema, a as TEMPLATE_COUNT, c as builder, d as createVirtual, f as docs, g as sponsors, h as router, i as SchemaNameSchema, k as ValidationError, l as create, m as getSchemaResult, n as GeneratorError, o as VirtualFileSystem, p as generate, r as Result, s as add, t as EMBEDDED_TEMPLATES, u as createBtsCli, w as CompatibilityError } from "./src-NAkPN6DN.mjs";
 export { CLIError, CompatibilityError, DatabaseSetupError, DirectoryConflictError, EMBEDDED_TEMPLATES, GeneratorError, ProjectCreationError, ProjectLauncherSchema, Result, SchemaNameSchema, TEMPLATE_COUNT, UserCancelledError, ValidationError, VirtualFileSystem, add, builder, create, createBtsCli, createVirtual, docs, generate, getSchemaResult, router, sponsors };

package/dist/{src-E3yd8mxg.mjs → src-NAkPN6DN.mjs}

@@ -234,6 +234,14 @@ const ADDON_COMPATIBILITY = {
 //#endregion
 //#region src/utils/context.ts
 const cliStorage = new AsyncLocalStorage();
+/** Process-wide mode for hosts that own the whole process, such as the MCP server. */
+let processMode;
+function setProcessMode(mode) {
+	processMode = mode;
+}
+function getProcessMode() {
+	return processMode;
+}
 function defaultContext() {
 	return {
 		navigation: {
@@ -241,7 +249,9 @@ function defaultContext() {
 			lastPromptShownUI: false
 		},
 		silent: false,
-		verbose: false
+		verbose: false,
+		promptShown: false,
+		analyticsDisabled: false
 	};
 }
 function getContext() {
@@ -264,6 +274,20 @@ function didLastPromptShowUI() {
 function getPromptProgress() {
 	return getContext().navigation.promptProgress;
 }
+function markPromptShown() {
+	const ctx = tryGetContext();
+	if (ctx) ctx.promptShown = true;
+}
+/**
+* How this run is being driven. Hosts that know (json, api, mcp) set it up front;
+* otherwise it is derived from whether prompts were rendered.
+*/
+function resolveInvocationMode(yes) {
+	const ctx = getContext();
+	if (ctx.mode) return ctx.mode;
+	if (yes) return "yes";
+	return ctx.promptShown ? "interactive" : "flags";
+}
 function setIsFirstPrompt$1(value) {
 	const ctx = tryGetContext();
 	if (ctx) ctx.navigation.isFirstPrompt = value;
@@ -276,19 +300,24 @@ function setPromptProgress(value) {
 	const ctx = tryGetContext();
 	if (ctx) ctx.navigation.promptProgress = value;
 }
-async function runWithContextAsync(options, fn) {
-	const ctx = {
+function createContext(options) {
+	return {
 		navigation: {
 			isFirstPrompt: false,
 			lastPromptShownUI: false
 		},
 		silent: options.silent ?? false,
 		verbose: options.verbose ?? false,
+		mode: options.mode ?? processMode,
+		promptShown: false,
+		analyticsDisabled: options.analyticsDisabled ?? false,
 		projectDir: options.projectDir,
 		projectName: options.projectName,
 		packageManager: options.packageManager
 	};
-	return cliStorage.run(ctx, fn);
+}
+async function runWithContextAsync(options, fn) {
+	return cliStorage.run(createContext(options), fn);
 }
 //#endregion
 //#region src/utils/terminal-output.ts
@@ -348,7 +377,10 @@ const cliConsola = {
 */
 var UserCancelledError = class extends TaggedError("UserCancelledError") {
 	constructor(args) {
-		super({ message: args?.message ?? "Operation cancelled" });
+		super({
+			message: args?.message ?? "Operation cancelled",
+			prompt: args?.prompt
+		});
 	}
 };
 /**
@@ -633,34 +665,36 @@ function formatHistoryEntry(entry, index) {
 	const details = rows.map(({ label, value }) => `${pc.dim(label.padEnd(labelWidth))}  ${value}`).join("\n");
 	return `${pc.cyan(pc.bold(`${index + 1}. ${entry.projectName}`))}\n${details}\n${pc.dim("Recreate")}\n${pc.cyan(entry.reproducibleCommand)}`;
 }
+/** Resolves to whether the command did what was asked; failures are reported to the user here. */
 async function historyHandler(input) {
 	if (input.clear) {
 		const clearResult = await clearHistory();
 		if (clearResult.isErr()) {
 			log.warn(pc.yellow(clearResult.error.message));
-			return;
+			return false;
 		}
 		log.success(pc.green("Project history cleared."));
-		return;
+		return true;
 	}
 	const historyResult = await getHistory(input.limit);
 	if (historyResult.isErr()) {
 		log.warn(pc.yellow(historyResult.error.message));
-		return;
+		return false;
 	}
 	const entries = historyResult.value;
 	if (input.json) {
 		console.log(JSON.stringify(entries, null, 2));
-		return;
+		return true;
 	}
 	renderTitle();
 	intro(pc.magenta(`Project history · ${entries.length}`));
 	if (entries.length === 0) {
 		outro(`${pc.dim("No saved projects yet · create one with")} ${pc.cyan("create-better-t-stack my-app")}`);
-		return;
+		return true;
 	}
 	log.message(entries.map(formatHistoryEntry).join("\n\n"));
 	outro(pc.dim("Run a command above to recreate that project"));
+	return true;
 }
 //#endregion
 //#region src/utils/open-url.ts
@@ -1704,6 +1738,125 @@ async function updateBtsConfig(projectDir, updates) {
 	} catch {}
 }
 //#endregion
+//#region src/utils/telemetry.ts
+/**
+* Returns true if telemetry/analytics should be enabled, false otherwise.
+*
+* - DO_NOT_TRACK=1 (the cross-tool convention from consoledonottrack.com) disables analytics.
+* - If BTS_TELEMETRY_DISABLED is present and "1", disables analytics.
+* - Otherwise, BTS_TELEMETRY: "0" disables, "1" enables (default: enabled).
+*/
+function isTelemetryEnabled() {
+	const DO_NOT_TRACK = process.env.DO_NOT_TRACK;
+	const BTS_TELEMETRY_DISABLED = process.env.BTS_TELEMETRY_DISABLED;
+	if (DO_NOT_TRACK === "1" || DO_NOT_TRACK?.toLowerCase() === "true") return false;
+	if (BTS_TELEMETRY_DISABLED !== void 0) return BTS_TELEMETRY_DISABLED !== "1";
+	return true;
+}
+//#endregion
+//#region src/utils/diagnostics.ts
+/**
+* Diagnostic events go to the self-hosted Umami instance (a separate "CLI" website),
+* not to the Convex project dataset. They cover what the project-creation event
+* cannot: failures, cancellations, non-create commands, slow stages, and MCP usage.
+* Everything is a no-op until UMAMI_CLI_WEBSITE_ID is baked in at build time.
+*/
+const UMAMI_HOST_URL = "https://umami.amanv.cloud";
+const UMAMI_CLI_WEBSITE_ID = "e658611d-dbcc-4d3a-bc4e-182b9f5b0d5d";
+const SEND_TIMEOUT_MS$1 = 3e3;
+const MAX_STRING_LENGTH = 500;
+const MAX_REASON_LENGTH = 160;
+const DURATION_BUCKETS = [
+	[1e3, "<1s"],
+	[5e3, "1-5s"],
+	[15e3, "5-15s"],
+	[6e4, "15-60s"],
+	[3e5, "1-5m"]
+];
+function durationBucket(elapsedMs) {
+	for (const [limit, label] of DURATION_BUCKETS) if (elapsedMs < limit) return label;
+	return ">5m";
+}
+/** Class name of the failure, which is stable and never carries user content. */
+function errorClass(cause) {
+	if (cause instanceof Error) return cause.name || cause.constructor.name || "Error";
+	return "UnknownError";
+}
+/** Coarse stage a create/add failure belongs to, derived from the tagged error types. */
+function failureStage(cause) {
+	if (ProjectCreationError.is(cause)) return cause.phase;
+	if (DatabaseSetupError.is(cause)) return "database-setup";
+	if (AddonSetupError.is(cause)) return "addons-setup";
+	if (DirectoryConflictError.is(cause)) return "directory";
+	if (ValidationError.is(cause) || CompatibilityError.is(cause)) return "validate";
+	if (CLIError.is(cause)) return "config";
+	return "unknown";
+}
+/**
+* First line of an error message with anything that could identify a machine or
+* project replaced by placeholders: file paths, URLs, emails, and quoted names.
+*/
+function scrubReason(cause) {
+	const scrubbed = ((cause instanceof Error ? cause.message : String(cause)).split(/\r?\n/, 1)[0] ?? "").replaceAll(/(["'`])(?:(?!\1).)*\1/g, "<name>").replaceAll(/https?:\/\/[^\s)\]"'>]+/gi, "<url>").replaceAll(/[\w.+-]+@[\w-]+\.[\w.-]+/g, "<email>").replaceAll(/(?:[a-zA-Z]:)?(?:[\\/][\w.@+ -]+)+[\\/][\w.@+-]+(?:[ \w.@+-]*\.\w+)?/g, "<path>").replaceAll(/\S*[\\/]\S*/g, "<path>").replaceAll(/\s+/g, " ").trim();
+	return scrubbed.length > MAX_REASON_LENGTH ? scrubbed.slice(0, MAX_REASON_LENGTH) : scrubbed;
+}
+function clampValue(value) {
+	const text = String(value);
+	return text.length > MAX_STRING_LENGTH ? text.slice(0, MAX_STRING_LENGTH) : value;
+}
+function isDiagnosticsEnabled() {
+	return Boolean(UMAMI_HOST_URL) && Boolean(UMAMI_CLI_WEBSITE_ID) && isTelemetryEnabled() && !getContext().analyticsDisabled;
+}
+function eventUrl(name, data) {
+	if (name.startsWith("mcp_")) return "/mcp";
+	const command = data.command;
+	return command === void 0 ? `/${name}` : `/${String(command)}`;
+}
+function buildDiagnosticPayload(name, data) {
+	const eventData = {};
+	for (const [key, value] of Object.entries(data)) if (value !== void 0) eventData[key] = clampValue(value);
+	return {
+		type: "event",
+		payload: {
+			website: UMAMI_CLI_WEBSITE_ID,
+			hostname: "cli",
+			url: eventUrl(name, eventData),
+			title: name,
+			name,
+			data: eventData
+		}
+	};
+}
+function diagnosticUserAgent() {
+	return `Mozilla/5.0 (compatible; create-better-t-stack/${getLatestCLIVersion()})`;
+}
+async function reportDiagnostic(name, data) {
+	if (!isDiagnosticsEnabled()) return;
+	await Result.tryPromise({
+		try: () => fetch(`${UMAMI_HOST_URL}/api/send`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"User-Agent": diagnosticUserAgent()
+			},
+			body: JSON.stringify(buildDiagnosticPayload(name, data)),
+			signal: AbortSignal.timeout(SEND_TIMEOUT_MS$1),
+			keepalive: true
+		}),
+		catch: () => void 0
+	});
+}
+/** Reports a stage only when it crossed the slow threshold, so the event is a signal. */
+async function reportSlowStage(command, stage, elapsedMs, packageManager) {
+	if (elapsedMs < 6e4) return;
+	await reportDiagnostic("cli_slow", {
+		command,
+		stage,
+		duration: durationBucket(elapsedMs),
+		packageManager
+	});
+}
+//#endregion
 //#region src/utils/input-hardening.ts
 function hasControlCharacters(value) {
 	for (const char of value) {
@@ -2561,6 +2714,7 @@ async function navigableGroup(prompts, opts) {
 			setIsFirstPrompt$1(currentIndex === 0);
 			setLastPromptShownUI(false);
 			const presetResult = opts?.preselected?.[name];
+			if (presetResult === void 0) markPromptShown();
 			const result = presetResult !== void 0 ? presetResult : await prompt({
 				results,
 				previousAnswer: previousAnswers[name]
@@ -2577,7 +2731,10 @@ async function navigableGroup(prompts, opts) {
 			if (isCancel$1(result)) {
 				if (opts?.onCancel) {
 					results[name] = "canceled";
-					opts.onCancel({ results });
+					opts.onCancel({
+						results,
+						prompt: String(name)
+					});
 				}
 				return results;
 			}
@@ -4759,9 +4916,14 @@ function updateViteConfigImportsForVitePlus(vfs) {
 	}
 }
 async function addHandler(input, options = {}) {
-	const { silent = false } = options;
-	return runWithContextAsync({ silent }, async () => {
+	const { silent = false, mode } = options;
+	return runWithContextAsync({
+		silent,
+		mode
+	}, async () => {
+		const startTime = Date.now();
 		const result = await addHandlerInternal(input);
+		await reportAddOutcome(input, result, Date.now() - startTime);
 		if (result.isOk()) return result.value;
 		const error = result.error;
 		if (UserCancelledError.is(error)) {
@@ -4783,6 +4945,42 @@ async function addHandler(input, options = {}) {
 		process.exit(1);
 	});
 }
+async function reportAddOutcome(input, result, elapsedMs) {
+	const mode = resolveInvocationMode(false);
+	const duration = durationBucket(elapsedMs);
+	if (result.isOk()) {
+		await reportDiagnostic("cli_command", {
+			command: "add",
+			mode,
+			ok: true,
+			duration
+		});
+		return;
+	}
+	const error = result.error;
+	if (UserCancelledError.is(error)) {
+		await reportDiagnostic("cli_cancelled", {
+			command: "add",
+			mode,
+			prompt: error.prompt ?? "unknown"
+		});
+		return;
+	}
+	await reportDiagnostic("cli_command", {
+		command: "add",
+		mode,
+		ok: false,
+		duration
+	});
+	await reportDiagnostic("cli_failed", {
+		command: "add",
+		mode,
+		stage: failureStage(error),
+		error: errorClass(error),
+		reason: scrubReason(error),
+		packageManager: input.packageManager
+	});
+}
 async function addHandlerInternal(input) {
 	const projectDir = input.projectDir || process.cwd();
 	const hardeningResult = validateAgentSafePathInput(projectDir, "projectDir");
@@ -4795,7 +4993,7 @@ async function addHandlerInternal(input) {
 		intro(pc.magenta("Add to your project"));
 	}
 	const existingConfig = await detectProjectConfig(projectDir);
-	if (!existingConfig) return Result.err(new CLIError({ message: `No Better-T-Stack project found in ${projectDir}. Make sure bts.jsonc exists.` }));
+	if (!existingConfig) return Result.err(new CLIError({ message: `No Better-T-Stack project found in "${projectDir}". Make sure bts.jsonc exists.` }));
 	if (!isSilent()) log.info(pc.dim(`Detected project: ${existingConfig.projectName}`));
 	let addonsToAdd;
 	if (input.addons && input.addons.length > 0) {
@@ -6080,8 +6278,11 @@ async function gatherConfig(flags, projectName, projectDir, relativePath, option
 				]
 			}
 		],
-		onCancel: () => {
-			throw new UserCancelledError({ message: "Operation cancelled" });
+		onCancel: ({ prompt }) => {
+			throw new UserCancelledError({
+				message: "Operation cancelled",
+				prompt
+			});
 		}
 	});
 	return {
@@ -6151,6 +6352,7 @@ async function getProjectName(initialName) {
 		counter++;
 	}
 	while (!isValid) {
+		markPromptShown();
 		const response = await text({
 			message: "Where should we create your project?",
 			placeholder: defaultName,
@@ -6165,40 +6367,34 @@ async function getProjectName(initialName) {
 				}
 			}
 		});
-		if (isCancel(response)) throw new UserCancelledError({ message: "Operation cancelled." });
+		if (isCancel(response)) throw new UserCancelledError({
+			message: "Operation cancelled.",
+			prompt: "projectName"
+		});
 		projectPath = response || defaultName;
 		isValid = true;
 	}
 	return projectPath;
 }
 //#endregion
-//#region src/utils/telemetry.ts
-/**
-* Returns true if telemetry/analytics should be enabled, false otherwise.
-*
-* - If BTS_TELEMETRY_DISABLED is present and "1", disables analytics.
-* - Otherwise, BTS_TELEMETRY: "0" disables, "1" enables (default: enabled).
-*/
-function isTelemetryEnabled() {
-	const BTS_TELEMETRY_DISABLED = process.env.BTS_TELEMETRY_DISABLED;
-	if (BTS_TELEMETRY_DISABLED !== void 0) return BTS_TELEMETRY_DISABLED !== "1";
-	return true;
-}
-//#endregion
 //#region src/utils/analytics.ts
 const CONVEX_INGEST_URL = "https://striped-seahorse-863.convex.site/api/analytics/ingest";
+const SEND_TIMEOUT_MS = 3e3;
 async function sendConvexEvent(payload) {
 	await Result.tryPromise({
 		try: () => fetch(CONVEX_INGEST_URL, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify(payload)
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+			keepalive: true
 		}),
 		catch: () => void 0
 	});
 }
-function buildAnalyticsEvent(config) {
+function buildAnalyticsEvent(config, mode) {
 	return types_exports.AnalyticsEventSchema.parse({
+		mode,
 		database: config.database,
 		orm: config.orm,
 		backend: config.backend,
@@ -6220,10 +6416,10 @@ function buildAnalyticsEvent(config) {
 		platform: process.platform
 	});
 }
-async function trackProjectCreation(config, disableAnalytics = false) {
+async function trackProjectCreation(config, disableAnalytics = false, mode) {
 	if (!isTelemetryEnabled() || disableAnalytics) return;
 	await Result.tryPromise({
-		try: () => sendConvexEvent(buildAnalyticsEvent(config)),
+		try: () => sendConvexEvent(buildAnalyticsEvent(config, mode)),
 		catch: () => void 0
 	});
 }
@@ -8809,10 +9005,14 @@ async function createProject(options, cliInput) {
 		}));
 		yield* Result.await(formatProject(projectDir));
 		if (!isSilent()) log.success("Project scaffolded");
-		if (options.install) yield* Result.await(installDependencies({
-			projectDir,
-			packageManager: options.packageManager
-		}));
+		if (options.install) {
+			const installStartTime = Date.now();
+			yield* Result.await(installDependencies({
+				projectDir,
+				packageManager: options.packageManager
+			}));
+			await reportSlowStage("create", "install", Date.now() - installStartTime, options.packageManager);
+		}
 		yield* Result.await(initializeGit(projectDir, options.git));
 		if (!isSilent()) await displayPostInstallInstructions({
 			...options,
@@ -8875,17 +9075,49 @@ function createEmptyResult(timeScaffolded, elapsedTimeMs, error) {
 	};
 }
 async function executeCreateProjectHandler(input, options) {
-	const { silent = false } = options;
-	return runWithContextAsync({ silent }, async () => {
+	const { silent = false, mode } = options;
+	return runWithContextAsync({
+		silent,
+		mode,
+		analyticsDisabled: input.disableAnalytics
+	}, async () => {
 		const startTime = Date.now();
 		const timeScaffolded = (/* @__PURE__ */ new Date()).toISOString();
+		const result = await createProjectHandlerInternal(input, startTime, timeScaffolded);
+		await reportCreateOutcome(input, result, Date.now() - startTime);
 		return {
-			result: await createProjectHandlerInternal(input, startTime, timeScaffolded),
+			result,
 			startTime,
 			timeScaffolded
 		};
 	});
 }
+/** Diagnostics for what the success-only project event cannot show; awaited so it beats process.exit. */
+async function reportCreateOutcome(input, result, elapsedMs) {
+	const mode = resolveInvocationMode(input.yes);
+	if (result.isOk()) {
+		if (!input.dryRun) await reportSlowStage("create", "create", elapsedMs, input.packageManager ?? "unknown");
+		return;
+	}
+	const error = result.error;
+	if (UserCancelledError.is(error)) {
+		await reportDiagnostic("cli_cancelled", {
+			command: "create",
+			mode,
+			prompt: error.prompt ?? "unknown"
+		});
+		return;
+	}
+	await reportDiagnostic("cli_failed", {
+		command: "create",
+		mode,
+		stage: failureStage(error),
+		error: errorClass(error),
+		reason: scrubReason(error),
+		packageManager: input.packageManager,
+		backend: input.backend
+	});
+}
 async function createProjectHandlerResult(input, options = {}) {
 	return (await executeCreateProjectHandler(input, options)).result;
 }
@@ -9058,7 +9290,7 @@ async function createProjectHandlerInternal(input, startTime, timeScaffolded) {
 			dbSetupOptions: effectiveDbSetupOptions,
 			packageManagerVersion: localRequirements.packageManagerVersion
 		}));
-		await trackProjectCreation(config, input.disableAnalytics);
+		await trackProjectCreation(config, input.disableAnalytics, resolveInvocationMode(input.yes));
 		const historyResult = await addToHistory(config, reproducibleCommand);
 		if (historyResult.isErr() && !isSilent()) {
 			log.warn(pc.yellow(historyResult.error.message));
@@ -9259,15 +9491,18 @@ const router = t.router({
 		description: "Create a project from a raw JSON payload (agent-friendly)",
 		jsonInput: "always"
 	}).input(types_exports.CreateInputSchema).mutation(async ({ input }) => {
-		const result = await createProjectHandler(input, { silent: true });
+		const result = await createProjectHandler(input, {
+			silent: true,
+			mode: "json"
+		});
 		if (!result) throw new UserCancelledError({ message: "Operation cancelled" });
 		if (!result.success) throw new CLIError({ message: result.error || "Unknown error occurred" });
 		return result;
 	}),
 	schema: t.procedure.meta({ description: "Show runtime CLI and input schemas as JSON" }).input(z.object({ name: SchemaNameSchema.describe("Schema name to inspect") })).query(({ input }) => getSchemaResult(input.name)),
-	sponsors: t.procedure.meta({ description: "Show Better-T-Stack sponsors" }).mutation(() => showSponsorsCommand()),
-	docs: t.procedure.meta({ description: "Open Better-T-Stack documentation" }).mutation(() => openDocsCommand()),
-	builder: t.procedure.meta({ description: "Open the web-based stack builder" }).mutation(() => openBuilderCommand()),
+	sponsors: t.procedure.meta({ description: "Show Better-T-Stack sponsors" }).mutation(() => trackCommand("sponsors", () => showSponsorsCommand())),
+	docs: t.procedure.meta({ description: "Open Better-T-Stack documentation" }).mutation(() => trackCommand("docs", () => openDocsCommand())),
+	builder: t.procedure.meta({ description: "Open the web-based stack builder" }).mutation(() => trackCommand("builder", () => openBuilderCommand())),
 	add: t.procedure.meta({ description: "Add addons or a workspace package to an existing Better-T-Stack project" }).input(z.object({
 		addons: z.array(types_exports.AddonsSchema).optional().describe("Addons to add"),
 		package: types_exports.WorkspacePackageNameSchema.optional(),
@@ -9282,7 +9517,10 @@ const router = t.router({
 		description: "Add addons or a workspace package from a raw JSON payload (agent-friendly)",
 		jsonInput: "always"
 	}).input(types_exports.AddInputSchema).mutation(async ({ input }) => {
-		const result = await addHandler(input, { silent: true });
+		const result = await addHandler(input, {
+			silent: true,
+			mode: "json"
+		});
 		if (!result) throw new UserCancelledError({ message: "Operation cancelled" });
 		if (!result.success) throw new CLIError({ message: result.error || "Unknown error occurred" });
 		return result;
@@ -9292,9 +9530,29 @@ const router = t.router({
 		clear: z.boolean().optional().default(false).describe("Clear all history"),
 		json: z.boolean().optional().default(false).describe("Output as JSON")
 	})).mutation(async ({ input }) => {
-		await historyHandler(input);
+		await trackCommand("history", () => historyHandler(input), (ok) => ok);
 	})
 });
+/** Usage diagnostics for commands that have no project event of their own. */
+async function trackCommand(command, run, isOk = () => true) {
+	const startTime = Date.now();
+	try {
+		const value = await run();
+		await reportDiagnostic("cli_command", {
+			command,
+			ok: isOk(value),
+			duration: durationBucket(Date.now() - startTime)
+		});
+		return value;
+	} catch (cause) {
+		await reportDiagnostic("cli_command", {
+			command,
+			ok: false,
+			duration: durationBucket(Date.now() - startTime)
+		});
+		throw cause;
+	}
+}
 function createBtsCli() {
 	return createCli({
 		router,
@@ -9352,7 +9610,10 @@ async function create(projectName, options) {
 	};
 	return Result.tryPromise({
 		try: async () => {
-			const result = await createProjectHandlerResult(input, { silent: true });
+			const result = await createProjectHandlerResult(input, {
+				silent: true,
+				mode: getProcessMode() ?? "api"
+			});
 			if (result.isErr()) throw result.error;
 			return result.value;
 		},
@@ -9467,7 +9728,10 @@ async function add(options = {}) {
 		projectDir: "",
 		error: formatInputValidationError("add", parsedInput.error)
 	};
-	return await addHandler(parsedInput.data, { silent: true }) ?? {
+	return await addHandler(parsedInput.data, {
+		silent: true,
+		mode: getProcessMode() ?? "api"
+	}) ?? {
 		success: false,
 		addedAddons: [],
 		projectDir: parsedInput.data.projectDir ?? "",
@@ -9475,4 +9739,4 @@ async function add(options = {}) {
 	};
 }
 //#endregion
-export { DirectoryConflictError as C, ValidationError as E, DatabaseSetupError as S, UserCancelledError as T, ProjectLauncherSchema as _, TEMPLATE_COUNT as a, CLIError as b, builder as c, createVirtual as d, docs as f, sponsors as g, router as h, SchemaNameSchema as i, create as l, getSchemaResult as m, GeneratorError$1 as n, VirtualFileSystem$1 as o, generate$1 as p, Result$1 as r, add as s, EMBEDDED_TEMPLATES$1 as t, createBtsCli as u, types_exports as v, ProjectCreationError as w, CompatibilityError as x, getLatestCLIVersion as y };
+export { setProcessMode as A, CLIError as C, ProjectCreationError as D, DirectoryConflictError as E, UserCancelledError as O, getLatestCLIVersion as S, DatabaseSetupError as T, ProjectLauncherSchema as _, TEMPLATE_COUNT as a, scrubReason as b, builder as c, createVirtual as d, docs as f, sponsors as g, router as h, SchemaNameSchema as i, ValidationError as k, create as l, getSchemaResult as m, GeneratorError$1 as n, VirtualFileSystem$1 as o, generate$1 as p, Result$1 as r, add as s, EMBEDDED_TEMPLATES$1 as t, createBtsCli as u, durationBucket as v, CompatibilityError as w, types_exports as x, reportDiagnostic as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-better-t-stack",
-  "version": "3.40.5",
+  "version": "3.41.0",
   "description": "A modern CLI tool for scaffolding end-to-end type-safe TypeScript projects with best practices and customizable configurations",
   "keywords": [
     "better-auth",
@@ -69,11 +69,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@better-t-stack/template-generator": "^3.40.5",
-    "@better-t-stack/types": "^3.40.5",
+    "@better-t-stack/template-generator": "^3.41.0",
+    "@better-t-stack/types": "^3.41.0",
     "@clack/core": "^1.4.3",
     "@clack/prompts": "^1.7.0",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@trpc/server": "^11.18.0",
     "better-result": "^3.0.0",
     "consola": "^3.4.2",
@@ -93,6 +93,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
     "@types/bun": "^1.3.14",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.1.2",