2026-05-06 06:22:36 +00:00
|
|
|
package cmdutil
|
|
|
|
|
|
|
|
|
|
import (
|
|
|
|
|
"bytes"
|
|
|
|
|
"errors"
|
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-21 10:40:06 +00:00
|
|
|
"strings"
|
2026-05-06 06:22:36 +00:00
|
|
|
"testing"
|
|
|
|
|
|
|
|
|
|
"github.com/stretchr/testify/assert"
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
func TestExitCode(t *testing.T) {
|
|
|
|
|
cases := []struct {
|
|
|
|
|
name string
|
|
|
|
|
err error
|
|
|
|
|
want int
|
|
|
|
|
}{
|
|
|
|
|
{"nil success", nil, 0},
|
|
|
|
|
{"flag error", NewFlagError(errors.New("bad flag")), 2},
|
|
|
|
|
{"silent", SilentError, 1},
|
|
|
|
|
{"auth.* prefix", NewError(CodeAuthUnauthenticated, "x"), 3},
|
|
|
|
|
{"auth.token_expired", NewError(CodeAuthTokenExpired, "x"), 3},
|
|
|
|
|
{"resource.not_found", NewError(CodeResourceNotFound, "x"), 4},
|
|
|
|
|
{"input.* prefix", NewError(CodeInputInvalidArgument, "x"), 5},
|
|
|
|
|
{"input.missing_flag", NewError(CodeInputMissingFlag, "x"), 5},
|
|
|
|
|
{"server.rate_limited", NewError(CodeServerRateLimited, "x"), 6},
|
|
|
|
|
{"server.* prefix", NewError(CodeServerError, "x"), 7},
|
|
|
|
|
{"server.timeout", NewError(CodeServerTimeout, "x"), 7},
|
|
|
|
|
{"network.* prefix", NewError(CodeNetworkError, "x"), 7},
|
|
|
|
|
{"unknown error", errors.New("plain"), 1},
|
|
|
|
|
{"local.* prefix", NewError(CodeLocalConfigCorrupt, "x"), 1},
|
2026-05-17 17:38:01 +00:00
|
|
|
{"operation.timeout", NewError(CodeOperationTimeout, "timed out"), 124},
|
|
|
|
|
{"operation.failed → 1 (fall-through bucket)", NewError(CodeOperationFailed, "failed"), 1},
|
|
|
|
|
{"operation.cancelled → 1 (main overrides to 130 on signal-cancelled ctx)", NewError(CodeOperationCancelled, "cancelled"), 1},
|
|
|
|
|
{"server.session_create_failed → 1 (workflow, not transient)", NewError(CodeSessionCreateFailed, "x"), 1},
|
2026-05-06 06:22:36 +00:00
|
|
|
}
|
|
|
|
|
for _, tc := range cases {
|
|
|
|
|
t.Run(tc.name, func(t *testing.T) {
|
|
|
|
|
assert.Equal(t, tc.want, ExitCode(tc.err))
|
|
|
|
|
})
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestPrintError(t *testing.T) {
|
|
|
|
|
t.Run("nil is silent", func(t *testing.T) {
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
PrintError(&buf, nil)
|
|
|
|
|
assert.Empty(t, buf.String())
|
|
|
|
|
})
|
|
|
|
|
t.Run("SilentError is silent", func(t *testing.T) {
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
PrintError(&buf, SilentError)
|
|
|
|
|
assert.Empty(t, buf.String())
|
|
|
|
|
})
|
|
|
|
|
t.Run("typed error prints message", func(t *testing.T) {
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
PrintError(&buf, NewError(CodeAuthUnauthenticated, "no creds"))
|
|
|
|
|
assert.Contains(t, buf.String(), "auth.unauthenticated")
|
|
|
|
|
assert.Contains(t, buf.String(), "no creds")
|
|
|
|
|
})
|
|
|
|
|
}
|
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-21 10:40:06 +00:00
|
|
|
|
|
|
|
|
func TestPrintError_JSONMode_WritesEnvelope(t *testing.T) {
|
|
|
|
|
t.Cleanup(func() { SetFormatMode("") })
|
|
|
|
|
SetFormatMode("json")
|
|
|
|
|
|
|
|
|
|
err := NewError(CodeInputConfirmationRequired, "kb delete kb_x requires confirmation").
|
|
|
|
|
WithHint("re-run with -y/--yes").
|
|
|
|
|
WithRetryCommand("weknora kb delete kb_x -y")
|
|
|
|
|
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
PrintError(&buf, err)
|
|
|
|
|
|
|
|
|
|
got := buf.String()
|
|
|
|
|
if !strings.Contains(got, `"ok":false`) {
|
|
|
|
|
t.Errorf("expected envelope ok:false; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
if !strings.Contains(got, `"type":"input.confirmation_required"`) {
|
|
|
|
|
t.Errorf("expected typed code; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
if !strings.Contains(got, `"retry_command":"weknora kb delete kb_x -y"`) {
|
|
|
|
|
t.Errorf("expected retry_command; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestPrintError_JSONMode_IncludesRetryAfter(t *testing.T) {
|
|
|
|
|
t.Cleanup(func() { SetFormatMode("") })
|
|
|
|
|
SetFormatMode("json")
|
|
|
|
|
|
|
|
|
|
err := NewError(CodeServerRateLimited, "rate limited").
|
|
|
|
|
WithRetryAfter(30)
|
|
|
|
|
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
PrintError(&buf, err)
|
|
|
|
|
|
|
|
|
|
got := buf.String()
|
|
|
|
|
if !strings.Contains(got, `"retry_after_seconds":30`) {
|
|
|
|
|
t.Errorf("expected retry_after_seconds:30; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func TestPrintError_TextMode_WritesProse(t *testing.T) {
|
|
|
|
|
t.Cleanup(func() { SetFormatMode("") })
|
2026-05-21 10:43:18 +00:00
|
|
|
SetFormatMode("text")
|
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-21 10:40:06 +00:00
|
|
|
|
|
|
|
|
err := NewError(CodeInputConfirmationRequired, "kb delete kb_x requires confirmation").
|
|
|
|
|
WithHint("re-run with -y/--yes").
|
|
|
|
|
WithRetryCommand("weknora kb delete kb_x -y")
|
|
|
|
|
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
PrintError(&buf, err)
|
|
|
|
|
|
|
|
|
|
got := buf.String()
|
|
|
|
|
if !strings.Contains(got, "input.confirmation_required: kb delete kb_x requires confirmation") {
|
|
|
|
|
t.Errorf("expected prose code:message line; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
if !strings.Contains(got, "hint: re-run with -y/--yes") {
|
|
|
|
|
t.Errorf("expected hint line; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
if !strings.Contains(got, "retry: weknora kb delete kb_x -y") {
|
|
|
|
|
t.Errorf("expected retry line; got %q", got)
|
|
|
|
|
}
|
|
|
|
|
}
|