feat: implement filesystem-based hierarchical subcommand routing (#623)

* feat: add hierarchical command proposal docs and initial test scaffolding for command parsing and routing

* feat: implement filesystem-based command router with tree-based path resolution and middleware support

* feat: implement hierarchical command routing and registration system with middleware support

* feat: implement hierarchical command structure with middleware tracing and demo utilities

* fromat & docs update

* chore: update path-to-regexp security override in package.json and lockfile

* feat: implement CommandsRouter for filesystem-based command and middleware discovery

* feat: implement AppCommandHandler and CommandsRouter for enhanced command management and routing

* feat: implement AppCommandHandler, CommandsRouter, and development CLI utilities for enhanced command management

* Refactor command handling system to dynamically support arbitrary subcommand nesting depth across parsers, handlers, and execution contexts.

* docs: update skills and operational guides to support hierarchical command discovery and routing conventions

* Fix command handler reloads, middleware scope, and docs

* Normalize generated docs and reject empty command bodies

- Normalize docs output line endings before writing
- Treat prefix-only message inputs as invalid command prefixes
- Update parser tests and generated API docs

---------

Co-authored-by: Twilight <46562212+twlite@users.noreply.github.com>

Author: AboMeezO

.github/workflows/code-quality.yaml

@@ -30,5 +30,11 @@ jobs:
       - name: Check TypeScript Types
         run: pnpm dlx turbo check-types
 
+      - name: Run CommandKit Command Handler Tests
+        run: pnpm test:commandkit
+
+      - name: Check Generated API Docs
+        run: pnpm docgen:check
+
       - name: Check Prettier Formatting
         run: pnpm prettier:check

AGENTS.md

@@ -37,7 +37,14 @@ preserve convention-based discovery:
 - Config file at root: `commandkit.config.ts` (or `.js`)
 - App entrypoint: `src/app.ts` (exports discord.js client)
 - Commands: `src/app/commands/**`
+- Hierarchical Discovery Tokens:
+  - `[command]` - top-level command directory
+  - `{group}` - subcommand group directory
+  - `(category)` - organizational category directory
+  - `command.ts` / `group.ts` - definition files
+  - `<name>.subcommand.ts` - subcommand shorthand
 - Events: `src/app/events/**`
+
 - Optional feature paths:
   - i18n: `src/app/locales/**`
   - tasks: `src/app/tasks/**`

apps/test-bot/src/app/commands/(general)/(animal)/cat.ts

@@ -28,6 +28,7 @@ export const command: CommandData = {
 export const metadata: CommandMetadata = {
   nameAliases: {
     message: 'Cat Message',
+    user: 'Cat User',
   },
 };
 

apps/test-bot/src/app/commands/(general)/help.ts

@@ -1,5 +1,6 @@
 import { CommandData, ChatInputCommand } from 'commandkit';
 import { redEmbedColor } from '@/feature-flags/red-embed-color';
+import { toMessageRoute, toSlashRoute } from '@/utils/hierarchical-demo';
 import { Colors } from 'discord.js';
 
 export const command: CommandData = {
@@ -34,11 +35,37 @@ export const chatInput: ChatInputCommand = async (ctx) => {
     })
     .join('\n');
 
+  const hierarchicalRoutes = ctx.commandkit.commandHandler
+    .getRuntimeCommandsArray()
+    .map((command) => {
+      return (
+        (command.data.command as Record<string, any>).__routeKey ??
+        command.data.command.name
+      );
+    })
+    .filter((route) => route.includes('.'))
+    .sort()
+    .map((route) => `${toSlashRoute(route)} | ${toMessageRoute(route)}`)
+    .join('\n');
+
   return interaction.editReply({
     embeds: [
       {
         title: 'Help',
         description: commands,
+        fields: hierarchicalRoutes
+          ? [
+              {
+                name: 'Hierarchical Routes',
+                value: hierarchicalRoutes,
+              },
+              {
+                name: 'Hierarchical Middleware',
+                value:
+                  'Global middleware always runs first. Hierarchical leaves then use only the current directory `+middleware` and any same-directory `+<command>.middleware`.',
+              },
+            ]
+          : undefined,
         footer: {
           text: `Bot Version: ${botVersion} | Shard ID ${interaction.guild?.shardId ?? 'N/A'}`,
         },

apps/test-bot/src/app/commands/(hierarchical)/+middleware.ts

@@ -0,0 +1,6 @@
+import { MiddlewareContext } from 'commandkit';
+import { recordHierarchyStage } from '@/utils/hierarchical-demo';
+
+export function beforeExecute(ctx: MiddlewareContext) {
+  recordHierarchyStage(ctx, 'category:(hierarchical)');
+}

apps/test-bot/src/app/commands/(hierarchical)/[ops]/+middleware.ts

@@ -0,0 +1,6 @@
+import { MiddlewareContext } from 'commandkit';
+import { recordHierarchyStage } from '@/utils/hierarchical-demo';
+
+export function beforeExecute(ctx: MiddlewareContext) {
+  recordHierarchyStage(ctx, 'root:ops');
+}

apps/test-bot/src/app/commands/(hierarchical)/[ops]/+status.middleware.ts

@@ -0,0 +1,6 @@
+import { MiddlewareContext } from 'commandkit';
+import { recordHierarchyStage } from '@/utils/hierarchical-demo';
+
+export function beforeExecute(ctx: MiddlewareContext) {
+  recordHierarchyStage(ctx, 'command:status');
+}

apps/test-bot/src/app/commands/(hierarchical)/[ops]/command.ts

@@ -0,0 +1,7 @@
+import { CommandData } from 'commandkit';
+
+export const command: CommandData = {
+  name: 'ops',
+  description:
+    'Direct-subcommand hierarchical root. Try /ops status or /ops deploy.',
+};

apps/test-bot/src/app/commands/(hierarchical)/[ops]/deploy/+middleware.ts

@@ -0,0 +1,6 @@
+import { MiddlewareContext } from 'commandkit';
+import { recordHierarchyStage } from '@/utils/hierarchical-demo';
+
+export function beforeExecute(ctx: MiddlewareContext) {
+  recordHierarchyStage(ctx, 'leaf-dir:deploy');
+}

apps/test-bot/src/app/commands/(hierarchical)/[ops]/deploy/deploy.subcommand.ts

@@ -0,0 +1,47 @@
+import { ApplicationCommandOptionType } from 'discord.js';
+import {
+  ChatInputCommandContext,
+  CommandData,
+  MessageCommandContext,
+} from 'commandkit';
+import { replyWithHierarchyDemo } from '@/utils/hierarchical-demo';
+
+export const command: CommandData = {
+  name: 'deploy',
+  description: 'Run a folder-based direct subcommand under the root.',
+  options: [
+    {
+      name: 'environment',
+      description: 'Where the deployment should go',
+      type: ApplicationCommandOptionType.String,
+      required: false,
+      choices: [
+        { name: 'staging', value: 'staging' },
+        { name: 'production', value: 'production' },
+      ],
+    },
+    {
+      name: 'dry_run',
+      description: 'Whether to simulate the deployment',
+      type: ApplicationCommandOptionType.Boolean,
+      required: false,
+    },
+  ],
+};
+
+async function execute(ctx: ChatInputCommandContext | MessageCommandContext) {
+  const environment = ctx.options.getString('environment') ?? 'staging';
+  const dryRun = ctx.options.getBoolean('dry_run') ?? true;
+
+  return replyWithHierarchyDemo(ctx, {
+    title: 'Ops Deploy',
+    shape: 'root command -> direct subcommand',
+    leafStyle: 'folder leaf ([deploy]/command.ts)',
+    summary:
+      'Shows a direct folder-based subcommand with middleware scoped only to the leaf directory, plus the same prefix route syntax.',
+    details: [`environment: ${environment}`, `dry_run: ${dryRun}`],
+  });
+}
+
+export const chatInput = execute;
+export const message = execute;