commandkit 1.2.1-dev.20260411010608 → 1.2.1-dev.20260411122819

package/dist/{commandkit-DNln6BAJ.js → commandkit-D2HMPuRQ.js}

@@ -631,20 +631,30 @@ function findAppDirectory() {
 */
 function debounce(fn, ms) {
 	let timer = null;
-	let resolve = null;
+	let sharedPromise = null;
+	let sharedResolve = null;
+	let sharedReject = null;
 	return ((...args) => {
-		if (timer) {
-			clearTimeout(timer);
-			if (resolve) resolve(null);
-		}
-		return new Promise((res) => {
-			resolve = res;
-			timer = setTimeout(() => {
-				res(fn(...args));
-				timer = null;
-				resolve = null;
-			}, ms);
+		if (timer) clearTimeout(timer);
+		if (!sharedPromise) sharedPromise = new Promise((res, rej) => {
+			sharedResolve = res;
+			sharedReject = rej;
 		});
+		timer = setTimeout(async () => {
+			const currentResolve = sharedResolve;
+			const currentReject = sharedReject;
+			timer = null;
+			sharedPromise = null;
+			sharedResolve = null;
+			sharedReject = null;
+			try {
+				const result = await fn(...args);
+				if (currentResolve) currentResolve(result);
+			} catch (err) {
+				if (currentReject) currentReject(err);
+			}
+		}, ms);
+		return sharedPromise;
 	});
 }
 /**
@@ -1579,9 +1589,12 @@ var Context = class Context {
 	* Gets the name of the current command.
 	*/
 	get commandName() {
+		const routeKey = this.command.data.command.__routeKey;
+		if (typeof routeKey === "string" && routeKey.length) return routeKey;
+		if (this.command.data.command.name) return this.command.data.command.name;
 		if (this.isInteraction()) return this.interaction.commandName;
-		const maybeAlias = this.config.messageCommandParser.getCommand();
-		return this.commandkit.commandHandler.resolveMessageCommandName(maybeAlias);
+		const parser = this.config.messageCommandParser;
+		return this.commandkit.commandHandler.resolveMessageCommandName(parser.getFullCommand());
 	}
 	/**
 	* Gets the invoked command name (could be an alias for message commands)
@@ -1675,7 +1688,7 @@ var Context = class Context {
 	*/
 	getCommandIdentifier() {
 		if (this.isInteraction()) return this.interaction.commandName;
-		else return this.message.content.split(" ")[0].slice(1);
+		else return this.commandName;
 	}
 	/**
 	* Returns the locale of the guild where this command was triggered.
@@ -1787,7 +1800,7 @@ var AppCommandRunner = class {
 		const env = new CommandKitEnvironment(commandkit);
 		env.setType(CommandKitEnvironmentType.CommandHandler);
 		env.variables.set("commandHandlerType", "app");
-		env.variables.set("currentCommandName", prepared.command.command.name);
+		env.variables.set("currentCommandName", prepared.command.data.command.__routeKey ?? prepared.command.command.name);
 		env.variables.set("execHandlerKind", executionMode);
 		env.variables.set("customHandler", (options === null || options === void 0 ? void 0 : options.handler) ?? null);
 		try {
@@ -1827,15 +1840,15 @@ var AppCommandRunner = class {
 				if (fn) try {
 					const _executeCommand = makeContextAwareFunction(env, async () => {
 						env.registerDeferredFunction(async (env) => {
-							var _prepared$command2;
+							var _prepared$command3, _prepared$command4;
 							env.markEnd();
 							const error = env.getExecutionError();
 							const marker = env.getMarker();
 							const time = `${env.getExecutionTime().toFixed(2)}ms`;
 							if (error) {
-								var _prepared$command;
+								var _prepared$command, _prepared$command2;
 								Logger.error`[${marker} - ${time}] Error executing command: ${error}`;
-								const commandName = ((_prepared$command = prepared.command) === null || _prepared$command === void 0 || (_prepared$command = _prepared$command.data) === null || _prepared$command === void 0 || (_prepared$command = _prepared$command.command) === null || _prepared$command === void 0 ? void 0 : _prepared$command.name) ?? prepared.command.command.name;
+								const commandName = ((_prepared$command = prepared.command) === null || _prepared$command === void 0 || (_prepared$command = _prepared$command.data) === null || _prepared$command === void 0 || (_prepared$command = _prepared$command.command) === null || _prepared$command === void 0 ? void 0 : _prepared$command.__routeKey) ?? ((_prepared$command2 = prepared.command) === null || _prepared$command2 === void 0 || (_prepared$command2 = _prepared$command2.data) === null || _prepared$command2 === void 0 || (_prepared$command2 = _prepared$command2.command) === null || _prepared$command2 === void 0 ? void 0 : _prepared$command2.name) ?? prepared.command.command.name;
 								await analytics.track({
 									name: require_analytics_constants.AnalyticsEvents.COMMAND_EXECUTION,
 									id: commandName,
@@ -1849,7 +1862,7 @@ var AppCommandRunner = class {
 								return;
 							}
 							Logger.info(`[${marker} - ${time}] Command executed successfully`);
-							const commandName = ((_prepared$command2 = prepared.command) === null || _prepared$command2 === void 0 || (_prepared$command2 = _prepared$command2.data) === null || _prepared$command2 === void 0 || (_prepared$command2 = _prepared$command2.command) === null || _prepared$command2 === void 0 ? void 0 : _prepared$command2.name) ?? prepared.command.command.name;
+							const commandName = ((_prepared$command3 = prepared.command) === null || _prepared$command3 === void 0 || (_prepared$command3 = _prepared$command3.data) === null || _prepared$command3 === void 0 || (_prepared$command3 = _prepared$command3.command) === null || _prepared$command3 === void 0 ? void 0 : _prepared$command3.__routeKey) ?? ((_prepared$command4 = prepared.command) === null || _prepared$command4 === void 0 || (_prepared$command4 = _prepared$command4.data) === null || _prepared$command4 === void 0 || (_prepared$command4 = _prepared$command4.command) === null || _prepared$command4 === void 0 ? void 0 : _prepared$command4.name) ?? prepared.command.command.name;
 							await analytics.track({
 								name: require_analytics_constants.AnalyticsEvents.COMMAND_EXECUTION,
 								id: commandName,
@@ -1864,7 +1877,7 @@ var AppCommandRunner = class {
 						return fn(middlewareCtx.clone());
 					}, this.#finalizer.bind(this));
 					const executeCommand = runCommand != null ? runCommand(_executeCommand) : _executeCommand;
-					env.markStart(prepared.command.data.command.name);
+					env.markStart(prepared.command.data.command.__routeKey ?? prepared.command.data.command.name);
 					if (!await commandkit.plugins.execute(async (ctx, plugin) => {
 						return plugin.executeCommand(ctx, env, source, prepared, executeCommand);
 					})) result = await executeCommand();
@@ -2024,11 +2037,17 @@ var CommandRegistrar = class {
 	* Gets the commands data, consuming pre-generated context menu entries when available.
 	*/
 	getCommandsData() {
+		return [...this.getFlatCommandsData(), ...this.getHierarchicalCommandsData()];
+	}
+	/**
+	* Gets flat command data, consuming pre-generated context menu entries when available.
+	*/
+	getFlatCommandsData() {
 		const commands = this.commandkit.commandHandler.getCommandsArray();
 		const commandIds = new Set(commands.map((command) => command.command.id));
 		return commands.flatMap((cmd) => {
 			const isPreGeneratedCtx = cmd.command.id.endsWith("::user-ctx") || cmd.command.id.endsWith("::message-ctx");
-			const json = "toJSON" in cmd.data.command ? cmd.data.command.toJSON() : cmd.data.command;
+			const json = this.sanitizeCommandData("toJSON" in cmd.data.command ? cmd.data.command.toJSON() : cmd.data.command);
 			const __metadata = cmd.metadata ?? cmd.data.metadata;
 			const isContextMenuType = json.type === discord_js.ApplicationCommandType.User || json.type === discord_js.ApplicationCommandType.Message;
 			const applyId = (id) => {
@@ -2079,6 +2098,119 @@ var CommandRegistrar = class {
 		});
 	}
 	/**
+	* Gets hierarchical chat-input command payloads compiled from cached tree nodes.
+	*/
+	getHierarchicalCommandsData() {
+		const router = this.commandkit.commandsRouter;
+		if (!router) return [];
+		const { treeNodes } = router.getData();
+		const hierarchicalNodes = new Map(this.commandkit.commandHandler.getHierarchicalNodesArray().map((node) => [node.command.id, node]));
+		const rootNodes = Array.from(treeNodes.values()).filter((node) => {
+			return node.source !== "flat" && node.kind === "command" && node.route.length === 1;
+		});
+		const commands = [];
+		for (const rootNode of rootNodes) {
+			const payload = this.buildHierarchicalRootPayload(rootNode.id, treeNodes, hierarchicalNodes);
+			if (payload) commands.push(payload);
+		}
+		return commands;
+	}
+	/**
+	* Removes internal runtime-only fields before Discord registration data is emitted.
+	*/
+	sanitizeCommandData(command) {
+		const { __routeKey, ...json } = command;
+		return json;
+	}
+	/**
+	* Builds a top-level Discord payload for a hierarchical command root.
+	*/
+	buildHierarchicalRootPayload(rootNodeId, treeNodes, hierarchicalNodes) {
+		const rootNode = treeNodes.get(rootNodeId);
+		const rootLoaded = hierarchicalNodes.get(rootNodeId);
+		if (!rootNode || !rootLoaded) return null;
+		const rootJson = this.sanitizeCommandData("toJSON" in rootLoaded.data.command ? rootLoaded.data.command.toJSON() : rootLoaded.data.command);
+		if (rootNode.executable) {
+			if (!rootLoaded.data.chatInput) return null;
+			return {
+				...rootJson,
+				type: discord_js.ApplicationCommandType.ChatInput,
+				description: rootJson.description ?? "No command description set.",
+				__metadata: rootLoaded.metadata ?? rootLoaded.data.metadata,
+				__applyId: (id) => {
+					rootLoaded.discordId = id;
+				}
+			};
+		}
+		const options = rootNode.childIds.map((childId) => this.buildHierarchicalOption(childId, treeNodes, hierarchicalNodes)).filter(Boolean);
+		if (!options.length) return null;
+		const scopeKeys = new Set(this.collectHierarchicalGuildScopes(rootNode.childIds, treeNodes, hierarchicalNodes));
+		if (scopeKeys.size > 1) {
+			Logger.error(`Failed to register hierarchical command "${rootJson.name ?? rootNode.token}": all chat-input leaves under the same root must use the same guild scope in v1.`);
+			return null;
+		}
+		const scopeKey = scopeKeys.values().next().value;
+		const scopeGuilds = scopeKey ? scopeKey.split(",").filter(Boolean) : [];
+		const metadata = {
+			...rootLoaded.metadata ?? rootLoaded.data.metadata,
+			guilds: scopeGuilds.length ? scopeGuilds : void 0
+		};
+		return {
+			...rootJson,
+			type: discord_js.ApplicationCommandType.ChatInput,
+			description: rootJson.description ?? "No command description set.",
+			options,
+			__metadata: metadata,
+			__applyId: (id) => {
+				rootLoaded.discordId = id;
+			}
+		};
+	}
+	/**
+	* Builds a nested subcommand or subcommand-group option from a hierarchical node.
+	*/
+	buildHierarchicalOption(nodeId, treeNodes, hierarchicalNodes) {
+		const node = treeNodes.get(nodeId);
+		const loadedNode = hierarchicalNodes.get(nodeId);
+		if (!node || !loadedNode) return null;
+		const json = this.sanitizeCommandData("toJSON" in loadedNode.data.command ? loadedNode.data.command.toJSON() : loadedNode.data.command);
+		if (node.kind === "group") {
+			const options = node.childIds.map((childId) => this.buildHierarchicalOption(childId, treeNodes, hierarchicalNodes)).filter(Boolean);
+			if (!options.length) return null;
+			return {
+				...json,
+				type: discord_js.ApplicationCommandOptionType.SubcommandGroup,
+				description: json.description ?? "No command description set.",
+				options
+			};
+		}
+		if (!node.executable || !loadedNode.data.chatInput) return null;
+		return {
+			...json,
+			type: discord_js.ApplicationCommandOptionType.Subcommand,
+			description: json.description ?? "No command description set."
+		};
+	}
+	/**
+	* Collects normalized guild scopes for all chat-input leaves within a hierarchical subtree.
+	*/
+	collectHierarchicalGuildScopes(nodeIds, treeNodes, hierarchicalNodes) {
+		const scopes = [];
+		for (const nodeId of nodeIds) {
+			var _loadedNode$metadata;
+			const node = treeNodes.get(nodeId);
+			const loadedNode = hierarchicalNodes.get(nodeId);
+			if (!node || !loadedNode) continue;
+			if (node.kind === "group") {
+				scopes.push(...this.collectHierarchicalGuildScopes(node.childIds, treeNodes, hierarchicalNodes));
+				continue;
+			}
+			if (!node.executable || !loadedNode.data.chatInput) continue;
+			scopes.push((((_loadedNode$metadata = loadedNode.metadata) === null || _loadedNode$metadata === void 0 ? void 0 : _loadedNode$metadata.guilds) ?? []).filter(Boolean).slice().sort().join(","));
+		}
+		return scopes;
+	}
+	/**
 	* Registers loaded commands.
 	*/
 	async register() {
@@ -2249,6 +2381,20 @@ var AppCommandHandler = class {
 	*/
 	loadedCommands = new discord_js.Collection();
 	/**
+	* Executable runtime commands indexed by canonical route key.
+	* This includes flat commands and hierarchical executable leaves.
+	* @private
+	* @internal
+	*/
+	runtimeRouteIndex = new discord_js.Collection();
+	/**
+	* Loaded hierarchical command nodes keyed by tree node id.
+	* Container nodes are cached here for registration compilation.
+	* @private
+	* @internal
+	*/
+	hierarchicalNodes = new discord_js.Collection();
+	/**
 	* @private
 	* @internal
 	*/
@@ -2291,31 +2437,54 @@ var AppCommandHandler = class {
 	* Prints a formatted banner showing all loaded commands organized by category.
 	*/
 	printBanner() {
+		var _this$commandkit$comm;
 		const uncategorized = crypto.randomUUID();
-		const categorizedCommands = this.getCommandsArray().reduce((acc, cmd) => {
-			const category = cmd.command.category || uncategorized;
-			acc[category] = acc[category] || [];
-			acc[category].push(cmd);
-			return acc;
-		}, {});
-		console.log(require_utils_colors.default.green(`Loaded ${require_utils_colors.default.magenta(this.loadedCommands.size.toString())} commands:`));
-		const categories = Object.keys(categorizedCommands).sort();
+		const flatCommands = this.getCommandsArray();
+		const treeNodes = Array.from(((_this$commandkit$comm = this.commandkit.commandsRouter) === null || _this$commandkit$comm === void 0 ? void 0 : _this$commandkit$comm.getData().treeNodes.values()) ?? []);
+		const hierarchicalRoots = treeNodes.filter((n) => n.kind === "command" && n.source !== "root");
+		const totalCount = flatCommands.length + hierarchicalRoots.length;
+		console.log(require_utils_colors.default.green(`Loaded ${require_utils_colors.default.magenta(totalCount.toString())} commands:`));
+		const printHierarchicalNode = (nodeId, prefix, indent) => {
+			const node = treeNodes.find((n) => n.id === nodeId);
+			if (!node || node.kind === "root") return;
+			const loadedNode = this.hierarchicalNodes.get(nodeId);
+			const hasMw = loadedNode && loadedNode.command.middlewares.length > 0 ? require_utils_colors.default.magenta(" (λ)") : "";
+			const kindLabel = node.kind === "group" ? require_utils_colors.default.cyan(` [group]`) : node.kind === "command" ? "" : "";
+			console.log(`${require_utils_colors.default.green(prefix)} ${require_utils_colors.default.yellow(node.token)}${kindLabel}${hasMw}`);
+			const children = node.childIds;
+			children.forEach((childId, idx) => {
+				const isLastChild = idx === children.length - 1;
+				printHierarchicalNode(childId, indent + (isLastChild ? "└─" : "├─"), indent + (isLastChild ? "   " : "│  "));
+			});
+		};
+		const categoryBuckets = {};
+		const ensureBucket = (cat) => {
+			categoryBuckets[cat] ??= {
+				flat: [],
+				hierarchical: []
+			};
+		};
+		for (const cmd of flatCommands) {
+			const cat = cmd.command.category || uncategorized;
+			ensureBucket(cat);
+			categoryBuckets[cat].flat.push(cmd);
+		}
+		for (const root of hierarchicalRoots) {
+			const cat = root.category || uncategorized;
+			ensureBucket(cat);
+			categoryBuckets[cat].hierarchical.push(root);
+		}
+		const categories = Object.keys(categoryBuckets).sort();
 		const categoryTree = {};
 		categories.forEach((category) => {
-			if (category === uncategorized) return;
-			if (category.includes(":")) {
-				const parts = category.split(":");
-				let bestParent = null;
-				for (let i = parts.length - 1; i > 0; i--) {
-					const potentialParent = parts.slice(0, i).join(":");
-					if (categories.includes(potentialParent)) {
-						bestParent = potentialParent;
-						break;
-					}
-				}
-				if (bestParent) {
-					categoryTree[bestParent] = categoryTree[bestParent] || [];
-					categoryTree[bestParent].push(category);
+			if (category === uncategorized || !category.includes(":")) return;
+			const parts = category.split(":");
+			for (let i = parts.length - 1; i > 0; i--) {
+				const potentialParent = parts.slice(0, i).join(":");
+				if (categories.includes(potentialParent)) {
+					categoryTree[potentialParent] ??= [];
+					categoryTree[potentialParent].push(category);
+					break;
 				}
 			}
 		});
@@ -2323,20 +2492,37 @@ var AppCommandHandler = class {
 		const printCategory = (category, indent = "", isLast = false, parentPrefix = "") => {
 			if (processedCategories.has(category)) return;
 			processedCategories.add(category);
-			const commands = categorizedCommands[category];
+			const bucket = categoryBuckets[category];
 			const hasChildren = categoryTree[category] && categoryTree[category].length > 0;
+			const allEntries = [...bucket.flat, ...bucket.hierarchical];
 			const thisPrefix = isLast ? "└─" : "├─";
 			const childIndent = parentPrefix + (isLast ? "   " : "│  ");
 			if (category !== uncategorized) {
 				const displayName = category.includes(":") ? category.split(":").pop() : category;
 				console.log(require_utils_colors.default.cyan(`${indent}${thisPrefix} ${require_utils_colors.default.bold(displayName)}`));
 			}
-			commands.forEach((cmd, cmdIndex) => {
-				const cmdPrefix = cmdIndex === commands.length - 1 && !hasChildren ? "└─" : "├─";
-				const cmdIndent = category !== uncategorized ? childIndent : indent;
+			const cmdIndent = category !== uncategorized ? childIndent : indent;
+			const totalEntries = allEntries.length;
+			let entryIndex = 0;
+			bucket.flat.forEach((cmd) => {
+				const cmdPrefix = entryIndex === totalEntries - 1 && !hasChildren ? "└─" : "├─";
 				const name = cmd.data.command.name;
 				const middlewareIcon = cmd.command.middlewares.length > 0 ? require_utils_colors.default.magenta(" (λ)") : "";
 				console.log(`${require_utils_colors.default.green(`${cmdIndent}${cmdPrefix}`)} ${require_utils_colors.default.yellow(name)}${middlewareIcon}`);
+				entryIndex++;
+			});
+			bucket.hierarchical.forEach((root) => {
+				const isLastEntry = entryIndex === totalEntries - 1 && !hasChildren;
+				const rootPrefix = cmdIndent + (isLastEntry ? "└─" : "├─");
+				const rootChildIndent = cmdIndent + (isLastEntry ? "   " : "│  ");
+				const loadedNode = this.hierarchicalNodes.get(root.id);
+				const hasMw = loadedNode && loadedNode.command.middlewares.length > 0 ? require_utils_colors.default.magenta(" (λ)") : "";
+				console.log(`${require_utils_colors.default.green(rootPrefix)} ${require_utils_colors.default.yellow(root.token)}${hasMw}`);
+				root.childIds.forEach((childId, idx) => {
+					const isLastChild = idx === root.childIds.length - 1;
+					printHierarchicalNode(childId, rootChildIndent + (isLastChild ? "└─" : "├─"), rootChildIndent + (isLastChild ? "   " : "│  "));
+				});
+				entryIndex++;
 			});
 			if (hasChildren) {
 				const children = categoryTree[category].sort();
@@ -2369,6 +2555,20 @@ var AppCommandHandler = class {
 		return Array.from(this.loadedCommands.values());
 	}
 	/**
+	* Gets all executable runtime routes, including hierarchical leaves.
+	* @returns Array of route-indexed commands
+	*/
+	getRuntimeCommandsArray() {
+		return Array.from(this.runtimeRouteIndex.values());
+	}
+	/**
+	* Gets loaded hierarchical command nodes, including non-executable containers.
+	* @returns Array of hierarchical node definitions
+	*/
+	getHierarchicalNodesArray() {
+		return Array.from(this.hierarchicalNodes.values());
+	}
+	/**
 	* Registers event handlers for Discord interactions and messages.
 	*/
 	registerCommandHandler() {
@@ -2394,6 +2594,35 @@ var AppCommandHandler = class {
 		this.commandkit.client.on(discord_js.Events.MessageCreate, this.onMessageCreate);
 	}
 	/**
+	* @private
+	* @internal
+	*/
+	normalizeRouteKey(input) {
+		return input.trim().replace(/[.:]/g, " ").split(/\s+/).filter(Boolean).join(".");
+	}
+	/**
+	* @private
+	* @internal
+	*/
+	buildInteractionRouteKey(source) {
+		if (!source.isCommand() && !source.isAutocomplete()) return "";
+		const segments = [source.commandName];
+		if (source.isChatInputCommand() || source.isAutocomplete()) {
+			const group = source.options.getSubcommandGroup(false);
+			const subcommand = source.options.getSubcommand(false);
+			if (group) segments.push(group);
+			if (subcommand) segments.push(subcommand);
+		}
+		return segments.filter(Boolean).join(".");
+	}
+	/**
+	* @private
+	* @internal
+	*/
+	buildMessageRouteKey(parser) {
+		return parser.getFullRoute().join(".");
+	}
+	/**
 	* Prepares a command for execution by resolving the command and its middleware.
 	* @param source - The interaction or message that triggered the command
 	* @param cmdName - Optional command name override
@@ -2403,13 +2632,19 @@ var AppCommandHandler = class {
 		var _loadedCommand$metada3, _loadedCommand$metada4;
 		if (getConfig().disablePrefixCommands && source instanceof discord_js.Message) return null;
 		let parser;
-		if (!cmdName) if (source instanceof discord_js.Message) {
+		let routeKey;
+		let usedCommandOverride = false;
+		if (cmdName) {
+			routeKey = this.normalizeRouteKey(cmdName);
+			usedCommandOverride = true;
+		}
+		if (!routeKey) if (source instanceof discord_js.Message) {
 			if (source.author.bot) return null;
 			const prefix = await this.commandkit.appConfig.getMessageCommandPrefix(source);
 			if (!prefix || (typeof prefix === "string" || Array.isArray(prefix)) && !prefix.length) return null;
 			parser = new require_app_commands_MessageCommandParser.MessageCommandParser(source, prefix instanceof RegExp ? prefix : Array.isArray(prefix) ? prefix : [prefix], (command) => {
 				var _loadedCommand$metada, _loadedCommand$metada2, _json$options;
-				const loadedCommand = this.findCommandByName(command);
+				const loadedCommand = this.findCommandByRoute(command);
 				if (!loadedCommand) {
 					if (require_utils_constants.COMMANDKIT_IS_DEV && this.commandkit.config.showUnknownPrefixCommandsWarning) Logger.error`Prefix command "${command}" was not found.\nNote: This warning is only shown in development mode as an alert to help you find the command. If you wish to remove this warning, set \`showUnknownPrefixCommandsWarning\` to \`false\` in your commandkit config.`;
 					return null;
@@ -2421,7 +2656,7 @@ var AppCommandHandler = class {
 				}, {})) ?? {};
 			});
 			try {
-				cmdName = parser.getFullCommand().split(" ")[0];
+				routeKey = this.buildMessageRouteKey(parser);
 			} catch (e) {
 				if (require_utils_error_codes.isErrorType(e, require_utils_error_codes.CommandKitErrorCodes.InvalidCommandPrefix)) return null;
 				Logger.error`${e}`;
@@ -2429,10 +2664,10 @@ var AppCommandHandler = class {
 			}
 		} else {
 			if (!(source.isChatInputCommand() || source.isAutocomplete() || source.isContextMenuCommand())) return null;
-			cmdName = source.commandName;
+			routeKey = this.buildInteractionRouteKey(source);
 		}
 		const hint = require_app_commands_helpers.isInteractionSource(source) ? source.isUserContextMenuCommand() ? "user" : source.isMessageContextMenuCommand() ? "message" : void 0 : void 0;
-		const loadedCommand = this.findCommandByName(cmdName, hint);
+		const loadedCommand = hint ? this.findCommandByName(routeKey, hint) : this.findCommandByRoute(routeKey, usedCommandOverride);
 		if (!loadedCommand) return null;
 		if ((source instanceof discord_js.CommandInteraction || source instanceof discord_js.AutocompleteInteraction) && source.guildId && ((_loadedCommand$metada3 = loadedCommand.metadata) === null || _loadedCommand$metada3 === void 0 || (_loadedCommand$metada3 = _loadedCommand$metada3.guilds) === null || _loadedCommand$metada3 === void 0 ? void 0 : _loadedCommand$metada3.length) && !((_loadedCommand$metada4 = loadedCommand.metadata) === null || _loadedCommand$metada4 === void 0 ? void 0 : _loadedCommand$metada4.guilds.includes(source.guildId))) return null;
 		if (source instanceof discord_js.Message) {
@@ -2483,21 +2718,46 @@ var AppCommandHandler = class {
 		}
 		return null;
 	}
-	resolveMessageCommandName(name) {
-		for (const [, loadedCommand] of this.loadedCommands) {
+	/**
+	* Finds a command by its canonical route key.
+	* @param route - The command route or command name
+	* @param allowFlatAliasFallback - Whether to check flat aliases if the route key was not found
+	* @returns The loaded command or null if not found
+	*/
+	findCommandByRoute(route, allowFlatAliasFallback = true) {
+		const normalizedRoute = this.normalizeRouteKey(route);
+		const directMatch = this.runtimeRouteIndex.get(normalizedRoute);
+		if (directMatch) return directMatch;
+		if (!allowFlatAliasFallback || normalizedRoute.includes(".")) return null;
+		for (const loadedCommand of this.runtimeRouteIndex.values()) {
 			var _loadedCommand$data$m3;
-			if (loadedCommand.data.command.name === name) return loadedCommand.data.command.name;
 			const aliases = (_loadedCommand$data$m3 = loadedCommand.data.metadata) === null || _loadedCommand$data$m3 === void 0 ? void 0 : _loadedCommand$data$m3.aliases;
-			if (aliases && Array.isArray(aliases) && aliases.includes(name)) return loadedCommand.data.command.name;
+			if (aliases && Array.isArray(aliases) && aliases.includes(normalizedRoute)) return loadedCommand;
 		}
+		return null;
+	}
+	/**
+	* @private
+	* @internal
+	*/
+	getRouteKeyFor(command) {
+		return command.data.command.__routeKey ?? this.normalizeRouteKey(command.data.command.name);
+	}
+	resolveMessageCommandName(name) {
+		const loadedCommand = this.findCommandByRoute(name);
+		if (loadedCommand) return this.getRouteKeyFor(loadedCommand);
 		return name;
 	}
 	/**
 	* Reloads all commands and middleware from scratch.
 	*/
 	async reloadCommands() {
+		var _this$commandkit$comm2;
+		await ((_this$commandkit$comm2 = this.commandkit.commandsRouter) === null || _this$commandkit$comm2 === void 0 ? void 0 : _this$commandkit$comm2.scan());
 		this.loadedCommands.clear();
 		this.loadedMiddlewares.clear();
+		this.runtimeRouteIndex.clear();
+		this.hierarchicalNodes.clear();
 		this.externalCommandData.clear();
 		this.externalMiddlewareData.clear();
 		await this.loadCommands();
@@ -2534,7 +2794,10 @@ var AppCommandHandler = class {
 	* @param data - Array of loaded commands to register
 	*/
 	async registerExternalLoadedCommands(data) {
-		for (const command of data) this.loadedCommands.set(command.command.id, command);
+		for (const command of data) {
+			this.loadedCommands.set(command.command.id, command);
+			this.registerRuntimeRoute(command);
+		}
 	}
 	/**
 	* Loads all commands and middleware from the router.
@@ -2545,15 +2808,20 @@ var AppCommandHandler = class {
 		});
 		const commandsRouter = this.commandkit.commandsRouter;
 		if (!commandsRouter) throw new Error("Commands router has not yet initialized");
-		const { commands, middlewares } = commandsRouter.getData();
+		const { commands, middlewares, treeNodes, compiledRoutes } = commandsRouter.getData();
 		const combinedCommands = this.externalCommandData.size ? commands.concat(this.externalCommandData) : commands;
 		const combinedMiddlewares = this.externalMiddlewareData.size ? middlewares.concat(this.externalMiddlewareData) : middlewares;
 		for (const [id, middleware] of combinedMiddlewares) await this.loadMiddleware(id, middleware);
 		for (const [id, command] of combinedCommands) await this.loadCommand(id, command);
+		const hierarchicalNodes = Array.from(treeNodes.values()).filter((node) => node.source !== "flat" && !!node.definitionPath).sort((left, right) => left.route.length - right.route.length);
+		for (const node of hierarchicalNodes) {
+			const routeKey = node.route.join(".");
+			await this.loadHierarchicalNode(node, compiledRoutes.get(routeKey) ?? void 0);
+		}
 		if (require_utils_constants.COMMANDKIT_IS_DEV) {
-			const commandNames = Array.from(this.loadedCommands.values()).map((v) => v.data.command.name);
-			const aliases = Array.from(this.loadedCommands.values()).flatMap((v) => v.metadata.aliases || []);
-			await require_utils_types_package.rewriteCommandDeclaration(`type CommandTypeData = ${[...commandNames, ...aliases].map((name) => JSON.stringify(name)).join(" | ")}`);
+			const commandNames = Array.from(this.runtimeRouteIndex.keys());
+			const aliases = Array.from(this.runtimeRouteIndex.values()).flatMap((v) => v.metadata.aliases || []);
+			await require_utils_types_package.rewriteCommandDeclaration(`type CommandTypeData = ${Array.from(new Set([...commandNames, ...aliases])).map((name) => JSON.stringify(name)).join(" | ")}`);
 		}
 		await this.commandkit.plugins.execute((ctx, plugin) => {
 			return plugin.onAfterCommandsLoad(ctx);
@@ -2584,10 +2852,84 @@ var AppCommandHandler = class {
 	* @private
 	* @internal
 	*/
+	shouldIndexAsRuntimeRoute(command) {
+		return !!(command.data.chatInput || command.data.message || command.data.autocomplete);
+	}
+	/**
+	* @private
+	* @internal
+	*/
+	registerRuntimeRoute(command, routeKey) {
+		if (!this.shouldIndexAsRuntimeRoute(command)) return;
+		const key = this.normalizeRouteKey(routeKey ?? command.data.command.name);
+		if (!key) return;
+		const commandData = command.data.command;
+		commandData.__routeKey ??= key;
+		this.runtimeRouteIndex.set(key, command);
+	}
+	/**
+	* @private
+	* @internal
+	*/
+	async processCommandFile(fileUrl, identifier, fallbackName, isHierarchical) {
+		const commandFileData = await import(`${require_utils_resolve_file_url.toFileURL(fileUrl)}?t=${Date.now()}`);
+		if (!commandFileData.command) throw new Error(`Invalid export for ${isHierarchical ? "hierarchical node" : "command"} ${identifier}: no command definition found`);
+		const metadataFunc = commandFileData.generateMetadata;
+		const metadataObj = commandFileData.metadata;
+		if (metadataFunc && metadataObj) throw new Error("A command may only export either `generateMetadata` or `metadata`, not both");
+		const metadata = (metadataFunc ? await metadataFunc() : metadataObj) ?? {
+			aliases: [],
+			guilds: [],
+			userPermissions: [],
+			botPermissions: []
+		};
+		let commandName = commandFileData.command.name;
+		if (isHierarchical) {
+			if (typeof commandName === "string" && commandName !== fallbackName) Logger.warn(`Hierarchical node \`${identifier}\` overrides its command name with \`${commandName}\`. The filesystem token \`${fallbackName}\` will be used instead.`);
+			commandName = fallbackName;
+		} else commandName = commandName || fallbackName;
+		let commandDescription = commandFileData.command.description;
+		if (!commandDescription && commandFileData.chatInput) commandDescription = "No command description set.";
+		const updatedCommandData = {
+			...commandFileData.command,
+			name: commandName,
+			description: commandDescription
+		};
+		let handlerCount = 0;
+		for (const [key, propValidator] of Object.entries(commandDataSchema)) {
+			const exportedProp = commandFileData[key];
+			if (exportedProp) {
+				if (!await propValidator(exportedProp)) throw new Error(`Invalid export for ${isHierarchical ? "hierarchical node" : "command"} ${identifier}: ${key} does not match expected value`);
+				if (!KNOWN_NON_HANDLER_KEYS.includes(key)) handlerCount++;
+			}
+		}
+		let lastUpdated = updatedCommandData;
+		await this.commandkit.plugins.execute(async (ctx, plugin) => {
+			const res = await plugin.prepareCommand(ctx, lastUpdated);
+			if (res) lastUpdated = res;
+		});
+		const commandJson = "toJSON" in lastUpdated && typeof lastUpdated.toJSON === "function" ? lastUpdated.toJSON() : lastUpdated;
+		if ("guilds" in commandJson || "aliases" in commandJson) Logger.warn(`Command \`${identifier}\` uses deprecated metadata properties. Please update to use the new \`metadata\` object or \`generateMetadata\` function.`);
+		const resolvedMetadata = {
+			guilds: commandJson.guilds,
+			aliases: commandJson.aliases,
+			...metadata
+		};
+		return {
+			commandFileData,
+			handlerCount,
+			commandJson,
+			resolvedMetadata
+		};
+	}
+	/**
+	* @private
+	* @internal
+	*/
 	async loadCommand(id, command) {
 		try {
 			if (command.path === null) {
-				this.loadedCommands.set(id, {
+				const loadedCommand = {
 					discordId: null,
 					command,
 					metadata: {
@@ -2597,50 +2939,14 @@ var AppCommandHandler = class {
 						botPermissions: []
 					},
 					data: { command: { name: command.name } }
-				});
+				};
+				this.loadedCommands.set(id, loadedCommand);
+				this.registerRuntimeRoute(loadedCommand);
 				return;
 			}
-			const commandFileData = await import(`${require_utils_resolve_file_url.toFileURL(command.path)}?t=${Date.now()}`);
-			if (!commandFileData.command) throw new Error(`Invalid export for command ${command.name}: no command definition found`);
-			const metadataFunc = commandFileData.generateMetadata;
-			const metadataObj = commandFileData.metadata;
-			if (metadataFunc && metadataObj) throw new Error("A command may only export either `generateMetadata` or `metadata`, not both");
-			const metadata = (metadataFunc ? await metadataFunc() : metadataObj) ?? {
-				aliases: [],
-				guilds: [],
-				userPermissions: [],
-				botPermissions: []
-			};
-			const commandName = commandFileData.command.name || command.name;
-			let commandDescription = commandFileData.command.description;
-			if (!commandDescription && commandFileData.chatInput) commandDescription = "No command description set.";
-			const updatedCommandData = {
-				...commandFileData.command,
-				name: commandName,
-				description: commandDescription
-			};
-			let handlerCount = 0;
-			for (const [key, propValidator] of Object.entries(commandDataSchema)) {
-				const exportedProp = commandFileData[key];
-				if (exportedProp) {
-					if (!await propValidator(exportedProp)) throw new Error(`Invalid export for command ${command.name}: ${key} does not match expected value`);
-					if (!KNOWN_NON_HANDLER_KEYS.includes(key)) handlerCount++;
-				}
-			}
+			const { commandFileData, handlerCount, commandJson, resolvedMetadata } = await this.processCommandFile(command.path, command.name, command.name, false);
 			if (handlerCount === 0) throw new Error(`Invalid export for command ${command.name}: at least one handler function must be provided`);
-			let lastUpdated = updatedCommandData;
-			await this.commandkit.plugins.execute(async (ctx, plugin) => {
-				const res = await plugin.prepareCommand(ctx, lastUpdated);
-				if (res) lastUpdated = res;
-			});
-			const commandJson = "toJSON" in lastUpdated && typeof lastUpdated.toJSON === "function" ? lastUpdated.toJSON() : lastUpdated;
-			if ("guilds" in commandJson || "aliases" in commandJson) Logger.warn(`Command \`${command.name}\` uses deprecated metadata properties. Please update to use the new \`metadata\` object or \`generateMetadata\` function.`);
-			const resolvedMetadata = {
-				guilds: commandJson.guilds,
-				aliases: commandJson.aliases,
-				...metadata
-			};
-			this.loadedCommands.set(id, {
+			const loadedCommand = {
 				discordId: null,
 				command,
 				metadata: resolvedMetadata,
@@ -2649,20 +2955,68 @@ var AppCommandHandler = class {
 					metadata: resolvedMetadata,
 					command: commandJson
 				}
-			});
+			};
+			this.loadedCommands.set(id, loadedCommand);
+			this.registerRuntimeRoute(loadedCommand);
 			this.generateContextMenuCommands(id, command, commandFileData, commandJson, resolvedMetadata);
 		} catch (error) {
 			Logger.error`Failed to load command ${command.name} (${id}): ${error}`;
 		}
 	}
 	/**
+	* Loads a hierarchical command node into the hierarchical cache.
+	* Executable leaves are also added to the runtime route index.
+	* @private
+	* @internal
+	*/
+	async loadHierarchicalNode(node, compiledRoute) {
+		if (!node.definitionPath) return;
+		const routeKey = node.route.join(".");
+		const command = {
+			id: node.id,
+			name: routeKey,
+			path: node.definitionPath,
+			relativePath: (compiledRoute === null || compiledRoute === void 0 ? void 0 : compiledRoute.relativePath) ?? node.relativePath,
+			parentPath: (0, node_path.dirname)(node.definitionPath),
+			middlewares: compiledRoute ? [...compiledRoute.middlewares] : [],
+			category: node.category
+		};
+		try {
+			const { commandFileData, handlerCount, commandJson, resolvedMetadata } = await this.processCommandFile(command.path, routeKey, node.token, true);
+			const isRootHierarchyLeaf = node.kind === "command";
+			const hasContextMenuHandlers = !!(commandFileData.userContextMenu || commandFileData.messageContextMenu);
+			const hasExecutableSlashHandlers = !!(commandFileData.chatInput || commandFileData.message || commandFileData.autocomplete);
+			if (!isRootHierarchyLeaf && hasContextMenuHandlers) throw new Error(`Invalid export for hierarchical node ${routeKey}: context menu handlers are only supported for top-level root commands.`);
+			if (node.executable && handlerCount === 0) throw new Error(`Invalid export for hierarchical node ${routeKey}: executable leaves must provide at least one handler function`);
+			if (!node.executable && hasExecutableSlashHandlers) throw new Error(`Invalid export for hierarchical node ${routeKey}: non-leaf hierarchical nodes cannot export executable slash/prefix handlers`);
+			const loadedCommand = {
+				discordId: null,
+				command,
+				metadata: resolvedMetadata,
+				data: {
+					...commandFileData,
+					metadata: resolvedMetadata,
+					command: {
+						...commandJson,
+						__routeKey: routeKey
+					}
+				}
+			};
+			this.hierarchicalNodes.set(node.id, loadedCommand);
+			if (node.executable) this.registerRuntimeRoute(loadedCommand, routeKey);
+			if (isRootHierarchyLeaf && hasContextMenuHandlers) this.generateContextMenuCommands(node.id, command, commandFileData, commandJson, resolvedMetadata);
+		} catch (error) {
+			Logger.error`Failed to load hierarchical node ${routeKey} (${node.id}): ${error}`;
+		}
+	}
+	/**
 	* Gets the metadata for a command.
 	* @param command - The command name to get metadata for
 	* @param hint - The hint for the command type (user or message)
 	* @returns The command metadata or null if not found
 	*/
 	getMetadataFor(command, hint) {
-		const loadedCommand = this.findCommandByName(command, hint);
+		const loadedCommand = hint ? this.findCommandByName(command, hint) : this.findCommandByRoute(command);
 		if (!loadedCommand) return null;
 		return loadedCommand.metadata ??= {
 			aliases: [],
@@ -3707,6 +4061,61 @@ function ChannelSelectMenu(props) {
 	return builder;
 }
 
+//#endregion
+//#region src/components/interactive/checkbox/checkbox.ts
+function Checkbox(props) {
+	const checkbox = new discord_js.CheckboxBuilder();
+	applyId(props, checkbox);
+	if (props.customId != null) checkbox.setCustomId(props.customId);
+	if (props.default != null) checkbox.setDefault(props.default);
+	return checkbox;
+}
+function CheckboxGroupOption(props) {
+	const option = new discord_js.CheckboxGroupOptionBuilder();
+	option.setLabel(props.label);
+	option.setValue(props.value);
+	if (props.description != null) option.setDescription(props.description);
+	if (props.default != null) option.setDefault(props.default);
+	return option;
+}
+function CheckboxGroup(props) {
+	const checkboxGroup = new discord_js.CheckboxGroupBuilder();
+	applyId(props, checkboxGroup);
+	if (props.customId != null) checkboxGroup.setCustomId(props.customId);
+	if (props.required != null) checkboxGroup.setRequired(props.required);
+	if (props.minValues != null) checkboxGroup.setMinValues(props.minValues);
+	if (props.maxValues != null) checkboxGroup.setMaxValues(props.maxValues);
+	if (props.children != null) {
+		const options = (Array.isArray(props.children) ? props.children : [props.children]).filter((option) => option != null);
+		if (options.length === 0) throw new Error("CheckboxGroup requires at least 1 option. Use <CheckboxGroupOption label=... value=... /> as a child.");
+		checkboxGroup.setOptions(options);
+	}
+	return checkboxGroup;
+}
+
+//#endregion
+//#region src/components/interactive/radio/radio.ts
+function RadioGroup(props) {
+	const radioGroup = new discord_js.RadioGroupBuilder();
+	applyId(props, radioGroup);
+	radioGroup.setCustomId(props.customId);
+	if (props.children != null) {
+		const options = (Array.isArray(props.children) ? props.children : [props.children]).filter((option) => option != null);
+		if (options.length === 0) throw new Error("RadioGroup requires at least 1 option. Use <RadioGroupOption label=... value=... /> as a child.");
+		radioGroup.setOptions(options);
+	}
+	if (props.required != null) radioGroup.setRequired(props.required);
+	return radioGroup;
+}
+function RadioGroupOption(props) {
+	const option = new discord_js.RadioGroupOptionBuilder();
+	option.setLabel(props.label);
+	option.setValue(props.value);
+	if (props.description != null) option.setDescription(props.description);
+	if (props.default != null) option.setDefault(props.default);
+	return option;
+}
+
 //#endregion
 //#region src/components/display/container.ts
 /**
@@ -4163,11 +4572,11 @@ function registerDevHooks(commandkit) {
 			if (prevented) return;
 			switch (event) {
 				case require_utils_constants.HMREventType.ReloadCommands:
-					commandkit.commandHandler.reloadCommands();
+					await commandkit.commandHandler.reloadCommands();
 					handled = true;
 					break;
 				case require_utils_constants.HMREventType.ReloadEvents:
-					commandkit.eventHandler.reloadEvents();
+					await commandkit.eventHandler.reloadEvents();
 					handled = true;
 					break;
 				case require_utils_constants.HMREventType.Unknown:
@@ -4670,6 +5079,24 @@ Object.defineProperty(exports, 'ChannelSelectMenuKit', {
     return ChannelSelectMenuKit;
   }
 });
+Object.defineProperty(exports, 'Checkbox', {
+  enumerable: true,
+  get: function () {
+    return Checkbox;
+  }
+});
+Object.defineProperty(exports, 'CheckboxGroup', {
+  enumerable: true,
+  get: function () {
+    return CheckboxGroup;
+  }
+});
+Object.defineProperty(exports, 'CheckboxGroupOption', {
+  enumerable: true,
+  get: function () {
+    return CheckboxGroupOption;
+  }
+});
 Object.defineProperty(exports, 'CommandExecutionMode', {
   enumerable: true,
   get: function () {
@@ -4832,6 +5259,18 @@ Object.defineProperty(exports, 'ParagraphInput', {
     return ParagraphInput;
   }
 });
+Object.defineProperty(exports, 'RadioGroup', {
+  enumerable: true,
+  get: function () {
+    return RadioGroup;
+  }
+});
+Object.defineProperty(exports, 'RadioGroupOption', {
+  enumerable: true,
+  get: function () {
+    return RadioGroupOption;
+  }
+});
 Object.defineProperty(exports, 'RoleSelectMenu', {
   enumerable: true,
   get: function () {
@@ -5144,4 +5583,4 @@ Object.defineProperty(exports, 'useStore', {
     return useStore;
   }
 });
-//# sourceMappingURL=commandkit-DNln6BAJ.js.map
+//# sourceMappingURL=commandkit-D2HMPuRQ.js.map