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:
@@ -1,35 +1,50 @@
|
||||
package cmdutil
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/prompt"
|
||||
)
|
||||
|
||||
// ConfirmDestructive prompts the user to confirm a destructive operation
|
||||
// (e.g. delete) when the call is interactive, and proceeds without
|
||||
// prompting otherwise. Behavior matrix:
|
||||
// ConfirmDestructive guards a destructive operation (delete, force-overwrite)
|
||||
// behind explicit user approval. Behavior matrix:
|
||||
//
|
||||
// yes=true → proceed (skip prompt; explicit user opt-in via -y)
|
||||
// non-TTY stdout → proceed (no UI to ask; safer to follow the call
|
||||
// than to break scripts/CI that don't pass
|
||||
// -y every time)
|
||||
// jsonOut=true → proceed (envelope mode is by definition scripted,
|
||||
// a prompt would deadlock the consumer)
|
||||
// yes=true → proceed (explicit user opt-in via -y/--yes)
|
||||
// non-TTY OR jsonOut → return CodeInputConfirmationRequired (exit 10);
|
||||
// no UI to prompt, agent/CI must re-invoke with -y
|
||||
// after the human explicitly approves
|
||||
// TTY + interactive → prompt; user-yes proceeds, user-no returns
|
||||
// CodeUserAborted ("Aborted." to stderr)
|
||||
// prompter error → returns CodeInputMissingFlag (rare; AgentPrompter
|
||||
// path or stdin closed mid-prompt)
|
||||
// prompter error → returns CodeInputMissingFlag (rare; stdin closed
|
||||
// mid-prompt)
|
||||
//
|
||||
// `yes` should be sourced from the persistent global -y/--yes flag (see
|
||||
// addGlobalFlags in cli/cmd/root.go). Mirrors gh's `--yes` semantics on
|
||||
// destructive commands: gh repo delete --yes
|
||||
// (https://cli.github.com/manual/gh_repo_delete).
|
||||
// The non-TTY branch is the lark-cli skill protocol: high-risk writes
|
||||
// always require explicit confirmation in scripted contexts, never silent
|
||||
// proceed. See cli/AGENTS.md "Exit codes" and
|
||||
// https://github.com/larksuite/cli/blob/main/skills/lark-shared/SKILL.md.
|
||||
//
|
||||
// `yes` should be sourced from the persistent global -y/--yes flag.
|
||||
//
|
||||
// On exit-10 path, the returned *Error carries OperationRisk so the envelope
|
||||
// printer attaches `risk: {level: "high-risk-write", action: ...}`.
|
||||
func ConfirmDestructive(p prompt.Prompter, yes, jsonOut bool, what, id string) error {
|
||||
if yes || !iostreams.IO.IsStdoutTTY() || jsonOut {
|
||||
if yes {
|
||||
return nil
|
||||
}
|
||||
risk := &OperationRisk{Level: "high-risk-write", Action: fmt.Sprintf("delete %s %s", what, id)}
|
||||
if !iostreams.IO.IsStdoutTTY() || jsonOut {
|
||||
e := NewError(
|
||||
CodeInputConfirmationRequired,
|
||||
fmt.Sprintf("delete %s %s requires explicit confirmation: re-run with -y/--yes", what, id),
|
||||
)
|
||||
var typed *Error
|
||||
if errors.As(e, &typed) {
|
||||
typed.OperationRisk = risk
|
||||
}
|
||||
return e
|
||||
}
|
||||
ok, err := p.Confirm(fmt.Sprintf("Delete %s %s? This cannot be undone.", what, id), false)
|
||||
if err != nil {
|
||||
return Wrapf(CodeInputMissingFlag, err, "confirm delete")
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
package cmdutil
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/format"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
)
|
||||
|
||||
// IsDryRun reports whether the global --dry-run flag was set on cmd or any
|
||||
// of its parents. Write commands check this and skip the SDK call, returning
|
||||
// an envelope with dry_run=true that describes the action that would have
|
||||
// run. Read commands ignore --dry-run (no side effect to preview).
|
||||
//
|
||||
// Pattern from lark-cli's `--dry-run` (cmd/api/api.go DryRun field).
|
||||
func IsDryRun(cmd *cobra.Command) bool {
|
||||
if cmd == nil {
|
||||
return false
|
||||
}
|
||||
v, _ := cmd.Flags().GetBool("dry-run")
|
||||
return v
|
||||
}
|
||||
|
||||
// EmitDryRun writes the canonical preview envelope for a write command. JSON
|
||||
// mode emits SuccessWithRisk + DryRun=true; human mode prints the
|
||||
// `[dry-run] would <risk.Action>` line to stdout, with " (high-risk)"
|
||||
// appended automatically when risk.Level == RiskHighRiskWrite. Centralized
|
||||
// so wire shape stays identical across kb create/delete, doc upload/delete,
|
||||
// api, and any future write command.
|
||||
func EmitDryRun(jsonOut bool, data any, meta *format.Meta, risk *format.Risk) error {
|
||||
out := iostreams.IO.Out
|
||||
if jsonOut {
|
||||
env := format.SuccessWithRisk(data, meta, risk)
|
||||
env.DryRun = true
|
||||
return format.WriteEnvelope(out, env)
|
||||
}
|
||||
line := risk.Action
|
||||
if risk.Level == format.RiskHighRiskWrite {
|
||||
line += " (high-risk)"
|
||||
}
|
||||
_, err := fmt.Fprintf(out, "[dry-run] would %s\n", line)
|
||||
return err
|
||||
}
|
||||
@@ -29,8 +29,14 @@ const (
|
||||
CodeResourceLocked ErrorCode = "resource.locked"
|
||||
|
||||
// input.* — flag and argument validation
|
||||
CodeInputInvalidArgument ErrorCode = "input.invalid_argument"
|
||||
CodeInputMissingFlag ErrorCode = "input.missing_flag"
|
||||
CodeInputInvalidArgument ErrorCode = "input.invalid_argument"
|
||||
CodeInputMissingFlag ErrorCode = "input.missing_flag"
|
||||
// CodeInputConfirmationRequired marks a high-risk write that has no
|
||||
// interactive UI (non-TTY or --json) and was invoked without -y/--yes.
|
||||
// Mapped to exit code 10 (lark-cli skill protocol — see cli/AGENTS.md).
|
||||
// Agents must surface the envelope to the user and only retry with -y
|
||||
// after explicit human approval; never auto-retry.
|
||||
CodeInputConfirmationRequired ErrorCode = "input.confirmation_required"
|
||||
|
||||
// server.* / network.*
|
||||
CodeServerError ErrorCode = "server.error"
|
||||
@@ -84,6 +90,19 @@ type Error struct {
|
||||
Cause error
|
||||
Retryable bool
|
||||
HTTPStatus int
|
||||
// Risk classifies the operation that produced this error. Set by callers
|
||||
// invoking destructive write paths so envelope.risk surfaces to agents.
|
||||
// Stored as the format.Risk JSON shape via OperationRisk to avoid an
|
||||
// import cycle with internal/format.
|
||||
OperationRisk *OperationRisk
|
||||
}
|
||||
|
||||
// OperationRisk mirrors format.Risk in the cmdutil layer (avoiding a circular
|
||||
// import). cmdutil → format is OK; the inverse is not, so cmdutil owns its
|
||||
// own type and ToErrorBody / PrintErrorEnvelope translate.
|
||||
type OperationRisk struct {
|
||||
Level string // "read" | "write" | "high-risk-write"
|
||||
Action string
|
||||
}
|
||||
|
||||
func (e *Error) Error() string {
|
||||
@@ -229,7 +248,7 @@ func AllCodes() []ErrorCode {
|
||||
// resource
|
||||
CodeResourceNotFound, CodeResourceAlreadyExists, CodeResourceLocked,
|
||||
// input
|
||||
CodeInputInvalidArgument, CodeInputMissingFlag,
|
||||
CodeInputInvalidArgument, CodeInputMissingFlag, CodeInputConfirmationRequired,
|
||||
// server / network
|
||||
CodeServerError, CodeServerTimeout, CodeServerRateLimited,
|
||||
CodeServerIncompatibleVersion, CodeNetworkError,
|
||||
|
||||
@@ -8,16 +8,19 @@ import (
|
||||
"github.com/Tencent/WeKnora/cli/internal/format"
|
||||
)
|
||||
|
||||
// ExitCode maps an error to the documented CLI exit code (spec §2.4).
|
||||
// Mirrors gh / Stripe convention:
|
||||
// - 0 success
|
||||
// - 1 generic / unknown
|
||||
// - 2 flag / argument problem
|
||||
// - 3 auth.*
|
||||
// - 4 resource.not_found
|
||||
// - 5 input.*
|
||||
// - 6 server.rate_limited
|
||||
// - 7 server.* (other) / network.*
|
||||
// ExitCode maps an error to the documented CLI exit code (spec §2.4 + ADR-3).
|
||||
// Mirrors gh / Stripe / lark-cli convention:
|
||||
// - 0 success
|
||||
// - 1 generic / unknown typed error
|
||||
// - 2 flag / argument problem
|
||||
// - 3 auth.*
|
||||
// - 4 resource.not_found
|
||||
// - 5 input.* (other than confirmation_required)
|
||||
// - 6 server.rate_limited
|
||||
// - 7 server.* (other) / network.*
|
||||
// - 10 input.confirmation_required — high-risk write needs explicit -y
|
||||
// (lark-cli skill protocol; see cli/AGENTS.md)
|
||||
// - 130 SIGINT (handled by Go runtime, not this function)
|
||||
func ExitCode(err error) int {
|
||||
if err == nil {
|
||||
return 0
|
||||
@@ -29,6 +32,9 @@ func ExitCode(err error) int {
|
||||
if errors.Is(err, SilentError) {
|
||||
return 1
|
||||
}
|
||||
if matchCode(err, CodeInputConfirmationRequired) {
|
||||
return 10
|
||||
}
|
||||
if IsAuthError(err) {
|
||||
return 3
|
||||
}
|
||||
@@ -72,12 +78,28 @@ func PrintError(w io.Writer, err error) {
|
||||
}
|
||||
|
||||
// PrintErrorEnvelope writes err as a JSON envelope on w. Used in agent mode /
|
||||
// --json / --format=json output so failures stay machine-parseable.
|
||||
// --json / --format=json output so failures stay machine-parseable. When the
|
||||
// error carries an OperationRisk (destructive write paths), it's surfaced as
|
||||
// the envelope-level Risk field so agents can decide whether to surface the
|
||||
// failure differently to the user.
|
||||
func PrintErrorEnvelope(w io.Writer, err error) {
|
||||
if err == nil || errors.Is(err, SilentError) {
|
||||
return
|
||||
}
|
||||
_ = format.WriteEnvelope(w, format.Failure(ToErrorBody(err)))
|
||||
env := format.Failure(ToErrorBody(err))
|
||||
if r := operationRiskOf(err); r != nil {
|
||||
env.Risk = &format.Risk{Level: format.RiskLevel(r.Level), Action: r.Action}
|
||||
}
|
||||
_ = format.WriteEnvelope(w, env)
|
||||
}
|
||||
|
||||
// operationRiskOf extracts an OperationRisk from a typed *Error chain, or nil.
|
||||
func operationRiskOf(err error) *OperationRisk {
|
||||
var typed *Error
|
||||
if errors.As(err, &typed) {
|
||||
return typed.OperationRisk
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ToErrorBody projects err into the canonical envelope ErrorBody. Exposed so
|
||||
@@ -145,6 +167,8 @@ func defaultHint(code ErrorCode) string {
|
||||
return "verify the resource ID; list available with `weknora kb list`"
|
||||
case CodeInputInvalidArgument, CodeInputMissingFlag:
|
||||
return "see `weknora <command> --help` for valid usage"
|
||||
case CodeInputConfirmationRequired:
|
||||
return "high-risk write — re-run with -y/--yes after the user explicitly approves"
|
||||
case CodeLocalKeychainDenied:
|
||||
return "verify keyring access; falls back to file storage"
|
||||
case CodeLocalConfigCorrupt:
|
||||
@@ -160,7 +184,7 @@ func defaultHint(code ErrorCode) string {
|
||||
case CodeProjectLinkCorrupt:
|
||||
return "remove .weknora/project.yaml and run `weknora init` again"
|
||||
case CodeUserAborted:
|
||||
return "no action taken; pass --force to skip the confirmation prompt"
|
||||
return "no action taken; pass -y/--yes to skip the confirmation prompt"
|
||||
case CodeUploadFileNotFound:
|
||||
return "verify the path is correct and readable"
|
||||
case CodeSSEStreamAborted:
|
||||
|
||||
@@ -17,7 +17,7 @@ import (
|
||||
)
|
||||
|
||||
// Factory is the dependency container injected at command construction. Each
|
||||
// closure is lazy: --help / completion / `weknora schema` must NOT trigger
|
||||
// closure is lazy: --help / completion / `weknora version` must NOT trigger
|
||||
// HTTP, keyring access, or filesystem I/O beyond the bare minimum.
|
||||
//
|
||||
// Four closures (ADR-4):
|
||||
|
||||
Reference in New Issue
Block a user