Documentation
¶
Overview ¶
Package affordance is the lazily-loaded store of usage guidance for service-API methods. The source of truth is one markdown file per service in the top-level affordance/ tree (see mdparse.go), injected via SetSource so domain owners maintain it next to skills/ and shortcuts/.
Guidance is keyed by method id, but the markdown headings use the command form ("user_mailbox messages list"), and mapping one to the other needs the API catalog that built the command tree. A Resolver therefore belongs to one build: it pairs the content tree with that build's Catalog and resolves each service at most once, so normal command execution never touches the markdown and help rendering never rebuilds a mapping it already has.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetSource ¶
SetSource installs the markdown guidance tree (the top-level affordance/ directory) as the content source for Resolvers created afterwards. Called once at startup before any lookup.
func SkillStatPath ¶ added in v1.0.67
SkillStatPath maps a domain- or command-level Skills entry to the path (relative to the skill tree) whose existence gates it: a bare skill name resolves to its SKILL.md, while an entry containing a slash is a name/relative-path reference (e.g. "lark-contact/references/lark-contact-search-user.md") and resolves to that path directly. Both render as `lark-cli skills read <entry>` — the slash form skills read already accepts — so an entry can point at a command's own reference file, not just re-point the domain skill.
Types ¶
type Resolver ¶ added in v1.0.95
type Resolver struct {
// contains filtered or unexported fields
}
Resolver serves guidance for one build: one content tree paired with the Catalog whose command forms the headings are written against. Each service is read, parsed, and mapped once, on first access.
func NewResolver ¶ added in v1.0.95
func NewResolver(source fs.FS, catalog apicatalog.Catalog) *Resolver
NewResolver pairs a guidance tree with the catalog that built the command tree. A nil source yields a Resolver that reports no guidance.
func (*Resolver) DomainSkill ¶ added in v1.0.95
DomainSkill returns the service-level canonical skill declared by `> skill:`. That declaration is independent of method command mappings.
func (*Resolver) DomainSkills ¶ added in v1.0.95
DomainSkills returns the skill references configured for service-level help. The canonical `> skill:` entry is first when present, followed by entries in the domain's `## Skills` section. The returned slice is a copy so callers cannot mutate the cache.
func (*Resolver) For ¶ added in v1.0.95
func (r *Resolver) For(service, methodID string) (json.RawMessage, bool)
For returns the raw affordance overlay for one method, loading the owning service on first access. ok is false when there is no entry (absent source, parse failure, or unknown method all collapse to "no guidance"). A nil Resolver reports no guidance.
Source Files