hexbus 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -5,42 +5,44 @@ 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 { spinner } from "@clack/prompts";
 import { loadConfig } from "c12";
-import color from "picocolors";
+import { promisify } from "node:util";
 import figlet from "figlet";
 import * as os from "node:os";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/detection.ts
 const LOCK_FILE_MAP = {
-	"bun.lockb": "bun",
 	"bun.lock": "bun",
+	"bun.lockb": "bun",
+	"package-lock.json": "npm",
 	"pnpm-lock.yaml": "pnpm",
-	"yarn.lock": "yarn",
-	"package-lock.json": "npm"
+	"yarn.lock": "yarn"
 };
 const PACKAGE_MANAGER_CONFIG = {
 	bun: {
-		installCommand: "bun install",
 		addCommand: "bun add",
-		runCommand: "bun run",
-		execCommand: "bunx"
+		execCommand: "bunx",
+		installCommand: "bun install",
+		runCommand: "bun run"
+	},
+	npm: {
+		addCommand: "npm install",
+		execCommand: "npx",
+		installCommand: "npm install",
+		runCommand: "npm run"
 	},
 	pnpm: {
-		installCommand: "pnpm install",
 		addCommand: "pnpm add",
-		runCommand: "pnpm",
-		execCommand: "pnpm dlx"
+		execCommand: "pnpm dlx",
+		installCommand: "pnpm install",
+		runCommand: "pnpm"
 	},
 	yarn: {
-		installCommand: "yarn",
 		addCommand: "yarn add",
-		runCommand: "yarn",
-		execCommand: "yarn dlx"
-	},
-	npm: {
-		installCommand: "npm install",
-		addCommand: "npm install",
-		runCommand: "npm run",
-		execCommand: "npx"
+		execCommand: "yarn dlx",
+		installCommand: "yarn",
+		runCommand: "yarn"
 	}
 };
 async function readPackageJson(projectRoot) {
@@ -48,6 +50,21 @@ async function readPackageJson(projectRoot) {
 	const content = await fs.readFile(packageJsonPath, "utf-8");
 	return JSON.parse(content);
 }
+/**
+* Detects common frontend frameworks from project dependencies.
+*
+* @remarks
+* Detection reads the nearest project's `package.json` and looks at
+* dependencies and devDependencies. It recognizes Next.js, Remix, Vite React,
+* Gatsby, generic React, Tailwind CSS, and a configured core fallback.
+*
+* @typeParam TPackage - Product-specific package identifier returned in
+* `FrameworkDetectionResult.pkg`.
+* @param projectRoot - Directory containing the package.json to inspect.
+* @param logger - Optional logger for debug diagnostics.
+* @param packageMap - Product packages to select for detected frameworks.
+* @returns Framework metadata and the selected product package identifier.
+*/
 async function detectFramework(projectRoot, logger, packageMap = {}) {
 	try {
 		logger?.debug(`Detecting framework in ${projectRoot}`);
@@ -86,8 +103,8 @@ async function detectFramework(projectRoot, logger, packageMap = {}) {
 		return {
 			framework,
 			frameworkVersion,
-			pkg,
 			hasReact,
+			pkg,
 			reactVersion: reactVersion ?? null,
 			tailwindVersion
 		};
@@ -96,13 +113,25 @@ async function detectFramework(projectRoot, logger, packageMap = {}) {
 		return {
 			framework: null,
 			frameworkVersion: null,
-			pkg: packageMap.core ?? null,
 			hasReact: false,
+			pkg: packageMap.core ?? null,
 			reactVersion: null,
 			tailwindVersion: null
 		};
 	}
 }
+/**
+* Finds the nearest project root by walking up to a package.json.
+*
+* @remarks
+* The search is capped at ten directory levels to avoid surprising filesystem
+* traversal. When no root is found, the original current working directory is
+* returned and a warning is logged.
+*
+* @param cwd - Directory where invocation started.
+* @param logger - Optional logger for warning output.
+* @returns The detected project root or `cwd` as a fallback.
+*/
 async function detectProjectRoot(cwd, logger) {
 	let projectRoot = cwd;
 	let previousDirectory = "";
@@ -143,30 +172,45 @@ async function promptForPackageManager(logger) {
 		message: "Which package manager do you use?",
 		options: [
 			{
-				value: "bun",
+				hint: "Fast all-in-one toolkit",
 				label: "bun",
-				hint: "Fast all-in-one toolkit"
+				value: "bun"
 			},
 			{
-				value: "pnpm",
+				hint: "Fast, disk space efficient",
 				label: "pnpm",
-				hint: "Fast, disk space efficient"
+				value: "pnpm"
 			},
 			{
-				value: "yarn",
+				hint: "Classic package manager",
 				label: "yarn",
-				hint: "Classic package manager"
+				value: "yarn"
 			},
 			{
-				value: "npm",
+				hint: "Default Node.js package manager",
 				label: "npm",
-				hint: "Default Node.js package manager"
+				value: "npm"
 			}
 		]
 	});
 	if (p.isCancel(result)) throw new Error("Package manager selection cancelled");
 	return result;
 }
+/**
+* Detects the package manager used by a project.
+*
+* @remarks
+* Detection prefers lockfiles, then the `packageManager` field in
+* `package.json`, then an optional interactive prompt, and finally `npm`.
+*
+* @param projectRoot - Directory to inspect for lockfiles and package.json.
+* @param logger - Optional logger for debug output.
+* @param options - Detection options.
+* @returns Command templates for the detected package manager.
+*
+* @throws When interactive prompting is enabled and the user cancels package
+* manager selection.
+*/
 async function detectPackageManager(projectRoot, logger, options) {
 	let pm = await detectFromLockFile(projectRoot, logger);
 	if (!pm) pm = await detectFromPackageJson(projectRoot, logger);
@@ -180,55 +224,129 @@ async function detectPackageManager(projectRoot, logger, options) {
 		...PACKAGE_MANAGER_CONFIG[pm]
 	};
 }
+/**
+* Builds a dependency installation command for the detected package manager.
+*
+* @param pm - Package manager command templates.
+* @param packages - Package names to install.
+* @param options - Install command options.
+* @returns A shell command string suitable for display or execution.
+*
+* @example
+* ```ts
+* getInstallCommand(pm, ['typescript'], { dev: true });
+* ```
+*/
 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, " ");
+	let devFlag = "";
+	if (options?.dev) devFlag = pm.name === "npm" ? "--save-dev" : "-D";
+	return `${pm.addCommand} ${devFlag} ${pkgList}`.trim().replaceAll(/\s+/g, " ");
 }
+/**
+* Builds a package-script command for the detected package manager.
+*
+* @param pm - Package manager command templates.
+* @param script - Package script name to run.
+* @returns A shell command string.
+*/
 function getRunCommand(pm, script) {
 	return `${pm.runCommand} ${script}`;
 }
+/**
+* Builds a one-off binary execution command for the detected package manager.
+*
+* @param pm - Package manager command templates.
+* @param binary - Binary name to execute.
+* @param args - Optional arguments appended after the binary name.
+* @returns A shell command string.
+*/
 function getExecCommand(pm, binary, args) {
 	const argString = args?.join(" ") || "";
 	return `${pm.execCommand} ${binary} ${argString}`.trim();
 }
 //#endregion
 //#region src/errors.ts
+/**
+* Built-in errors used by the Hexbus runtime.
+*/
 const DEFAULT_ERROR_CATALOG = {
+	CANCELLED: {
+		code: "CANCELLED",
+		message: "Operation cancelled"
+	},
+	COMMAND_NOT_FOUND: {
+		code: "COMMAND_NOT_FOUND",
+		hint: "Run --help to see available commands",
+		message: "Unknown command"
+	},
 	CONFIG_NOT_FOUND: {
 		code: "CONFIG_NOT_FOUND",
-		message: "Configuration not found",
-		hint: "Run the setup command to create a configuration"
+		hint: "Run the setup command to create a configuration",
+		message: "Configuration not found"
 	},
 	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 };
+/**
+* Adds or replaces entries in the active error catalog.
+*
+* @remarks
+* This mutates process-local catalog state. Product CLIs should call it once
+* during startup before command actions create `CliError` instances.
+*
+* @param entries - Error entries keyed by their stable code.
+*
+* @example
+* ```ts
+* extendErrorCatalog({
+*   PROJECT_NOT_READY: {
+*     code: 'PROJECT_NOT_READY',
+*     message: 'Project is not ready',
+*     hint: 'Run init before running this command.',
+*   },
+* });
+* ```
+*/
 function extendErrorCatalog(entries) {
 	activeCatalog = {
 		...activeCatalog,
 		...entries
 	};
 }
+/**
+* Error type that carries a catalog entry and optional structured context.
+*
+* @remarks
+* `CliError` keeps command code focused on stable error codes while shared
+* handlers render the configured message, hint, and documentation link.
+*/
 var CliError = class CliError extends Error {
+	/**
+	* Error code requested by the caller.
+	*/
 	code;
+	/**
+	* Structured diagnostic details attached by the caller.
+	*/
 	context;
+	/**
+	* Catalog entry used to render this error.
+	*/
 	entry;
+	/**
+	* Creates a catalog-backed CLI error.
+	*
+	* @param code - Built-in or product-defined error code.
+	* @param context - Optional diagnostic details for rendering or telemetry.
+	*/
 	constructor(code, context) {
 		const entry = activeCatalog[code] ?? activeCatalog.UNKNOWN_ERROR ?? DEFAULT_ERROR_CATALOG.UNKNOWN_ERROR;
 		super(entry.message);
@@ -238,13 +356,27 @@ var CliError = class CliError extends Error {
 		this.entry = entry;
 		if (Error.captureStackTrace) Error.captureStackTrace(this, CliError);
 	}
+	/**
+	* Renders the error message, hint, and docs link through a logger.
+	*
+	* @param logger - Logger used for user-facing output.
+	*/
 	display(logger) {
-		let message = this.entry.message;
+		let { message } = this.entry;
 		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}`);
 	}
+	/**
+	* Normalizes an unknown thrown value into a `CliError`.
+	*
+	* @param error - Value caught from a `try`/`catch` block.
+	* @param fallbackCode - Catalog code to use when `error` is not already a
+	* `CliError`.
+	* @returns `error` unchanged when it is already a `CliError`, otherwise a
+	* wrapped `CliError`.
+	*/
 	static from(error, fallbackCode = "UNKNOWN_ERROR") {
 		if (error instanceof CliError) return error;
 		return new CliError(fallbackCode, {
@@ -253,31 +385,59 @@ var CliError = class CliError extends Error {
 		});
 	}
 };
+/**
+* Narrows an unknown value to a `CliError`.
+*
+* @param error - Value to inspect.
+* @param code - Optional code that must match the error.
+* @returns `true` when the value is a `CliError` and, if provided, matches the
+* requested code.
+*/
 function isCliError(error, code) {
 	if (!(error instanceof CliError)) return false;
 	if (code) return error.code === code;
 	return true;
 }
+/**
+* Creates shared process-ending error and cancellation handlers.
+*
+* @param logger - Logger used to render messages.
+* @param telemetry - Optional telemetry sink for failed command errors.
+* @returns Error handlers suitable for `CliContext.error`.
+*/
 function createErrorHandlers(logger, telemetry) {
 	return {
+		handleCancel(message = "Operation cancelled", context) {
+			logger.warn(message);
+			if (context?.command) logger.info(`Command: ${context.command}`);
+			process.exit(0);
+		},
 		handleError(error, command) {
 			const cliError = CliError.from(error);
 			try {
 				telemetry?.trackError(cliError, command);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
+			} catch (telemetryError) {
+				const message = telemetryError instanceof Error ? telemetryError.message : String(telemetryError);
 				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);
 		}
 	};
 }
+/**
+* Wraps an async function with CLI-style error rendering and process exit.
+*
+* @remarks
+* This helper is useful near process entrypoints. Library-style code should
+* usually throw `CliError` and let the caller decide when to exit.
+*
+* @typeParam T - Async function type to preserve.
+* @param fn - Async function to run.
+* @param logger - Logger used to render caught errors.
+* @param context - Optional command metadata shown after an error.
+* @returns A function with the same call signature as `fn`.
+*/
 function withErrorHandling(fn, logger, context) {
 	return (async (...args) => {
 		try {
@@ -290,19 +450,141 @@ function withErrorHandling(fn, logger, context) {
 	});
 }
 //#endregion
+//#region src/color.ts
+const replaceClose = (string, close, replace, startIndex) => {
+	let result = "";
+	let cursor = 0;
+	let index = startIndex;
+	do {
+		result += string.slice(cursor, index) + replace;
+		cursor = index + close.length;
+		index = string.indexOf(close, cursor);
+	} while (index !== -1);
+	return result + string.slice(cursor);
+};
+const createFormatter = (open, close, replace = open) => (input) => {
+	const string = String(input);
+	const index = string.indexOf(close, open.length);
+	return index === -1 ? open + string + close : open + replaceClose(string, close, replace, index) + close;
+};
+const createPlainFormatter = () => String;
+/**
+* Detects whether ANSI color output should be enabled.
+*
+* @remarks
+* Detection follows common CLI conventions: `NO_COLOR`, `--no-color`, and
+* `FORCE_COLOR=0` disable colors; `FORCE_COLOR` and `--color` enable colors;
+* Windows defaults to enabled; otherwise TTY, non-dumb terminals, and CI
+* environments are considered color-capable.
+*
+* @param options - Optional process-like inputs for detection.
+* @returns `true` when color formatters should emit ANSI escape codes.
+*/
+function detectColorSupport(options = {}) {
+	const argv = options.argv ?? process.argv;
+	const env = options.env ?? process.env;
+	const platform = options.platform ?? process.platform;
+	const stdout = options.stdout ?? process.stdout;
+	const forceColor = env.FORCE_COLOR ? env.FORCE_COLOR.toLowerCase() : void 0;
+	const hasNoColor = !!env.NO_COLOR;
+	const isCI = !!env.CI;
+	const isForceColorDisabled = forceColor === "0" || forceColor === "false";
+	if (hasNoColor || argv.includes("--no-color") || isForceColorDisabled) return false;
+	if (forceColor !== void 0 && forceColor !== "0" && forceColor !== "false" || argv.includes("--color")) return true;
+	if (platform === "win32") return true;
+	return Boolean(stdout.isTTY) && env.TERM !== "dumb" || isCI;
+}
+/**
+* Process-level color support detected at module load time.
+*/
+const isColorSupported = detectColorSupport();
+/**
+* Creates a complete set of color and style formatters.
+*
+* @param enabled - Whether returned formatters should emit ANSI escape codes.
+* @returns A `Colors` object with either active ANSI formatters or plain string
+* pass-through formatters.
+*/
+function createColors(enabled = isColorSupported) {
+	const formatter = enabled ? createFormatter : createPlainFormatter;
+	return {
+		bgBlack: formatter("\x1B[40m", "\x1B[49m"),
+		bgBlackBright: formatter("\x1B[100m", "\x1B[49m"),
+		bgBlue: formatter("\x1B[44m", "\x1B[49m"),
+		bgBlueBright: formatter("\x1B[104m", "\x1B[49m"),
+		bgCyan: formatter("\x1B[46m", "\x1B[49m"),
+		bgCyanBright: formatter("\x1B[106m", "\x1B[49m"),
+		bgGreen: formatter("\x1B[42m", "\x1B[49m"),
+		bgGreenBright: formatter("\x1B[102m", "\x1B[49m"),
+		bgMagenta: formatter("\x1B[45m", "\x1B[49m"),
+		bgMagentaBright: formatter("\x1B[105m", "\x1B[49m"),
+		bgRed: formatter("\x1B[41m", "\x1B[49m"),
+		bgRedBright: formatter("\x1B[101m", "\x1B[49m"),
+		bgWhite: formatter("\x1B[47m", "\x1B[49m"),
+		bgWhiteBright: formatter("\x1B[107m", "\x1B[49m"),
+		bgYellow: formatter("\x1B[43m", "\x1B[49m"),
+		bgYellowBright: formatter("\x1B[103m", "\x1B[49m"),
+		black: formatter("\x1B[30m", "\x1B[39m"),
+		blackBright: formatter("\x1B[90m", "\x1B[39m"),
+		blue: formatter("\x1B[34m", "\x1B[39m"),
+		blueBright: formatter("\x1B[94m", "\x1B[39m"),
+		bold: formatter("\x1B[1m", "\x1B[22m", "\x1B[22m\x1B[1m"),
+		cyan: formatter("\x1B[36m", "\x1B[39m"),
+		cyanBright: formatter("\x1B[96m", "\x1B[39m"),
+		dim: formatter("\x1B[2m", "\x1B[22m", "\x1B[22m\x1B[2m"),
+		gray: formatter("\x1B[90m", "\x1B[39m"),
+		green: formatter("\x1B[32m", "\x1B[39m"),
+		greenBright: formatter("\x1B[92m", "\x1B[39m"),
+		hidden: formatter("\x1B[8m", "\x1B[28m"),
+		inverse: formatter("\x1B[7m", "\x1B[27m"),
+		isColorSupported: enabled,
+		italic: formatter("\x1B[3m", "\x1B[23m"),
+		magenta: formatter("\x1B[35m", "\x1B[39m"),
+		magentaBright: formatter("\x1B[95m", "\x1B[39m"),
+		red: formatter("\x1B[31m", "\x1B[39m"),
+		redBright: formatter("\x1B[91m", "\x1B[39m"),
+		reset: formatter("\x1B[0m", "\x1B[0m"),
+		strikethrough: formatter("\x1B[9m", "\x1B[29m"),
+		underline: formatter("\x1B[4m", "\x1B[24m"),
+		white: formatter("\x1B[37m", "\x1B[39m"),
+		whiteBright: formatter("\x1B[97m", "\x1B[39m"),
+		yellow: formatter("\x1B[33m", "\x1B[39m"),
+		yellowBright: formatter("\x1B[93m", "\x1B[39m")
+	};
+}
+/**
+* Default color formatter set for the current process.
+*
+* @remarks
+* Use `color.createColors(false)` when tests need deterministic plain-text
+* output.
+*/
+const color = Object.assign(createColors(), { createColors });
+/**
+* Named color and style formatter exports from the default `color` object.
+*/
+const { reset, bold, dim, italic, underline, inverse, hidden, strikethrough, black, red, green, yellow, blue, magenta, cyan, white, gray, bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, blackBright, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright, bgBlackBright, bgRedBright, bgGreenBright, bgYellowBright, bgBlueBright, bgMagentaBright, bgCyanBright, bgWhiteBright } = color;
+//#endregion
 //#region src/logger.ts
+/**
+* Supported log levels in ascending verbosity.
+*/
 const LOG_LEVELS = [
 	"error",
 	"warn",
 	"info",
 	"debug"
 ];
+/**
+* Alias for `LOG_LEVELS` kept for callers that prefer validation-oriented
+* naming.
+*/
 const validLogLevels = LOG_LEVELS;
 const LOG_LEVEL_PRIORITY = {
+	debug: 3,
 	error: 0,
-	warn: 1,
 	info: 2,
-	debug: 3
+	warn: 1
 };
 function safeStringify(arg) {
 	try {
@@ -315,6 +597,14 @@ function formatArgs(args) {
 	if (args.length === 0) return "";
 	return `\n${args.map((arg) => `  - ${safeStringify(arg)}`).join("\n")}`;
 }
+/**
+* Formats a log message with a level badge and optional structured arguments.
+*
+* @param logLevel - Log level or custom badge label.
+* @param message - Primary message to render.
+* @param args - Additional values rendered as indented JSON-like bullets.
+* @returns A formatted message string.
+*/
 function formatLogMessage(logLevel, message, args = []) {
 	const messageStr = typeof message === "string" ? message : String(message);
 	const formattedArgs = formatArgs(args);
@@ -328,6 +618,13 @@ function formatLogMessage(logLevel, message, args = []) {
 		default: return `[${logLevel.toUpperCase()}] ${messageStr}${formattedArgs}`;
 	}
 }
+/**
+* Emits a formatted message through the prompt logger.
+*
+* @param logLevel - Log level or custom badge label.
+* @param message - Primary message to render.
+* @param args - Additional values rendered below the message.
+*/
 function logMessage(logLevel, message, ...args) {
 	const formattedMessage = formatLogMessage(logLevel, message, args);
 	switch (logLevel) {
@@ -348,11 +645,35 @@ function logMessage(logLevel, message, ...args) {
 		default: p.log.message(formattedMessage);
 	}
 }
+/**
+* Formats a bounded progress step indicator.
+*
+* @remarks
+* `current` is clamped between `0` and `total`, and `total` is clamped to at
+* least `0` so malformed progress values still render predictably.
+*
+* @param current - Current step number.
+* @param total - Total number of steps.
+* @param label - Step label shown after the progress bar.
+* @returns A formatted progress row.
+*/
 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}`;
 }
+/**
+* Creates a `CliLogger` backed by Clack prompt output.
+*
+* @remarks
+* Messages below the configured verbosity are ignored for `debug`, `info`,
+* `warn`, and `error`. Other output helpers such as `message`, `note`,
+* `success`, `failed`, and `outro` always render because they represent
+* explicit user interaction states rather than diagnostic verbosity.
+*
+* @param level - Minimum log level to emit.
+* @returns A logger suitable for `CliContext.logger`.
+*/
 function createCliLogger(level = "info") {
 	const currentLevelPriority = LOG_LEVEL_PRIORITY[level];
 	const shouldLog = (targetLevel) => LOG_LEVEL_PRIORITY[targetLevel] <= currentLevelPriority;
@@ -360,91 +681,112 @@ function createCliLogger(level = "info") {
 		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);
 		},
+		failed(message, exitCode = 1) {
+			logMessage("failed", message);
+			process.exit(exitCode);
+		},
+		info(message, ...args) {
+			if (shouldLog("info")) logMessage("info", 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));
+		},
+		success(message) {
+			logMessage("success", message);
+		},
+		warn(message, ...args) {
+			if (shouldLog("warn")) logMessage("warn", message, ...args);
 		}
 	};
 }
 //#endregion
 //#region src/parser.ts
+/**
+* Built-in flags parsed for every Hexbus CLI invocation.
+*
+* @remarks
+* Primary flag names are derived from the first long flag in each entry. For
+* example, `--no-telemetry` is exposed as `parsedFlags['no-telemetry']`.
+*/
 const globalFlags = [
 	{
-		names: ["--help", "-h"],
 		description: "Show this help message",
-		type: "special",
-		expectsValue: false
+		expectsValue: false,
+		names: ["--help", "-h"],
+		type: "special"
 	},
 	{
-		names: ["--version", "-v"],
 		description: "Show the CLI version",
-		type: "special",
-		expectsValue: false
+		expectsValue: false,
+		names: ["--version", "-v"],
+		type: "special"
 	},
 	{
-		names: ["--logger"],
+		defaultValue: "info",
 		description: "Set log level (error, warn, info, debug)",
-		type: "string",
 		expectsValue: true,
-		defaultValue: "info"
+		names: ["--logger"],
+		type: "string"
+	},
+	{
+		defaultValue: false,
+		description: "Force color output",
+		expectsValue: false,
+		names: ["--color"],
+		type: "boolean"
+	},
+	{
+		defaultValue: false,
+		description: "Disable color output",
+		expectsValue: false,
+		names: ["--no-color"],
+		type: "boolean"
 	},
 	{
-		names: ["--config"],
 		description: "Specify path to configuration file",
-		type: "string",
-		expectsValue: true
+		expectsValue: true,
+		names: ["--config"],
+		type: "string"
 	},
 	{
-		names: ["-y", "--yes"],
+		defaultValue: false,
 		description: "Skip confirmation prompts",
-		type: "boolean",
 		expectsValue: false,
-		defaultValue: false
+		names: ["-y", "--yes"],
+		type: "boolean"
 	},
 	{
-		names: ["--no-telemetry"],
+		defaultValue: false,
 		description: "Disable telemetry data collection",
-		type: "boolean",
 		expectsValue: false,
-		defaultValue: false
+		names: ["--no-telemetry"],
+		type: "boolean"
 	},
 	{
-		names: ["--telemetry-debug"],
+		defaultValue: false,
 		description: "Enable debug mode for telemetry",
-		type: "boolean",
 		expectsValue: false,
-		defaultValue: false
+		names: ["--telemetry-debug"],
+		type: "boolean"
 	},
 	{
-		names: ["--force"],
+		defaultValue: false,
 		description: "Force operation even if files exist",
-		type: "boolean",
 		expectsValue: false,
-		defaultValue: false
+		names: ["--force"],
+		type: "boolean"
 	}
 ];
 function getPrimaryFlagName(flag) {
@@ -452,12 +794,51 @@ function getPrimaryFlagName(flag) {
 	const fallback = flag.names.reduce((longest, name) => name.length > longest.length ? name : longest, "");
 	return (longName ?? fallback).replace(/^--?/, "");
 }
-function parseCliArgs(rawArgs, commands) {
+function mergeFlags(flags) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const flag of globalFlags) {
+		const primaryName = getPrimaryFlagName(flag);
+		if (primaryName) merged.set(primaryName, flag);
+	}
+	for (const flag of flags) {
+		const primaryName = getPrimaryFlagName(flag);
+		if (primaryName) merged.set(primaryName, flag);
+	}
+	return [...merged.values()];
+}
+/**
+* Parses raw command-line arguments into command name, command args, and
+* global and caller-provided flags.
+*
+* @remarks
+* Flags declared in `globalFlags` and `flags` are parsed. Unknown flags and
+* other positional arguments are preserved as command arguments. If the first
+* positional argument matches a registered top-level command in `commands`, it
+* is returned as `commandName` and removed from `commandArgs`.
+*
+* @param rawArgs - Arguments after the executable and script path.
+* @param commands - Top-level commands used to identify the command name.
+* @param flags - Additional global flag definitions to parse alongside
+* `globalFlags`. Caller-provided flags override built-in definitions that use
+* the same primary flag name.
+* @returns Normalized parsed output containing the matched command name,
+* remaining command arguments, and parsed flag values keyed by primary name.
+*
+* @example
+* ```ts
+* const parsed = parseCliArgs(['init', '--logger', 'debug'], commands);
+* // parsed.commandName === 'init'
+* // parsed.parsedFlags.logger === 'debug'
+* ```
+*/
+function parseCliArgs(rawArgs, commands, flags = []) {
+	const mergedFlags = mergeFlags(flags);
 	const parsedFlags = {};
 	const potentialCommandArgs = [];
 	let commandName;
 	const commandArgs = [];
-	for (const flag of globalFlags) {
+	const knownFlagSet = new Set(mergedFlags.flatMap((flag) => flag.names));
+	for (const flag of mergedFlags) {
 		const primaryName = getPrimaryFlagName(flag);
 		if (!primaryName) continue;
 		if (flag.type === "boolean") parsedFlags[primaryName] = flag.defaultValue ?? false;
@@ -467,7 +848,7 @@ function parseCliArgs(rawArgs, commands) {
 		const arg = rawArgs[i];
 		if (typeof arg !== "string") continue;
 		let isFlag = false;
-		for (const flag of globalFlags) {
+		for (const flag of mergedFlags) {
 			if (!flag.names.includes(arg)) continue;
 			const primaryName = getPrimaryFlagName(flag);
 			if (!primaryName) continue;
@@ -475,7 +856,7 @@ function parseCliArgs(rawArgs, commands) {
 			if (flag.type === "boolean") parsedFlags[primaryName] = true;
 			else if (flag.expectsValue) {
 				const nextArg = rawArgs[i + 1];
-				if (nextArg && !nextArg.startsWith("-")) {
+				if (nextArg && !knownFlagSet.has(nextArg)) {
 					parsedFlags[primaryName] = nextArg;
 					i++;
 				} else p.log.warn(formatLogMessage("warn", `Flag ${arg} expects a value, but none was provided`));
@@ -484,72 +865,146 @@ function parseCliArgs(rawArgs, commands) {
 		}
 		if (!isFlag) potentialCommandArgs.push(arg);
 	}
-	const firstPositional = potentialCommandArgs[0];
+	const [firstPositional] = potentialCommandArgs;
 	if (typeof firstPositional === "string" && commands.some((cmd) => cmd.name === firstPositional)) {
 		commandName = firstPositional;
 		commandArgs.push(...potentialCommandArgs.slice(1));
 	} else commandArgs.push(...potentialCommandArgs);
 	return {
-		commandName,
 		commandArgs,
+		commandName,
 		parsedFlags
 	};
 }
+/**
+* Formats a single flag for display in help output.
+*
+* @param flag - Flag definition to render.
+* @returns A help row containing names, value hint, and description.
+*/
 function formatFlagHelp(flag) {
 	return `  ${flag.names.join(", ")}${flag.expectsValue ? " <value>" : ""}\t${flag.description}`;
 }
-function generateFlagsHelp() {
-	return globalFlags.map(formatFlagHelp).join("\n");
+/**
+* Formats a provided set of flags for help output.
+*
+* @param flags - Flag definitions to render with `formatFlagHelp`, defaulting
+* to `globalFlags`.
+*
+* @returns Newline-delimited help rows for the provided flag definitions.
+*/
+function generateFlagsHelp(flags = globalFlags) {
+	return flags.map(formatFlagHelp).join("\n");
 }
+/**
+* Checks whether a parsed boolean flag is enabled.
+*
+* @param flags - Parsed flag map from `parseCliArgs` or `CliContext`.
+* @param name - Primary flag name without leading dashes.
+* @returns `true` only when the flag value is exactly `true`.
+*
+* @example
+* ```ts
+* if (hasFlag(context.flags, 'force')) {
+*   // overwrite existing files
+* }
+* ```
+*/
 function hasFlag(flags, name) {
 	return flags[name] === true;
 }
+/**
+* Reads a string-valued flag from a parsed flag map.
+*
+* @param flags - Parsed flag map from `parseCliArgs` or `CliContext`.
+* @param name - Primary flag name without leading dashes.
+* @returns The flag value when it is a string, otherwise `undefined`.
+*/
 function getFlagValue(flags, name) {
 	const value = flags[name];
 	if (typeof value === "string") return value;
 }
+/**
+* Splits command arguments into an optional nested subcommand and remaining
+* args.
+*
+* @param args - Positional command arguments to inspect.
+* @param subcommands - Available subcommands for the current command.
+* @returns The matched subcommand, if any, plus arguments after the subcommand
+* name.
+*
+* @example
+* ```ts
+* const { subcommand, remainingArgs } = parseSubcommand(
+*   context.commandArgs,
+*   command.subcommands ?? []
+* );
+* ```
+*/
 function parseSubcommand(args, subcommands) {
-	const subcommandName = args[0];
+	const [subcommandName] = args;
 	const subcommand = subcommands.find((cmd) => cmd.name === subcommandName);
 	if (subcommand) return {
-		subcommand,
-		remainingArgs: args.slice(1)
+		remainingArgs: args.slice(1),
+		subcommand
 	};
 	return {
-		subcommand: void 0,
-		remainingArgs: args
+		remainingArgs: args,
+		subcommand: void 0
 	};
 }
 //#endregion
 //#region src/telemetry.ts
+/**
+* Standard telemetry event names emitted by Hexbus runtime helpers.
+*/
 const TelemetryEventName = {
-	CLI_INVOKED: "cli_invoked",
-	CLI_ENVIRONMENT_DETECTED: "cli_environment_detected",
 	CLI_COMPLETED: "cli_completed",
+	CLI_ENVIRONMENT_DETECTED: "cli_environment_detected",
+	CLI_INVOKED: "cli_invoked",
+	COMMAND_FAILED: "command_failed",
 	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_EXITED: "interactive_menu_exited",
 	INTERACTIVE_MENU_OPENED: "interactive_menu_opened",
-	INTERACTIVE_MENU_EXITED: "interactive_menu_exited"
+	VERSION_DISPLAYED: "version_displayed"
 };
 function isEnvDisabled(prefix) {
 	const value = process.env[`${prefix}_TELEMETRY_DISABLED`];
 	return value === "1" || value === "true";
 }
+/**
+* Creates a no-op telemetry client.
+*
+* @returns A telemetry implementation whose methods do nothing and whose
+* `isDisabled()` method returns `true`.
+*/
 function createDisabledTelemetry() {
 	return {
-		trackEvent: () => {},
-		trackCommand: () => {},
-		trackError: () => {},
 		flush: async () => {},
+		flushBackground: () => {},
+		isDisabled: () => true,
 		shutdown: async () => {},
-		isDisabled: () => true
+		trackCommand: () => {},
+		trackError: () => {},
+		trackEvent: () => {}
 	};
 }
+/**
+* Creates the built-in telemetry client.
+*
+* @remarks
+* Events are queued in memory. `flush()` posts the queue to `endpoint` when one
+* is configured, then clears the queue. Failed flushes are reported through
+* the optional logger and do not throw, keeping telemetry best effort.
+*
+* @param options - Telemetry behavior and event defaults.
+* @returns An enabled or disabled telemetry client depending on options and
+* environment opt-out variables.
+*/
 function createTelemetry(options = {}) {
 	const envVarPrefix = options.envVarPrefix ?? "APP";
 	const disabled = options.disabled === true || isEnvDisabled(envVarPrefix);
@@ -573,45 +1028,57 @@ function createTelemetry(options = {}) {
 			events.length = 0;
 			return;
 		}
-		const batch = events.splice(0, events.length);
+		const batch = events.splice(0);
 		try {
 			await fetch(options.endpoint, {
-				method: "POST",
-				headers: { "content-type": "application/json" },
 				body: JSON.stringify({ events: batch }),
-				keepalive: true
+				headers: { "content-type": "application/json" },
+				keepalive: true,
+				method: "POST"
 			});
 		} catch (error) {
 			options.logger?.warn(`Failed to send telemetry: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	};
 	return {
-		trackEvent,
+		flush,
+		flushBackground() {
+			flush();
+		},
+		isDisabled() {
+			return false;
+		},
+		async shutdown() {
+			await flush();
+		},
 		trackCommand(command, args = [], flags = {}) {
+			const enabledFlags = Object.entries(flags).filter(([, value]) => value !== false && value !== void 0).map(([key]) => key);
+			enabledFlags.sort();
 			trackEvent(TelemetryEventName.COMMAND_INVOKED, {
-				command,
 				argsCount: args.length,
-				enabledFlags: Object.entries(flags).filter(([, value]) => value !== false && value !== void 0).map(([key]) => key).sort()
+				command,
+				enabledFlags
 			});
 		},
 		trackError(error, command) {
 			trackEvent(TelemetryEventName.ERROR_OCCURRED, {
 				command,
-				errorName: error.name,
-				errorMessage: error.message
+				errorMessage: error.message,
+				errorName: error.name
 			});
 		},
-		flush,
-		async shutdown() {
-			await flush();
-		},
-		isDisabled() {
-			return false;
-		}
+		trackEvent
 	};
 }
 //#endregion
 //#region src/context.ts
+/**
+* Resolves the active logger level from parsed CLI flags.
+*
+* @param parsedFlags - Parsed global flags from the current invocation.
+* @returns A valid log level, falling back to `info` for missing or invalid
+* values.
+*/
 function getLogLevel(parsedFlags) {
 	const levelArg = parsedFlags.logger;
 	if (typeof levelArg === "string") {
@@ -620,17 +1087,34 @@ function getLogLevel(parsedFlags) {
 	}
 	return "info";
 }
+/**
+* Creates file-system helpers scoped to a project root.
+*
+* @param cwd - Project root used for package metadata lookup.
+* @returns File-system utilities for context consumers.
+*/
 function createFileSystem(cwd) {
 	return {
+		async exists(filePath) {
+			try {
+				await fs.access(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
 		getPackageInfo() {
 			const packageJsonPath = path.join(cwd, "package.json");
 			try {
 				const content = fsSync.readFileSync(packageJsonPath, "utf-8");
 				const packageInfo = JSON.parse(content);
+				const packageFields = packageInfo && typeof packageInfo === "object" && !Array.isArray(packageInfo) ? packageInfo : {};
+				const name = typeof packageFields.name === "string" ? packageFields.name : "unknown";
+				const version = typeof packageFields.version === "string" ? packageFields.version : "unknown";
 				return {
-					...packageInfo,
-					name: packageInfo.name || "unknown",
-					version: packageInfo.version || "unknown"
+					...packageFields,
+					name: name || "unknown",
+					version: version || "unknown"
 				};
 			} catch {
 				return {
@@ -639,66 +1123,83 @@ function createFileSystem(cwd) {
 				};
 			}
 		},
-		async exists(filePath) {
-			try {
-				await fs.access(filePath);
-				return true;
-			} catch {
-				return false;
-			}
+		async mkdir(dirPath) {
+			await fs.mkdir(dirPath, { recursive: true });
 		},
 		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 });
 		}
 	};
 }
+/**
+* Creates the resolved context passed to command actions.
+*
+* @remarks
+* Context creation performs the standard CLI bootstrap sequence: parse global
+* flags, create the logger, detect the project root, detect framework and
+* package manager metadata, set up telemetry, and attach helpers for config
+* loading, file-system access, confirmation prompts, and process-ending error
+* handling.
+*
+* @typeParam TPackage - Product-specific package identifier returned from
+* framework detection.
+* @param options - Context creation options for the current invocation.
+* @returns A fully initialized `CliContext`.
+*
+* @example
+* ```ts
+* const context = await createCliContext({
+*   rawArgs: process.argv.slice(2),
+*   appName: 'acme',
+*   commands,
+* });
+*
+* await commands.find((command) => command.name === context.commandName)
+*   ?.action(context);
+* ```
+*/
 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 { commandName, commandArgs, parsedFlags } = parseCliArgs(options.rawArgs, options.commands, options.globalFlags);
 	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(),
+		debug: options.telemetry?.debug === true || parsedFlags["telemetry-debug"] === true,
 		defaultProperties: {
-			entryCommand: commandName ?? "interactive",
-			commandArgsCount: commandArgs.length,
 			cliVersion: fsUtils.getPackageInfo().version,
+			commandArgsCount: commandArgs.length,
+			entryCommand: commandName ?? "interactive",
 			framework: framework.framework ?? "unknown",
 			frameworkVersion: framework.frameworkVersion ?? "unknown",
 			packageManager: packageManager.name,
 			...options.telemetry?.defaultProperties
 		},
+		disabled: options.telemetry?.disabled === true || parsedFlags["no-telemetry"] === true,
+		endpoint: options.telemetry?.endpoint,
+		envVarPrefix: options.telemetry?.envVarPrefix ?? appName.toUpperCase(),
 		logger
 	});
 	const errorHandlers = createErrorHandlers(logger, telemetry);
 	const context = {
-		logger,
-		flags: parsedFlags,
-		commandName,
 		commandArgs,
-		cwd,
-		error: errorHandlers,
+		commandName,
 		config: {
+			getPathAliases() {
+				return null;
+			},
 			async loadConfig() {
-				const configPath = typeof parsedFlags.config === "string" ? parsedFlags.config : void 0;
 				const { config } = await loadConfig({
-					name: options.configName ?? appName,
+					configFile: typeof parsedFlags.config === "string" ? parsedFlags.config : void 0,
 					cwd: projectRoot,
-					configFile: configPath
+					name: options.configName ?? appName
 				});
 				return config ?? null;
 			},
@@ -706,89 +1207,117 @@ async function createCliContext(options) {
 				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
+				initialValue,
+				message
 			});
 			if (p.isCancel(result)) errorHandlers.handleCancel("Confirmation cancelled");
 			return result;
 		},
-		projectRoot,
+		cwd,
+		error: errorHandlers,
+		flags: parsedFlags,
 		framework,
-		packageManager
+		fs: fsUtils,
+		logger,
+		packageManager,
+		projectRoot,
+		telemetry
 	};
 	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,
+		packageManager: packageManager.name,
+		projectRootChanged: projectRoot !== cwd,
 		reactVersion: framework.reactVersion ?? "unknown",
 		tailwindVersion: framework.tailwindVersion ?? "unknown"
 	});
 	return context;
 }
+/**
+* Creates a deterministic context for unit tests.
+*
+* @remarks
+* The test context disables telemetry, uses an error-only logger, avoids real
+* framework or package-manager detection, and provides no-op file-system
+* helpers. Pass overrides to replace only the services a test needs.
+*
+* @param overrides - Partial context fields to merge into the default test
+* context.
+* @returns A `CliContext` suitable for command and helper tests.
+*
+* @example
+* ```ts
+* const context = createTestContext({
+*   flags: { force: true },
+*   commandName: 'init',
+* });
+* ```
+*/
 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,
+		commandName: void 0,
 		config: {
-			loadConfig: async () => null,
-			requireConfig: async () => {
-				throw new CliError("CONFIG_NOT_FOUND");
-			},
-			getPathAliases: () => null
+			getPathAliases: () => null,
+			loadConfig: () => Promise.resolve(null),
+			requireConfig: () => Promise.reject(new CliError("CONFIG_NOT_FOUND"))
 		},
-		fs: {
-			getPackageInfo: () => ({
-				name: "test",
-				version: "0.0.0"
-			}),
-			exists: async () => false,
-			read: async () => "",
-			write: async () => {},
-			mkdir: async () => {}
-		},
-		telemetry,
-		confirm: async () => true,
-		projectRoot: process.cwd(),
+		confirm: () => Promise.resolve(true),
+		cwd: process.cwd(),
+		error,
+		flags: {},
 		framework: {
 			framework: null,
 			frameworkVersion: null,
-			pkg: null,
 			hasReact: false,
+			pkg: null,
 			reactVersion: null,
 			tailwindVersion: null
 		},
+		fs: {
+			exists: () => Promise.resolve(false),
+			getPackageInfo: () => ({
+				name: "test",
+				version: "0.0.0"
+			}),
+			mkdir: () => Promise.resolve(),
+			read: () => Promise.resolve(""),
+			write: () => Promise.resolve()
+		},
+		logger,
 		packageManager: {
-			name: "npm",
-			installCommand: "npm install",
 			addCommand: "npm install",
-			runCommand: "npm run",
-			execCommand: "npx"
+			execCommand: "npx",
+			installCommand: "npm install",
+			name: "npm",
+			runCommand: "npm run"
 		},
+		projectRoot: process.cwd(),
+		telemetry,
 		...overrides
 	};
 }
 //#endregion
 //#region src/help.ts
+/**
+* Renders a help menu for commands and global flags.
+*
+* @param context - Context subset providing the logger used for output.
+* @param options - Application metadata for the help menu.
+* @param commands - Commands to list; commands with `hidden: true` are
+* omitted.
+* @param flags - Global flags to list.
+*/
 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) => {
@@ -800,17 +1329,23 @@ function showHelpMenu(context, options, commands, flags) {
 }
 //#endregion
 //#region src/intro.ts
-function renderFiglet(text) {
-	return new Promise((resolve) => {
-		figlet(text, (error, data) => {
-			if (error || !data) {
-				resolve(text);
-				return;
-			}
-			resolve(data);
-		});
-	});
+const renderFigletAsync = promisify(figlet);
+async function renderFiglet(text) {
+	try {
+		return await renderFigletAsync(text) ?? text;
+	} catch {
+		return text;
+	}
 }
+/**
+* Renders a figlet banner and short intro note.
+*
+* @remarks
+* If figlet rendering fails, the plain banner text is displayed instead.
+*
+* @param context - Context subset providing the logger used for output.
+* @param options - Intro banner metadata.
+*/
 async function displayIntro(context, options) {
 	const banner = await renderFiglet(options.figletText ?? options.appName);
 	const versionLabel = options.version ? ` v${options.version}` : "";
@@ -819,49 +1354,104 @@ async function displayIntro(context, options) {
 }
 //#endregion
 //#region src/spinner.ts
+/**
+* Creates a Clack-backed spinner.
+*
+* @param initialMessage - Message used when `start()` is called without an
+* explicit message.
+* @returns A spinner controller.
+*/
 function createSpinner(initialMessage) {
-	const spinner = p.spinner();
+	const spinnerInstance = spinner();
 	return {
+		message(message) {
+			spinnerInstance.message(message);
+		},
 		start(message) {
-			spinner.start(message || initialMessage || "Processing...");
+			spinnerInstance.start(message ?? initialMessage ?? "Processing...");
 		},
 		stop(message) {
-			spinner.stop(message || "Done");
-		},
-		message(message) {
-			spinner.message(message);
+			spinnerInstance.stop(message ?? "Done");
 		}
 	};
 }
+/**
+* Runs an async task while displaying a spinner.
+*
+* @typeParam T - Value returned by the task.
+* @param message - Message shown when the spinner starts.
+* @param task - Async work to run.
+* @param options - Optional success and error messages shown when the task
+* settles.
+* @returns The value returned by `task`.
+*
+* @throws Re-throws any error from `task` after stopping the spinner.
+*/
 async function withSpinner(message, task, options) {
-	const spinner = createSpinner(message);
-	spinner.start();
+	const spinnerInstance = createSpinner(message);
+	spinnerInstance.start();
 	try {
 		const result = await task();
-		spinner.stop(options?.successMessage || "Done");
+		spinnerInstance.stop(options?.successMessage ?? "Done");
 		return result;
 	} catch (error) {
-		spinner.stop(options?.errorMessage || "Failed");
+		spinnerInstance.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`);
+//#region src/version-check/compare.ts
+function parseVersionParts(version) {
+	const [coreVersion = "", prerelease] = version.replace(/^[^\d]*/, "").split("-", 2);
+	return {
+		parts: coreVersion.split(".").map((part) => {
+			const parsed = Number.parseInt(part.replace(/\D.*$/, ""), 10);
+			return Number.isNaN(parsed) ? 0 : parsed;
+		}),
+		prerelease
+	};
+}
+function comparePrereleaseIdentifiers(left, right) {
+	const leftIsNumeric = /^\d+$/.test(left);
+	const rightIsNumeric = /^\d+$/.test(right);
+	if (leftIsNumeric && rightIsNumeric) return Math.sign(Number.parseInt(left, 10) - Number.parseInt(right, 10));
+	if (leftIsNumeric) return -1;
+	if (rightIsNumeric) return 1;
+	return Math.sign(left.localeCompare(right));
+}
+function comparePrerelease(left, right) {
+	if (!left && !right) return 0;
+	if (!left) return 1;
+	if (!right) return -1;
+	const leftParts = left.split(".");
+	const rightParts = right.split(".");
+	const length = Math.max(leftParts.length, rightParts.length);
+	for (let index = 0; index < length; index++) {
+		const leftValue = leftParts[index];
+		const rightValue = rightParts[index];
+		if (leftValue === void 0) return -1;
+		if (rightValue === void 0) return 1;
+		const result = comparePrereleaseIdentifiers(leftValue, rightValue);
+		if (result !== 0) return result;
 	}
-};
-function isVersionRequest(rawArgs) {
-	return rawArgs.includes("-v") || rawArgs.includes("--version");
+	return 0;
+}
+function compareVersions(left, right) {
+	const leftVersion = parseVersionParts(left);
+	const rightVersion = parseVersionParts(right);
+	const leftParts = leftVersion.parts;
+	const rightParts = rightVersion.parts;
+	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 comparePrerelease(leftVersion.prerelease, rightVersion.prerelease);
 }
+//#endregion
+//#region src/version-check/install-source.ts
 function normalizePath(filePath) {
 	return filePath.replaceAll("\\", "/");
 }
@@ -884,12 +1474,28 @@ function isPathUnder(candidate, parent) {
 function envValue(name) {
 	return process.env[name];
 }
+/**
+* Infers how the current CLI binary was installed.
+*
+* @remarks
+* Detection is heuristic and based on binary path, realpath, and package
+* manager environment variables. Unknown or transient install modes return
+* `unknown` instead of throwing.
+*
+* @param binPath - Binary path to inspect.
+* @returns The inferred installation source.
+*/
 function detectInstallSource(binPath = process.argv[1] ?? "") {
 	const resolvedPath = normalizePath(safeRealpath(binPath || ""));
 	const npmPrefix = envValue("npm_config_prefix");
+	const execPath = normalizePath(process.execPath);
+	const argvPath = normalizePath(process.argv[0] ?? "");
+	const execName = path$1.basename(execPath);
+	const argvName = path$1.basename(argvPath);
+	const isBunInvocation = execName === "bun" || execName === "bunx" || argvName === "bun" || argvName === "bunx";
 	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("/.bun/install/cache/") || Boolean(envValue("BUN_INSTALL")) && (resolvedPath.includes("/.bun/install/run/") || isBunInvocation)) 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";
@@ -906,6 +1512,15 @@ function detectInstallSource(binPath = process.argv[1] ?? "") {
 	})) return "npm-global";
 	return "unknown";
 }
+/**
+* Builds an update command for an installation source.
+*
+* @param source - Installation source returned by `detectInstallSource`.
+* @param packageName - Package name to update.
+* @param brewFormula - Homebrew formula name when `source` is `brew`.
+* @returns A command string when the source has an actionable update path,
+* otherwise `null`.
+*/
 function getUpdateCommand(source, packageName, brewFormula = packageName) {
 	switch (source) {
 		case "npm-global": return `npm install -g ${packageName}@latest`;
@@ -914,8 +1529,48 @@ function getUpdateCommand(source, packageName, brewFormula = packageName) {
 		default: return null;
 	}
 }
+//#endregion
+//#region src/version-check/registry.ts
+const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_CACHE_TTL_MS = 1440 * 60 * 1e3;
+const MAX_CACHE_NAME_LENGTH = 80;
+const WINDOWS_RESERVED_NAMES = new Set([
+	"con",
+	"prn",
+	"aux",
+	"nul",
+	"com1",
+	"com2",
+	"com3",
+	"com4",
+	"com5",
+	"com6",
+	"com7",
+	"com8",
+	"com9",
+	"lpt1",
+	"lpt2",
+	"lpt3",
+	"lpt4",
+	"lpt5",
+	"lpt6",
+	"lpt7",
+	"lpt8",
+	"lpt9"
+]);
+function getCacheNameHash(packageName) {
+	return createHash("sha256").update(packageName).digest("hex").slice(0, 8);
+}
 function sanitizeCacheName(packageName) {
-	return packageName.replaceAll("/", "__").replaceAll("@", "");
+	const normalized = packageName.normalize("NFKD").toLowerCase().replaceAll(/[^a-z0-9._-]+/g, "_").replaceAll(/_+/g, "_").replaceAll(/^[._-]+|[._-]+$/g, "");
+	const fallbackName = normalized || "package";
+	const baseName = fallbackName.split(".")[0] ?? fallbackName;
+	const isReservedName = WINDOWS_RESERVED_NAMES.has(baseName);
+	if (!(normalized !== packageName || normalized.length === 0 || isReservedName || normalized.length > MAX_CACHE_NAME_LENGTH)) return normalized;
+	const hash = getCacheNameHash(packageName);
+	const maxStemLength = MAX_CACHE_NAME_LENGTH - hash.length - 1;
+	return `${(isReservedName ? `package-${fallbackName}` : fallbackName).slice(0, maxStemLength).replaceAll(/[._-]+$/g, "") || "package"}-${hash}`;
 }
 function getCacheDir(options) {
 	return options.cacheDir ?? path$1.join(os.tmpdir(), "hexbus-version-cache");
@@ -928,8 +1583,8 @@ function readCachedVersion(options) {
 		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
+			fetchedAt: parsed.fetchedAt,
+			version: parsed.version
 		};
 	} catch {}
 	return null;
@@ -942,52 +1597,19 @@ function isCacheFresh(cache, options) {
 async function writeCachedVersion(options, version) {
 	const cachePath = getCachePath(options);
 	const cacheDir = path$1.dirname(cachePath);
-	const tempPath = `${cachePath}.${process.pid}.tmp`;
+	const tempPath = `${cachePath}.${process.pid}.${randomUUID()}.tmp`;
 	const payload = {
-		version,
-		fetchedAt: options.now?.() ?? Date.now()
+		fetchedAt: options.now?.() ?? Date.now(),
+		version
 	};
-	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;
+	try {
+		await fs$1.mkdir(cacheDir, { recursive: true });
+		await fs$1.writeFile(tempPath, `${JSON.stringify(payload)}\n`, "utf-8");
+		await fs$1.rename(tempPath, cachePath);
+	} catch (error) {
+		await fs$1.unlink(tempPath).catch(() => {});
+		throw error;
 	}
-	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();
@@ -1010,11 +1632,24 @@ async function refreshCache(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));
+//#endregion
+//#region src/version-check/check.ts
+/**
+* Checks whether raw arguments request version output.
+*
+* @param rawArgs - Arguments after executable and script path.
+* @returns `true` when `-v` or `--version` is present.
+*/
+function isVersionRequest(rawArgs) {
+	return rawArgs.includes("-v") || rawArgs.includes("--version");
 }
+/**
+* Formats a user-facing update hint from an update-check result.
+*
+* @param result - Update-check result to render.
+* @returns A formatted hint when the result is outdated and has an update
+* command, otherwise `null`.
+*/
 function formatUpdateHint(result) {
 	if (!result.isOutdated || result.updateCommand === null || result.latestVersion === null) return null;
 	if (result.source === "brew") return [
@@ -1028,23 +1663,95 @@ function formatUpdateHint(result) {
 		`  ${color.cyan(result.updateCommand)}`
 	].join("\n");
 }
+function createUpdateCheckResult(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,
+		isOutdated,
+		latestVersion,
+		source,
+		updateCommand
+	};
+	const hint = formatUpdateHint({
+		...result,
+		hint: null
+	});
+	return {
+		...result,
+		hint
+	};
+}
+/**
+* Checks whether a newer package version is available.
+*
+* @remarks
+* The function first reads the local cache. On a cache miss it refreshes the
+* cache from the configured registry. Refresh failures produce a result with
+* `latestVersion: null` rather than throwing.
+*
+* @param options - Update-check configuration.
+* @returns Update metadata and a formatted hint when an update is available.
+*/
+async function checkForUpdate(options) {
+	const cached = readCachedVersion(options);
+	if (cached) return createUpdateCheckResult(options, cached.version);
+	try {
+		return createUpdateCheckResult(options, await refreshCache(options));
+	} catch (error) {
+		options.logger?.debug?.(`Update check failed: ${error instanceof Error ? error.message : String(error)}`);
+		return createUpdateCheckResult(options, null);
+	}
+}
+//#endregion
+//#region src/version-check/display.ts
+const defaultLogger = {
+	message(message) {
+		process.stdout.write(`${message}\n`);
+	},
+	note(content, title) {
+		const prefix = title ? `${title}\n` : "";
+		process.stdout.write(`${prefix}${content}\n`);
+	}
+};
+/**
+* Prints CLI version information and any available update hint.
+*
+* @param options - Version display and update-check options.
+*/
 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");
 }
+async function refreshCacheInBackground(options, logger) {
+	try {
+		await refreshCache(options);
+	} catch (error) {
+		logger.debug?.(`Update check failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Starts a non-blocking update check.
+*
+* @remarks
+* Cached hints are displayed synchronously when available. If the cache is
+* stale or missing, a refresh is started in the background and failures are
+* only logged at debug level.
+*
+* @param options - Version display and update-check options.
+*/
 function startBackgroundUpdateCheck(options) {
 	const logger = options.logger ?? defaultLogger;
 	const cached = readCachedVersion(options);
 	if (cached) {
-		const result = createResult(options, cached.version);
+		const result = createUpdateCheckResult(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)}`);
-	});
+	refreshCacheInBackground(options, logger);
 }
 //#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 };