mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 14:02:43 +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.
38 lines
1.4 KiB
Go
38 lines
1.4 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
// Package errs is the public error-contract surface for lark-cli.
|
|
//
|
|
// It defines a closed taxonomy (9 Categories) and a small set of typed
|
|
// errors that embed Problem — an RFC 7807-aligned shared shape. External
|
|
// consumers (AI agents, shell scripts, integrating SDKs) read structured
|
|
// fields instead of regex-parsing free-string error messages.
|
|
//
|
|
// # The Problem shape
|
|
//
|
|
// Every typed error embeds Problem so the JSON wire shape (`type`,
|
|
// `subtype`, `code`, `message`, `hint`, `log_id`, `retryable`) is uniform
|
|
// across categories. Typed extensions (PermissionError.MissingScopes,
|
|
// SecurityPolicyError.ChallengeURL, etc.) appear at the top level of the
|
|
// envelope alongside the shared fields, not nested under a `detail` key.
|
|
//
|
|
// # Working with typed errors
|
|
//
|
|
// Use ProblemOf to read shared fields polymorphically:
|
|
//
|
|
// if p, ok := errs.ProblemOf(err); ok {
|
|
// log.Printf("category=%s subtype=%s retryable=%t", p.Category, p.Subtype, p.Retryable)
|
|
// }
|
|
//
|
|
// Use the IsXxx predicates or stdlib errors.As to branch on concrete type:
|
|
//
|
|
// if errs.IsPermission(err) {
|
|
// var pe *errs.PermissionError
|
|
// _ = errors.As(err, &pe)
|
|
// fmt.Println("missing scopes:", pe.MissingScopes)
|
|
// }
|
|
//
|
|
// Use WrapInternal at boundaries to lift any non-typed error to
|
|
// *InternalError; typed errors pass through unchanged.
|
|
package errs
|