72 lines
3.6 KiB
Markdown
72 lines
3.6 KiB
Markdown
|
# ADR 0004: Separate optional CLI integrations from the core
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation).
|
||
|
|
|
||
|
|
## Date
|
||
|
|
|
||
|
|
2026-11-07; consolidates decisions made on 2026-10-09 and 2026-10-11.
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Applications need CommandKit with different combinations of library integrations,
|
||
|
|
including none. A core-only consumer should not acquire optional libraries in its
|
||
|
|
module graph. Integrations also need a clear boundary between exposing operator
|
||
|
|
tasks and taking over the upstream libraries' domain functionality.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
Keep the core and optional integrations in separate Go modules with their own
|
||
|
|
public package contracts. Core owns shared CLI infrastructure. Integrations own
|
||
|
|
standard operator-facing commands, provider contracts, content projections, and
|
||
|
|
adapters for their libraries. They are not convenience libraries for
|
||
|
|
application-internal use of upstream APIs.
|
||
|
|
|
||
|
|
Dependencies point from integrations toward core. Core's API, implementation,
|
||
|
|
tests, examples, tools, and module requirements remain independent of optional
|
||
|
|
integration libraries. An integration may depend on another integration when
|
||
|
|
its responsibility requires it; document that dependency for consumers.
|
||
|
|
|
||
|
|
Applications explicitly install integration declarations through public core
|
||
|
|
contracts. Importing a module installs nothing. Integrations supply convenient
|
||
|
|
complete-family assembly and supported composition without accessing private
|
||
|
|
core state or backend structures. Add narrow public core capabilities for actual
|
||
|
|
integration needs rather than a universal provider or plugin framework.
|
||
|
|
|
||
|
|
The integrated libraries own configuration resolution, prompt preparation,
|
||
|
|
comparison, validation, and other domain algorithms. CommandKit invokes their
|
||
|
|
supported public APIs and preserves returned meaning, supported error identity,
|
||
|
|
and safe-disclosure rules. The adopted upstream version governs those semantics;
|
||
|
|
CommandKit does not maintain a parallel domain specification or reconstruct
|
||
|
|
comparison from rendered text or redacted snapshots.
|
||
|
|
|
||
|
|
Integrations choose report content from suitable inspection evidence, preserving
|
||
|
|
upstream confidentiality and presence distinctions. CommandKit may summarize or
|
||
|
|
project that safe evidence for operator needs. Applications retain ownership of
|
||
|
|
schemas, loading, engine construction, credentials, domain execution, and startup.
|
||
|
|
Arbitrary application content is not implicitly safe for disclosure.
|
||
|
|
|
||
|
|
## Alternatives considered
|
||
|
|
|
||
|
|
- Keeping integrations in core, or in packages within its module, would retain
|
||
|
|
their dependencies in the core module graph.
|
||
|
|
- Requiring applications to implement standard integration handlers would repeat
|
||
|
|
command and reporting infrastructure.
|
||
|
|
- Universal core provider types would introduce abstraction and conversion work
|
||
|
|
before concrete integrations justify it.
|
||
|
|
- Reimplementing upstream algorithms would duplicate domain ownership and could
|
||
|
|
lose evidence already withheld from safe inspection values.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
Consumers can adopt core independently and add integrations as needed. Separate
|
||
|
|
modules require coordinated dependency, validation, and release work. Integrations
|
||
|
|
remain maintained parts of CommandKit with shared CLI conventions.
|
||
|
|
|
||
|
|
Upstream changes require adapter and documentation updates against the adopted
|
||
|
|
public contract. The [CLI reference](../cli.md) owns operator behavior, GoDoc owns
|
||
|
|
provider contracts, and [ADR 0006](0006-invocation-reporting.md) owns the shared
|
||
|
|
presentation boundary. Report formats, comparison statuses, and individual
|
||
|
|
operation inventories can evolve without changing domain ownership.
|