base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete the performance audit and update documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-09 01:54:31 +00:00
parent 62b4a48e4f
commit 18ff0d6639
8 changed files with 157 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/internal/overview.md
View File

@@ -13,20 +13,30 @@ provider adapters. Configuration reports adapt ConfigKit's public records and
writers. PromptKit scope and definition handlers use PromptKit's public
inspection methods and map their results to CommandKit-owned reports.
The root lowers registered command metadata into the internal adapter's neutral
bridge. The adapter returns raw parsed values and neutral syntax-failure data;
the root prepares typed input, invokes application/standard handlers, and
coordinates outcomes and diagnostic delivery. Application callbacks and their
supported error identity are handled in the root through its typed contracts.
Context and streams are passed to the adapter for its parsing and help operations.
The root lazily caches one immutable neutral bridge tree per `App`, invalidating
it after successful nonempty registration. For each `Execute`, it prepares one
adapter session and reuses that session for parsing, help, and usage. If a
callback registers commands during execution, metadata-dependent presentation
refreshes without repeating input callbacks. The root still prepares typed
input, invokes application/standard handlers, and coordinates outcomes and
diagnostic delivery. Application callbacks and their supported error identity
are handled in the root through its typed contracts.
Configuration registration owns and normalizes its declarations, then prepares
ordered scopes, name lookup, installed operations, and a discovery DTO. Command
handlers reuse that private metadata; each invocation still creates its context
and invokes acquisition only for selected scopes.
## `internal/cobra`
This package owns the Cobra-specific command tree, argument/flag parsing,
and help rendering. It translates neutral command metadata and parsed values
into a bridge result consumed by the root package. It does not import `commandkit`
and does not own registry policy, public command declarations, provider loading,
or standard inspection report rendering.
and help rendering. A session owns one mutable backend tree for an invocation;
parsing and presentation reuse it. Backend commands map directly to neutral
declarations, and Cobra parent links reconstruct only the selected command path.
The adapter returns raw parsed values and neutral syntax-failure data consumed
by the root package. It does not import `commandkit` and does not own registry
policy, public command declarations, provider loading, or standard inspection
report rendering.
## External implementation boundaries