Unify Command Metadata and Registration via Declarative Command Factory #28
Description
Summary
The current command system in Hatchling (and related projects) suffers from redundancy and maintainability issues due to the separation of command metadata (names, descriptions, arguments, etc.) and their implementation. Since language support was introduced in commit 9f85af02b594f0b820f98e8ff8f32a19b2cca51b and stabilized in commit fc54e2504de5dade556321296c17ec01d45ba7a6, command metadata is now duplicated between Python code (e.g., _register_commands methods) and translation files (en.toml, fr.toml, etc.).
Problem
- Duplication: Command names, descriptions, and argument help are defined both in Python and in translation files.
- Maintenance Burden: Adding or updating commands requires changes in multiple places, increasing the risk of inconsistencies.
- Scalability: As the command set grows (especially with multi-language support), this approach will become increasingly difficult to maintain.
- Integration: The MCP server package manager in Hatch also relies on CLI for its frontend, and would benefit from a unified command definition system.
Proposal
- Declarative Command Factory: Implement a system to register all commands at startup from a single source of truth (e.g., TOML/YAML/JSON files).
- Handler Binding: Standardize a way to link command definitions in files to their Python handler implementations (e.g., via a
"handler": "module:function"convention or explicit registration). - Extraction: Extract this command factory/registry into a standalone package, so that both Hatch and Hatchling can share command definitions and reduce integration work.
- Overrides: Allow for per-app or per-context overrides (e.g., for styling, argument completion, or async/sync behavior).
- Validation: Enable static analysis and validation of command schemas and translations.
Benefits
- Single Source of Truth: All command metadata (including i18n) is defined in one place.
- Consistency: Reduces the risk of mismatches between code and documentation/help output.
- Reusability: Shared command definitions between CLI, chat, and potentially REST APIs.
- Community Contribution: Easier for contributors to add new commands or translations.
- Documentation: Enables auto-generation of help and user documentation.
Open Questions
- What is the best way to map file-based command definitions to Python handler functions?
- How should overrides (e.g., for styling or advanced argument completion) be handled?
- What migration path should we provide for existing commands?