Enterprise-Knowledge-Base/cli/internal/output/envelope.go

// Package output defines the symmetric envelope wire contract:
// success envelopes on stdout (Envelope) and error envelopes on
// stderr (ErrorEnvelope), plus NDJSON stream helpers.
package output

import (
	"encoding/json"
	"io"
)

// Envelope is the success-path stdout envelope. See AGENTS.md
// "Stdout (success path)" for the full wire contract.
type Envelope struct {
	OK      bool           `json:"ok"`
	Data    any            `json:"data,omitempty"`
	Meta    *Meta          `json:"meta,omitempty"`
	Notice  map[string]any `json:"_notice,omitempty"`
	Profile string         `json:"profile,omitempty"`
}

// ErrorEnvelope is the error-path stderr envelope. See AGENTS.md
// "Stderr (error path)" for the full wire contract.
type ErrorEnvelope struct {
	OK     bool           `json:"ok"`
	Error  *ErrDetail     `json:"error"`
	Notice map[string]any `json:"_notice,omitempty"`
}

// Meta carries optional metadata in success envelopes.
type Meta struct {
	Count      int    `json:"count,omitempty"`
	HasMore    bool   `json:"has_more,omitempty"`
	NextCursor string `json:"next_cursor,omitempty"`
	TotalCount int    `json:"total_count,omitempty"`
	RequestID  string `json:"request_id,omitempty"`
	// Successes and Failures are *int so zero is serialized when explicitly set
	// by the batch path (omitempty on *int omits only nil, not zero).
	// Non-batch commands leave these nil so they are omitted from the envelope.
	Successes *int `json:"successes,omitempty"` // batch ops
	Failures  *int `json:"failures,omitempty"`  // batch ops
}

// ErrDetail describes a structured error. Embedded in ErrorEnvelope.Error
// and also surfaced in batch envelope per-item failures.
type ErrDetail struct {
	Type              string      `json:"type"`
	Message           string      `json:"message"`
	Hint              string      `json:"hint,omitempty"`
	RetryCommand      string      `json:"retry_command,omitempty"`
	RetryAfterSeconds int         `json:"retry_after_seconds,omitempty"`
	Risk              *RiskDetail `json:"risk,omitempty"`
	Detail            any         `json:"detail,omitempty"`
}

// RiskDetail tags high-risk writes for the agent protocol. Surfaces in
// error.risk on confirmation_required errors.
// Level: only "destructive" is emitted; "read" / "write" slots reserved.
type RiskDetail struct {
	Level  string `json:"level"`
	Action string `json:"action"`
}

// PendingNotice, if set, returns system-level notices to inject as the
// "_notice" field on every envelope. Currently nil — Task 4.x deferred
// the registration. Tests may set this directly.
var PendingNotice func() map[string]any

// GetNotice returns the current pending notice. Nil when nothing to report.
func GetNotice() map[string]any {
	if PendingNotice == nil {
		return nil
	}
	return PendingNotice()
}

// NewEnvelope assembles a success Envelope with the given data + optional
// meta + profile, injecting the pending _notice automatically. Single source
// of construction so callers that need the envelope value (e.g. jq filtering)
// stay in sync with WriteEnvelope when fields are added.
func NewEnvelope(data any, meta *Meta, profile string) Envelope {
	return Envelope{
		OK:      true,
		Data:    data,
		Meta:    meta,
		Notice:  GetNotice(),
		Profile: profile,
	}
}

// WriteEnvelope writes a success envelope to w. Caller sets data + optional meta;
// notice is injected from GetNotice() automatically.
//
// When profile is non-empty, the envelope includes a "profile" field.
// indent: if true, output is multi-line (TTY mode); else compact (pipe mode).
func WriteEnvelope(w io.Writer, data any, meta *Meta, indent bool, profile string) error {
	return writeJSON(w, NewEnvelope(data, meta, profile), indent)
}

// WriteErrorEnvelope writes an error envelope to w (typically stderr).
func WriteErrorEnvelope(w io.Writer, err *ErrDetail, indent bool) error {
	env := ErrorEnvelope{
		OK:     false,
		Error:  err,
		Notice: GetNotice(),
	}
	return writeJSON(w, env, indent)
}

func writeJSON(w io.Writer, v any, indent bool) error {
	enc := json.NewEncoder(w)
	enc.SetEscapeHTML(false)
	if indent {
		enc.SetIndent("", "  ")
	}
	return enc.Encode(v)
}