feat: implement filesystem-based hierarchical subcommand routing by AboMeezO · Pull Request #623 · neplextech/commandkit

AboMeezO · 2026-04-08T19:27:46Z

Summary

Introduces a filesystem-based routing system for Discord commands, enabling hierarchical subcommands and subcommand groups to be defined through directory structure. The system builds a CommandTree and resolves it into valid Discord application commands automatically.

This update improves modularity, scalability, and command organization while maintaining full backward compatibility with flat command structures.

Key Changes

Filesystem Router
- Added CommandsRouter to resolve directory structure into a command tree
- Introduced CommandTree to represent hierarchical command relationships
Command Registration
- Refactored AppCommandHandler to process hierarchical nodes
- Generates ApplicationCommandData from the resolved tree
- Includes diagnostic output for visualizing command structure
Middleware System
- Added support for +middleware.ts at the directory level
- Middleware is scoped and inherited by descendant commands only
Message Command Support
- Enhanced MessageCommandParser to support hierarchical command paths
- Maintains parity between slash commands and message-based commands
Testing & Examples
- Added comprehensive tests for routing, parsing, and command generation
- Included a full working example in the test-bot application

Impact

Fully backward compatible with existing flat commands
No breaking changes to current command handling
Hierarchical routing is opt-in and does not affect legacy structure

…ding for command parsing and routing

…resolution and middleware support

…with middleware support

…g and demo utilities

…ckfile

…eware discovery

…mand management and routing

…I utilities for enhanced command management

vercel · 2026-04-08T19:27:56Z

@AboMeezO is attempting to deploy a commit to the Neplex Team on Vercel.

A member of the Team first needs to authorize it.

…command nesting depth across parsers, handlers, and execution contexts.

…mmand discovery and routing conventions

vercel · 2026-04-09T01:56:22Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
commandkit	Ready	Preview, Comment	Apr 11, 2026 4:39am

Copilot

Pull request overview

Implements filesystem-based hierarchical routing for CommandKit commands, allowing [command]/{group}/<leaf> structures to be discovered, compiled into a command tree, and registered/executed consistently across slash + message commands.

Changes:

Added a command-tree model + router enhancements to discover/validate hierarchical structures and compile executable route keys with middleware chains.
Refactored command handling + registration to load hierarchical nodes, index executable leaves by route key, and emit correct Discord registration payloads.
Updated docs/examples/tests (including a test-bot demo) and CI to cover hierarchical routing, parsing, and registration behavior.

Reviewed changes

Copilot reviewed 83 out of 90 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
skills/commandkit/SKILL.md	Adds hierarchical-commands tag + description update.
skills/commandkit/references/08-file-naming-conventions.md	Documents new `[command]/{group}` + definition file conventions.
skills/commandkit/references/05-middlewares.md	Documents middleware variants + hierarchical scoping rules.
skills/commandkit/references/02-chat-input-command.md	Adds hierarchical command examples + clarifies handler context.
skills/commandkit/references/00-filesystem-structure.md	Adds “advanced” hierarchical filesystem structure section.
pnpm-lock.yaml	Lockfile updates (notably path-to-regexp resolution).
packages/commandkit/src/utils/utilities.ts	Updates debounce behavior to share promises across a debounce window.
packages/commandkit/src/utils/dev-hooks.ts	Awaits reload hooks for commands/events in dev HMR flow.
packages/commandkit/src/app/router/index.ts	Re-exports `CommandTree`.
packages/commandkit/src/app/router/CommandTree.ts	Introduces tree node/kind/source + compiled route/diagnostic types.
packages/commandkit/src/app/router/CommandsRouter.ts	Implements hierarchical filesystem discovery, diagnostics, and compiled route middleware chains.
packages/commandkit/src/app/register/CommandRegistrar.ts	Builds hierarchical slash payloads from cached tree nodes + sanitizes runtime-only fields.
packages/commandkit/src/app/handlers/AppCommandHandler.ts	Loads hierarchical nodes, indexes runtime routes, resolves message/interaction route keys, updates banner/type generation.
packages/commandkit/src/app/commands/MessageCommandParser.ts	Adds full route parsing for colon-delimited message commands.
packages/commandkit/src/app/commands/Context.ts	Returns canonical route identifier via `__routeKey` / full message route resolution.
packages/commandkit/src/app/commands/AppCommandRunner.ts	Uses canonical route key for env markers/logging.
packages/commandkit/spec/reload-commands.test.ts	Tests reload behavior across flat + hierarchical command additions/removals.
packages/commandkit/spec/message-command-parser.test.ts	Adds tests for hierarchical message route parsing.
packages/commandkit/spec/hierarchical-command-registration.test.ts	Tests Discord registration payload generation for hierarchical roots/leaves.
packages/commandkit/spec/hierarchical-command-handler.test.ts	Tests runtime loading/indexing and middleware chaining for hierarchical leaves.
packages/commandkit/spec/context-command-identifier.test.ts	Tests canonical identifier output across prefixes/aliases and hierarchy.
packages/commandkit/spec/commands-router.test.ts	Tests hierarchical discovery/diagnostics + compiled middleware chains.
package.json	Adds `docgen:check` and `test:commandkit`; adjusts pnpm override for path-to-regexp.
apps/website/docs/guide/08-advanced/02-file-naming-conventions.mdx	Updates guide to include hierarchical directories + middleware scoping explanations.
apps/website/docs/guide/02-commands/09-subcommand-hierarchy.mdx	New guide page describing filesystem-based subcommand hierarchy.
apps/website/docs/guide/02-commands/08-middlewares.mdx	Clarifies directory middleware scope (same-directory) + hierarchical leaf semantics.
apps/website/docs/guide/02-commands/07-category-directory.mdx	Adds note contrasting categories vs hierarchy.
apps/website/docs/api-reference/ratelimit/interfaces/rate-limit-hooks.mdx	Regenerated API docs formatting updates.
apps/website/docs/api-reference/ratelimit/functions/resolve-scope-keys.mdx	Regenerated API docs formatting updates.
apps/website/docs/api-reference/ratelimit/functions/ratelimit.mdx	Regenerated API docs formatting updates.
apps/website/docs/api-reference/ratelimit/functions/build-scope-prefix.mdx	Regenerated API docs formatting updates.
apps/website/docs/api-reference/commandkit/types/run-command.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/types/resolvable-command.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/types/message-command-options-schema.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/types/command-type-data.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/types/command-tree-node-source.mdx	New generated API doc for `CommandTreeNodeSource`.
apps/website/docs/api-reference/commandkit/types/command-tree-node-kind.mdx	New generated API doc for `CommandTreeNodeKind`.
apps/website/docs/api-reference/commandkit/types/command-builder-like.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/types/app-command.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/simple-proxy.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/prepared-app-command-execution.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/pre-register-commands-event.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/parsed-message-command.mdx	Adds `fullRoute` property to generated API docs.
apps/website/docs/api-reference/commandkit/interfaces/parsed-command-data.mdx	Adds treeNodes/compiledRoutes/diagnostics to generated API docs.
apps/website/docs/api-reference/commandkit/interfaces/middleware.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/loaded-command.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/custom-app-command-props.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/compiled-command-route.mdx	New generated API doc for compiled hierarchical routes.
apps/website/docs/api-reference/commandkit/interfaces/commands-router-options.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/command.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/interfaces/command-tree-node.mdx	New generated API doc for `CommandTreeNode`.
apps/website/docs/api-reference/commandkit/interfaces/command-route-diagnostic.mdx	New generated API doc for diagnostics.
apps/website/docs/api-reference/commandkit/interfaces/app-command-native.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/functions/no-build-only.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/functions/json-serialize.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/functions/dev-only.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/functions/defer.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/functions/create-proxy.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/functions/build-only.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/classes/middleware-context.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/classes/message-command-parser.mdx	Regenerated API docs to include `getFullRoute`.
apps/website/docs/api-reference/commandkit/classes/message-command-options.mdx	Regenerated API docs sourceLine updates.
apps/website/docs/api-reference/commandkit/classes/commands-router.mdx	Regenerated API docs to reflect new methods/return types.
apps/website/docs/api-reference/commandkit/classes/command-registrar.mdx	Regenerated API docs to reflect hierarchical registration.
apps/website/docs/api-reference/commandkit/classes/app-command-handler.mdx	Regenerated API docs to reflect runtime route APIs + async signatures.
apps/website/docs/api-reference/cache/interfaces/cache-context.mdx	Regenerated cache API docs.
apps/website/docs/api-reference/cache/functions/cache.mdx	Regenerated cache API docs.
apps/test-bot/src/utils/hierarchical-demo.ts	Adds demo utilities to visualize routes/middleware trace.
apps/test-bot/src/app/commands/(hierarchical)/+middleware.ts	Adds category-scoped middleware for hierarchical demo.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/command.ts	Adds `workspace` hierarchical root definition.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/+middleware.ts	Adds root middleware for `workspace`.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{team}/handoff.subcommand.ts	Adds shorthand leaf under second group branch.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{team}/group.ts	Adds `{team}` group definition.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{team}/+middleware.ts	Adds group middleware for `{team}`.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{notes}/group.ts	Adds `{notes}` group definition.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{notes}/archive/archive.subcommand.ts	Adds archive leaf demo.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{notes}/archive/+middleware.ts	Adds leaf-dir middleware for archive.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{notes}/add.subcommand.ts	Adds add leaf demo.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{notes}/+middleware.ts	Adds group middleware for `{notes}`.
apps/test-bot/src/app/commands/(hierarchical)/[workspace]/{notes}/+add.middleware.ts	Adds same-dir command-scoped middleware for `add`.
apps/test-bot/src/app/commands/(hierarchical)/[ops]/status.subcommand.ts	Adds direct shorthand subcommand demo.
apps/test-bot/src/app/commands/(hierarchical)/[ops]/deploy/deploy.subcommand.ts	Adds direct folder-leaf demo content.
apps/test-bot/src/app/commands/(hierarchical)/[ops]/deploy/+middleware.ts	Adds leaf-dir middleware for deploy.
apps/test-bot/src/app/commands/(hierarchical)/[ops]/command.ts	Adds `ops` hierarchical root definition.
apps/test-bot/src/app/commands/(hierarchical)/[ops]/+status.middleware.ts	Adds command-scoped middleware for status leaf.
apps/test-bot/src/app/commands/(hierarchical)/[ops]/+middleware.ts	Adds root middleware for `ops`.
apps/test-bot/src/app/commands/(general)/help.ts	Extends help output with hierarchical routes.
apps/test-bot/src/app/commands/(general)/(animal)/cat.ts	Updates context menu name aliases metadata.
AGENTS.md	Documents hierarchical discovery tokens for agents/contributors.
.github/workflows/code-quality.yaml	Adds CommandKit test + docgen:check steps to CI.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/commandkit/src/app/router/CommandsRouter.ts

packages/commandkit/src/app/commands/MessageCommandParser.ts

apps/website/docs/guide/02-commands/07-category-directory.mdx

apps/website/docs/api-reference/cache/interfaces/cache-context.mdx

apps/website/docs/api-reference/cache/functions/cache.mdx

package.json

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

twlite · 2026-04-11T07:22:03Z

@AboMeezO could you resolve the merge conflict?

AboMeezO added 9 commits April 8, 2026 04:48

feat: add hierarchical command proposal docs and initial test scaffol…

e95f8dc

…ding for command parsing and routing

feat: implement filesystem-based command router with tree-based path …

60308bc

…resolution and middleware support

feat: implement hierarchical command routing and registration system …

4d61d84

…with middleware support

feat: implement hierarchical command structure with middleware tracin…

37ee84e

…g and demo utilities

fromat & docs update

a47ae0e

chore: update path-to-regexp security override in package.json and lo…

faa3e11

…ckfile

feat: implement CommandsRouter for filesystem-based command and middl…

2a7ba24

…eware discovery

feat: implement AppCommandHandler and CommandsRouter for enhanced com…

0ea8a99

…mand management and routing

feat: implement AppCommandHandler, CommandsRouter, and development CL…

890150c

…I utilities for enhanced command management

AboMeezO added 3 commits April 8, 2026 22:47

Refactor command handling system to dynamically support arbitrary sub…

d89384f

…command nesting depth across parsers, handlers, and execution contexts.

docs: update skills and operational guides to support hierarchical co…

dad59a1

…mmand discovery and routing conventions

Fix command handler reloads, middleware scope, and docs

824e5e8

twlite requested a review from Copilot April 9, 2026 15:03

Copilot started reviewing on behalf of twlite April 9, 2026 15:04 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

Normalize generated docs and reject empty command bodies

4469fc3

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

vercel bot deployed to Preview April 11, 2026 04:39 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implement filesystem-based hierarchical subcommand routing#623

feat: implement filesystem-based hierarchical subcommand routing#623
AboMeezO wants to merge 13 commits intoneplextech:mainfrom
AboMeezO:CommandHandler2.0

AboMeezO commented Apr 8, 2026

Uh oh!

vercel bot commented Apr 8, 2026

Uh oh!

vercel bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

twlite commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

AboMeezO commented Apr 8, 2026

Summary

Key Changes

Impact

Uh oh!

vercel bot commented Apr 8, 2026

Uh oh!

vercel bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

twlite commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel bot commented Apr 9, 2026 •

edited

Loading