create-kubojs 0.4.1 → 0.5.1

package/README.md

@@ -104,27 +104,31 @@ For MCP project creation, prefer `install: false`. Long dependency installs can
 
 ## Telemetry
 
-This CLI collects anonymous usage data to help improve the tool. The data collected includes:
+This CLI collects anonymous usage data to help improve the tool. Each `create` run (except `--dry-run`) sends one event with:
 
-- Configuration options selected
-- CLI version
-- Node.js version
-- Platform (OS)
+- Selected stack options (only when the project is created)
+- Outcome (`success`, `failure`, `cancelled`), duration and, on failure, the error class name (never the message)
+- How the CLI was invoked (`cli`, `json`, `mcp`, `api`) and how the stack was chosen (`interactive`, `flags`, `yes`, `template`)
+- CLI version, Node.js version, platform, whether it runs in CI, and the coding agent detected from environment markers (e.g. `claude-code`, `cursor`, `codex`)
+- A random anonymous install ID stored in the kubojs config directory (`telemetry.json`), used to count unique installs
 
-**Telemetry is enabled by default in published versions** to help us understand usage patterns and improve the tool.
+Project names, paths, file contents, error messages and environment variable values are never sent. See https://kubojs.dev/docs/analytics.
 
 ### Disabling Telemetry
 
-You can disable telemetry by setting the `BTS_TELEMETRY_DISABLED` environment variable:
-
 ```bash
 # Disable telemetry for a single run
-BTS_TELEMETRY_DISABLED=1 npx kubojs
+KUBO_TELEMETRY_DISABLED=1 npx kubojs
+
+# DO_NOT_TRACK is also honored
+DO_NOT_TRACK=1 npx kubojs
 
 # Disable telemetry globally in your shell profile (.bashrc, .zshrc, etc.)
-export BTS_TELEMETRY_DISABLED=1
+export KUBO_TELEMETRY_DISABLED=1
 ```
 
+The legacy `BTS_TELEMETRY_DISABLED=1` variable still works.
+
 ## Examples
 
 Create a project with default configuration:

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { _ as getLatestCLIVersion, g as types_exports, i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli } from "./src-L3WKWfns.mjs";
+import { _ as types_exports, g as setTelemetrySource, i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli, v as getLatestCLIVersion } from "./src-DdCJmpnU.mjs";
 import z from "zod";
 import { format } from "node:util";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -353,7 +353,7 @@ function createBtsMcpServer() {
 			if (input.install) return formatToolError(getMcpInstallTimeoutMessage(input.packageManager));
 			const result = await create(input.projectName, {
 				...input,
-				disableAnalytics: true
+				disableAnalytics: false
 			});
 			if (result.isErr()) return formatToolError(result.error);
 			return formatToolSuccess(result.value);
@@ -408,6 +408,7 @@ function createBtsMcpServer() {
 	return server;
 }
 async function startBtsMcpServer() {
+	setTelemetrySource("mcp");
 	const server = createBtsMcpServer();
 	const transport = new StdioServerTransport();
 	await server.connect(transport);

package/dist/index.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { C as UserCancelledError, S as ProjectCreationError, a as TEMPLATE_COUNT, b as DatabaseSetupError, c as builder, d as createVirtual, f as docs, 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, v as CLIError, w as ValidationError, x as DirectoryConflictError, y as CompatibilityError } from "./src-L3WKWfns.mjs";
+import { C as ProjectCreationError, S as DirectoryConflictError, T as ValidationError, a as TEMPLATE_COUNT, b as CompatibilityError, c as builder, d as createVirtual, f as docs, 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 UserCancelledError, x as DatabaseSetupError, y as CLIError } from "./src-DdCJmpnU.mjs";
 export { CLIError, CompatibilityError, DatabaseSetupError, DirectoryConflictError, EMBEDDED_TEMPLATES, GeneratorError, ProjectCreationError, Result, SchemaNameSchema, TEMPLATE_COUNT, UserCancelledError, ValidationError, VirtualFileSystem, add, builder, create, createBtsCli, createVirtual, docs, generate, getSchemaResult, router };

package/dist/{src-L3WKWfns.mjs → src-DdCJmpnU.mjs}

@@ -21,6 +21,7 @@ import { writeSelected, writeTree } from "@kubojs/template-generator/fs-writer";
 import { ConfirmPrompt, GroupMultiSelectPrompt, MultiSelectPrompt, SelectPrompt, TextPrompt, isCancel as isCancel$1, isCancel as isCancel$2 } from "@clack/core";
 import { createJiti } from "jiti";
 import { parse } from "jsonc-parser";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import { format } from "oxfmt";
 import { Generator, configSchema } from "@tanstack/router-generator";
@@ -4022,33 +4023,40 @@ async function getDeploymentChoice(deployment, _runtime, backend, frontend = [],
 }
 //#endregion
 //#region src/prompts/config-prompts.ts
-async function gatherConfig(flags, projectName, projectDir, relativePath) {
-	if (isSilent()) return {
-		projectName,
-		projectDir,
-		relativePath,
-		addonOptions: flags.addonOptions,
-		dbSetupOptions: flags.dbSetupOptions,
-		frontend: flags.frontend ?? [...DEFAULT_CONFIG.frontend],
-		backend: flags.backend ?? DEFAULT_CONFIG.backend,
-		runtime: flags.runtime ?? DEFAULT_CONFIG.runtime,
-		database: flags.database ?? DEFAULT_CONFIG.database,
-		orm: flags.orm ?? DEFAULT_CONFIG.orm,
-		auth: flags.auth ?? DEFAULT_CONFIG.auth,
-		payments: flags.payments ?? DEFAULT_CONFIG.payments,
-		observability: flags.observability ?? DEFAULT_CONFIG.observability,
-		communication: normalizeCommunication$2(flags.communication ?? DEFAULT_CONFIG.communication),
-		addons: flags.addons ?? [...DEFAULT_CONFIG.addons],
-		examples: flags.examples ?? [...DEFAULT_CONFIG.examples],
-		testing: flags.testing ?? [...DEFAULT_CONFIG.testing],
-		git: flags.git ?? DEFAULT_CONFIG.git,
-		packageManager: flags.packageManager ?? DEFAULT_CONFIG.packageManager,
-		install: flags.install ?? DEFAULT_CONFIG.install,
-		dbSetup: flags.dbSetup ?? DEFAULT_CONFIG.dbSetup,
-		api: flags.api ?? DEFAULT_CONFIG.api,
-		webDeploy: flags.webDeploy ?? DEFAULT_CONFIG.webDeploy,
-		serverDeploy: flags.serverDeploy ?? DEFAULT_CONFIG.serverDeploy
-	};
+/** Prompts need a TTY on stdin; without one (CI, pipes, agents) they never resolve. */
+function canPromptForInput(stdin = process.stdin) {
+	return stdin.isTTY === true;
+}
+async function gatherConfig(flags, projectName, projectDir, relativePath, stdin = process.stdin) {
+	if (isSilent() || !canPromptForInput(stdin)) {
+		if (!isSilent()) log.info(pc.yellow("No interactive terminal detected; using defaults for options not passed as flags."));
+		return {
+			projectName,
+			projectDir,
+			relativePath,
+			addonOptions: flags.addonOptions,
+			dbSetupOptions: flags.dbSetupOptions,
+			frontend: flags.frontend ?? [...DEFAULT_CONFIG.frontend],
+			backend: flags.backend ?? DEFAULT_CONFIG.backend,
+			runtime: flags.runtime ?? DEFAULT_CONFIG.runtime,
+			database: flags.database ?? DEFAULT_CONFIG.database,
+			orm: flags.orm ?? DEFAULT_CONFIG.orm,
+			auth: flags.auth ?? DEFAULT_CONFIG.auth,
+			payments: flags.payments ?? DEFAULT_CONFIG.payments,
+			observability: flags.observability ?? DEFAULT_CONFIG.observability,
+			communication: normalizeCommunication$2(flags.communication ?? DEFAULT_CONFIG.communication),
+			addons: flags.addons ?? [...DEFAULT_CONFIG.addons],
+			examples: flags.examples ?? [...DEFAULT_CONFIG.examples],
+			testing: flags.testing ?? [...DEFAULT_CONFIG.testing],
+			git: flags.git ?? DEFAULT_CONFIG.git,
+			packageManager: flags.packageManager ?? DEFAULT_CONFIG.packageManager,
+			install: flags.install ?? DEFAULT_CONFIG.install,
+			dbSetup: flags.dbSetup ?? DEFAULT_CONFIG.dbSetup,
+			api: flags.api ?? DEFAULT_CONFIG.api,
+			webDeploy: flags.webDeploy ?? DEFAULT_CONFIG.webDeploy,
+			serverDeploy: flags.serverDeploy ?? DEFAULT_CONFIG.serverDeploy
+		};
+	}
 	const result = await navigableGroup({
 		frontend: ({ previousAnswer }) => getFrontendChoice(flags.frontend, flags.backend, flags.auth, previousAnswer),
 		backend: ({ results, previousAnswer }) => getBackendFrameworkChoice(flags.backend, results.frontend, previousAnswer),
@@ -4176,50 +4184,162 @@ async function getProjectName(initialName) {
 }
 //#endregion
 //#region src/utils/telemetry.ts
+const TRUTHY = new Set([
+	"1",
+	"true",
+	"yes"
+]);
+function isTruthy(value) {
+	return value !== void 0 && TRUTHY.has(value.toLowerCase());
+}
 /**
 * 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).
+* Opt-out, checked in order:
+* - `KUBO_TELEMETRY_DISABLED=1` disables.
+* - `DO_NOT_TRACK=1` disables (https://consoledonottrack.com).
+* - Legacy `BTS_TELEMETRY_DISABLED=1` disables; legacy `BTS_TELEMETRY=0` disables.
+* - Otherwise enabled.
 */
-function isTelemetryEnabled() {
-	const BTS_TELEMETRY_DISABLED = process.env.BTS_TELEMETRY_DISABLED;
-	const BTS_TELEMETRY = "0";
-	if (BTS_TELEMETRY_DISABLED !== void 0) return BTS_TELEMETRY_DISABLED !== "1";
-	if (BTS_TELEMETRY !== void 0) return BTS_TELEMETRY === "1";
+function isTelemetryEnabled(env = process.env) {
+	if (isTruthy(env.KUBO_TELEMETRY_DISABLED)) return false;
+	if (isTruthy(env.DO_NOT_TRACK)) return false;
+	if (env.BTS_TELEMETRY_DISABLED !== void 0) return env.BTS_TELEMETRY_DISABLED !== "1";
+	if (env.BTS_TELEMETRY !== void 0) return env.BTS_TELEMETRY === "1";
 	return true;
 }
+/** Coding agents we can recognize from the environment they set for child processes. */
+const AGENT_ENV_MARKERS = [
+	["claude-code", "CLAUDECODE"],
+	["cursor", "CURSOR_AGENT"],
+	["cursor", "CURSOR_TRACE_ID"],
+	["codex", "CODEX_SANDBOX"],
+	["codex", "CODEX_MANAGED_BY_NPM"],
+	["gemini-cli", "GEMINI_CLI"],
+	["opencode", "OPENCODE"],
+	["amp", "AMP_CURRENT_THREAD_ID"],
+	["cline", "CLINE_ACTIVE"],
+	["replit", "REPL_ID"]
+];
+function detectAgent(env = process.env) {
+	const match = AGENT_ENV_MARKERS.find(([, envVar]) => Boolean(env[envVar]));
+	if (match) return match[0];
+	return env.AI_AGENT ? "other" : void 0;
+}
+function isCI(env = process.env) {
+	return isTruthy(env.CI) || Boolean(env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE || env.CIRCLECI);
+}
 //#endregion
 //#region src/utils/analytics.ts
-async function sendConvexEvent(payload) {}
-async function trackProjectCreation(config, disableAnalytics = false) {
-	if (!isTelemetryEnabled() || disableAnalytics) return;
-	const { database, orm, backend, runtime, frontend, addons, examples, auth, payments, git, packageManager, install, dbSetup, api, webDeploy, serverDeploy } = config;
+const CONVEX_INGEST_URL = "https://moonlit-seal-677.convex.site/api/analytics/ingest";
+const SEND_TIMEOUT_MS = 2e3;
+const TELEMETRY_FILE = "telemetry.json";
+const TELEMETRY_DOCS_URL = "https://kubojs.dev/docs/analytics";
+let telemetrySource = "cli";
+/** Set once per process by entry points that are not the interactive terminal (e.g. MCP). */
+function setTelemetrySource(source) {
+	telemetrySource = source;
+}
+/** The JS API (`create()`) reports as "api" unless an entry point (e.g. MCP) already set a source. */
+function markProgrammaticTelemetrySource() {
+	if (telemetrySource === "cli") telemetrySource = "api";
+}
+function getTelemetryFilePath() {
+	return path.join(envPaths("kubojs", { suffix: "" }).config, TELEMETRY_FILE);
+}
+function isTelemetryState(value) {
+	return typeof value === "object" && value !== null && "installId" in value && typeof value.installId === "string" && "noticeShown" in value && typeof value.noticeShown === "boolean";
+}
+/**
+* Reads the anonymous install id (a random UUID, not derived from the machine or user),
+* creating it on first use. Returns undefined if the config dir is not writable.
+*/
+async function loadTelemetryState() {
+	const filePath = getTelemetryFilePath();
+	const existing = await Result.tryPromise({
+		try: async () => fs.readJson(filePath),
+		catch: () => void 0
+	});
+	if (existing.isOk() && isTelemetryState(existing.value)) return existing.value;
+	const state = {
+		installId: randomUUID(),
+		noticeShown: false
+	};
+	return (await Result.tryPromise({
+		try: async () => {
+			await fs.ensureDir(path.dirname(filePath));
+			await fs.writeJson(filePath, state, { spaces: 2 });
+		},
+		catch: () => void 0
+	})).isOk() ? state : void 0;
+}
+async function markNoticeShown(state) {
 	await Result.tryPromise({
-		try: () => sendConvexEvent({
-			database,
-			orm,
-			backend,
-			runtime,
-			frontend,
-			addons,
-			examples,
-			auth,
-			payments,
-			git,
-			packageManager,
-			install,
-			dbSetup,
-			api,
-			webDeploy,
-			serverDeploy,
-			cli_version: getLatestCLIVersion(),
-			node_version: typeof process !== "undefined" ? process.version : "",
-			platform: typeof process !== "undefined" ? process.platform : ""
+		try: () => fs.writeJson(getTelemetryFilePath(), {
+			...state,
+			noticeShown: true
+		}, { spaces: 2 }),
+		catch: () => void 0
+	});
+}
+function showTelemetryNotice() {
+	log.info(pc.dim(`kubojs collects anonymous usage data (stack choices, CLI version, OS) to guide development.
+No project names, paths or personal data. Opt out with KUBO_TELEMETRY_DISABLED=1.
+Details: ${TELEMETRY_DOCS_URL}`));
+}
+async function sendConvexEvent(payload) {
+	await Result.tryPromise({
+		try: () => fetch(CONVEX_INGEST_URL, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(SEND_TIMEOUT_MS)
 		}),
 		catch: () => void 0
 	});
 }
+function getStackPayload(config) {
+	return {
+		database: config.database,
+		orm: config.orm,
+		backend: config.backend,
+		runtime: config.runtime,
+		frontend: config.frontend,
+		addons: config.addons,
+		examples: config.examples,
+		auth: config.auth,
+		payments: config.payments,
+		git: config.git,
+		packageManager: config.packageManager,
+		install: config.install,
+		dbSetup: config.dbSetup,
+		api: config.api,
+		webDeploy: config.webDeploy,
+		serverDeploy: config.serverDeploy
+	};
+}
+async function trackCreateEvent(event, disableAnalytics = false) {
+	if (!isTelemetryEnabled() || disableAnalytics) return;
+	const state = await loadTelemetryState();
+	if (state && !state.noticeShown && !isSilent()) {
+		showTelemetryNotice();
+		await markNoticeShown(state);
+	}
+	await sendConvexEvent({
+		...event.config ? getStackPayload(event.config) : {},
+		install_id: state?.installId,
+		source: telemetrySource,
+		mode: event.mode,
+		agent: detectAgent(),
+		ci: isCI(),
+		outcome: event.outcome,
+		error_category: event.errorCategory,
+		duration_ms: event.durationMs,
+		cli_version: getLatestCLIVersion(),
+		node_version: process.version,
+		platform: process.platform
+	});
+}
 //#endregion
 //#region src/utils/display-config.ts
 function displayConfig(config) {
@@ -6583,10 +6703,26 @@ async function createProjectHandler(input, options = {}) {
 		const startTime = Date.now();
 		const timeScaffolded = (/* @__PURE__ */ new Date()).toISOString();
 		const result = await createProjectHandlerInternal(input, startTime, timeScaffolded);
-		if (result.isOk()) return result.value;
+		const mode = getTelemetryMode(input);
+		if (result.isOk()) {
+			if (!input.dryRun) await trackCreateEvent({
+				outcome: "success",
+				mode,
+				durationMs: result.value.elapsedTimeMs,
+				config: result.value.projectConfig
+			}, input.disableAnalytics);
+			return result.value;
+		}
 		const error = result.error;
 		const elapsedTimeMs = Date.now() - startTime;
-		if (UserCancelledError.is(error)) {
+		const cancelled = UserCancelledError.is(error);
+		if (!input.dryRun) await trackCreateEvent({
+			outcome: cancelled ? "cancelled" : "failure",
+			mode,
+			durationMs: elapsedTimeMs,
+			errorCategory: cancelled ? void 0 : getErrorCategory(error)
+		}, input.disableAnalytics);
+		if (cancelled) {
 			if (isSilent()) return createEmptyResult(timeScaffolded, elapsedTimeMs, error.message);
 			return;
 		}
@@ -6595,6 +6731,38 @@ async function createProjectHandler(input, options = {}) {
 		process.exit(1);
 	});
 }
+/** Stack-selecting flags; their presence means the user chose the stack via flags, not prompts. */
+const STACK_FLAG_KEYS = [
+	"database",
+	"orm",
+	"backend",
+	"runtime",
+	"frontend",
+	"api",
+	"auth",
+	"payments",
+	"addons",
+	"examples",
+	"dbSetup",
+	"webDeploy",
+	"serverDeploy"
+];
+function getTelemetryMode(input) {
+	if (input.template && input.template !== "none") return "template";
+	if (input.yes) return "yes";
+	if (isSilent() || STACK_FLAG_KEYS.some((key) => input[key] !== void 0)) return "flags";
+	return "interactive";
+}
+function getTag(value) {
+	if (typeof value !== "object" || value === null || !("_tag" in value)) return void 0;
+	return typeof value._tag === "string" ? value._tag : void 0;
+}
+/** Error class names only (e.g. `CLIError:ValidationError`), never messages or paths. */
+function getErrorCategory(error) {
+	const tag = getTag(error) ?? "UnknownError";
+	const causeTag = "cause" in error ? getTag(error.cause) : void 0;
+	return causeTag ? `${tag}:${causeTag}` : tag;
+}
 async function createProjectHandlerInternal(input, startTime, timeScaffolded) {
 	return Result.gen(async function* () {
 		if (!isSilent() && input.renderTitle !== false) renderTitle();
@@ -6760,7 +6928,6 @@ async function createProjectHandlerInternal(input, startTime, timeScaffolded) {
 			dbSetupOptions: effectiveDbSetupOptions
 		}));
 		if (!isSilent()) log.success(cliColors.bright(`You can reproduce this setup with the following command:\n${reproducibleCommand}`));
-		await trackProjectCreation(config, input.disableAnalytics);
 		const historyResult = await addToHistory(config, reproducibleCommand);
 		if (historyResult.isErr() && !isSilent()) log.warn(pc.yellow(historyResult.error.message));
 		const elapsedTimeMs = Date.now() - startTime;
@@ -6952,6 +7119,7 @@ const router = t.router({
 		description: "Create a project from a raw JSON payload (agent-friendly)",
 		jsonInput: true
 	}).input(types_exports.CreateInputSchema).mutation(async ({ input }) => {
+		setTelemetrySource("json");
 		const result = await createProjectHandler(input, { silent: true });
 		if (!result) throw new UserCancelledError({ message: "Operation cancelled" });
 		if (!result.success) throw new CLIError({ message: result.error || "Unknown error occurred" });
@@ -7019,6 +7187,7 @@ function createBtsCli() {
 * ```
 */
 async function create(projectName, options) {
+	markProgrammaticTelemetrySource();
 	const input = {
 		...options,
 		projectName,
@@ -7154,4 +7323,4 @@ async function add(options = {}) {
 	return addHandler(options, { silent: true });
 }
 //#endregion
-export { UserCancelledError as C, ProjectCreationError as S, getLatestCLIVersion as _, TEMPLATE_COUNT as a, DatabaseSetupError as b, builder as c, createVirtual as d, docs as f, types_exports 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, CLIError as v, ValidationError as w, DirectoryConflictError as x, CompatibilityError as y };
+export { ProjectCreationError as C, DirectoryConflictError as S, ValidationError as T, types_exports as _, TEMPLATE_COUNT as a, CompatibilityError as b, builder as c, createVirtual as d, docs as f, setTelemetrySource 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, getLatestCLIVersion as v, UserCancelledError as w, DatabaseSetupError as x, CLIError as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kubojs",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "A modern CLI tool for scaffolding end-to-end type-safe TypeScript projects with best practices and customizable configurations",
   "keywords": [
     "better-auth",
@@ -73,8 +73,8 @@
   "dependencies": {
     "@clack/core": "^1.4.1",
     "@clack/prompts": "^1.5.1",
-    "@kubojs/template-generator": "^0.4.1",
-    "@kubojs/types": "^0.4.1",
+    "@kubojs/template-generator": "^0.5.1",
+    "@kubojs/types": "^0.5.1",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@tanstack/router-generator": "1.167.28",
     "@trpc/server": "^11.17.0",
@@ -93,7 +93,7 @@
     "trpc-cli": "^0.14.1",
     "ts-morph": "^28.0.0",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "zod": "~4.4.3"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",