nullkey
da9faa9e07
Borrows the lark-cli agent-affordance model (https://github.com/larksuite/cli/blob/main/AGENTS.md + skills/lark-shared/SKILL.md) so weknora is designed to be agent-friendly: error messages, output format, and flag design follow conventions agents can rely on. cli/AGENTS.md (operational reference for LLM agents invoking weknora): Public document covering envelope schema, exit-code protocol (0/1/2/10/130), stdout/stderr separation, and behavioral rules. Sensitive commands (\`context use\`, \`kb delete\`, \`doc delete\`, \`init\`) gain "AI agents:" paragraphs in their cobra Long descriptions so guidance shows in --help. format.Envelope schema additions: Risk per-operation classification (read / write / high-risk-write + action description), populated by write commands on both success and failure paths. Notice system advisories (CLI update available, server-CLI version skew); type defined, emit sites land in v0.3. DryRun marker for envelopes returned from --dry-run preview paths. RiskLevel constants realigned to lark's taxonomy: read / write / high-risk-write (was: read / mutating / destructive — not yet wired by any command). cmdutil.Error gains OperationRisk; PrintErrorEnvelope auto-attaches it to envelope.Risk so destructive failure paths surface uniformly. Exit-10 confirmation protocol: New ErrorCode \`input.confirmation_required\` mapped to exit code 10 in cmdutil.ExitCode. ConfirmDestructive now returns this code (with OperationRisk attached) when stdout is non-TTY or --json was set, with -y/--yes absent. Previous behavior — silent proceed in non-TTY — was unsafe: scripts and agents could delete resources with no explicit approval. Three test cases re-pinned around the new contract. This is a wire-contract change for any caller who relied on silent proceed; v0.0/v0.1 had no destructive commands, so the blast radius is contained to v0.2 itself. --dry-run global flag: cmd write paths (kb create/delete, doc upload/delete, api POST/PUT/PATCH/ DELETE) check cmdutil.IsDryRun(cmd) and skip the SDK call, emitting an envelope with dry_run=true plus a Risk classification. Read commands ignore --dry-run by design (no side effect to preview). Human-mode prints \`[dry-run] would <action>\` to stdout. Command discovery: agents introspect via the existing \`--help\` surface (consistent with gh / kubectl / aws / gcloud / terraform — none of them ship a CLI-tree self-description command). An earlier draft added a \`weknora schema\` reflection command; dropped after a mainstream survey found it has no stable analog (lark-cli's schema describes Lark API methods, not its own CLI tree). Tests: 27 cli packages pass at this commit. Added two new tests covering envelope.risk and envelope._notice serialization.
66 lines
2.1 KiB
Go
66 lines
2.1 KiB
Go
package format
|
|
|
|
import (
|
|
"bytes"
|
|
"encoding/json"
|
|
"testing"
|
|
|
|
"github.com/stretchr/testify/assert"
|
|
"github.com/stretchr/testify/require"
|
|
)
|
|
|
|
func TestSuccessEnvelope(t *testing.T) {
|
|
env := Success(map[string]string{"id": "kb_abc"}, &Meta{Context: "prod", RequestID: "cli-01"})
|
|
var buf bytes.Buffer
|
|
require.NoError(t, WriteEnvelope(&buf, env))
|
|
var got map[string]any
|
|
require.NoError(t, json.Unmarshal(buf.Bytes(), &got))
|
|
assert.Equal(t, true, got["ok"])
|
|
assert.NotNil(t, got["data"])
|
|
assert.NotNil(t, got["_meta"])
|
|
assert.Nil(t, got["error"])
|
|
}
|
|
|
|
func TestFailureEnvelope(t *testing.T) {
|
|
env := Failure(&ErrorBody{
|
|
Code: "auth.unauthenticated",
|
|
Message: "no creds",
|
|
Hint: "run weknora auth login",
|
|
Retryable: false,
|
|
})
|
|
var buf bytes.Buffer
|
|
require.NoError(t, WriteEnvelope(&buf, env))
|
|
var got map[string]any
|
|
require.NoError(t, json.Unmarshal(buf.Bytes(), &got))
|
|
assert.Equal(t, false, got["ok"])
|
|
errBody := got["error"].(map[string]any)
|
|
assert.Equal(t, "auth.unauthenticated", errBody["code"])
|
|
assert.Equal(t, "run weknora auth login", errBody["hint"])
|
|
}
|
|
|
|
func TestEnvelope_RiskAndNotice(t *testing.T) {
|
|
env := Success(map[string]string{"id": "kb_x"}, nil)
|
|
env.Risk = &Risk{Level: RiskHighRiskWrite, Action: "delete kb_x"}
|
|
env.Notice = &Notice{Update: &UpdateNotice{Available: true, Current: "0.2.0", Latest: "0.3.0"}}
|
|
var buf bytes.Buffer
|
|
require.NoError(t, WriteEnvelope(&buf, env))
|
|
var got map[string]any
|
|
require.NoError(t, json.Unmarshal(buf.Bytes(), &got))
|
|
risk := got["risk"].(map[string]any)
|
|
assert.Equal(t, "high-risk-write", risk["level"])
|
|
assert.Equal(t, "delete kb_x", risk["action"])
|
|
notice := got["_notice"].(map[string]any)
|
|
upd := notice["update"].(map[string]any)
|
|
assert.Equal(t, true, upd["available"])
|
|
assert.Equal(t, "0.3.0", upd["latest"])
|
|
}
|
|
|
|
func TestEnvelope_NoEscapeHTML(t *testing.T) {
|
|
// Hints / messages may include & or <; ensure we don't HTML-escape them
|
|
// (would break agent jq pipelines).
|
|
env := Failure(&ErrorBody{Code: "x", Message: "a & b < c"})
|
|
var buf bytes.Buffer
|
|
require.NoError(t, WriteEnvelope(&buf, env))
|
|
assert.Contains(t, buf.String(), "a & b < c")
|
|
}
|