Files
skillshare/internal/skillpkg/skillpkg.go
T
Willie 1c7cf1259c fix(mcp): read only the file the link check saw
Files were checked with Lstat and then opened by path, so one replaced
by a link in between was followed and published. Each read now checks
that the opened file is the one Lstat described, and skips the skill
otherwise.
2026-10-06 16:59:50 +08:00

214 lines
6.9 KiB
Go

// Package skillpkg reads one skill directory as an Agent Skills package: its
// full frontmatter and every regular file, within the SEP-2640 limits. It has
// no configuration dependencies, so sync can share its naming rules.
package skillpkg
import (
"crypto/sha256"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"unicode"
"unicode/utf8"
"golang.org/x/text/unicode/norm"
"skillshare/internal/sourcewalk"
"skillshare/internal/utils"
)
// Per-skill limits from SEP-2640, and the Agent Skills field limits in characters.
const (
MaxFiles = 512
MaxBytes = 16 << 20
MaxDescription = 1024
MaxCompatibility = 500
)
// File is one regular file of a package. Digest and Size come from one read, so
// they describe the same bytes even when the file changes while it is loaded.
type File struct {
Path string // absolute
Rel string // slash-separated, relative to the package directory
Digest string // sha256:<hex>
Size int64
}
// Package is a valid skill directory. Its SKILL.md entry is the read the
// frontmatter was parsed from.
type Package struct {
Dir string // resolved
Frontmatter map[string]any
Files []File
}
var errTooLarge = fmt.Errorf("is larger than %d MiB", MaxBytes>>20)
// Load reads the skill in dir. The error says why the directory is not a
// valid package. .git directories are left out; links are neither listed nor read.
func Load(dir string) (*Package, error) {
dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's
dir = utils.ResolveSymlink(dir)
// A linked SKILL.md would be missing from the manifest, which lists no links.
skillPath := filepath.Join(dir, "SKILL.md")
info, err := os.Lstat(skillPath)
if err != nil {
return nil, err
}
if !info.Mode().IsRegular() {
return nil, fmt.Errorf("SKILL.md is not a regular file")
}
content, err := readAtMost(skillPath, info, MaxBytes)
if err != nil {
return nil, err
}
fm, err := utils.ParseFrontmatterMap(content)
if err != nil {
return nil, fmt.Errorf("SKILL.md has %w", err)
}
name, _ := fm["name"].(string)
if reason := ValidateName(name, dirName); reason != "" {
return nil, fmt.Errorf("%s", reason)
}
desc, _ := fm["description"].(string)
if strings.TrimSpace(desc) == "" {
return nil, fmt.Errorf("SKILL.md is missing a description")
}
if n := utf8.RuneCountInString(desc); n > MaxDescription {
return nil, fmt.Errorf("description has %d characters; the limit is %d", n, MaxDescription)
}
// metadata is left unchecked: the format wants string values, but lists there are
// common and tool clients read them fine, so skipping those skills would cost more.
compat, ok := fm["compatibility"].(string)
if _, set := fm["compatibility"]; set && (!ok || compat == "") {
return nil, fmt.Errorf("compatibility must be non-empty text")
}
if n := utf8.RuneCountInString(compat); n > MaxCompatibility {
return nil, fmt.Errorf("compatibility has %d characters; the limit is %d", n, MaxCompatibility)
}
p := &Package{Dir: dir, Frontmatter: fm, Files: []File{{Path: skillPath, Rel: "SKILL.md", Digest: Digest(content), Size: int64(len(content))}}}
// Every read is bounded by what is left of the package budget, so a file that
// grows while it is read cannot push the package past the limit.
left := MaxBytes - int64(len(content))
err = sourcewalk.Walk(dir, sourcewalk.Options{}, func(path string, info os.FileInfo, err error) error {
if err != nil {
return err
}
if info.IsDir() {
if info.Name() == ".git" {
return filepath.SkipDir
}
return nil
}
if !info.Mode().IsRegular() {
return nil
}
rel, err := filepath.Rel(dir, path)
if err != nil || rel == "SKILL.md" { // SKILL.md is listed from the read above
return err
}
if len(p.Files) == MaxFiles {
return fmt.Errorf("has more than %d files", MaxFiles)
}
sum, n, err := hashAtMost(path, info, left)
if err != nil {
return err
}
left -= n
p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Digest: sum, Size: n})
return nil
})
if err != nil {
return nil, err
}
return p, nil
}
// Digest is the manifest digest of b.
func Digest(b []byte) string { return fmt.Sprintf("sha256:%x", sha256.Sum256(b)) }
// openSame opens path and checks that it is the file info (from Lstat) described,
// so a file swapped for a link after it was checked is not followed.
func openSame(path string, info os.FileInfo) (*os.File, error) {
f, err := os.Open(path)
if err != nil {
return nil, err
}
if got, err := f.Stat(); err != nil || !os.SameFile(info, got) {
f.Close()
return nil, fmt.Errorf("%s changed while it was read", filepath.Base(path))
}
return f, nil
}
// readAtMost reads the file, failing past limit bytes.
func readAtMost(path string, info os.FileInfo, limit int64) ([]byte, error) {
f, err := openSame(path, info)
if err != nil {
return nil, err
}
defer f.Close()
data, err := io.ReadAll(io.LimitReader(f, limit+1))
if err != nil {
return nil, err
}
if int64(len(data)) > limit {
return nil, errTooLarge
}
return data, nil
}
// hashAtMost streams the file into its digest and size, failing past limit bytes.
func hashAtMost(path string, info os.FileInfo, limit int64) (string, int64, error) {
f, err := openSame(path, info)
if err != nil {
return "", 0, err
}
defer f.Close()
h := sha256.New()
n, err := io.Copy(h, io.LimitReader(f, limit+1))
if err != nil {
return "", 0, err
}
if n > limit {
return "", 0, errTooLarge
}
return fmt.Sprintf("sha256:%x", h.Sum(nil)), n, nil
}
// ValidateName returns why a SKILL.md name breaks the Agent Skills naming rules
// (including name == directory name), or "" when it follows them. Like the
// reference validator, it checks lowercase Unicode letters and digits after NFKC
// normalization and counts the limit in characters.
func ValidateName(name, dirName string) string {
// Not trimmed: surrounding whitespace is not a letter, digit or hyphen, so it fails below.
exact := name
name = norm.NFKC.String(name)
if name == "" {
return "SKILL.md is missing a name"
}
if utf8.RuneCountInString(name) > 64 {
return fmt.Sprintf("SKILL.md name %q is longer than 64 characters", name)
}
if strings.HasPrefix(name, "-") || strings.HasSuffix(name, "-") {
return fmt.Sprintf("SKILL.md name %q cannot start or end with '-'", name)
}
if strings.Contains(name, "--") {
return fmt.Sprintf("SKILL.md name %q cannot contain consecutive hyphens", name)
}
if name != strings.ToLower(name) || strings.ContainsFunc(name, func(r rune) bool {
return r != '-' && !unicode.IsLetter(r) && !unicode.IsNumber(r)
}) {
return fmt.Sprintf("SKILL.md name %q must use only lowercase letters, numbers, and hyphens", name)
}
// Exactly, not only after NFKC: the directory is the skill path's last segment,
// which the Skills extension requires to equal the name.
if exact != dirName {
return fmt.Sprintf("SKILL.md name %q does not match directory name %q", exact, dirName)
}
return ""
}