feat(cli): add agent-first affordance — envelope, exit-10, --dry-run
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.
This commit is contained in:
@@ -10,11 +10,57 @@ import (
|
||||
)
|
||||
|
||||
// Envelope is the canonical success/failure shape returned by every command.
|
||||
//
|
||||
// v0.2 ADR-3 added Notice / Risk / DryRun, borrowed from lark-cli's envelope
|
||||
// (https://github.com/larksuite/cli/blob/main/internal/output/envelope.go).
|
||||
// All three are absent on read-only commands; write commands populate Risk
|
||||
// even on success so agents can record what action ran.
|
||||
type Envelope struct {
|
||||
OK bool `json:"ok"`
|
||||
Data any `json:"data,omitempty"`
|
||||
Error *ErrorBody `json:"error,omitempty"`
|
||||
Meta *Meta `json:"_meta,omitempty"`
|
||||
OK bool `json:"ok"`
|
||||
Data any `json:"data,omitempty"`
|
||||
Error *ErrorBody `json:"error,omitempty"`
|
||||
Meta *Meta `json:"_meta,omitempty"`
|
||||
Notice *Notice `json:"_notice,omitempty"`
|
||||
Risk *Risk `json:"risk,omitempty"`
|
||||
// DryRun is intentionally NOT omitempty: AGENTS.md documents
|
||||
// `dry_run: false` as the literal default in the schema example, so
|
||||
// agents that pin the field's presence aren't surprised by it
|
||||
// disappearing on non-dry-run envelopes.
|
||||
DryRun bool `json:"dry_run"`
|
||||
}
|
||||
|
||||
// Notice carries system-level advisories independent of the command outcome:
|
||||
// CLI update available, server-CLI version skew, etc. Agents read these to
|
||||
// surface upgrade prompts to users without polluting `data`.
|
||||
type Notice struct {
|
||||
Update *UpdateNotice `json:"update,omitempty"`
|
||||
VersionSkew *VersionSkewNotice `json:"version_skew,omitempty"`
|
||||
}
|
||||
|
||||
// UpdateNotice indicates a newer CLI version is available.
|
||||
type UpdateNotice struct {
|
||||
Available bool `json:"available"`
|
||||
Current string `json:"current"`
|
||||
Latest string `json:"latest,omitempty"`
|
||||
}
|
||||
|
||||
// VersionSkewNotice indicates the server is behind the CLI within the compat
|
||||
// window. `Level` mirrors doctor's status semantics: "warn" (degraded but
|
||||
// functional) or "error" (out of compat).
|
||||
type VersionSkewNotice struct {
|
||||
Client string `json:"client"`
|
||||
Server string `json:"server"`
|
||||
Level string `json:"level"`
|
||||
}
|
||||
|
||||
// Risk classifies the operation the user is performing — not the error.
|
||||
// Agents inspect this on every envelope. When Level == RiskHighRiskWrite and
|
||||
// the operation requires confirmation (no -y), the CLI exits 10. See
|
||||
// cli/AGENTS.md "Exit codes" and lark-cli's
|
||||
// skills/lark-shared/SKILL.md.
|
||||
type Risk struct {
|
||||
Level RiskLevel `json:"level"`
|
||||
Action string `json:"action,omitempty"`
|
||||
}
|
||||
|
||||
// Meta carries non-payload context fields useful to agents and observability.
|
||||
@@ -29,26 +75,27 @@ type Meta struct {
|
||||
AppliedFilters []string `json:"applied_filters,omitempty"`
|
||||
}
|
||||
|
||||
// RiskLevel classifies an error by the kind of operation that produced it.
|
||||
// Agents use this to decide whether to retry, escalate, or stop.
|
||||
// RiskLevel classifies an operation. Agents use this to decide whether to
|
||||
// retry, require explicit user approval, or stop. Values are aligned with
|
||||
// lark-cli's risk taxonomy
|
||||
// (https://github.com/larksuite/cli/blob/main/internal/output/envelope.go).
|
||||
type RiskLevel string
|
||||
|
||||
const (
|
||||
RiskRead RiskLevel = "read"
|
||||
RiskMutating RiskLevel = "mutating"
|
||||
RiskDestructive RiskLevel = "destructive"
|
||||
RiskRead RiskLevel = "read"
|
||||
RiskWrite RiskLevel = "write"
|
||||
RiskHighRiskWrite RiskLevel = "high-risk-write"
|
||||
)
|
||||
|
||||
// ErrorBody is the failure shape. `code` is a stable namespaced ID (e.g.
|
||||
// "auth.unauthenticated"); `hint` is an actionable next step; `risk` flags
|
||||
// destructive intent for agent self-governance.
|
||||
// "auth.unauthenticated"); `hint` is an actionable next step. Operation-level
|
||||
// risk lives at the envelope level (Envelope.Risk), not here.
|
||||
type ErrorBody struct {
|
||||
Code string `json:"code"`
|
||||
Message string `json:"message"`
|
||||
Hint string `json:"hint,omitempty"`
|
||||
RequestID string `json:"request_id,omitempty"`
|
||||
Context string `json:"context,omitempty"`
|
||||
Risk RiskLevel `json:"risk,omitempty"`
|
||||
Retryable bool `json:"retryable,omitempty"`
|
||||
ConsoleURL string `json:"console_url,omitempty"`
|
||||
Details map[string]any `json:"details,omitempty"`
|
||||
@@ -56,7 +103,7 @@ type ErrorBody struct {
|
||||
|
||||
// WriteEnvelope serializes env as one-line JSON to w. Used for non-TTY output
|
||||
// and for `--json` per-command mode (the omnibus `--agent` mode-switch was
|
||||
// removed in v0.2 ADR-3; see docs/superpowers/specs/2026-05-09).
|
||||
// removed in v0.2 ADR-3; see cli/AGENTS.md for the agent contract).
|
||||
func WriteEnvelope(w io.Writer, env Envelope) error {
|
||||
enc := json.NewEncoder(w)
|
||||
enc.SetEscapeHTML(false)
|
||||
@@ -68,6 +115,14 @@ func Success(data any, meta *Meta) Envelope {
|
||||
return Envelope{OK: true, Data: data, Meta: meta}
|
||||
}
|
||||
|
||||
// SuccessWithRisk is Success + a per-operation Risk classification. Used by
|
||||
// every write command (kb create/delete, doc upload/delete, api POST/PUT/
|
||||
// DELETE, ...) so an agent reading any envelope can tell what kind of
|
||||
// operation produced it without parsing the data shape.
|
||||
func SuccessWithRisk(data any, meta *Meta, risk *Risk) Envelope {
|
||||
return Envelope{OK: true, Data: data, Meta: meta, Risk: risk}
|
||||
}
|
||||
|
||||
// Failure constructs a failure envelope.
|
||||
func Failure(err *ErrorBody) Envelope {
|
||||
return Envelope{OK: false, Error: err}
|
||||
|
||||
@@ -26,7 +26,6 @@ func TestFailureEnvelope(t *testing.T) {
|
||||
Code: "auth.unauthenticated",
|
||||
Message: "no creds",
|
||||
Hint: "run weknora auth login",
|
||||
Risk: RiskRead,
|
||||
Retryable: false,
|
||||
})
|
||||
var buf bytes.Buffer
|
||||
@@ -37,7 +36,23 @@ func TestFailureEnvelope(t *testing.T) {
|
||||
errBody := got["error"].(map[string]any)
|
||||
assert.Equal(t, "auth.unauthenticated", errBody["code"])
|
||||
assert.Equal(t, "run weknora auth login", errBody["hint"])
|
||||
assert.Equal(t, "read", errBody["risk"])
|
||||
}
|
||||
|
||||
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) {
|
||||
|
||||
Reference in New Issue
Block a user