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

Cleaned up documentation language

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 19:36:02 -05:00
parent 84234275eb
commit a722bc1505
11 changed files with 40 additions and 696 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/adr/0001-command-dispatch-and-inputs.md
View File

@@ -10,11 +10,12 @@ Accepted.
## Context
Audita, Narratio, Notarius, and Scriptorium repeat configuration inspection,
routing, parsing, help, and error handling. Their command vocabulary and syntax
have diverged. CommandKit aims to provide one implementation of standard
inspection, consistent vocabulary and mechanics, and less application
infrastructure. Application migrations are expected to make breaking changes.
Several downstream consumers of the ConfigKit and PromptKit libraries include
duplicated or near-duplicated code relating to configuration inspection,
routing, parsing, help, and error handling. However, their command vocabulary
and syntax have diverged. CommandKit aims to provide a single, unified CLI
implementation that will reduce duplication, provide consistent vocabulary and
grammar, and reduce the amount of code each individual applicaiton must own.
Applications have genuine domain commands, such as Narratio's `session restore`,
that remain outside the standard suite. Merely forwarding standard families from
@@ -35,11 +36,13 @@ syntax diagnostics, and standard-family handlers and outcomes. Applications own
custom command names, domain meaning, validation, effects, artifacts, and
operational outcomes.
Use namespace/resource-first syntax for the standard suite. The `config` family
and an installed `promptkit` family belong to CommandKit. PromptKit definition
inspection uses the single `promptkit` namespace; root `prompt` and `profile`
names remain available to applications. This provides a clear family ownership
boundary without spreading a namespace across root verbs.
Use namespace-first syntax for the standard suite, which provides a clear
family ownership boundary. The initial release of CommandKit will ship with two
bundled standard command families:
(1) The `config` family provides ConfigKit inspection and validation; and
(2) the `promptkit` family provides PromptKit inspection and utilities.
CommandKit integrates ConfigKit and PromptKit through their supported public
semantics.
CommandKit accepts custom commands outside its reserved standard families and
reports registration errors for attempts to replace standard handlers or add
@@ -49,8 +52,7 @@ selectors and typed overrides for standard operations.
CommandKit accepts caller-supplied context, streams, handlers, and inspection
providers and returns invocation outcomes. It leaves process termination to the
caller. Executable startup, signals, runtime construction, schemas, acquisition,
and domain resolution remain application choices. CommandKit integrates ConfigKit
and PromptKit through their supported public semantics.
and domain resolution remain application choices.
### Explicit registry and capability installation
@@ -159,8 +161,8 @@ resources, with standard meanings preserved for operations that are installed.
| Both full dispatch and embeddable family handlers | Serves established external CLI architectures but adds integration surfaces and maintenance. Add embedding only for a concrete need. |
| Raw-argument handlers for custom commands | Eases migration but leaves parsing and help responsibilities with applications. A future transition adapter would need to describe its separate parsing and help contract. |
| Universal application runtime framework | Could absorb startup and operational services, but expands beyond the demonstrated CLI boundary and domain ownership. |
| Verb-first standard paths | Groups actions but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. |
| Reserve root `prompt` and `profile` | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. |
| Verb-first standard paths | Groups actions, but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. |
| Reserve root `prompt` and `profile` for PromptKit | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. |
### Registration