733bb3aaa1
Re-introduce the agent-first symmetric envelope deleted in commite623e820(2026-05-15). Under the v0.7 constraint that AI agents are primary consumers, the bare-JSON shape can't carry protocol channels (_notice / risk / meta / request_id / profile) that agents need. Errors-on-stderr and typed exit codes frome623e820are preserved; the envelope wraps the success/error payloads on top. - cli/internal/output/envelope.go (new): Envelope / ErrorEnvelope / Meta / ErrDetail / RiskDetail structs; WriteEnvelope + WriteErrorEnvelope writers; PendingNotice plumbing for the open-map _notice channel (reserved infra; producer wiring planned for v0.8). - cli/internal/output/envelope_test.go (new): 7 tests covering success / error / TTY indent / Notice / Risk shapes. - cmdutil.Error extended with RetryCommand (directly-executable argv distinct from prose Hint), RetryAfterSeconds (HTTP Retry-After), *RiskInfo (nested level+action; ErrInternalServer- vs-NotFound distinction), Detail (open structured payload), Silent (suppress stderr emit while preserving Code for ExitCode). - ErrorToDetail single source of envelope.error construction; reused by stderr PrintError, MCP StructuredContent, and batch per-item error path. - WithHint / WithRetryCommand / WithRetryAfter / WithDetail / WithRisk builders. IsCancelled helper. AsError unwrap helper. - defaultHint covers ~21 codes; defaultRetryCommand symmetric counterpart for 6 keyway codes. DefaultHint / DefaultRetryCommand exported wrappers for cross-package callers. - ClassifyHTTPError tightened: rescues HTTP 500 with structured server-side code 1003 (ErrNotFound) into resource.not_found. Server's generic 1007 (ErrInternalServer) bucket stays as server.error — including it would mis-route validation failures (e.g. SQLSTATE 22001) as not-found. - PrintError dual-mode: text/human → prose with code:msg / hint / retry lines; json/ndjson → envelope on stderr. Mode pinned by root PersistentPreRunE via SetFormatMode. resolveFormatEarly() scans argv before cobra dispatch so cobra-side validators (unknown flag, arg-count) still surface as envelope when --format json is in effect. Silent typed errors short-circuit the stderr emit. FlagError mapped to input.invalid_argument for the envelope (exit code stays 2 via FlagError class). - Unknown-subcommand guard installed recursively at the root: parents with subcommands but no Run/RunE get a typed RunE that emits input.unknown_subcommand envelope with detail.{unknown, command_path, available[]} and retry_command "<parent> --help". cobra.ArbitraryArgs bypasses legacyArgs validation so the guard receives unmatched argv. - cmdutil.Error.Error() returns "<code>: <message>[: <cause>]" for chain debugging; ErrorToDetail strips the code prefix from envelope.message since the separate type field carries it (prevents the doubled-prefix "code: code: ..." that agents would see). Spec: docs/superpowers/specs/2026-05-20-weknora-cli-v0.7-design.md §0 / §4
112 lines
3.3 KiB
Go
112 lines
3.3 KiB
Go
package output_test
|
||
|
||
import (
|
||
"bytes"
|
||
"strings"
|
||
"testing"
|
||
|
||
"github.com/Tencent/WeKnora/cli/internal/output"
|
||
)
|
||
|
||
func TestWriteEnvelope_SuccessWithData(t *testing.T) {
|
||
var buf bytes.Buffer
|
||
data := map[string]string{"id": "kb_x"}
|
||
if err := output.WriteEnvelope(&buf, data, nil, false, ""); err != nil {
|
||
t.Fatalf("unexpected error: %v", err)
|
||
}
|
||
got := buf.String()
|
||
if !strings.Contains(got, `"ok":true`) {
|
||
t.Errorf("missing ok:true; got %q", got)
|
||
}
|
||
if !strings.Contains(got, `"data":{"id":"kb_x"}`) {
|
||
t.Errorf("missing data; got %q", got)
|
||
}
|
||
}
|
||
|
||
func TestWriteEnvelope_OmitDataWhenNil(t *testing.T) {
|
||
// mutation 无 payload 时 data 字段应被省略(omitempty)
|
||
var buf bytes.Buffer
|
||
if err := output.WriteEnvelope(&buf, nil, nil, false, ""); err != nil {
|
||
t.Fatalf("unexpected error: %v", err)
|
||
}
|
||
got := buf.String()
|
||
if strings.Contains(got, `"data"`) {
|
||
t.Errorf("data field should be omitted when nil; got %q", got)
|
||
}
|
||
if !strings.Contains(got, `"ok":true`) {
|
||
t.Errorf("missing ok:true; got %q", got)
|
||
}
|
||
}
|
||
|
||
func TestWriteEnvelope_WithMeta(t *testing.T) {
|
||
var buf bytes.Buffer
|
||
meta := &output.Meta{Count: 2, HasMore: false}
|
||
if err := output.WriteEnvelope(&buf, []string{"a", "b"}, meta, false, ""); err != nil {
|
||
t.Fatalf("unexpected error: %v", err)
|
||
}
|
||
got := buf.String()
|
||
if !strings.Contains(got, `"meta":{"count":2}`) {
|
||
// has_more:false should be omitted by omitempty when false
|
||
t.Errorf("meta unexpected shape; got %q", got)
|
||
}
|
||
}
|
||
|
||
func TestWriteErrorEnvelope_FullShape(t *testing.T) {
|
||
var buf bytes.Buffer
|
||
errDetail := &output.ErrDetail{
|
||
Type: "input.confirmation_required",
|
||
Message: "kb delete kb_x requires confirmation",
|
||
Hint: "re-run with -y/--yes",
|
||
RetryCommand: "weknora kb delete kb_x -y",
|
||
Risk: &output.RiskDetail{
|
||
Level: "destructive",
|
||
Action: "kb.delete",
|
||
},
|
||
}
|
||
if err := output.WriteErrorEnvelope(&buf, errDetail, false); err != nil {
|
||
t.Fatalf("unexpected error: %v", err)
|
||
}
|
||
got := buf.String()
|
||
if !strings.Contains(got, `"ok":false`) {
|
||
t.Errorf("missing ok:false; got %q", got)
|
||
}
|
||
if !strings.Contains(got, `"type":"input.confirmation_required"`) {
|
||
t.Errorf("missing typed code; got %q", got)
|
||
}
|
||
if !strings.Contains(got, `"retry_command":"weknora kb delete kb_x -y"`) {
|
||
t.Errorf("missing retry_command; got %q", got)
|
||
}
|
||
if !strings.Contains(got, `"risk":{"level":"destructive","action":"kb.delete"}`) {
|
||
t.Errorf("missing risk; got %q", got)
|
||
}
|
||
}
|
||
|
||
func TestWriteEnvelope_IndentedTTYMode(t *testing.T) {
|
||
var buf bytes.Buffer
|
||
if err := output.WriteEnvelope(&buf, map[string]string{"id": "x"}, nil, true, ""); err != nil {
|
||
t.Fatalf("unexpected error: %v", err)
|
||
}
|
||
got := buf.String()
|
||
if !strings.Contains(got, "\n \"") {
|
||
t.Errorf("expected indented multi-line output; got %q", got)
|
||
}
|
||
}
|
||
|
||
func TestGetNotice_NilSafe(t *testing.T) {
|
||
output.PendingNotice = nil
|
||
if got := output.GetNotice(); got != nil {
|
||
t.Errorf("GetNotice with nil PendingNotice should return nil; got %v", got)
|
||
}
|
||
}
|
||
|
||
func TestGetNotice_WithSetter(t *testing.T) {
|
||
output.PendingNotice = func() map[string]any {
|
||
return map[string]any{"deprecation": "foo is deprecated"}
|
||
}
|
||
defer func() { output.PendingNotice = nil }()
|
||
got := output.GetNotice()
|
||
if got["deprecation"] != "foo is deprecated" {
|
||
t.Errorf("notice not populated; got %v", got)
|
||
}
|
||
}
|