hexbus 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1050 @@
+import * as fsSync$1 from "node:fs";
+import fsSync from "node:fs";
+import * as fs$1 from "node:fs/promises";
+import fs from "node:fs/promises";
+import * as path$1 from "node:path";
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { loadConfig } from "c12";
+import color from "picocolors";
+import figlet from "figlet";
+import * as os from "node:os";
+//#region src/detection.ts
+const LOCK_FILE_MAP = {
+	"bun.lockb": "bun",
+	"bun.lock": "bun",
+	"pnpm-lock.yaml": "pnpm",
+	"yarn.lock": "yarn",
+	"package-lock.json": "npm"
+};
+const PACKAGE_MANAGER_CONFIG = {
+	bun: {
+		installCommand: "bun install",
+		addCommand: "bun add",
+		runCommand: "bun run",
+		execCommand: "bunx"
+	},
+	pnpm: {
+		installCommand: "pnpm install",
+		addCommand: "pnpm add",
+		runCommand: "pnpm",
+		execCommand: "pnpm dlx"
+	},
+	yarn: {
+		installCommand: "yarn",
+		addCommand: "yarn add",
+		runCommand: "yarn",
+		execCommand: "yarn dlx"
+	},
+	npm: {
+		installCommand: "npm install",
+		addCommand: "npm install",
+		runCommand: "npm run",
+		execCommand: "npx"
+	}
+};
+async function readPackageJson(projectRoot) {
+	const packageJsonPath = path.join(projectRoot, "package.json");
+	const content = await fs.readFile(packageJsonPath, "utf-8");
+	return JSON.parse(content);
+}
+async function detectFramework(projectRoot, logger, packageMap = {}) {
+	try {
+		logger?.debug(`Detecting framework in ${projectRoot}`);
+		const packageJson = await readPackageJson(projectRoot);
+		const deps = {
+			...packageJson.dependencies,
+			...packageJson.devDependencies
+		};
+		const hasReact = "react" in deps;
+		const reactVersion = hasReact ? deps.react : null;
+		const tailwindVersion = deps.tailwindcss ?? null;
+		let framework = null;
+		let frameworkVersion = null;
+		let pkg = hasReact ? packageMap.react ?? null : null;
+		if ("next" in deps) {
+			framework = "Next.js";
+			frameworkVersion = deps.next ?? null;
+			pkg = packageMap.next ?? packageMap.react ?? null;
+		} else if ("@remix-run/react" in deps) {
+			framework = "Remix";
+			frameworkVersion = deps["@remix-run/react"] ?? null;
+			pkg = packageMap.react ?? null;
+		} else if ("@vitejs/plugin-react" in deps || "@vitejs/plugin-react-swc" in deps) {
+			framework = "Vite + React";
+			frameworkVersion = deps["@vitejs/plugin-react"] ?? deps["@vitejs/plugin-react-swc"] ?? null;
+			pkg = packageMap.react ?? null;
+		} else if ("gatsby" in deps) {
+			framework = "Gatsby";
+			frameworkVersion = deps.gatsby ?? null;
+			pkg = packageMap.react ?? null;
+		} else if (hasReact) {
+			framework = "React";
+			frameworkVersion = reactVersion ?? null;
+			pkg = packageMap.react ?? null;
+		} else pkg = packageMap.core ?? null;
+		return {
+			framework,
+			frameworkVersion,
+			pkg,
+			hasReact,
+			reactVersion: reactVersion ?? null,
+			tailwindVersion
+		};
+	} catch (error) {
+		logger?.debug(`Framework detection failed: ${error instanceof Error ? error.message : String(error)}`);
+		return {
+			framework: null,
+			frameworkVersion: null,
+			pkg: packageMap.core ?? null,
+			hasReact: false,
+			reactVersion: null,
+			tailwindVersion: null
+		};
+	}
+}
+async function detectProjectRoot(cwd, logger) {
+	let projectRoot = cwd;
+	let previousDirectory = "";
+	let depth = 0;
+	const maxDepth = 10;
+	while (projectRoot !== previousDirectory && depth < maxDepth) try {
+		await fs.access(path.join(projectRoot, "package.json"));
+		return projectRoot;
+	} catch {
+		previousDirectory = projectRoot;
+		projectRoot = path.dirname(projectRoot);
+		depth++;
+	}
+	logger?.warn("Could not find project root; using current working directory");
+	return cwd;
+}
+async function detectFromLockFile(projectRoot, logger) {
+	for (const [lockFile, pm] of Object.entries(LOCK_FILE_MAP)) try {
+		await fs.access(path.join(projectRoot, lockFile));
+		logger?.debug(`Found ${lockFile}, using ${pm}`);
+		return pm;
+	} catch {}
+	return null;
+}
+async function detectFromPackageJson(projectRoot, logger) {
+	try {
+		const match = (await readPackageJson(projectRoot)).packageManager?.match(/^(npm|yarn|pnpm|bun)@/);
+		if (match) {
+			logger?.debug(`Found packageManager field: ${match[1]}`);
+			return match[1];
+		}
+	} catch {}
+	return null;
+}
+async function promptForPackageManager(logger) {
+	logger?.debug("Prompting user to select package manager");
+	const result = await p.select({
+		message: "Which package manager do you use?",
+		options: [
+			{
+				value: "bun",
+				label: "bun",
+				hint: "Fast all-in-one toolkit"
+			},
+			{
+				value: "pnpm",
+				label: "pnpm",
+				hint: "Fast, disk space efficient"
+			},
+			{
+				value: "yarn",
+				label: "yarn",
+				hint: "Classic package manager"
+			},
+			{
+				value: "npm",
+				label: "npm",
+				hint: "Default Node.js package manager"
+			}
+		]
+	});
+	if (p.isCancel(result)) throw new Error("Package manager selection cancelled");
+	return result;
+}
+async function detectPackageManager(projectRoot, logger, options) {
+	let pm = await detectFromLockFile(projectRoot, logger);
+	if (!pm) pm = await detectFromPackageJson(projectRoot, logger);
+	if (!pm) if (options?.interactive === true && process.stdin.isTTY && !process.env.CI) pm = await promptForPackageManager(logger);
+	else {
+		pm = "npm";
+		logger?.debug("Defaulting to npm");
+	}
+	return {
+		name: pm,
+		...PACKAGE_MANAGER_CONFIG[pm]
+	};
+}
+function getInstallCommand(pm, packages, options) {
+	const pkgList = packages.join(" ");
+	const devFlag = options?.dev ? pm.name === "npm" ? "--save-dev" : "-D" : "";
+	return `${pm.addCommand} ${devFlag} ${pkgList}`.trim().replace(/\s+/g, " ");
+}
+function getRunCommand(pm, script) {
+	return `${pm.runCommand} ${script}`;
+}
+function getExecCommand(pm, binary, args) {
+	const argString = args?.join(" ") || "";
+	return `${pm.execCommand} ${binary} ${argString}`.trim();
+}
+//#endregion
+//#region src/errors.ts
+const DEFAULT_ERROR_CATALOG = {
+	CONFIG_NOT_FOUND: {
+		code: "CONFIG_NOT_FOUND",
+		message: "Configuration not found",
+		hint: "Run the setup command to create a configuration"
+	},
+	FLAG_VALUE_REQUIRED: {
+		code: "FLAG_VALUE_REQUIRED",
+		message: "Flag requires a value"
+	},
+	COMMAND_NOT_FOUND: {
+		code: "COMMAND_NOT_FOUND",
+		message: "Unknown command",
+		hint: "Run --help to see available commands"
+	},
+	CANCELLED: {
+		code: "CANCELLED",
+		message: "Operation cancelled"
+	},
+	UNKNOWN_ERROR: {
+		code: "UNKNOWN_ERROR",
+		message: "An unexpected error occurred"
+	}
+};
+let activeCatalog = { ...DEFAULT_ERROR_CATALOG };
+function extendErrorCatalog(entries) {
+	activeCatalog = {
+		...activeCatalog,
+		...entries
+	};
+}
+var CliError = class CliError extends Error {
+	code;
+	context;
+	entry;
+	constructor(code, context) {
+		const entry = activeCatalog[code] ?? activeCatalog.UNKNOWN_ERROR ?? DEFAULT_ERROR_CATALOG.UNKNOWN_ERROR;
+		super(entry.message);
+		this.name = "CliError";
+		this.code = code;
+		this.context = context;
+		this.entry = entry;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, CliError);
+	}
+	display(logger) {
+		let message = this.entry.message;
+		if (this.context?.details) message += `: ${this.context.details}`;
+		logger.error(message);
+		if (this.entry.hint) logger.info(`Hint: ${this.entry.hint}`);
+		if (this.entry.docs) logger.info(`Docs: ${this.entry.docs}`);
+	}
+	static from(error, fallbackCode = "UNKNOWN_ERROR") {
+		if (error instanceof CliError) return error;
+		return new CliError(fallbackCode, {
+			details: error instanceof Error ? error.message : String(error),
+			originalError: error
+		});
+	}
+};
+function isCliError(error, code) {
+	if (!(error instanceof CliError)) return false;
+	if (code) return error.code === code;
+	return true;
+}
+function createErrorHandlers(logger, telemetry) {
+	return {
+		handleError(error, command) {
+			const cliError = CliError.from(error);
+			try {
+				telemetry?.trackError(cliError, command);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				logger.warn(`Failed to track error telemetry: ${message}`);
+			}
+			cliError.display(logger);
+			process.exit(1);
+		},
+		handleCancel(message = "Operation cancelled", context) {
+			logger.warn(message);
+			if (context?.command) logger.info(`Command: ${context.command}`);
+			process.exit(0);
+		}
+	};
+}
+function withErrorHandling(fn, logger, context) {
+	return (async (...args) => {
+		try {
+			return await fn(...args);
+		} catch (error) {
+			CliError.from(error).display(logger);
+			if (context?.command) logger.info(`Command: ${context.command}`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/logger.ts
+const LOG_LEVELS = [
+	"error",
+	"warn",
+	"info",
+	"debug"
+];
+const validLogLevels = LOG_LEVELS;
+const LOG_LEVEL_PRIORITY = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	debug: 3
+};
+function safeStringify(arg) {
+	try {
+		return JSON.stringify(arg, null, 2);
+	} catch {
+		return String(arg);
+	}
+}
+function formatArgs(args) {
+	if (args.length === 0) return "";
+	return `\n${args.map((arg) => `  - ${safeStringify(arg)}`).join("\n")}`;
+}
+function formatLogMessage(logLevel, message, args = []) {
+	const messageStr = typeof message === "string" ? message : String(message);
+	const formattedArgs = formatArgs(args);
+	switch (logLevel) {
+		case "error": return `${color.bgRed(color.black(" error "))} ${messageStr}${formattedArgs}`;
+		case "warn": return `${color.bgYellow(color.black(" warning "))} ${messageStr}${formattedArgs}`;
+		case "info": return `${color.bgGreen(color.black(" info "))} ${messageStr}${formattedArgs}`;
+		case "debug": return `${color.bgBlack(color.white(" debug "))} ${messageStr}${formattedArgs}`;
+		case "success": return `${color.bgGreen(color.white(" success "))} ${messageStr}${formattedArgs}`;
+		case "failed": return `${color.bgRed(color.white(" failed "))} ${messageStr}${formattedArgs}`;
+		default: return `[${logLevel.toUpperCase()}] ${messageStr}${formattedArgs}`;
+	}
+}
+function logMessage(logLevel, message, ...args) {
+	const formattedMessage = formatLogMessage(logLevel, message, args);
+	switch (logLevel) {
+		case "error":
+			p.log.error(formattedMessage);
+			break;
+		case "warn":
+			p.log.warn(formattedMessage);
+			break;
+		case "info":
+		case "debug":
+			p.log.info(formattedMessage);
+			break;
+		case "success":
+		case "failed":
+			p.outro(formattedMessage);
+			break;
+		default: p.log.message(formattedMessage);
+	}
+}
+function formatStep(current, total, label) {
+	const safeTotal = Math.max(0, total);
+	const safeCurrent = Math.min(Math.max(0, current), safeTotal);
+	return `[${color.green("█".repeat(safeCurrent))}${color.dim("░".repeat(safeTotal - safeCurrent))}] Step ${safeCurrent}/${safeTotal}: ${label}`;
+}
+function createCliLogger(level = "info") {
+	const currentLevelPriority = LOG_LEVEL_PRIORITY[level];
+	const shouldLog = (targetLevel) => LOG_LEVEL_PRIORITY[targetLevel] <= currentLevelPriority;
+	return {
+		debug(message, ...args) {
+			if (shouldLog("debug")) logMessage("debug", message, ...args);
+		},
+		info(message, ...args) {
+			if (shouldLog("info")) logMessage("info", message, ...args);
+		},
+		warn(message, ...args) {
+			if (shouldLog("warn")) logMessage("warn", message, ...args);
+		},
+		error(message, ...args) {
+			if (shouldLog("error")) logMessage("error", message, ...args);
+		},
+		message(message) {
+			p.log.message(message);
+		},
+		note(content, title) {
+			p.note(content, title, { format: (line) => line });
+		},
+		success(message) {
+			logMessage("success", message);
+		},
+		failed(message, exitCode = 1) {
+			logMessage("failed", message);
+			process.exit(exitCode);
+		},
+		outro(message) {
+			p.outro(message);
+		},
+		step(current, total, label) {
+			p.log.step(formatStep(current, total, label));
+		}
+	};
+}
+//#endregion
+//#region src/parser.ts
+const globalFlags = [
+	{
+		names: ["--help", "-h"],
+		description: "Show this help message",
+		type: "special",
+		expectsValue: false
+	},
+	{
+		names: ["--version", "-v"],
+		description: "Show the CLI version",
+		type: "special",
+		expectsValue: false
+	},
+	{
+		names: ["--logger"],
+		description: "Set log level (error, warn, info, debug)",
+		type: "string",
+		expectsValue: true,
+		defaultValue: "info"
+	},
+	{
+		names: ["--config"],
+		description: "Specify path to configuration file",
+		type: "string",
+		expectsValue: true
+	},
+	{
+		names: ["-y", "--yes"],
+		description: "Skip confirmation prompts",
+		type: "boolean",
+		expectsValue: false,
+		defaultValue: false
+	},
+	{
+		names: ["--no-telemetry"],
+		description: "Disable telemetry data collection",
+		type: "boolean",
+		expectsValue: false,
+		defaultValue: false
+	},
+	{
+		names: ["--telemetry-debug"],
+		description: "Enable debug mode for telemetry",
+		type: "boolean",
+		expectsValue: false,
+		defaultValue: false
+	},
+	{
+		names: ["--force"],
+		description: "Force operation even if files exist",
+		type: "boolean",
+		expectsValue: false,
+		defaultValue: false
+	}
+];
+function getPrimaryFlagName(flag) {
+	const longName = flag.names.find((name) => name.startsWith("--"));
+	const fallback = flag.names.reduce((longest, name) => name.length > longest.length ? name : longest, "");
+	return (longName ?? fallback).replace(/^--?/, "");
+}
+function parseCliArgs(rawArgs, commands) {
+	const parsedFlags = {};
+	const potentialCommandArgs = [];
+	let commandName;
+	const commandArgs = [];
+	for (const flag of globalFlags) {
+		const primaryName = getPrimaryFlagName(flag);
+		if (!primaryName) continue;
+		if (flag.type === "boolean") parsedFlags[primaryName] = flag.defaultValue ?? false;
+		else parsedFlags[primaryName] = flag.defaultValue;
+	}
+	for (let i = 0; i < rawArgs.length; i++) {
+		const arg = rawArgs[i];
+		if (typeof arg !== "string") continue;
+		let isFlag = false;
+		for (const flag of globalFlags) {
+			if (!flag.names.includes(arg)) continue;
+			const primaryName = getPrimaryFlagName(flag);
+			if (!primaryName) continue;
+			isFlag = true;
+			if (flag.type === "boolean") parsedFlags[primaryName] = true;
+			else if (flag.expectsValue) {
+				const nextArg = rawArgs[i + 1];
+				if (nextArg && !nextArg.startsWith("-")) {
+					parsedFlags[primaryName] = nextArg;
+					i++;
+				} else p.log.warn(formatLogMessage("warn", `Flag ${arg} expects a value, but none was provided`));
+			} else parsedFlags[primaryName] = true;
+			break;
+		}
+		if (!isFlag) potentialCommandArgs.push(arg);
+	}
+	const firstPositional = potentialCommandArgs[0];
+	if (typeof firstPositional === "string" && commands.some((cmd) => cmd.name === firstPositional)) {
+		commandName = firstPositional;
+		commandArgs.push(...potentialCommandArgs.slice(1));
+	} else commandArgs.push(...potentialCommandArgs);
+	return {
+		commandName,
+		commandArgs,
+		parsedFlags
+	};
+}
+function formatFlagHelp(flag) {
+	return `  ${flag.names.join(", ")}${flag.expectsValue ? " <value>" : ""}\t${flag.description}`;
+}
+function generateFlagsHelp() {
+	return globalFlags.map(formatFlagHelp).join("\n");
+}
+function hasFlag(flags, name) {
+	return flags[name] === true;
+}
+function getFlagValue(flags, name) {
+	const value = flags[name];
+	if (typeof value === "string") return value;
+}
+function parseSubcommand(args, subcommands) {
+	const subcommandName = args[0];
+	const subcommand = subcommands.find((cmd) => cmd.name === subcommandName);
+	if (subcommand) return {
+		subcommand,
+		remainingArgs: args.slice(1)
+	};
+	return {
+		subcommand: void 0,
+		remainingArgs: args
+	};
+}
+//#endregion
+//#region src/telemetry.ts
+const TelemetryEventName = {
+	CLI_INVOKED: "cli_invoked",
+	CLI_ENVIRONMENT_DETECTED: "cli_environment_detected",
+	CLI_COMPLETED: "cli_completed",
+	COMMAND_INVOKED: "command_invoked",
+	COMMAND_SUCCEEDED: "command_succeeded",
+	COMMAND_FAILED: "command_failed",
+	COMMAND_UNKNOWN: "command_unknown",
+	ERROR_OCCURRED: "error_occurred",
+	HELP_DISPLAYED: "help_displayed",
+	VERSION_DISPLAYED: "version_displayed",
+	INTERACTIVE_MENU_OPENED: "interactive_menu_opened",
+	INTERACTIVE_MENU_EXITED: "interactive_menu_exited"
+};
+function isEnvDisabled(prefix) {
+	const value = process.env[`${prefix}_TELEMETRY_DISABLED`];
+	return value === "1" || value === "true";
+}
+function createDisabledTelemetry() {
+	return {
+		trackEvent: () => {},
+		trackCommand: () => {},
+		trackError: () => {},
+		flush: async () => {},
+		shutdown: async () => {},
+		isDisabled: () => true
+	};
+}
+function createTelemetry(options = {}) {
+	const envVarPrefix = options.envVarPrefix ?? "APP";
+	const disabled = options.disabled === true || isEnvDisabled(envVarPrefix);
+	const events = [];
+	if (disabled) return createDisabledTelemetry();
+	const trackEvent = (eventName, properties = {}) => {
+		const payload = {
+			name: eventName,
+			properties: {
+				appName: options.appName ?? "cli",
+				...options.defaultProperties,
+				...properties,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			}
+		};
+		events.push(payload);
+		if (options.debug) options.logger?.debug("Telemetry event queued", payload);
+	};
+	const flush = async () => {
+		if (!options.endpoint || events.length === 0) {
+			events.length = 0;
+			return;
+		}
+		const batch = events.splice(0, events.length);
+		try {
+			await fetch(options.endpoint, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ events: batch }),
+				keepalive: true
+			});
+		} catch (error) {
+			options.logger?.warn(`Failed to send telemetry: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+	return {
+		trackEvent,
+		trackCommand(command, args = [], flags = {}) {
+			trackEvent(TelemetryEventName.COMMAND_INVOKED, {
+				command,
+				argsCount: args.length,
+				enabledFlags: Object.entries(flags).filter(([, value]) => value !== false && value !== void 0).map(([key]) => key).sort()
+			});
+		},
+		trackError(error, command) {
+			trackEvent(TelemetryEventName.ERROR_OCCURRED, {
+				command,
+				errorName: error.name,
+				errorMessage: error.message
+			});
+		},
+		flush,
+		async shutdown() {
+			await flush();
+		},
+		isDisabled() {
+			return false;
+		}
+	};
+}
+//#endregion
+//#region src/context.ts
+function getLogLevel(parsedFlags) {
+	const levelArg = parsedFlags.logger;
+	if (typeof levelArg === "string") {
+		if (validLogLevels.includes(levelArg)) return levelArg;
+		process.stderr.write(`[CLI Setup] Invalid log level '${levelArg}' provided via --logger. Using default 'info'.\n`);
+	}
+	return "info";
+}
+function createFileSystem(cwd) {
+	return {
+		getPackageInfo() {
+			const packageJsonPath = path.join(cwd, "package.json");
+			try {
+				const content = fsSync.readFileSync(packageJsonPath, "utf-8");
+				const packageInfo = JSON.parse(content);
+				return {
+					...packageInfo,
+					name: packageInfo.name || "unknown",
+					version: packageInfo.version || "unknown"
+				};
+			} catch {
+				return {
+					name: "unknown",
+					version: "unknown"
+				};
+			}
+		},
+		async exists(filePath) {
+			try {
+				await fs.access(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		read(filePath) {
+			return fs.readFile(filePath, "utf-8");
+		},
+		write(filePath, content) {
+			return fs.writeFile(filePath, content, "utf-8");
+		},
+		async mkdir(dirPath) {
+			await fs.mkdir(dirPath, { recursive: true });
+		}
+	};
+}
+async function createCliContext(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const appName = options.appName ?? "cli";
+	const { commandName, commandArgs, parsedFlags } = parseCliArgs(options.rawArgs, options.commands);
+	const logger = createCliLogger(getLogLevel(parsedFlags));
+	const projectRoot = await detectProjectRoot(cwd, logger);
+	const fsUtils = createFileSystem(projectRoot);
+	const framework = await detectFramework(projectRoot, logger, options.packageMap);
+	const packageManager = await detectPackageManager(projectRoot, logger, { interactive: options.interactivePackageManagerDetection });
+	const telemetry = createTelemetry({
+		disabled: options.telemetry?.disabled === true || parsedFlags["no-telemetry"] === true,
+		debug: options.telemetry?.debug === true || parsedFlags["telemetry-debug"] === true,
+		endpoint: options.telemetry?.endpoint,
+		appName,
+		envVarPrefix: options.telemetry?.envVarPrefix ?? appName.toUpperCase(),
+		defaultProperties: {
+			entryCommand: commandName ?? "interactive",
+			commandArgsCount: commandArgs.length,
+			cliVersion: fsUtils.getPackageInfo().version,
+			framework: framework.framework ?? "unknown",
+			frameworkVersion: framework.frameworkVersion ?? "unknown",
+			packageManager: packageManager.name,
+			...options.telemetry?.defaultProperties
+		},
+		logger
+	});
+	const errorHandlers = createErrorHandlers(logger, telemetry);
+	const context = {
+		logger,
+		flags: parsedFlags,
+		commandName,
+		commandArgs,
+		cwd,
+		error: errorHandlers,
+		config: {
+			async loadConfig() {
+				const configPath = typeof parsedFlags.config === "string" ? parsedFlags.config : void 0;
+				const { config } = await loadConfig({
+					name: options.configName ?? appName,
+					cwd: projectRoot,
+					configFile: configPath
+				});
+				return config ?? null;
+			},
+			async requireConfig() {
+				const config = await this.loadConfig();
+				if (!config) throw new CliError("CONFIG_NOT_FOUND");
+				return config;
+			},
+			getPathAliases() {
+				return null;
+			}
+		},
+		fs: fsUtils,
+		telemetry,
+		async confirm(message, initialValue = true) {
+			if (parsedFlags.y === true || parsedFlags.yes === true) return true;
+			const result = await p.confirm({
+				message,
+				initialValue
+			});
+			if (p.isCancel(result)) errorHandlers.handleCancel("Confirmation cancelled");
+			return result;
+		},
+		projectRoot,
+		framework,
+		packageManager
+	};
+	telemetry.trackEvent(TelemetryEventName.CLI_ENVIRONMENT_DETECTED, {
+		command: commandName ?? "interactive",
+		projectRootChanged: projectRoot !== cwd,
+		framework: framework.framework ?? "unknown",
+		frameworkVersion: framework.frameworkVersion ?? "unknown",
+		packageManager: packageManager.name,
+		hasReact: framework.hasReact,
+		reactVersion: framework.reactVersion ?? "unknown",
+		tailwindVersion: framework.tailwindVersion ?? "unknown"
+	});
+	return context;
+}
+function createTestContext(overrides = {}) {
+	const logger = createCliLogger("error");
+	const telemetry = createDisabledTelemetry();
+	const error = createErrorHandlers(logger, telemetry);
+	return {
+		logger,
+		flags: {},
+		commandName: void 0,
+		commandArgs: [],
+		cwd: process.cwd(),
+		error,
+		config: {
+			loadConfig: async () => null,
+			requireConfig: async () => {
+				throw new CliError("CONFIG_NOT_FOUND");
+			},
+			getPathAliases: () => null
+		},
+		fs: {
+			getPackageInfo: () => ({
+				name: "test",
+				version: "0.0.0"
+			}),
+			exists: async () => false,
+			read: async () => "",
+			write: async () => {},
+			mkdir: async () => {}
+		},
+		telemetry,
+		confirm: async () => true,
+		projectRoot: process.cwd(),
+		framework: {
+			framework: null,
+			frameworkVersion: null,
+			pkg: null,
+			hasReact: false,
+			reactVersion: null,
+			tailwindVersion: null
+		},
+		packageManager: {
+			name: "npm",
+			installCommand: "npm install",
+			addCommand: "npm install",
+			runCommand: "npm run",
+			execCommand: "npx"
+		},
+		...overrides
+	};
+}
+//#endregion
+//#region src/help.ts
+function showHelpMenu(context, options, commands, flags) {
+	const commandRows = commands.filter((command) => !command.hidden).map((command) => `  ${command.name.padEnd(16)} ${command.description}`).join("\n");
+	const flagRows = flags.map((flag) => {
+		const valueHint = flag.expectsValue ? " <value>" : "";
+		return `  ${flag.names.join(", ")}${valueHint}\t${flag.description}`;
+	}).join("\n");
+	const docsLine = options.docsUrl ? `\n\nDocs:\n  ${options.docsUrl}` : "";
+	context.logger.note(`${options.appName} ${options.version}\n\nUsage:\n  ${options.appName} <command> [options]\n\nCommands:\n${commandRows}\n\nGlobal Flags:\n${flagRows}${docsLine}`, `${options.appName} CLI`);
+}
+//#endregion
+//#region src/intro.ts
+function renderFiglet(text) {
+	return new Promise((resolve) => {
+		figlet(text, (error, data) => {
+			if (error || !data) {
+				resolve(text);
+				return;
+			}
+			resolve(data);
+		});
+	});
+}
+async function displayIntro(context, options) {
+	const banner = await renderFiglet(options.figletText ?? options.appName);
+	const versionLabel = options.version ? ` v${options.version}` : "";
+	context.logger.message(banner);
+	context.logger.note(options.tagline ?? `${options.appName}${versionLabel}`, options.appName);
+}
+//#endregion
+//#region src/spinner.ts
+function createSpinner(initialMessage) {
+	const spinner = p.spinner();
+	return {
+		start(message) {
+			spinner.start(message || initialMessage || "Processing...");
+		},
+		stop(message) {
+			spinner.stop(message || "Done");
+		},
+		message(message) {
+			spinner.message(message);
+		}
+	};
+}
+async function withSpinner(message, task, options) {
+	const spinner = createSpinner(message);
+	spinner.start();
+	try {
+		const result = await task();
+		spinner.stop(options?.successMessage || "Done");
+		return result;
+	} catch (error) {
+		spinner.stop(options?.errorMessage || "Failed");
+		throw error;
+	}
+}
+//#endregion
+//#region src/version-check.ts
+const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_CACHE_TTL_MS = 1440 * 60 * 1e3;
+const defaultLogger = {
+	message(message) {
+		process.stdout.write(`${message}\n`);
+	},
+	note(content, title) {
+		const prefix = title ? `${title}\n` : "";
+		process.stdout.write(`${prefix}${content}\n`);
+	}
+};
+function isVersionRequest(rawArgs) {
+	return rawArgs.includes("-v") || rawArgs.includes("--version");
+}
+function normalizePath(filePath) {
+	return filePath.replaceAll("\\", "/");
+}
+function expandHomePrefix(prefix) {
+	if (!prefix.startsWith("~/")) return prefix;
+	return path$1.join(os.homedir(), prefix.slice(2));
+}
+function safeRealpath(filePath) {
+	try {
+		return fsSync$1.realpathSync(filePath);
+	} catch {
+		return filePath;
+	}
+}
+function isPathUnder(candidate, parent) {
+	const normalizedCandidate = normalizePath(path$1.resolve(candidate));
+	const normalizedParent = normalizePath(path$1.resolve(expandHomePrefix(parent)));
+	return normalizedCandidate === normalizedParent || normalizedCandidate.startsWith(`${normalizedParent}/`);
+}
+function envValue(name) {
+	return process.env[name];
+}
+function detectInstallSource(binPath = process.argv[1] ?? "") {
+	const resolvedPath = normalizePath(safeRealpath(binPath || ""));
+	const npmPrefix = envValue("npm_config_prefix");
+	if (resolvedPath.includes("/opt/homebrew/") || resolvedPath.includes("/usr/local/Cellar/") || resolvedPath.includes("/home/linuxbrew/") || resolvedPath.includes("/Homebrew/Cellar/")) return "brew";
+	if (resolvedPath.includes("/.npm/_npx/") || resolvedPath.includes("/_npx/") || process.env.npm_command === "exec") return "npx";
+	if (resolvedPath.includes("/.bun/install/cache/") || Boolean(envValue("BUN_INSTALL"))) return "bunx";
+	if (resolvedPath.includes("/.pnpm-store/") || resolvedPath.includes("/dlx-")) return "pnpm-dlx";
+	if (resolvedPath.includes("/.yarn/berry/cache/") || resolvedPath.includes("/yarn/dlx-")) return "yarn-dlx";
+	if (resolvedPath.includes("/node_modules/.bin/") || resolvedPath.endsWith("/node_modules/.bin")) return "local";
+	if ([
+		"/usr/local/lib/node_modules",
+		"~/.npm-global/lib/node_modules",
+		"~/.nvm/versions/node",
+		process.env.APPDATA ? `${process.env.APPDATA}/npm/node_modules` : null,
+		npmPrefix ? `${npmPrefix}/lib/node_modules` : null
+	].filter((item) => typeof item === "string").some((prefix) => {
+		const expandedPrefix = expandHomePrefix(prefix);
+		if (prefix.endsWith("/node")) return resolvedPath.includes("/.nvm/versions/node/") && resolvedPath.includes("/lib/node_modules/");
+		return isPathUnder(resolvedPath, expandedPrefix);
+	})) return "npm-global";
+	return "unknown";
+}
+function getUpdateCommand(source, packageName, brewFormula = packageName) {
+	switch (source) {
+		case "npm-global": return `npm install -g ${packageName}@latest`;
+		case "brew": return `brew upgrade ${brewFormula}`;
+		case "local": return `npm install ${packageName}@latest`;
+		default: return null;
+	}
+}
+function sanitizeCacheName(packageName) {
+	return packageName.replaceAll("/", "__").replaceAll("@", "");
+}
+function getCacheDir(options) {
+	return options.cacheDir ?? path$1.join(os.tmpdir(), "hexbus-version-cache");
+}
+function getCachePath(options) {
+	return path$1.join(getCacheDir(options), `${sanitizeCacheName(options.packageName)}.json`);
+}
+function readCachedVersion(options) {
+	try {
+		const content = fsSync$1.readFileSync(getCachePath(options), "utf-8");
+		const parsed = JSON.parse(content);
+		if (typeof parsed.version === "string" && typeof parsed.fetchedAt === "number") return {
+			version: parsed.version,
+			fetchedAt: parsed.fetchedAt
+		};
+	} catch {}
+	return null;
+}
+function isCacheFresh(cache, options) {
+	const now = options.now?.() ?? Date.now();
+	const ttl = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+	return now - cache.fetchedAt < ttl;
+}
+async function writeCachedVersion(options, version) {
+	const cachePath = getCachePath(options);
+	const cacheDir = path$1.dirname(cachePath);
+	const tempPath = `${cachePath}.${process.pid}.tmp`;
+	const payload = {
+		version,
+		fetchedAt: options.now?.() ?? Date.now()
+	};
+	await fs$1.mkdir(cacheDir, { recursive: true });
+	await fs$1.writeFile(tempPath, `${JSON.stringify(payload)}\n`, "utf-8");
+	await fs$1.rename(tempPath, cachePath);
+}
+function parseVersionParts(version) {
+	return (version.replace(/^[^\d]*/, "").split("-")[0] ?? "").split(".").map((part) => {
+		const parsed = Number.parseInt(part.replace(/\D.*$/, ""), 10);
+		return Number.isNaN(parsed) ? 0 : parsed;
+	});
+}
+function compareVersions(left, right) {
+	const leftParts = parseVersionParts(left);
+	const rightParts = parseVersionParts(right);
+	const length = Math.max(leftParts.length, rightParts.length);
+	for (let index = 0; index < length; index++) {
+		const leftValue = leftParts[index] ?? 0;
+		const rightValue = rightParts[index] ?? 0;
+		if (leftValue > rightValue) return 1;
+		if (leftValue < rightValue) return -1;
+	}
+	return 0;
+}
+function createResult(options, latestVersion) {
+	const source = detectInstallSource(options.binPath);
+	const updateCommand = getUpdateCommand(source, options.packageName, options.brewFormula);
+	const isOutdated = typeof latestVersion === "string" && compareVersions(options.currentVersion, latestVersion) < 0;
+	const result = {
+		currentVersion: options.currentVersion,
+		latestVersion,
+		isOutdated,
+		source,
+		updateCommand
+	};
+	const hint = formatUpdateHint({
+		...result,
+		hint: null
+	});
+	return {
+		...result,
+		hint
+	};
+}
+async function fetchLatestVersion(options) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	const registryUrl = options.registryUrl ?? DEFAULT_REGISTRY_URL;
+	const encodedName = encodeURIComponent(options.packageName);
+	try {
+		const response = await fetch(`${registryUrl.replace(/\/$/, "")}/${encodedName}/latest`, { signal: controller.signal });
+		if (!response.ok) return null;
+		const payload = await response.json();
+		return typeof payload.version === "string" ? payload.version : null;
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+async function refreshCache(options) {
+	const latestVersion = await fetchLatestVersion(options);
+	if (latestVersion) await writeCachedVersion(options, latestVersion);
+	return latestVersion;
+}
+async function checkForUpdate(options) {
+	const cached = readCachedVersion(options);
+	if (cached) return createResult(options, cached.version);
+	return createResult(options, await refreshCache(options));
+}
+function formatUpdateHint(result) {
+	if (!result.isOutdated || result.updateCommand === null || result.latestVersion === null) return null;
+	if (result.source === "brew") return [
+		`Latest npm version is ${color.green(result.latestVersion)}.`,
+		"If you installed with Homebrew, update with:",
+		`  ${color.cyan(result.updateCommand)}`
+	].join("\n");
+	return [
+		`A new version is available: ${color.dim(result.currentVersion)} -> ${color.green(result.latestVersion)}`,
+		"Update with:",
+		`  ${color.cyan(result.updateCommand)}`
+	].join("\n");
+}
+async function printVersionInfo(options) {
+	const logger = options.logger ?? defaultLogger;
+	logger.message(`${options.appName} v${options.currentVersion}`);
+	const result = await checkForUpdate(options);
+	if (result.hint) logger.note(result.hint, "Update available");
+}
+function startBackgroundUpdateCheck(options) {
+	const logger = options.logger ?? defaultLogger;
+	const cached = readCachedVersion(options);
+	if (cached) {
+		const result = createResult(options, cached.version);
+		if (result.hint) logger.note(result.hint, "Update available");
+	}
+	if (cached && isCacheFresh(cached, options)) return;
+	refreshCache(options).catch((error) => {
+		logger.debug?.(`Update check failed: ${error instanceof Error ? error.message : String(error)}`);
+	});
+}
+//#endregion
+export { CliError, DEFAULT_ERROR_CATALOG, LOG_LEVELS, TelemetryEventName, checkForUpdate, color, createCliContext, createCliLogger, createDisabledTelemetry, createErrorHandlers, createSpinner, createTelemetry, createTestContext, detectFramework, detectInstallSource, detectPackageManager, detectProjectRoot, displayIntro, extendErrorCatalog, formatFlagHelp, formatLogMessage, formatStep, formatUpdateHint, generateFlagsHelp, getExecCommand, getFlagValue, getInstallCommand, getRunCommand, getUpdateCommand, globalFlags, hasFlag, isCliError, isVersionRequest, logMessage, parseCliArgs, parseSubcommand, printVersionInfo, showHelpMenu, startBackgroundUpdateCheck, validLogLevels, withErrorHandling, withSpinner };