feat(cli): agent-first WeKnora CLI
The `weknora` command-line client for the WeKnora RAG server. Full command surface: kb / doc / chunk / session / message / agent / model / search / chat / auth / profile / link / api / mcp / skills / config / doctor / schema / exit-codes. Agent-first wire contract: JSON envelope by default, typed error codes mapped to stable exit codes, error.retry_argv / retryable / partial-failure status, global --dry-run preview, the exit-10 confirmation protocol for writes, and control/ANSI/Bidi input hygiene. Stateless env-credential auth (WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use. A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills (`skills install`). Extensive unit + contract-golden tests and CI.
This commit is contained in:
@@ -30,15 +30,29 @@ func WriteBatchEnvelope(w io.Writer, items []BatchItem, indent bool, profile str
|
||||
}
|
||||
}
|
||||
env := Envelope{
|
||||
OK: failures == 0,
|
||||
Data: items,
|
||||
OK: failures == 0,
|
||||
Status: batchStatus(successes, failures),
|
||||
Data: items,
|
||||
Meta: &Meta{
|
||||
Count: len(items),
|
||||
Count: IntPtr(len(items)),
|
||||
Successes: &successes,
|
||||
Failures: &failures,
|
||||
},
|
||||
Notice: GetNotice(),
|
||||
Profile: profile,
|
||||
}
|
||||
return writeJSON(w, env, indent)
|
||||
}
|
||||
|
||||
// batchStatus maps the (successes, failures) counts to the tri-state envelope
|
||||
// status: "success" when no failures, "error" when no successes, "partial"
|
||||
// when both occur.
|
||||
func batchStatus(successes, failures int) string {
|
||||
switch {
|
||||
case failures == 0:
|
||||
return "success"
|
||||
case successes == 0:
|
||||
return "error"
|
||||
default:
|
||||
return "partial"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -74,6 +74,53 @@ func TestWriteBatchEnvelope_EmptyItems_EmitsEmptyArray(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestWriteBatchEnvelope_StatusTriState verifies the additive tri-state
|
||||
// envelope.status: "success" (all ok), "partial" (mixed), "error" (all fail).
|
||||
func TestWriteBatchEnvelope_StatusTriState(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
items []output.BatchItem
|
||||
status string
|
||||
}{
|
||||
{
|
||||
name: "all_success",
|
||||
items: []output.BatchItem{
|
||||
{ID: "a", OK: true}, {ID: "b", OK: true},
|
||||
},
|
||||
status: "success",
|
||||
},
|
||||
{
|
||||
name: "partial",
|
||||
items: []output.BatchItem{
|
||||
{ID: "a", OK: true},
|
||||
{ID: "b", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
|
||||
},
|
||||
status: "partial",
|
||||
},
|
||||
{
|
||||
name: "all_fail",
|
||||
items: []output.BatchItem{
|
||||
{ID: "a", OK: false, Error: &output.ErrDetail{Type: "auth.forbidden", Message: "no perm"}},
|
||||
{ID: "b", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
|
||||
},
|
||||
status: "error",
|
||||
},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
var buf bytes.Buffer
|
||||
if err := output.WriteBatchEnvelope(&buf, tc.items, false, ""); err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
got := buf.String()
|
||||
want := `"status":"` + tc.status + `"`
|
||||
if !strings.Contains(got, want) {
|
||||
t.Errorf("expected %s; got %q", want, got)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestWriteBatchEnvelope_AllFail(t *testing.T) {
|
||||
items := []output.BatchItem{
|
||||
{ID: "id1", OK: false, Error: &output.ErrDetail{Type: "auth.forbidden", Message: "no perm"}},
|
||||
|
||||
@@ -11,28 +11,35 @@ import (
|
||||
// Envelope is the success-path stdout envelope. See AGENTS.md
|
||||
// "Stdout (success path)" for the full wire contract.
|
||||
type Envelope struct {
|
||||
OK bool `json:"ok"`
|
||||
Data any `json:"data,omitempty"`
|
||||
Meta *Meta `json:"meta,omitempty"`
|
||||
Notice map[string]any `json:"_notice,omitempty"`
|
||||
Profile string `json:"profile,omitempty"`
|
||||
OK bool `json:"ok"`
|
||||
// Status is the batch tri-state outcome: "success" (all items ok),
|
||||
// "partial" (some ok, some failed), or "error" (all failed). Set only by
|
||||
// batch commands; omitted on ordinary single-result envelopes. `ok` stays
|
||||
// authoritative — Status is an additive convenience for agents triaging
|
||||
// multi-target results.
|
||||
Status string `json:"status,omitempty"`
|
||||
Data any `json:"data,omitempty"`
|
||||
Meta *Meta `json:"meta,omitempty"`
|
||||
Profile string `json:"profile,omitempty"`
|
||||
}
|
||||
|
||||
// ErrorEnvelope is the error-path stderr envelope. See AGENTS.md
|
||||
// "Stderr (error path)" for the full wire contract.
|
||||
type ErrorEnvelope struct {
|
||||
OK bool `json:"ok"`
|
||||
Error *ErrDetail `json:"error"`
|
||||
Notice map[string]any `json:"_notice,omitempty"`
|
||||
OK bool `json:"ok"`
|
||||
Error *ErrDetail `json:"error"`
|
||||
}
|
||||
|
||||
// Meta carries optional metadata in success envelopes.
|
||||
type Meta struct {
|
||||
Count int `json:"count,omitempty"`
|
||||
HasMore bool `json:"has_more,omitempty"`
|
||||
NextCursor string `json:"next_cursor,omitempty"`
|
||||
TotalCount int `json:"total_count,omitempty"`
|
||||
RequestID string `json:"request_id,omitempty"`
|
||||
// Count and TotalCount are *int so zero is serialized when explicitly set
|
||||
// by list commands (omitempty on *int omits only nil, not zero). This keeps
|
||||
// the agent contract stable: an empty list still emits count/total_count as 0
|
||||
// instead of dropping the key. Non-list / dry-run metas leave them nil so they
|
||||
// are omitted. Mirrors the Successes/Failures pointer pattern below.
|
||||
Count *int `json:"count,omitempty"`
|
||||
HasMore bool `json:"has_more,omitempty"`
|
||||
TotalCount *int `json:"total_count,omitempty"`
|
||||
// Successes and Failures are *int so zero is serialized when explicitly set
|
||||
// by the batch path (omitempty on *int omits only nil, not zero).
|
||||
// Non-batch commands leave these nil so they are omitted from the envelope.
|
||||
@@ -47,13 +54,21 @@ type Meta struct {
|
||||
// ErrDetail describes a structured error. Embedded in ErrorEnvelope.Error
|
||||
// and also surfaced in batch envelope per-item failures.
|
||||
type ErrDetail struct {
|
||||
Type string `json:"type"`
|
||||
Message string `json:"message"`
|
||||
Hint string `json:"hint,omitempty"`
|
||||
RetryCommand string `json:"retry_command,omitempty"`
|
||||
RetryAfterSeconds int `json:"retry_after_seconds,omitempty"`
|
||||
Risk *RiskDetail `json:"risk,omitempty"`
|
||||
Detail any `json:"detail,omitempty"`
|
||||
Type string `json:"type"`
|
||||
Message string `json:"message"`
|
||||
Hint string `json:"hint,omitempty"`
|
||||
// RetryArgv is a directly-executable argv array (e.g.
|
||||
// ["weknora","auth","login"]) so an agent can exec it without
|
||||
// shell-splitting or quote-handling. Distinct from the prose Hint.
|
||||
RetryArgv []string `json:"retry_argv,omitempty"`
|
||||
RetryAfterSeconds int `json:"retry_after_seconds,omitempty"`
|
||||
// Retryable indicates whether re-running the SAME command may succeed:
|
||||
// true for transient failures (timeouts, rate limits, transport), false
|
||||
// for deterministic ones (auth, bad input, not-found), omitted (nil) when
|
||||
// genuinely unknown.
|
||||
Retryable *bool `json:"retryable,omitempty"`
|
||||
Risk *RiskDetail `json:"risk,omitempty"`
|
||||
Detail any `json:"detail,omitempty"`
|
||||
}
|
||||
|
||||
// RiskDetail tags high-risk writes for the agent protocol. Surfaces in
|
||||
@@ -64,35 +79,20 @@ type RiskDetail struct {
|
||||
Action string `json:"action"`
|
||||
}
|
||||
|
||||
// PendingNotice, if set, returns system-level notices to inject as the
|
||||
// "_notice" field on every envelope. Currently nil — Task 4.x deferred
|
||||
// the registration. Tests may set this directly.
|
||||
var PendingNotice func() map[string]any
|
||||
|
||||
// GetNotice returns the current pending notice. Nil when nothing to report.
|
||||
func GetNotice() map[string]any {
|
||||
if PendingNotice == nil {
|
||||
return nil
|
||||
}
|
||||
return PendingNotice()
|
||||
}
|
||||
|
||||
// NewEnvelope assembles a success Envelope with the given data + optional
|
||||
// meta + profile, injecting the pending _notice automatically. Single source
|
||||
// of construction so callers that need the envelope value (e.g. jq filtering)
|
||||
// stay in sync with WriteEnvelope when fields are added.
|
||||
// meta + profile. Single source of construction so callers that need the
|
||||
// envelope value (e.g. jq filtering) stay in sync with WriteEnvelope when
|
||||
// fields are added.
|
||||
func NewEnvelope(data any, meta *Meta, profile string) Envelope {
|
||||
return Envelope{
|
||||
OK: true,
|
||||
Data: data,
|
||||
Meta: meta,
|
||||
Notice: GetNotice(),
|
||||
Profile: profile,
|
||||
}
|
||||
}
|
||||
|
||||
// WriteEnvelope writes a success envelope to w. Caller sets data + optional meta;
|
||||
// notice is injected from GetNotice() automatically.
|
||||
// WriteEnvelope writes a success envelope to w. Caller sets data + optional meta.
|
||||
//
|
||||
// When profile is non-empty, the envelope includes a "profile" field.
|
||||
// indent: if true, output is multi-line (TTY mode); else compact (pipe mode).
|
||||
@@ -103,13 +103,17 @@ func WriteEnvelope(w io.Writer, data any, meta *Meta, indent bool, profile strin
|
||||
// WriteErrorEnvelope writes an error envelope to w (typically stderr).
|
||||
func WriteErrorEnvelope(w io.Writer, err *ErrDetail, indent bool) error {
|
||||
env := ErrorEnvelope{
|
||||
OK: false,
|
||||
Error: err,
|
||||
Notice: GetNotice(),
|
||||
OK: false,
|
||||
Error: err,
|
||||
}
|
||||
return writeJSON(w, env, indent)
|
||||
}
|
||||
|
||||
// IntPtr returns a pointer to i. Used by list commands to set Meta.Count /
|
||||
// Meta.TotalCount so that a zero count still serializes (omitempty on *int
|
||||
// omits only nil). Mirrors the Successes/Failures pointer pattern.
|
||||
func IntPtr(i int) *int { return &i }
|
||||
|
||||
func writeJSON(w io.Writer, v any, indent bool) error {
|
||||
enc := json.NewEncoder(w)
|
||||
enc.SetEscapeHTML(false)
|
||||
|
||||
@@ -40,7 +40,7 @@ func TestWriteEnvelope_OmitDataWhenNil(t *testing.T) {
|
||||
|
||||
func TestWriteEnvelope_WithMeta(t *testing.T) {
|
||||
var buf bytes.Buffer
|
||||
meta := &output.Meta{Count: 2, HasMore: false}
|
||||
meta := &output.Meta{Count: output.IntPtr(2), HasMore: false}
|
||||
if err := output.WriteEnvelope(&buf, []string{"a", "b"}, meta, false, ""); err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
@@ -51,13 +51,36 @@ func TestWriteEnvelope_WithMeta(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestWriteEnvelope_ZeroCountSerializes pins the *int fix: a list command that
|
||||
// sets Count to 0 (empty result) must still emit "count":0, while a meta that
|
||||
// leaves Count nil (non-list / dry-run) must omit the key entirely. This is the
|
||||
// agent-contract guarantee that omitempty on a plain int silently broke.
|
||||
func TestWriteEnvelope_ZeroCountSerializes(t *testing.T) {
|
||||
var bufZero bytes.Buffer
|
||||
zero := &output.Meta{Count: output.IntPtr(0)}
|
||||
if err := output.WriteEnvelope(&bufZero, []string{}, zero, false, ""); err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
if gotZero := bufZero.String(); !strings.Contains(gotZero, `"count":0`) {
|
||||
t.Errorf("explicit zero count must serialize; got %q", gotZero)
|
||||
}
|
||||
|
||||
var bufNil bytes.Buffer
|
||||
if err := output.WriteEnvelope(&bufNil, []string{}, &output.Meta{}, false, ""); err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
if gotNil := bufNil.String(); strings.Contains(gotNil, "count") {
|
||||
t.Errorf("nil count must be omitted; got %q", gotNil)
|
||||
}
|
||||
}
|
||||
|
||||
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",
|
||||
Type: "input.confirmation_required",
|
||||
Message: "kb delete kb_x requires confirmation",
|
||||
Hint: "re-run with -y/--yes",
|
||||
RetryArgv: []string{"weknora", "kb", "delete", "kb_x", "-y"},
|
||||
Risk: &output.RiskDetail{
|
||||
Level: "destructive",
|
||||
Action: "kb.delete",
|
||||
@@ -73,8 +96,8 @@ func TestWriteErrorEnvelope_FullShape(t *testing.T) {
|
||||
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, `"retry_argv":["weknora","kb","delete","kb_x","-y"]`) {
|
||||
t.Errorf("missing retry_argv; got %q", got)
|
||||
}
|
||||
if !strings.Contains(got, `"risk":{"level":"destructive","action":"kb.delete"}`) {
|
||||
t.Errorf("missing risk; got %q", got)
|
||||
@@ -91,21 +114,3 @@ func TestWriteEnvelope_IndentedTTYMode(t *testing.T) {
|
||||
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)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user