CLI-Core 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: cli-core 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
[ ] 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.
- 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.
[ ] Improve help rendering.
- Problem: default help output is plain text and currently surfaces only command name/description.
- 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.