Add ConfigKit scope contracts and adapters

integrations/ckconfig/contracts.go

@@ -0,0 +1,101 @@
+package ckconfig
+
+import (
+	"context"
+	"io"
+
+	commandkit "gitea.maximumdirect.net/eric/CommandKit"
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+// Selection carries the configuration and overlay choices supplied for a
+// configuration scope.
+type Selection struct {
+	Config  commandkit.Supplied[string]
+	Overlay commandkit.Supplied[string]
+}
+
+// Operation identifies a supported configuration inspection operation.
+type Operation string
+
+const (
+	// Validate checks the selected configuration and reports diagnostics.
+	Validate Operation = "validate"
+	// Show writes the selected configuration's effective form.
+	Show Operation = "show"
+	// Sources reports the selected configuration's input sources.
+	Sources Operation = "sources"
+	// Explain reports the history and provenance of a selected path.
+	Explain Operation = "explain"
+)
+
+// Request describes one configuration operation and its selected inputs.
+type Request struct {
+	Operation Operation
+	Selection Selection
+}
+
+// EffectiveWriter writes a configuration's native effective representation.
+type EffectiveWriter interface {
+	WriteEffective(io.Writer) error
+}
+
+// SourceReader reports the native source inventory for a configuration.
+type SourceReader interface {
+	Sources() []configkit.SourceInfo
+}
+
+// ExplanationReader reads and writes a configuration's native path explanation.
+type ExplanationReader interface {
+	Explain(configkit.Path) (configkit.Explanation, bool)
+	WriteExplanation(io.Writer, configkit.Path) error
+}
+
+// View exposes native configuration facets without reconstructing their
+// reports.
+type View struct {
+	Effective   EffectiveWriter
+	Sources     SourceReader
+	Explanation ExplanationReader
+}
+
+// Scope declares the operations and acquisition callback for one named
+// configuration. Construction issues are retained privately until family
+// assembly attaches them to its command declaration.
+type Scope[I, S any] struct {
+	Name       string
+	Summary    string
+	Operations []Operation
+	Acquire    func(context.Context, Request, I, S) (commandkit.Acquired[View], error)
+
+	issues []error
+}
+
+// Selector binds a typed flag to the configuration scopes that use it.
+type Selector[I any] struct {
+	Binding commandkit.Flag[I]
+	Scopes  []string
+}
+
+// Suite declares the typed input, shared state, selectors, and configuration
+// scopes used to assemble configuration commands.
+type Suite[I, S any] struct {
+	NewInput   func() I
+	NewState   func() S
+	Selectors  []Selector[I]
+	CheckInput func(scope string, selection Selection, input I) error
+	Scopes     []Scope[I, S]
+}
+
+// WithScopeError returns a copy of scope that retains err as a construction
+// issue. Existing issues remain available to family assembly, and scope is not
+// mutated. A nil error returns scope unchanged.
+func WithScopeError[I, S any](scope Scope[I, S], err error) Scope[I, S] {
+	if err == nil {
+		return scope
+	}
+	issues := make([]error, len(scope.issues), len(scope.issues)+1)
+	copy(issues, scope.issues)
+	scope.issues = append(issues, err)
+	return scope
+}