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

Clarify the internal adapter and handler ownership boundary

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 18:28:44 +00:00
parent 8b6835b84b
commit e421099de6
2 changed files with 15 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/internal/overview.md
View File

@@ -13,18 +13,21 @@ provider adapters. Configuration reports adapt ConfigKit's public records and
writers. PromptKit scope and definition handlers use PromptKit's public writers. PromptKit scope and definition handlers use PromptKit's public
inspection methods and map their results to CommandKit-owned reports. inspection methods and map their results to CommandKit-owned reports.
The root package imports `internal/cobra` to bridge its command declarations and The root lowers registered command metadata into the internal adapter's neutral
invocations to Cobra parsing and routing. Application callbacks, output streams, bridge. The adapter returns raw parsed values and neutral syntax-failure data;
context, and supported error identity cross that bridge through the root's typed the root prepares typed input, invokes application/standard handlers, and
contracts. coordinates outcomes and diagnostic delivery. Application callbacks and their
supported error identity remain in the root's typed contracts rather than
crossing the backend bridge. Context and streams are passed to the adapter for
its parsing and help operations.
## `internal/cobra` ## `internal/cobra`
This package owns the Cobra-specific command tree and argument/flag parsing This package owns the Cobra-specific command tree, argument/flag parsing,
adapter. It translates neutral command metadata and parsed values into a bridge 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 result consumed by the root package. It does not import `commandkit` and does not
own registry policy, public command declarations, provider loading, or report own registry policy, public command declarations, provider loading, or standard
rendering. inspection report rendering.
## External implementation boundaries ## External implementation boundaries

6
docs/roadmap/remediation.md
View File

@@ -186,12 +186,14 @@ Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/oss.md).
Owner: [internal/overview.md](../internal/overview.md). Owner: [internal/overview.md](../internal/overview.md).
- [ ] Correct the claim that application callbacks cross the adapter bridge. - [x] Correct the claim that application callbacks cross the adapter bridge.
Handler callbacks and typed invocation coordination remain in the root; Handler callbacks and typed invocation coordination remain in the root;
the adapter exchanges neutral metadata and parse results. the adapter exchanges neutral metadata and parse results.
- [ ] Keep inventory/mechanics here and normative responsibility boundaries in - [x] Keep inventory/mechanics here and normative responsibility boundaries in
the architecture policy. the architecture policy.
**Completion:** Corrected neutral metadata/results flow and root callback ownership; distinguished adapter help rendering from standard inspection reports.
## D-10: reconcile navigation and reading guidance ## D-10: reconcile navigation and reading guidance
Owners: [development.md](../development.md) and [README.md](../../README.md). Owners: [development.md](../development.md) and [README.md](../../README.md).