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

Clarify comparison provider and delivery guarantees

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-12 00:15:04 +00:00
parent 98c9c3f00d
commit 251d3adeee
2 changed files with 30 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/cli.md
View File

@@ -232,15 +232,16 @@ serialized as `[]`.
### Compare configuration selections
`config diff` compares two independently loaded selections for one scope that
declares comparison. The default scope is `app`; `--scope all` is unsupported.
`config diff` prepares two selections for one scope that declares comparison
and invokes its comparison provider after input checks pass. The default scope
is `app`; `--scope all` is unsupported.
The PromptKit engine scope does not currently declare comparison, so selecting
`--scope promptkit` is a usage error.
`--config` and `--overlay` select the left side. `--against-config` and
`--against-overlay` independently override the right side. When a right-side
field is omitted, it inherits the corresponding left value and supplied state;
an explicit empty string overrides it and remains supplied. Equal selections are
allowed and both reached sides are loaded.
allowed; their equality alone does not cause CommandKit to skip the provider.
YAML is the only format and the default. Explicit `--format yaml` is accepted;
`text` and other formats are usage errors. For example:
@@ -279,13 +280,21 @@ null values and deletions retain their distinction.
Successful comparisons return status `0`, including concealed or empty results.
Unsupported scopes and format errors are usage errors; input checks retain the
existing usage/operational classification. Load and native comparison failures
are operational and preserve supported error identity. Comparison
diagnostics identify their left/right side and source legend. The adapter loads
left before right, retains left diagnostics if right loading fails, and gathers
both loads' diagnostics before native comparison. The complete report is
prepared before writing. Cancellation and preparation failures leave report
output empty; an output error or short write uses the existing incomplete-report
delivery outcome.
are operational and preserve supported error identity.
The bundled `FromConfigKit` and `AppCommand` adapters invoke the supplied loader
for each reached side, left before right, then call native comparison. They label
native diagnostics with their left/right side and source legend, retain left
diagnostics if right loading fails, and gather both loads' diagnostics before
native comparison. Custom pair providers own their loading and diagnostics;
application loaders and caches determine whether a loader call reads sources
again.
The complete report is prepared before writing. Report preparation failures and
cancellation observed before report delivery starts leave CommandKit's report
output empty. Once writing starts, CommandKit does not interrupt the supplied
writer or roll back delivered bytes. A write error or short write uses the
existing incomplete-report delivery outcome and can leave partial output.
## PromptKit definition inspection