GitLabgitlab-org

cli

main
ply8 git calls219 ms99 KiB6 cachedprotocol v2
160 lines4.6 KiBRaw
1// Package remote is the source for agent skills hosted on gitlab.com and
2// listed in this repo's curated registry. Discovery (`All`) is offline —
3// metadata comes from the embedded registry.yaml. Installation (`Get`)
4// reaches gitlab.com to fetch the actual SKILL.md and supporting files
5// at the pinned ref.
6package remote
8import (
9 _ "embed"
10 "errors"
11 "fmt"
12 "net/http"
13 "regexp"
14 "sort"
15 "sync"
17 "go.yaml.in/yaml/v3"
19 "gitlab.com/gitlab-org/cli/internal/commands/skills/skill"
22//go:embed registry.yaml
23var registryYAML []byte
25// supportedRegistryVersion is the only registry schema version this
26// build understands. Bump it (and the loader) if the format ever needs
27// breaking changes; older glab binaries should refuse unknown versions
28// rather than silently misread them.
29const supportedRegistryVersion = 1
31// ErrNotFound is returned by Get when no entry in the curated remote
32// registry matches the requested name.
33var ErrNotFound = errors.New("not in remote registry")
35// Entry is a single row in registry.yaml — the curated pointer to a
36// remote skill. The description exists purely so `skills list` can
37// render without a network call. Name is the public skill name and
38// install directory; when the upstream SKILL.md frontmatter names the
39// skill differently, the fetcher rewrites it to Name at install time.
40type Entry struct {
41 Name string `yaml:"name"`
42 Description string `yaml:"description"`
43 Project string `yaml:"project"`
44 Ref string `yaml:"ref"`
45 Path string `yaml:"path"`
48type registryFile struct {
49 Version int `yaml:"version"`
50 Skills []Entry `yaml:"skills"`
53// skillNamePattern is the name format required by the Agent Skills spec.
54var skillNamePattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
56var (
57 loadOnce sync.Once
58 entries []Entry
59 loadErr error
62// All returns every registered remote skill as metadata-only Skills
63// (Files is nil). It performs no network I/O.
64func All() ([]skill.Skill, error) {
65 loadOnce.Do(load)
66 if loadErr != nil {
67 return nil, loadErr
68 }
69 out := make([]skill.Skill, 0, len(entries))
70 for _, e := range entries {
71 out = append(out, skill.Skill{
72 Name: e.Name,
73 Description: e.Description,
74 Source: skill.SourceRemote,
75 })
76 }
77 return out, nil
80// Get fetches the named remote skill from gitlab.com and returns it
81// with files populated. Returns an error if the registry doesn't list
82// the name or the fetch fails.
83func Get(name string) (skill.Skill, error) {
84 loadOnce.Do(load)
85 if loadErr != nil {
86 return skill.Skill{}, loadErr
87 }
89 var entry *Entry
90 for i := range entries {
91 if entries[i].Name == name {
92 entry = &entries[i]
93 break
94 }
95 }
96 if entry == nil {
97 return skill.Skill{}, fmt.Errorf("%w: %q", ErrNotFound, name)
98 }
100 f := newFetcher(http.DefaultClient)
101 return f.fetch(*entry)
104func load() {
105 var rf registryFile
106 if err := yaml.Unmarshal(registryYAML, &rf); err != nil {
107 loadErr = fmt.Errorf("parsing remote skills registry: %w", err)
108 return
109 }
111 if rf.Version != supportedRegistryVersion {
112 loadErr = fmt.Errorf("remote skills registry version %d is unsupported (expected %d)", rf.Version, supportedRegistryVersion)
113 return
114 }
116 if err := validateEntries(rf.Skills); err != nil {
117 loadErr = err
118 return
119 }
121 // Defensive: sort so All() output is deterministic regardless of
122 // how the generator wrote registry.yaml. The generator already
123 // sorts on insert, but we don't want to rely on that contract.
124 sort.Slice(rf.Skills, func(i, j int) bool { return rf.Skills[i].Name < rf.Skills[j].Name })
125 entries = rf.Skills
128// validateEntries checks per-entry sanity and cross-entry uniqueness.
129// We intentionally don't enforce ref format here — `latest`, tags, and
130// SHAs are all valid; per-entry tightening is a hand-review decision.
131func validateEntries(es []Entry) error {
132 seen := map[string]bool{}
133 var errs []error
134 for i, e := range es {
135 if e.Name == "" {
136 errs = append(errs, fmt.Errorf("entry %d: missing 'name'", i))
137 continue
138 }
139 if !skillNamePattern.MatchString(e.Name) {
140 errs = append(errs, fmt.Errorf("entry %q: name must be lowercase letters, digits, and single hyphens", e.Name))
141 }
142 if e.Description == "" {
143 errs = append(errs, fmt.Errorf("entry %q: missing 'description'", e.Name))
144 }
145 if e.Project == "" {
146 errs = append(errs, fmt.Errorf("entry %q: missing 'project'", e.Name))
147 }
148 if e.Ref == "" {
149 errs = append(errs, fmt.Errorf("entry %q: missing 'ref'", e.Name))
150 }
151 if e.Path == "" {
152 errs = append(errs, fmt.Errorf("entry %q: missing 'path'", e.Name))
153 }
154 if seen[e.Name] {
155 errs = append(errs, fmt.Errorf("entry %q is listed more than once", e.Name))
156 }
157 seen[e.Name] = true
158 }
159 return errors.Join(errs...)
Diagnostics8 git calls · 219 ms
CallStatusSizeTime0219 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchtree:02001.8 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=1857
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1857
git.pkt.payload.max=1830
git.sideband.band1.bytes=1830
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1830
git.pack.trailer=fb03183b7909876778f740d196d7516811003517
Open pack map
fetchtree:0200370 B · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=370
git.response.cache=HIT
git.response.duration_ms=5
git.fetch.filter=tree:0
git.fetch.wants=290ae7a62f76e23cbbd60697570f19b90ddcece6
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=370
git.pkt.payload.max=343
git.sideband.band1.bytes=343
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=343
git.pack.trailer=0795a26d2b25022c69da2ef2e68cfb92a77ef4bb
Open pack map
fetchtree:0200205 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=205
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=81dc066a953916d0f0a002cd7235dfc47cfbe9ea
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=205
git.pkt.payload.max=178
git.sideband.band1.bytes=178
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=178
git.pack.trailer=a6b69d21421b8ef5347f95fc10c7bb5be79155a9
Open pack map
fetch2002.0 KiB203 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=203
git.response.bytes=2007
git.response.cache=MISS
git.response.duration_ms=203
git.fetch.wants=1713f8e2c5dd5061f95ba893aa9002a34b6ec405
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2007
git.pkt.payload.max=1980
git.sideband.band1.bytes=1980
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e2d9649c5c14c2
Request
30293b17…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format