legacy-command-client-keeper

name	legacy-command-client-keeper
description	Maintain the optional prefix-command layer — DiscordCommandClient, Command class, parsing, aliases, cooldowns, and help system. Use when touching message-based command handling.

Skill: legacy-command-client-keeper

Use this skill when work touches:

• src/Discord/DiscordCommandClient.php
• src/Discord/CommandClient/Command.php

This is optional-prefix-command skill. Load it when maintaining the message-command layer built on top of core Discord.

Goal

Keep prefix-command behavior as a clean optional layer:

• built on top of Discord
• driven by message events
• owning its own parsing, aliases, subcommands, cooldowns, and help behavior
• separate from application-command interaction flow

Read in this order

1. src/Discord/DiscordCommandClient.php
2. src/Discord/CommandClient/Command.php
3. Example or guide material using command client, if public behavior changes
4. Interaction command path only if change risks cross-layer leakage:
   • src/Discord/Helpers/RegisteredCommand.php
   • src/Discord/WebSockets/Events/InteractionCreate.php

Core contract

DiscordCommandClient extends Discord, but it does not replace core client architecture. It layers:

• command-specific options
• prefix detection
• alias maps
• command registry
• default help command
• message event routing into command callbacks

The command layer should stay optional and message-driven.

Main responsibilities by class

DiscordCommandClient

Owns:

• command-client option resolution
• wiring message event listeners during init
• prefix and mention-prefix expansion
• top-level command and alias registry
• default help command behavior

CommandClient\Command

Owns:

• one command's callback
• subcommand tree
• alias mapping for subcommands
• help metadata
• cooldown tracking and cooldown messaging

If code does not clearly belong to one of those two, re-check whether it belongs in core Discord instead.

Option rules

DiscordCommandClient uses OptionsResolver for its own layer. Preserve existing semantics around:

• prefix
• prefixes
• name
• description
• defaultHelpCommand
• discordOptions
• caseInsensitiveCommands
• internalRejectedPromiseHandler

Command-client options are not core runtime options. Keep them isolated unless a true cross-layer dependency exists.

Parsing rules

Message-command flow today:

1. command client listens on init
2. prefix strings get mention placeholders expanded
3. on message event, ignore self messages
4. checkForPrefix() strips prefix
5. args parsed via str_getcsv(..., ' ', '\"', '\\\\')
6. command name resolved through commands then aliases
7. command callback invoked
8. string return values become reply messages

If changing parsing, preserve expectations around:

• mention prefixes
• quoted arguments
• alias lookup
• case-insensitive mode

Help-system rules

The default help command is not incidental. It is part of command-client feature set.

Preserve:

• per-command descriptions and long descriptions
• usage text
• alias display
• subcommand display
• embed-based help formatting

If help behavior changes, inspect both top-level help and per-command help.

Cooldown and subcommand rules

CommandClient\Command carries its own operational semantics:

• cooldowns keyed by author id
• subcommands recurse
• alias lookup for subcommands
• help visibility controlled by option metadata

Do not move cooldown logic into unrelated core message or user models.

Boundaries with interaction commands

This layer is not the same as application commands.

Keep these separate:

• prefix commands use DiscordCommandClient + CommandClient\Command
• application commands use Discord::listenCommand() + RegisteredCommand + interaction events

Do not try to force one abstraction to power both unless you intend a broad architectural redesign.

Shared naming concepts are fine. Shared execution path is not current repo design.

Error-handling rules

Internal rejected promises use internalRejectedPromiseHandler. Preserve that pattern rather than sprinkling silent catches or inconsistent logger behavior through callbacks.

If user-facing callback returns string, reply behavior should remain simple and unsurprising.

Existing patterns worth copying

• top-level command registration through registerCommand()
• alias registration separated from command registration
• subcommand tree managed inside Command
• command options resolved once, then carried as help/cooldown metadata

Smells

Stop if you see:

• prefix-command concerns moving into Message, Channel, Discord, or interaction code
• alias or cooldown state stored outside command layer
• parsing changes that break quoted args or mention prefixes without explicit intent
• help system logic duplicated in multiple places
• interaction-command abstractions merged into prefix-command path

Checklist before commit

• command-client options still resolve cleanly
• prefix expansion and parsing still intentional
• command and alias registry behavior still coherent
• subcommand recursion still works
• cooldown behavior still belongs to command objects
• default help command still reflects command metadata
• no leakage into interaction command layer unless explicitly intended

Bottom line

Legacy command client is convenience layer, not core runtime. Keep it self-contained, predictable, and clearly separate from slash-command interactions.