3.6 KiB
ADR 0004: Separate optional CLI integrations from the core
Status
Accepted. Consolidated during the alpha ADR cleanup.
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 owns operator behavior, GoDoc owns provider contracts, and ADR 0006 owns the shared presentation boundary. Report formats, comparison statuses, and individual operation inventories can evolve without changing domain ownership.