mirror of
https://github.com/larksuite/cli.git
synced 2026-07-06 08:12:36 +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.
87 lines
3.7 KiB
Go
87 lines
3.7 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package output
|
|
|
|
// Envelope is the standard success response wrapper.
|
|
type Envelope struct {
|
|
OK bool `json:"ok"`
|
|
Identity string `json:"identity,omitempty"`
|
|
Data interface{} `json:"data,omitempty"`
|
|
Meta *Meta `json:"meta,omitempty"`
|
|
ContentSafetyAlert interface{} `json:"_content_safety_alert,omitempty"`
|
|
Notice map[string]interface{} `json:"_notice,omitempty"`
|
|
}
|
|
|
|
// ErrorEnvelope is the standard error response wrapper.
|
|
//
|
|
// Deprecated: ErrorEnvelope belongs to the legacy *output.ExitError surface
|
|
// that predates the typed error contract introduced by errs/. New code MUST
|
|
// NOT use it — the typed envelope shape is owned by
|
|
// internal/output.WriteTypedErrorEnvelope which marshals typed errs.* errors
|
|
// directly via JSON reflection (no wrapper struct needed). This struct is
|
|
// retained only while existing *ExitError call sites are migrated; it will
|
|
// be removed once they have moved to the typed surface.
|
|
type ErrorEnvelope struct {
|
|
OK bool `json:"ok"`
|
|
Identity string `json:"identity,omitempty"`
|
|
Error *ErrDetail `json:"error"`
|
|
Meta *Meta `json:"meta,omitempty"`
|
|
Notice map[string]interface{} `json:"_notice,omitempty"`
|
|
}
|
|
|
|
// ErrDetail describes a structured error.
|
|
//
|
|
// Deprecated: ErrDetail belongs to the legacy *output.ExitError surface that
|
|
// predates the typed error contract introduced by errs/. New code MUST NOT
|
|
// use it — typed errs.* structs embed errs.Problem and own their wire shape
|
|
// via JSON tags (Category, Subtype, Hint, etc. promote to the top level).
|
|
// This struct is retained only while existing *ExitError call sites are
|
|
// migrated; it will be removed once they have moved to the typed surface.
|
|
type ErrDetail struct {
|
|
Type string `json:"type"`
|
|
Code int `json:"code,omitempty"`
|
|
Message string `json:"message"`
|
|
Hint string `json:"hint,omitempty"`
|
|
ConsoleURL string `json:"console_url,omitempty"`
|
|
Risk *RiskDetail `json:"risk,omitempty"`
|
|
Detail interface{} `json:"detail,omitempty"`
|
|
}
|
|
|
|
// RiskDetail carries agent-protocol risk information alongside
|
|
// confirmation_required errors. Level is one of "read" | "write" |
|
|
// "high-risk-write". Action identifies the command for the agent (e.g.
|
|
// "mail +send", "drive.files.delete").
|
|
//
|
|
// Deprecated: RiskDetail is reachable only via *output.ExitError.Detail.Risk,
|
|
// part of the legacy envelope surface that predates the typed error contract
|
|
// introduced by errs/. New code MUST NOT use it — confirmation-required
|
|
// signals belong on *errs.ConfirmationRequiredError (its own typed extension
|
|
// fields can carry agent-protocol metadata directly). This struct is
|
|
// retained only while existing *ExitError call sites are migrated; it will
|
|
// be removed once they have moved to the typed surface.
|
|
type RiskDetail struct {
|
|
Level string `json:"level"`
|
|
Action string `json:"action"`
|
|
}
|
|
|
|
// Meta carries optional metadata in envelope responses.
|
|
type Meta struct {
|
|
Count int `json:"count,omitempty"`
|
|
Rollback string `json:"rollback,omitempty"`
|
|
}
|
|
|
|
// PendingNotice, if set, returns system-level notices to inject as the
|
|
// "_notice" field in JSON output envelopes. Set by cmd/root.go.
|
|
// Returns nil when there is nothing to report.
|
|
var PendingNotice func() map[string]interface{}
|
|
|
|
// GetNotice returns the current pending notice for struct-based callers.
|
|
// Returns nil when there is nothing to report.
|
|
func GetNotice() map[string]interface{} {
|
|
if PendingNotice == nil {
|
|
return nil
|
|
}
|
|
return PendingNotice()
|
|
}
|