Files
Enterprise-Knowledge-Base/cli/internal/output/envelope_test.go
T
nullkey 733bb3aaa1 refactor(cli): symmetric envelope infrastructure (supersedes e623e820)
Re-introduce the agent-first symmetric envelope deleted in commit
e623e820 (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 from e623e820 are 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
2026-05-27 10:56:34 +08:00

112 lines
3.3 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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)
}
}