74 lines
2.5 KiB
Go
74 lines
2.5 KiB
Go
// Package format renders command output: JSON envelope, jq, template, table.
|
|
//
|
|
// Non-TTY default = JSON envelope (ADR-5). Envelope schema is the contract
|
|
// shared with `weknora mcp serve` tools and external agents.
|
|
package format
|
|
|
|
import (
|
|
"encoding/json"
|
|
"io"
|
|
)
|
|
|
|
// Envelope is the canonical success/failure shape returned by every command.
|
|
type Envelope struct {
|
|
OK bool `json:"ok"`
|
|
Data any `json:"data,omitempty"`
|
|
Error *ErrorBody `json:"error,omitempty"`
|
|
Meta *Meta `json:"_meta,omitempty"`
|
|
}
|
|
|
|
// Meta carries non-payload context fields useful to agents and observability.
|
|
type Meta struct {
|
|
Context string `json:"context,omitempty"`
|
|
TenantID uint64 `json:"tenant_id,omitempty"`
|
|
KBID string `json:"kb_id,omitempty"`
|
|
RequestID string `json:"request_id,omitempty"`
|
|
NextCursor string `json:"next_cursor,omitempty"`
|
|
HasMore bool `json:"has_more,omitempty"`
|
|
Warnings []string `json:"warnings,omitempty"`
|
|
AppliedFilters []string `json:"applied_filters,omitempty"`
|
|
}
|
|
|
|
// RiskLevel classifies an error by the kind of operation that produced it.
|
|
// Agents use this to decide whether to retry, escalate, or stop.
|
|
type RiskLevel string
|
|
|
|
const (
|
|
RiskRead RiskLevel = "read"
|
|
RiskMutating RiskLevel = "mutating"
|
|
RiskDestructive RiskLevel = "destructive"
|
|
)
|
|
|
|
// ErrorBody is the failure shape. `code` is a stable namespaced ID (e.g.
|
|
// "auth.unauthenticated"); `hint` is an actionable next step; `risk` flags
|
|
// destructive intent for agent self-governance.
|
|
type ErrorBody struct {
|
|
Code string `json:"code"`
|
|
Message string `json:"message"`
|
|
Hint string `json:"hint,omitempty"`
|
|
RequestID string `json:"request_id,omitempty"`
|
|
Context string `json:"context,omitempty"`
|
|
Risk RiskLevel `json:"risk,omitempty"`
|
|
Retryable bool `json:"retryable,omitempty"`
|
|
ConsoleURL string `json:"console_url,omitempty"`
|
|
Details map[string]any `json:"details,omitempty"`
|
|
}
|
|
|
|
// WriteEnvelope serializes env as one-line JSON to w. Used for non-TTY output
|
|
// and for `--format json` / `--agent` modes.
|
|
func WriteEnvelope(w io.Writer, env Envelope) error {
|
|
enc := json.NewEncoder(w)
|
|
enc.SetEscapeHTML(false)
|
|
return enc.Encode(env)
|
|
}
|
|
|
|
// Success constructs a success envelope.
|
|
func Success(data any, meta *Meta) Envelope {
|
|
return Envelope{OK: true, Data: data, Meta: meta}
|
|
}
|
|
|
|
// Failure constructs a failure envelope.
|
|
func Failure(err *ErrorBody) Envelope {
|
|
return Envelope{OK: false, Error: err}
|
|
}
|