a733a927f3
Preserve Settings as an independent navigation destination while landing the reviewed notification and skill-management updates. Keep the server and CLI skill contracts versioned and validated so the merged tree can be verified by the delivery gate.
174 lines
4.3 KiB
Go
174 lines
4.3 KiB
Go
// Package skills validates and fingerprints Claude/Codex/OpenCode/Pi skill bundles.
|
|
package skills
|
|
|
|
import (
|
|
"crypto/sha256"
|
|
"encoding/hex"
|
|
"fmt"
|
|
"io/fs"
|
|
"os"
|
|
"path/filepath"
|
|
"regexp"
|
|
"sort"
|
|
"strings"
|
|
)
|
|
|
|
const (
|
|
MaxFiles = 200
|
|
MaxTotalBytes = 5 * 1024 * 1024
|
|
MaxFileBytes = 1024 * 1024
|
|
)
|
|
|
|
var slug = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
|
|
|
|
// ValidateName checks the server-facing skill name before it is used in a
|
|
// filesystem path.
|
|
func ValidateName(name string) error {
|
|
if !slug.MatchString(name) {
|
|
return fmt.Errorf("skill name must be a lowercase slug")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
type File struct {
|
|
Path string
|
|
Bytes []byte
|
|
}
|
|
type Bundle struct {
|
|
Name, Description, Digest string
|
|
Files []File
|
|
TotalBytes int64
|
|
}
|
|
|
|
func Validate(root string) (Bundle, error) {
|
|
root, err := filepath.Abs(root)
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
st, err := os.Lstat(root)
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
if st.Mode()&os.ModeSymlink != 0 {
|
|
return Bundle{}, fmt.Errorf("symlinks are not allowed: %s", root)
|
|
}
|
|
if !st.IsDir() {
|
|
return Bundle{}, fmt.Errorf("skill path is not a directory")
|
|
}
|
|
var files []File
|
|
err = filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
|
|
if walkErr != nil {
|
|
return walkErr
|
|
}
|
|
rel, e := filepath.Rel(root, path)
|
|
if e != nil {
|
|
return e
|
|
}
|
|
if rel == "." {
|
|
return nil
|
|
}
|
|
if d.Type()&os.ModeSymlink != 0 {
|
|
return fmt.Errorf("symlinks are not allowed: %s", rel)
|
|
}
|
|
if d.IsDir() {
|
|
if filepath.Dir(rel) == "." && rel != "references" && rel != "scripts" && rel != "assets" {
|
|
return fmt.Errorf("unsupported top-level directory: %s", rel)
|
|
}
|
|
return nil
|
|
}
|
|
clean := filepath.ToSlash(rel)
|
|
if filepath.Dir(rel) == "." && clean != "SKILL.md" {
|
|
return fmt.Errorf("unsupported top-level file: %s", clean)
|
|
}
|
|
if filepath.IsAbs(rel) || strings.HasPrefix(clean, "../") || clean == ".." {
|
|
return fmt.Errorf("invalid path: %s", rel)
|
|
}
|
|
if filepath.Base(rel) == "SKILL.md" && filepath.Dir(rel) != "." {
|
|
return fmt.Errorf("nested SKILL.md is not allowed: %s", rel)
|
|
}
|
|
if len(files) >= MaxFiles {
|
|
return fmt.Errorf("skill has more than %d files", MaxFiles)
|
|
}
|
|
info, e := d.Info()
|
|
if e != nil {
|
|
return e
|
|
}
|
|
if info.Size() > MaxFileBytes {
|
|
return fmt.Errorf("file %s exceeds %d bytes", clean, MaxFileBytes)
|
|
}
|
|
b, e := os.ReadFile(path)
|
|
if e != nil {
|
|
return e
|
|
}
|
|
if info.Mode()&0111 != 0 && !strings.HasPrefix(clean, "scripts/") {
|
|
return fmt.Errorf("executable outside scripts/: %s", clean)
|
|
}
|
|
files = append(files, File{Path: clean, Bytes: b})
|
|
return nil
|
|
})
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
sort.Slice(files, func(i, j int) bool { return files[i].Path < files[j].Path })
|
|
var md []byte
|
|
for _, f := range files {
|
|
if f.Path == "SKILL.md" {
|
|
md = f.Bytes
|
|
break
|
|
}
|
|
}
|
|
if md == nil {
|
|
return Bundle{}, fmt.Errorf("skill must contain exactly one top-level SKILL.md")
|
|
}
|
|
name, desc, err := frontmatter(md)
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
if err := ValidateName(name); err != nil {
|
|
return Bundle{}, fmt.Errorf("frontmatter name must be a lowercase slug")
|
|
}
|
|
var total int64
|
|
h := sha256.New()
|
|
for _, f := range files {
|
|
total += int64(len(f.Bytes))
|
|
fmt.Fprintf(h, "%s\x00%d\x00", f.Path, len(f.Bytes))
|
|
h.Write(f.Bytes)
|
|
}
|
|
if total > MaxTotalBytes {
|
|
return Bundle{}, fmt.Errorf("skill exceeds %d total bytes", MaxTotalBytes)
|
|
}
|
|
return Bundle{Name: name, Description: desc, Digest: hex.EncodeToString(h.Sum(nil)), Files: files, TotalBytes: total}, nil
|
|
}
|
|
|
|
func frontmatter(b []byte) (string, string, error) {
|
|
s := strings.ReplaceAll(string(b), "\r\n", "\n")
|
|
lines := strings.Split(s, "\n")
|
|
if len(lines) < 3 || strings.TrimSpace(lines[0]) != "---" {
|
|
return "", "", fmt.Errorf("SKILL.md must begin with YAML frontmatter")
|
|
}
|
|
name, desc := "", ""
|
|
end := -1
|
|
for i := 1; i < len(lines); i++ {
|
|
if strings.TrimSpace(lines[i]) == "---" {
|
|
end = i
|
|
break
|
|
}
|
|
k, v, ok := strings.Cut(lines[i], ":")
|
|
if !ok {
|
|
continue
|
|
}
|
|
v = strings.TrimSpace(v)
|
|
v = strings.Trim(v, "\"'")
|
|
switch strings.TrimSpace(k) {
|
|
case "name":
|
|
name = v
|
|
case "description":
|
|
desc = v
|
|
}
|
|
}
|
|
if end < 0 || name == "" || desc == "" {
|
|
return "", "", fmt.Errorf("SKILL.md frontmatter requires name and description")
|
|
}
|
|
return name, desc, nil
|
|
}
|