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

Record proposed CLI decisions and clarify CommandKit boundaries

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 23:36:06 +00:00
parent 6a0467148e
commit 84234275eb
15 changed files with 1243 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/policy/architecture.md
View File

@@ -50,8 +50,8 @@ diagnostics, and the handlers and observable contracts of its standard families.
Applications register domain commands outside those families and own their
meaning, effects, domain validation, artifacts, and operational outcomes.
Namespaces provide the ownership boundary: standard `config` and an installed
`promptkit` family remain CommandKit-owned. Applications do not replace their
handlers or add private operations beneath them.
`promptkit` family remain CommandKit-owned. CommandKit reports registration errors
for attempts to replace their handlers or add private operations beneath them.
Applications own their executable entry points, context creation, signals,
stream selection, runtime construction, and final process exit. CommandKit
@@ -64,12 +64,25 @@ package-global or import-time registries. One definition supplies routing,
parsing, and help metadata. Duplicate paths and attempts to replace reserved
commands report errors rather than letting registration order select a winner.
Standard families are installed from supplied capabilities. Help and version use
application identity/build metadata; configuration and PromptKit providers install
their complete corresponding families. Provider registration is lazy and does
not acquire configuration or construct engines. Help and version remain available
with missing or invalid configuration. Do not install placeholder commands or
claim complete adoption for unsupported operations.
Standard families are assembled from declared provider capabilities. Each family
specifies its own resources and supported operations; shared verbs retain
consistent meanings across families. Configuration scopes describe their supported
inspection operations. CommandKit installs the supplied handlers and metadata and
reports actual availability through help and discovery. Missing upstream
capabilities leave other supported operations available.
Help and version use identity/build metadata. CommandKit's registration and
metadata paths leave acquisition callbacks uninvoked. Help and version remain
available with missing or invalid configuration. Callers retain their startup and
callback effects. Version reporting defaults to application identity; explicit
component selection reports embedded library identity.
These rules govern CommandKit's own API, dispatcher, and standard handlers.
Provider contracts define required inputs and results for enabled operations;
callback internals and application execution remain consumer choices. Shared
inspection/execution loading and focused acquisition callbacks are recommended
integration practices. Independent consumer use of other CLI frameworks remains
application-owned.
## Handler Inputs And Invocation State
@@ -78,9 +91,10 @@ Use presence-aware fields where omission matters; preserve explicitly supplied
empty, false, and zero values independently of parser defaults. Context, streams,
and execution dependencies are separate from CLI inputs.
Create fresh input and backend command/flag state per invocation. Registered
commands must not retain input values, collections, or presence state across
runs. This does not establish a concurrent-dispatch guarantee.
CommandKit creates fresh input and backend command/flag state per invocation,
keeping its parsed values, collections, and presence out of subsequent runs.
Caller-owned closures and runtime state retain their own lifecycle. Concurrent
dispatch is a separate contract.
Applications may interpret parsed domain values and provide domain value parsers
through the binding system. Raw-argument parsing is not the primary handler model.