mirror of
https://github.com/larksuite/cli.git
synced 2026-07-08 10:08:02 +08:00
461e3c62c9
Introduces extension/platform — the in-process plugin SDK external
Go forks of lark-cli use to extend or restrict the command surface.
Plugins compile in via blank import; there is no dynamic loading
and no RPC isolation.
Public SDK (extension/platform):
- Plugin interface (Name / Version / Capabilities / Install).
- Registrar verbs: Observe, Wrap, On, Restrict.
- Hook types: Observer (side-effect, panic-safe, fires Before/After
RunE), Wrapper (middleware, may short-circuit via AbortError),
LifecycleHandler (Startup / Shutdown), Selector with nil-safe
And/Or/Not composition.
- Risk / Identity are defined string types with closed taxonomies;
ParseRisk / ParseIdentity convert raw strings with the
absent-vs-invalid distinction the engine relies on.
- Builder ergonomic constructor (NewPlugin().Observer().Wrap()
...MustBuild()) that enforces name/hookName grammar, hookName
uniqueness, and the Restrict ↔ FailClosed pairing regardless of
call order.
- Invocation is a read-only interface; the framework's concrete
invocation type lives in internal/hook so plugins cannot
fabricate denial / strict-mode / identity state. Args() returns
a defensive copy on every call so hook mutation cannot leak
into the original RunE.
- CommandDeniedError + AbortError carry structured fields for the
closed `command_denied` / `hook` envelope contract.
- ResetForTesting gated behind //go:build testing.
- README + godoc examples (Observer / Wrapper / Restrict) + two
runnable example forks (audit-observer, readonly-policy).
Host (internal/platform, internal/hook, internal/cmdpolicy):
- InstallAll: staged plugin registration with atomic commit, panic
isolation, FailOpen / FailClosed semantics, RequiredCLIVersion
semver check, single-Restrict invariant, duplicate-plugin-name
detection.
- hook.Install wraps every runnable cmd.RunE with:
Before observers (panic-safe) → denial guard → composed Wrap
chain → original RunE → After observers (always fire, even on
err). Denied commands physically bypass the Wrap chain so a
plugin Wrapper cannot suppress or rewrite a denial; observers
still see the attempt for audit.
- Recover shim around plugin Wrappers converts panics (including
the factory call) into a structured `hook` envelope with
reason_code=panic; namespacing shim attributes AbortError to
the namespaced hook name.
- cmdpolicy (renamed from internal/pruning) is the user-layer
command policy engine: walks the cobra tree, evaluates each
runnable command against a Rule's four-axis filter (Allow /
Deny / MaxRisk / Identities), produces parent-group aggregate
denials, and installs denyStubs. Rule.AllowUnannotated opts out
of the unannotated-deny gate for gradual adoption; risk_invalid
typos always deny with an edit-distance "did you mean"
suggestion.
- Strict-mode stub in cmd/prune.go composes the shared
detail.* / wrapped CommandDeniedError shape via cmdpolicy
helpers (BuildDenialError / CommandDeniedFromDenial /
DenialDetailMap), so command_denied envelopes from strict-mode
and user-layer policy carry the same closed-enum fields
(detail.layer / reason_code / policy_source). The historical
short Message + independent Hint are preserved unchanged.
- cmdpolicy/yaml: structural parsing of ~/.lark-cli/policy.yml
with KnownFields strict mode, including allow_unannotated.
- `config policy show` / `config policy validate` and the plugin
inventory diagnostic surface the resolved Rule (allow,
deny, max_risk, identities, allow_unannotated) and the hook
contributions per plugin.
Envelope contract (docs/extension/reason-codes.md):
- error.type is a closed set: command_denied, hook, plugin_install,
plugin_conflict, plugin_lifecycle.
- reason_code is a closed enum per error.type, dispatched on by
external agents and CI integrations.
- detail.layer = "policy" | "strict_mode" attributes the rejection.
Build / CI:
- Makefile unit-test / vet / coverage and ci.yml fast-gate +
unit-test + coverage now pass -tags testing so register_testing.go
is visible; ./extension/... is in the package list so the SDK's
own tests actually run.
- fmt-check and examples-build Makefile targets.
- bmatcuk/doublestar/v4 added as a direct dependency for `**` glob
matching in Rule.Allow / Rule.Deny.
Author-facing material:
- docs/extension/ (quickstart, plugin-author-guide, reason-codes)
is provided in the working tree but kept out of git tracking
per repo convention (.gitignore covers docs/).
Change-Id: I3b8ecc2923bd54c2dff19e5dce8a0855a6f9e703
58 lines
2.1 KiB
Go
58 lines
2.1 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package internalplatform
|
|
|
|
import "fmt"
|
|
|
|
// PluginInstallError is the typed install-time failure. ReasonCode comes
|
|
// from the closed enum in the design doc (section 5.3 reason_code
|
|
// table). Cause carries the underlying error, if any, so consumers can
|
|
// errors.As to inspect it.
|
|
type PluginInstallError struct {
|
|
PluginName string
|
|
ReasonCode string
|
|
Reason string
|
|
Cause error
|
|
}
|
|
|
|
func (e *PluginInstallError) Error() string {
|
|
prefix := fmt.Sprintf("plugin %q (%s)", e.PluginName, e.ReasonCode)
|
|
if e.Reason != "" {
|
|
prefix += ": " + e.Reason
|
|
}
|
|
if e.Cause != nil {
|
|
prefix += ": " + e.Cause.Error()
|
|
}
|
|
return prefix
|
|
}
|
|
|
|
func (e *PluginInstallError) Unwrap() error { return e.Cause }
|
|
|
|
// ReasonCodes for PluginInstallError. The closed enum is referenced by
|
|
// the design doc's hard-constraint #15 (reason_code enum closure) and
|
|
// drives the JSON envelope's error.detail.reason_code field.
|
|
const (
|
|
ReasonInvalidPluginName = "invalid_plugin_name"
|
|
ReasonPluginNamePanic = "plugin_name_panic"
|
|
ReasonInvalidHookName = "invalid_hook_name"
|
|
ReasonDuplicateHookName = "duplicate_hook_name"
|
|
ReasonInvalidHookRegister = "invalid_hook_registration"
|
|
ReasonInvalidRule = "invalid_rule"
|
|
ReasonDoubleRestrict = "double_restrict"
|
|
ReasonRestrictsMismatch = "restricts_mismatch"
|
|
ReasonCapabilityUnmet = "capability_unmet"
|
|
ReasonCapabilitiesPanic = "capabilities_panic"
|
|
// ReasonInvalidCapability flags a plugin authoring error in
|
|
// Capabilities() output -- e.g. a syntactically malformed
|
|
// RequiredCLIVersion string. This is distinct from
|
|
// ReasonCapabilityUnmet (legitimate version mismatch): an authoring
|
|
// bug must NOT be hidden by FailurePolicy=FailOpen, so this code is
|
|
// classified as untrusted-config and aborts unconditionally.
|
|
ReasonInvalidCapability = "invalid_capability"
|
|
ReasonInstallFailed = "install_failed"
|
|
ReasonInstallPanic = "install_panic"
|
|
ReasonDuplicatePluginName = "duplicate_plugin_name"
|
|
ReasonMultipleRestricts = "multiple_restrict_plugins"
|
|
)
|