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 CMDKit 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 `CMDKit::create(...)` time, with `CMDKit::new()` preserved as the backward-compatible default constructor.
    - Scope: src/core.rs public API (`CMDKit` construction/configuration) + tests.
    - Acceptance met: runtime configuration is no longer scattered across ad hoc setters, and changing config requires constructing a new `CMDKit`.

[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

Async runtime follow-up

P2
[ ] Add a config-level preflight phase to detect and apply overrides before dispatch.
    - Problem: runtime override intent (for example mode toggles or global switches) is currently mixed into normal dispatch input and is not resolved centrally before interpretation/execution.
    - Scope: src/core.rs CoreConfig + CMDKit::try_run_from_args + CMDKitMaster::try_run_from_args + tests/core tests + tests/clicore_suite.rs.
    - Acceptance: preflight runs before command dispatch, can normalize/filter args, can return runtime directives, and behavior is identical across CMDKit and CMDKitMaster paths.

[ ] Add an explicit shutdown/join lifecycle for CMDKitMaster workers.
    - Problem: worker threads are spawned, but the public API does not expose a clean way to stop them or wait for termination.
    - Scope: src/core.rs CMDKitMaster worker management + tests/core tests.
    - Acceptance: callers can close the executor, stop workers, and observe deterministic shutdown behavior without leaking background threads.

P3 
[ ] Align public naming and docs with the broader runtime model.
    - Problem: some user-facing wording still implies a CLI-only framing even though the crate now models general command dispatch and orchestration.
    - Scope: README.md + Cargo.toml metadata + public API docs in src/lib.rs and src/core.rs.
    - Acceptance: public docs and metadata describe the runtime consistently without over-constraining the use case to CLI-only workflows.

P4 (Optional)
[ ] Wrap the execution handle in a more ergonomic awaitable type.
    - Problem: the public handle currently exposes the underlying oneshot result shape, which is correct but a bit awkward for callers.
    - Scope: src/core.rs public async handle API + lib exports + tests.
    - Acceptance: callers can await a single-layer result type or helper wrapper without manually handling the internal oneshot cancellation shape.


-- Inspect

1.
core-parse-command-clones — src/core.rs parse_command still clones commands, tokens, arguments, and switches while building InvocationArgs.
2.
strategy-router-dispatch-clones — src/cli/strategy.rs SubcommandRouter::resolve and recursive dispatch clone Command/InvocationArgs pieces during routing.
3.
registry-lookup-clones — src/cli/registry.rs get() and get_all() clone Command values; worth checking whether borrowed lookup is possible.
4.
catalog-merge-clones — src/cli/strategy.rs FallbackSubcommandStrategy::subcommands() clones and merges command catalogs; likely the biggest remaining aggregation hotspot.