Files
pipelines/internal/skills/validate.go
T
alan a733a927f3 Finalize reviewed destination and skill changes
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.
2026-11-12 11:30:17 +00:00

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
}