mirror of
https://github.com/larksuite/cli.git
synced 2026-07-07 00:55:53 +08:00
a07239b923
Add strongly-typed shortcut protocol that coexists with the legacy
common.Shortcut. The new common.TypedShortcut[T] is a generic outer
wrapper backed by a reflect-driven binder; both legacy and typed
shortcuts satisfy a new common.Mountable / common.ShortcutDescriptor
interface pair so register.go can dispatch either through the same
pipeline.
Framework (shortcuts/common):
- protocol.go — Mountable / ShortcutDescriptor / OneOfMarker /
Validatable / Normalizable[T] / ArgsValidator / Maybe[T] /
HelpExample
- binder.go — reflect Args walk, intra-Args flag-tag uniqueness
panic, cobra flag registration, bindFlags + bindMaybe, runNormalize
(via MethodByName dispatch — Normalizable[T] can't be type-asserted
through a non-generic interface), runValidateValue, runFrameworkRules
for required / enum / OneOf / group
- typed_shortcut.go — TypedShortcut[T] struct, 8 descriptor methods,
mountTyped adapter that synthesizes a legacy Shortcut shell and
reuses runShortcut verbatim (identity / scopes / @file / stdin / jq
/ dry-run / high-risk gate)
- typed_help.go — sectioned --help (CHOOSE ONE / OPTIONAL / EXAMPLES)
with cmdutil.GetRisk/GetTips passthrough so typed shortcuts keep the
Risk: and Tips: blocks
- runner.go — typedArgs lifecycle slot on RuntimeContext
- types.go — 5 GetX accessors on *Shortcut so legacy shortcuts
satisfy ShortcutDescriptor alongside the existing pointer-receiver
scope methods
Typed primitives (shortcuts/common/argstype):
- ChatID / UserOpenID / UserOpenIDList — prefix-validated identifiers
- SafePath — cwd-relative, rejects absolute paths and ".." segments
- MediaInput — tri-state (URL bypass / img_xxx-file_xxx key bypass /
SafePath delegation)
- SpreadsheetRef — Normalize extracts shtcn token from feishu URLs
Error contract (errs):
- 3 new Subtype constants: shortcut_oneof_missing /
shortcut_oneof_multiple / shortcut_group_incomplete. Per-field
failures (required / enum / typed primitive format) reuse the
existing SubtypeInvalidArgument so no new error type is introduced.
Registry refactor (shortcuts + cmd):
- AllShortcuts() now returns []common.ShortcutDescriptor; legacy
shortcuts are boxed as *Shortcut (pointer required for the
pointer-receiver scope methods), typed shortcuts boxed as Mountable
- Register dispatches via the Mountable interface
- cmd/auth/login, cmd/auth/login_interactive, cmd/error_auth_hint,
cmd/diagnose_scope_test, shortcuts/register_test (shortcuts.json
generator) updated to read through GetService / GetCommand /
GetAuthTypes / GetDescription / DeclaredScopesForIdentity
- shortcutSupportsIdentity helpers accept ShortcutDescriptor
Pilot (shortcuts/im):
- protocol.go — MessageTarget / MessageContent (with seven content
variants) / VideoContent (paired video + cover) / RawContent
(--content with explicit msg-type, validates JSON in
ValidateValue)
- im_messages_send.go — migrated to TypedShortcut[*ImMessagesSendArgs].
Inline Validate closure is replaced by framework-derived checks
(OneOf target, OneOf content, VideoContent group, typed-primitive
formats, RawContent JSON). Helpers (resolveMediaContent,
wrapMarkdownAsPostForDryRun, normalizeAtMentions, etc.) reused
verbatim; only the field-access pattern changes from
runtime.Str("x") to args.X.
- shortcuts.go — new TypedShortcuts() exporter; ImMessagesSend
removed from the legacy Shortcuts() slice so it is not
double-mounted
- register.go wires addTyped(im.TypedShortcuts()) into init
Known follow-ups:
- runFrameworkRules and bindFlags do not recurse into OneOf bucket /
group sub-structs; im messages-send compensates with a local
bindMessagesSendArgs + validateVideoGroup. Generalizing the binder
to recurse will let future migrations drop the local shim.
- common.ValidateChatID / common.ValidateUserID become redundant
once all legacy shortcuts that call them migrate; can be retired
with the last legacy caller.
Refs: docs/superpowers/specs/2026-05-26-shortcut-protocol-design.md