WeKnora/cli/cmd
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
..
agent docs(cli): README / AGENTS.md / CHANGELOG + CI parity test 2026-05-18 11:10:19 +08:00
api feat(cli): doc delete multi-id + api --paginate + paginate fixes + batch deletes 2026-05-18 11:10:19 +08:00
auth feat(cli): --log-level + kb/agent status & check + cross-cutting refactor 2026-05-18 11:10:19 +08:00
chat feat(cli): --format / NDJSON / chat & agent invoke / MCP / SetAgentHelp / signal-aware ctx / kb create --storage-provider 2026-05-18 11:10:19 +08:00
chunk docs(cli): README / AGENTS.md / CHANGELOG + CI parity test 2026-05-18 11:10:19 +08:00
context docs(cli): README / AGENTS.md / CHANGELOG + CI parity test 2026-05-18 11:10:19 +08:00
doc feat(cli): doc delete multi-id + api --paginate + paginate fixes + batch deletes 2026-05-18 11:10:19 +08:00
doctor feat(cli): --log-level + kb/agent status & check + cross-cutting refactor 2026-05-18 11:10:19 +08:00
kb feat(cli): doc delete multi-id + api --paginate + paginate fixes + batch deletes 2026-05-18 11:10:19 +08:00
link feat(cli): --log-level + kb/agent status & check + cross-cutting refactor 2026-05-18 11:10:19 +08:00
mcp chore(cli): polish + docs sync + pre-PR audit fixes 2026-05-16 16:56:33 +08:00
search feat(cli): doc delete multi-id + api --paginate + paginate fixes + batch deletes 2026-05-18 11:10:19 +08:00
session feat(cli): doc delete multi-id + api --paginate + paginate fixes + batch deletes 2026-05-18 11:10:19 +08:00
completion_test.go feat(cli): api --input + completion smoke 2026-05-14 10:57:17 +08:00
root.go refactor(cli): symmetric envelope infrastructure (supersedes e623e820) 2026-05-27 10:56:34 +08:00
root_test.go refactor(cli): symmetric envelope infrastructure (supersedes e623e820) 2026-05-27 10:56:34 +08:00
root_unknown_subcommand_test.go refactor(cli): symmetric envelope infrastructure (supersedes e623e820) 2026-05-27 10:56:34 +08:00