mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
* feat(mcp): support Skills directory reads and metadata listing Expose accepted skill directories and SKILL.md metadata so MCP hosts can browse served packages without guessing manifest filenames. Reuse catalog selection and refresh boundaries, including empty directories and stable pagination, and normalize strict frontmatter for YAML 1.2 Core readback. Add regressions and a pinned official conformance runner, and update the runbook and MCP references to describe the browsing contract. Refs #895 * fix(mcp): preserve supporting file MIME types in directory listings Record UTF-8 classification from the same bounded bytes used for package digests so directory metadata agrees with resource reads for extensionless and unknown-extension text. Reuse the existing bounded reader without adding listing-time payload reads or changing package limits. Share pagination with skills/list, trust the SDK's typed request boundary, and repair the pagination regression to detect stale catalog snapshots. Refs #895 * fix(mcp): stream supporting file metadata inspection Buffering supporting files during catalog refresh allocated with asset size. Restore one bounded stream for digest, size and UTF-8 classification, retaining at most three incomplete rune bytes and consuming invalid text through EOF. Preserve the existing same-file checks, package caps and SKILL.md byte reader. Keep real package-load benchmarks and strengthen the existing MIME fixtures for split runes and bytes after invalid sequences. Use one first-match sed command for the conformance URL without a truncated pipeline under pipefail. Scoped packages, focused race tests, vet, shell syntax/shellcheck and all 45 pinned official checks pass. Allocation stays near 48 KB for 64 KiB and 8 MiB assets; multibyte UTF-8 validation still costs CPU versus digest-only loading. * test(mcp): consolidate directory and frontmatter coverage Check every directory continuation URI so a duplicated middle entry cannot hide a missing resource. Keep the existing before/after-cursor refresh cases. Merge nested-skill acceptance fixtures in the catalog owner, preserving all skill-count, skip-warning and directory assertions across configured and targetless cases. Move directory capability coverage to initialization and merge scalar, alias and rejection cases under the existing parser test. Give cached-page benchmark skills names that match their URI directories. Narrow tests, benchmark smoke and vet pass; duplicate-result and stale-catalog mutations both fail, then restored source passes. Production is unchanged.
264 lines
7.8 KiB
Go
264 lines
7.8 KiB
Go
package utils
|
|
|
|
import (
|
|
"bytes"
|
|
"encoding/json"
|
|
"fmt"
|
|
"os"
|
|
"path/filepath"
|
|
"strings"
|
|
|
|
"gopkg.in/yaml.v3"
|
|
)
|
|
|
|
// IsRootFrontmatterLine reports whether a nonblank, noncomment line shares the
|
|
// first content line's indentation. Initialize *indent to -1 for each
|
|
// frontmatter block.
|
|
func IsRootFrontmatterLine(raw string, indent *int) bool {
|
|
trimmed := strings.TrimSpace(raw)
|
|
if trimmed == "" || trimmed[0] == '#' {
|
|
return false
|
|
}
|
|
lineIndent := len(raw) - len(strings.TrimLeft(raw, " \t"))
|
|
if *indent < 0 {
|
|
*indent = lineIndent
|
|
}
|
|
return lineIndent == *indent
|
|
}
|
|
|
|
// ParseSkillName reads the SKILL.md and extracts the top-level "name" from frontmatter.
|
|
// It reads line by line and stops at a plain top-level name line ("name", 'name' and
|
|
// name : count; top-level keys share the first key's indent). Any other form YAML
|
|
// allows (flow mapping, block scalar, alias, merge key, explicit key, ...) leaves the
|
|
// scan without a name, and then the whole block is decoded.
|
|
func ParseSkillName(skillPath string) (string, error) {
|
|
name, literal, indent := "", "", -1
|
|
path := filepath.Join(skillPath, "SKILL.md")
|
|
err := scanLenientBlock(path, func(raw []byte) bool {
|
|
line := string(raw)
|
|
trimmed := strings.TrimLeft(line, " \t")
|
|
if !IsRootFrontmatterLine(line, &indent) {
|
|
return true
|
|
}
|
|
key, value, ok := strings.Cut(trimmed, ":")
|
|
if !ok || strings.Trim(strings.TrimSpace(key), `"'`) != "name" {
|
|
return true
|
|
}
|
|
if v := strings.TrimSpace(value); v != "" && strings.ContainsRune("*|>&!", rune(v[0])) {
|
|
return false // alias, block scalar, anchor or tag: decode the whole block
|
|
}
|
|
// The line alone decodes quotes and a trailing comment. When it does not decode to
|
|
// a string (a multi-line quoted scalar, a number), the whole block is decoded, and
|
|
// the line read as is is kept for frontmatter YAML rejects.
|
|
var fm map[string]any
|
|
if yaml.Unmarshal([]byte("name:"+value), &fm) == nil {
|
|
if v, isString := fm["name"].(string); isString {
|
|
name = v
|
|
return false
|
|
}
|
|
}
|
|
literal = strings.Trim(strings.TrimSpace(value), `"'`)
|
|
return false
|
|
})
|
|
if err != nil || name != "" {
|
|
return name, err
|
|
}
|
|
raw, err := readLenientBlock(path)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
if name, isString := decodeFrontmatter(raw)["name"].(string); isString {
|
|
return name, nil
|
|
}
|
|
return literal, nil
|
|
}
|
|
|
|
// isYAMLBlockIndicator returns true for YAML block scalar indicators (>, >-, >+, |, |-, |+).
|
|
func isYAMLBlockIndicator(s string) bool {
|
|
switch s {
|
|
case ">", ">-", ">+", "|", "|-", "|+":
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
|
|
// resolveField looks up a field in the frontmatter map.
|
|
// Priority: metadata.<field> > top-level <field>.
|
|
// Returns nil when the field is absent in both locations.
|
|
func resolveField(fm map[string]any, field string) any {
|
|
if md, ok := fm["metadata"]; ok {
|
|
if mdMap, ok := md.(map[string]any); ok {
|
|
if val, ok := mdMap[field]; ok {
|
|
return val
|
|
}
|
|
}
|
|
}
|
|
val, ok := fm[field]
|
|
if !ok {
|
|
return nil
|
|
}
|
|
return val
|
|
}
|
|
|
|
// ParseFrontmatterList reads a SKILL.md file and extracts a YAML list field from frontmatter.
|
|
// Supports both inline [a, b] and block (- a\n- b) formats.
|
|
// Returns nil when the field is absent or the file cannot be read.
|
|
func ParseFrontmatterList(filePath, field string) []string {
|
|
raw, err := readLenientBlock(filePath)
|
|
if err != nil {
|
|
return nil
|
|
}
|
|
return stringList(decodeFrontmatter(raw), field)
|
|
}
|
|
|
|
// ParseFrontmatterListFromBytes parses a YAML list field from pre-read content.
|
|
// Same as ParseFrontmatterList but avoids re-reading the file.
|
|
func ParseFrontmatterListFromBytes(content []byte, field string) []string {
|
|
raw := locateFrontmatter(content, lenientBlock).withoutLastNewline()
|
|
return stringList(decodeFrontmatter(raw), field)
|
|
}
|
|
|
|
// stringList returns the string items of a list field, resolved by resolveField.
|
|
func stringList(fm map[string]any, field string) []string {
|
|
list, _ := resolveField(fm, field).([]any)
|
|
var result []string
|
|
for _, item := range list {
|
|
if s, ok := item.(string); ok {
|
|
result = append(result, s)
|
|
}
|
|
}
|
|
return result
|
|
}
|
|
|
|
// decodeFrontmatter decodes the block a lenient reader found. It is nil when the block
|
|
// is empty or not a YAML mapping.
|
|
func decodeFrontmatter(raw []byte) map[string]any {
|
|
var fm map[string]any
|
|
if err := yaml.Unmarshal(raw, &fm); err != nil {
|
|
return nil
|
|
}
|
|
return fm
|
|
}
|
|
|
|
// ParseFrontmatterMap returns the complete YAML frontmatter of SKILL.md content.
|
|
// The Agent Skills format requires the file to begin with it, closed by a second ---.
|
|
func ParseFrontmatterMap(content []byte) (map[string]any, error) {
|
|
block := locateFrontmatter(content, strictBlock)
|
|
if !block.open {
|
|
return nil, fmt.Errorf("no frontmatter at the start")
|
|
}
|
|
if !block.closed {
|
|
return nil, fmt.Errorf("unclosed frontmatter: no closing ---")
|
|
}
|
|
if len(bytes.TrimSpace(block.raw)) == 0 {
|
|
return nil, fmt.Errorf("no frontmatter")
|
|
}
|
|
var doc yaml.Node
|
|
if err := yaml.Unmarshal(block.raw, &doc); err != nil {
|
|
return nil, fmt.Errorf("invalid frontmatter: %w", err)
|
|
}
|
|
normalizeCoreScalars(&doc)
|
|
var fm map[string]any
|
|
if err := doc.Decode(&fm); err != nil {
|
|
return nil, fmt.Errorf("invalid frontmatter: %w", err)
|
|
}
|
|
// A non-string key decodes to map[any]any, which JSON cannot carry.
|
|
if _, err := json.Marshal(fm); err != nil {
|
|
return nil, fmt.Errorf("frontmatter JSON cannot carry: %w", err)
|
|
}
|
|
return fm, nil
|
|
}
|
|
|
|
// ParseFrontmatterFields reads a SKILL.md file once and returns the values of
|
|
// multiple frontmatter fields. This avoids opening the same file repeatedly
|
|
// when multiple fields are needed (e.g. description + license).
|
|
// Note: does not resolve metadata.<field> — only reads top-level scalar fields.
|
|
// Use ParseFrontmatterMap for the complete structured frontmatter, including nested values.
|
|
func ParseFrontmatterFields(filePath string, fields []string) map[string]string {
|
|
result := make(map[string]string, len(fields))
|
|
if len(fields) == 0 {
|
|
return result
|
|
}
|
|
|
|
raw, err := readLenientBlock(filePath)
|
|
if err != nil {
|
|
return result
|
|
}
|
|
fm := decodeFrontmatter(raw)
|
|
|
|
for _, field := range fields {
|
|
val, ok := fm[field]
|
|
if !ok || val == nil {
|
|
continue
|
|
}
|
|
switch v := val.(type) {
|
|
case string:
|
|
result[field] = v
|
|
case int:
|
|
result[field] = fmt.Sprintf("%d", v)
|
|
case float64:
|
|
result[field] = fmt.Sprintf("%g", v)
|
|
case bool:
|
|
result[field] = fmt.Sprintf("%t", v)
|
|
}
|
|
}
|
|
|
|
return result
|
|
}
|
|
|
|
// ReadSkillBody reads a file and returns everything after the YAML frontmatter.
|
|
// If no frontmatter is present, the entire content is returned.
|
|
// Returns "" on read error.
|
|
func ReadSkillBody(filePath string) string {
|
|
data, err := os.ReadFile(filePath)
|
|
if err != nil {
|
|
return ""
|
|
}
|
|
|
|
block := locateFrontmatter(scanLines(data), bodyBlock)
|
|
if !block.open {
|
|
return strings.TrimSpace(string(data))
|
|
}
|
|
if !block.closed {
|
|
return ""
|
|
}
|
|
return strings.TrimSpace(string(block.body))
|
|
}
|
|
|
|
// ParseFrontmatterField reads a SKILL.md file and extracts the value of a given frontmatter field.
|
|
// It supports both inline values and YAML block scalars (>, >-, |, |-).
|
|
func ParseFrontmatterField(filePath, field string) string {
|
|
prefix := field + ":"
|
|
indent := -1
|
|
val := ""
|
|
var blockParts []string // set once val is a block scalar indicator
|
|
err := scanLenientBlock(filePath, func(raw []byte) bool {
|
|
if blockParts != nil {
|
|
// The block scalar continues while lines are indented
|
|
if len(raw) > 0 && (raw[0] == ' ' || raw[0] == '\t') {
|
|
blockParts = append(blockParts, strings.TrimSpace(string(raw)))
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
rawLine := string(raw)
|
|
line := strings.TrimSpace(rawLine)
|
|
if !IsRootFrontmatterLine(rawLine, &indent) || !strings.HasPrefix(line, prefix) {
|
|
return true
|
|
}
|
|
val = strings.TrimSpace(strings.SplitN(line, ":", 2)[1])
|
|
if isYAMLBlockIndicator(val) {
|
|
blockParts = []string{}
|
|
return true
|
|
}
|
|
return false
|
|
})
|
|
if err != nil {
|
|
return ""
|
|
}
|
|
if blockParts != nil {
|
|
return strings.Join(blockParts, " ")
|
|
}
|
|
return strings.Trim(val, `"'`)
|
|
}
|