Add JSON output format for CLI commands

internal/app/output.go

@@ -0,0 +1,76 @@
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+)
+
+const outputSchemaVersion = 1
+
+type OutputFormat string
+
+const (
+	OutputFormatText OutputFormat = "text"
+	OutputFormatJSON OutputFormat = "json"
+)
+
+type OutputWarning struct {
+	Message string `json:"message"`
+}
+
+type OutputError struct {
+	PipelineID    string `json:"pipeline_id,omitempty"`
+	DestinationID string `json:"destination_id,omitempty"`
+	Backend       string `json:"backend,omitempty"`
+	BundlePath    string `json:"bundle_path,omitempty"`
+	Message       string `json:"message"`
+}
+
+type outputEnvelope struct {
+	SchemaVersion int             `json:"schema_version"`
+	Command       string          `json:"command"`
+	OK            bool            `json:"ok"`
+	Warnings      []OutputWarning `json:"warnings"`
+	Result        any             `json:"result"`
+	Errors        []OutputError   `json:"errors,omitempty"`
+}
+
+func NormalizeOutputFormat(format OutputFormat) OutputFormat {
+	if format == "" {
+		return OutputFormatText
+	}
+	return format
+}
+
+func ValidateOutputFormat(format OutputFormat) error {
+	switch NormalizeOutputFormat(format) {
+	case OutputFormatText, OutputFormatJSON:
+		return nil
+	default:
+		return fmt.Errorf("format must be text or json")
+	}
+}
+
+func IsJSONOutput(format OutputFormat) bool {
+	return NormalizeOutputFormat(format) == OutputFormatJSON
+}
+
+func WriteJSONEnvelope(w io.Writer, command string, ok bool, warnings []OutputWarning, result any, errors []OutputError) error {
+	if w == nil {
+		return nil
+	}
+	if warnings == nil {
+		warnings = []OutputWarning{}
+	}
+	envelope := outputEnvelope{
+		SchemaVersion: outputSchemaVersion,
+		Command:       command,
+		OK:            ok,
+		Warnings:      warnings,
+		Result:        result,
+		Errors:        errors,
+	}
+	encoder := json.NewEncoder(w)
+	return encoder.Encode(envelope)
+}