mirror of
https://github.com/larksuite/cli.git
synced 2026-07-06 16:18:05 +08:00
fe72e41fb2
Introduce a typed error contract framework for lark-cli so in-process
Go callers can branch via errors.As(&errs.XxxError{}) and shell scripts,
AI agents, and protocol adapters can branch on stable JSON type/subtype
fields instead of regex-parsing free-form messages.
Adds:
- Canonical taxonomy under errs/ (9 categories + typed Error structs
embedding a shared Problem, RFC 7807-aligned)
- Centralized Lark code metadata + identity-aware BuildAPIError dispatch
- Typed JSON envelope writer alongside the legacy envelope writer
- MCP / OAuth (RFC 6750 Bearer) projection adapters
- Five CI lint guards preventing ad-hoc taxonomy drift
Backward compatibility: legacy *output.ExitError producers (ErrAPI,
ErrWithHint, Errorf, ErrBare) and business shortcuts that use them
continue to render the legacy envelope unchanged. SecurityPolicyError
wire format and exit code are preserved via a carve-out; taxonomy
migration is deferred to PR 2. Domain-specific business migration is
staged across PR 3+.
Framework-direct paths now return typed *errs.*Error: ErrAuth /
ErrValidation / ErrNetwork emit category literals on the wire
(authentication / validation / network), *core.ConfigError is promoted
at the cmd/root boundary with exit code aligned from 2 to 3, and Lark
API permission denials classified by BuildAPIError exit 3.
At the SDK boundary, WrapDoAPIError preserves any already-classified
error (legacy *output.ExitError or typed *errs.*) so output.ErrAuth
from missing credentials surfaces with the auth category and exit 3
intact instead of being downgraded to a network error. Policy responses
classified by BuildAPIError (codes 21000 / 21001) extract challenge_url
and the canonical hint from the response body, matching what the
auth transport already surfaces at the HTTP layer; non-https
challenge URLs are dropped.
First PR in the feat/error-contract-* series.
43 lines
1.6 KiB
Go
43 lines
1.6 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package cmdutil
|
|
|
|
import (
|
|
"fmt"
|
|
|
|
"github.com/larksuite/cli/internal/output"
|
|
)
|
|
|
|
// RequireConfirmation constructs a confirmation_required error with exit code
|
|
// ExitConfirmationRequired and a structured Risk envelope. Used by both
|
|
// shortcut and service command execution paths when a statically
|
|
// high-risk-write operation has not been confirmed with --yes.
|
|
//
|
|
// action identifies the operation for the agent (e.g. "mail +send",
|
|
// "drive.files.delete"). The envelope does not carry a pre-built retry
|
|
// command: agents already know their original invocation and only need to
|
|
// append --yes per the hint, which keeps the protocol free of shell-quoting
|
|
// pitfalls.
|
|
// Deprecated: RequireConfirmation produces a legacy *output.ExitError that
|
|
// predates the typed error contract introduced by errs/. New code MUST NOT
|
|
// use it — confirmation-required signals should move to typed
|
|
// *errs.ConfirmationRequiredError carrying the same agent-protocol metadata
|
|
// (level/action) as typed extension fields. This helper is retained only
|
|
// while existing call sites are migrated; it will be removed once they have
|
|
// moved to the typed surface.
|
|
func RequireConfirmation(action string) error {
|
|
return &output.ExitError{
|
|
Code: output.ExitConfirmationRequired,
|
|
Detail: &output.ErrDetail{
|
|
Type: "confirmation_required",
|
|
Message: fmt.Sprintf("%s requires confirmation", action),
|
|
Hint: "add --yes to confirm",
|
|
Risk: &output.RiskDetail{
|
|
Level: "high-risk-write",
|
|
Action: action,
|
|
},
|
|
},
|
|
}
|
|
}
|