CMDkit Architecture TODO
Priority legend:
- P1 = High priority (fix soon)
- P2 = Medium priority
- P3 = Low priority
P1
[x] Remove shared-runtime coupling from root-level wrappers.
- Status: done. global_core was removed and wrappers now instantiate fresh CliCore runtimes per call.
- Scope: src/core.rs wrapper functions + root wrappers in src/lib.rs.
- Acceptance met: no shared process-global runtime is used for wrapper execution.
P2
[x] Decouple help binary name from process env args when running explicit arg dispatch.
- Status: done. help text is now generated from the caller-provided argv context and static help rendering.
- Scope: src/cli/help.rs + call path from src/core.rs try_run_from_args.
- Acceptance met: help text for explicit-args execution reflects provided argv context.
[x] Relax initializer contract to support fallible and configurable registration.
- Status: done via closure-based initializer API.
- Scope: src/core.rs run_with_initializers/try_run_with_initializers APIs.
- Acceptance met: supports closure-based registration (`F: Fn() -> Functionality`) and chained registration via `register` returning self.
[x] Add tests for wrapper/global behavior.
- Status: done. Added subprocess-based coverage that exercises root wrappers repeatedly and verifies no state is shared across calls.
- Scope: tests/ dedicated wrapper behavior coverage + helper binary for probe execution.
- Acceptance met: tests demonstrate and lock expected semantics across repeated calls.
P3
[x] Revisit public visibility of FunctionalityRegistry methods and type purpose.
- Status: done by making FunctionalityRegistry and its constructor crate-internal.
- Scope: src/cli.rs FunctionalityRegistry.
- Acceptance met: registry is now fully internal and no longer appears as a confusing partial public API.
[x] Decide and document lock-poisoning policy.
- Status: done. Added configurable `LockPoisonPolicy` with default `FailFast` and optional `Recover` behavior.
- Scope: src/core.rs lock handling + public configuration API.
- Acceptance met: policy is explicit in docs and code paths; lock retrieval now fails fast by default unless user opts into recovery.
[x] Add explicit test for help text behavior in try_run_from_args context.
- Status: done. Added dedicated tests for missing and unknown command paths using explicit caller argv.
- Scope: tests/clicore_suite.rs
- Acceptance met: tests assert usage/help text includes the caller-provided binary name.
[x] Allow for nested Function so that CLIStrategies can hold other Strategies.
- Status: done via hierarchical Functionality children + longest-path dispatch + child retrieval API.
- Scope: src/cli.rs src/core.rs tests/
- Acceptance met: nested path commands (for example: CMDkit test all) resolve and execute correctly from tree registration without duplicating strategies.
[x] Allow for options and flags being passed to further alter the functionality of the CLI.
- Status: done. Strategy execution now receives parsed `options`, `arguments`, and `subcommands`, and command execution parses flag/value pairs before dispatching nested commands.
- Problem: trailing args were forwarded raw; there was no built-in option/flag interpretation contract.
- Scope: src/cli.rs public API + src/core.rs dispatch + cmdkit-macros/ + tests/
- Acceptance: a stable strategy-facing parsed contract exists and nested dispatch coverage validates flag/value parsing plus subcommand boundaries.
Architecture re-evaluation (2026-05-27)
P1
[x] Align README and public examples with current API surface.
- Status: done. README and public docs now describe the flat command model, strategy-owned chaining, `CoreConfig`, and pluggable `HelpRenderer`.
- Scope: README.md + example snippets in docs/comments.
- Acceptance met: examples align with current APIs (`Command`, `CommandMetaData`, `CommandStrategy`, `CoreConfig`, macro usage) and stale trait methods were removed.
[x] Introduce a forward-compatible runtime configuration object.
- Status: done. `CoreConfig` is now the runtime-owned config object, injected at `CliCore::create(...)` time, with `CliCore::new()` preserved as the backward-compatible default constructor.
- Scope: src/core.rs public API (`CliCore` construction/configuration) + tests.
- Acceptance met: runtime configuration is no longer scattered across ad hoc setters, and changing config requires constructing a new `CliCore`.
[x] Naming lacks in precision the User might not understand what Functionality is and why he needs it
- Status: done. Renamed `Functionality`/`CommandSpec` usage to explicit `Command` + `CommandMetaData`, and updated APIs/tests accordingly.
- Scope: src/cli.rs + src/core.rs + src/lib.rs + tests/
- Acceptance met: command intent is explicit at type level and metadata fields are grouped into `CommandMetaData`.
P2
[x] Define and test strategy-facing token semantics for chained command arguments.
- Problem: command routing is intentionally first-token only; strategy-level chaining behavior and token contracts should be documented explicitly for consumers.
- Status: done. Documented explicit argv forwarding/boundary rules in README and core docs, and added edge-case tests for subcommand-boundary parsing ownership.
- Scope: README.md + src/core.rs docs + tests/clicore_suite.rs.
- Acceptance: explicit documented rule for `argv[2..]` forwarding and edge-case tests for strategy-owned subtask interpretation.
[x] Add optional recursive subcommand catalogs for help rendering.
- Status: done. `FallbackSubcommandStrategy` now exposes a merged catalog so nested help traversal can see wrapped subcommand trees.
- Problem: renderer needs deep subcommand visibility without forcing every strategy to implement help methods.
- Scope: src/cli.rs strategy capability + src/core.rs renderer traversal + tests/clicore_suite.rs.
- Acceptance: recursive subcommand chains are discoverable for help output while `CommandStrategy::execute` remains the only required strategy method.
[x] Improve help rendering.
- Problem: default help output is plain text and currently surfaces only command name/description.
- Status: done. Plain-text help now includes optional metadata fields (usage, long description, examples, switches, arguments, aliases) and has stable test coverage for output formatting.
- Scope: src/core.rs `PlainTextHelpRenderer` + tests.
- Acceptance: renderer output can include optional metadata fields (`usage`, `long_description`, `examples`, `options`, `aliases`) with stable formatting tests.
P3
[x] Remove or replace dead registration helper path.
- Status: done by removing the dead `register_function` helper from runtime internals.
- Scope: src/core.rs.
- Acceptance met: no ambiguous unused fallible-registration path remains in the codebase.
[x] Revisit Argument Parser in order to use arguments declared on the CommandMetaData. Arguments provide a setter and a required flag.
All required Arguments must not be empty after parsing.
- Status: done. Parser is metadata-driven, rejects unknown flags, respects aliases, enforces required non-empty arguments, and keeps last value for repeated arguments.
- Problem: Current argument parser parses against available or declared arguments and switches but does not respect argument metadata such as required.
Further more the argument parsing algorithm is more complex than it should be as we should be able to find all available Arguments in the metadata and only need to populate the setters.
- Scope src/cli/command.rs
- Acceptance:
1. Argument Parser is reworked to use metadata values rather creating new Arguments.
2. All tests pass