skills

type CreateInput struct {
	Name     string
	BaseDir  string
	Force    bool
	Template string
	DirPerm  os.FileMode
	FilePerm os.FileMode
}

type DefaultLocalManager struct{}

type DefaultManager struct {
	// contains filtered or unexported fields
}

type Entry struct {
	ID          string         `json:"id,omitempty"`
	Kind        string         `json:"kind,omitempty"`
	Namespace   string         `json:"namespace,omitempty"`
	Name        string         `json:"name"`
	Slug        string         `json:"slug,omitempty"`
	DisplayName string         `json:"displayName,omitempty"`
	Summary     string         `json:"summary,omitempty"`
	Version     string         `json:"version,omitempty"`
	Tags        []string       `json:"tags,omitempty"`
	UseWhen     []string       `json:"useWhen,omitempty"`
	Tools       []string       `json:"tools,omitempty"`
	Path        string         `json:"path"`
	Dir         string         `json:"dir"`
	Description string         `json:"description,omitempty"`
	Title       string         `json:"title,omitempty"`
	H2          []string       `json:"h2,omitempty"`
	H3          []string       `json:"h3,omitempty"`
	Sections    []Section      `json:"sections,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	Source      string         `json:"source,omitempty"`
}

type LocalManager interface {
	// Discover 扫描 skills 根目录列表，返回可用技能条目与告警信息。
	//
	// 参数：
	//   - skillDirs: skills 根目录列表（例如 ./skills、./.copilot/skills）。
	//
	// 返回：
	//   - []Entry: 已成功解析的技能集合（已去重）。
	//   - []string: 非致命告警（如某个目录不存在、某个 SKILL.md 解析失败）。
	Discover(skillDirs []string) ([]Entry, []string)

	// FindByName 在 Discover 返回的条目中按技能名查找。
	// name 匹配不区分大小写；找不到时返回 error。
	FindByName(entries []Entry, name string) (Entry, error)

	// ReadSkill 读取指定 SKILL.md 原始文本内容。
	// path 应指向具体文件路径，路径为空或读取失败会返回 error。
	ReadSkill(path string) (string, error)

	// CreateSkill 根据输入参数创建技能目录与 SKILL.md 文件。
	// 默认会生成标准模板；若 Force=false 且文件已存在会返回 error。
	CreateSkill(in CreateInput) (Entry, error)

	// BuildTemplate 生成标准 SKILL.md 模板文本（包含 frontmatter 与基础章节）。
	BuildTemplate(name string) string

	// SanitizeName 规范化技能名：小写、空格转中划线，并校验字符合法性。
	// 返回空字符串表示名称非法。
	SanitizeName(name string) string

	// ParseFile 解析单个 SKILL.md 文件，返回结构化结果。
	// fallbackName 用于当前文件缺失可用名称时的兜底值（通常传目录名）。
	ParseFile(path string, fallbackName string) (ParsedSkill, error)

	// ParseContent 解析 SKILL.md 文本内容。
	// 支持：frontmatter 元数据、一级/二级/三级标题提取，以及名称来源判定。
	ParseContent(content, fallbackName string) (ParsedSkill, error)

	// FindSectionContent 按标题路径提取正文内容。
	//
	// 用法：
	//   - headings=[]{"二级标题"}            => 返回该 H2 的内容
	//   - headings=[]{"二级标题","三级标题"} => 返回该 H3 的内容
	FindSectionContent(sections []Section, headings ...string) (string, bool)

	// ExistingDirs 过滤并返回实际存在的目录列表。
	ExistingDirs(candidates []string) []string

	// DirExists 判断路径是否为存在的目录。
	DirExists(path string) bool

	// CompactStringSlice 清理字符串数组（trim + 去空项）。
	CompactStringSlice(in []string) []string
}

type Manager interface {
	Local() LocalManager
	Remote() RemoteManager
}

type ParsedSkill struct {
	Name        string
	Slug        string
	Description string
	Summary     string
	Version     string
	Tags        []string
	UseWhen     []string
	Tools       []string
	Title       string
	H2          []string
	H3          []string
	Sections    []Section
	Metadata    map[string]any
	Source      string
}

type PullRequest struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	TargetDir string `json:"targetDir"`
	Force     bool   `json:"force"`
}

type PushRequest struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	Path      string `json:"path"`
}

type RemoteEntry struct {
	Namespace   string `json:"namespace"`
	Name        string `json:"name"`
	Version     string `json:"version,omitempty"`
	Description string `json:"description,omitempty"`
	UpdatedAt   string `json:"updatedAt,omitempty"`
}

type RemoteManager interface {
	// List 列出命名空间下的远程技能摘要。
	List(ctx context.Context, namespace string) ([]RemoteEntry, error)
	// Get 获取远程技能完整内容。
	Get(ctx context.Context, namespace, name string) (RemoteSkill, error)
	// Upsert 创建或更新远程技能。
	Upsert(ctx context.Context, skill RemoteSkill) (RemoteEntry, error)
	// Delete 删除远程技能。
	Delete(ctx context.Context, namespace, name string) error
	// Pull 从远端拉取技能并落地到本地。
	Pull(ctx context.Context, req PullRequest) (Entry, error)
	// Push 将本地技能推送到远端。
	Push(ctx context.Context, req PushRequest) (RemoteEntry, error)
}

type RemoteSkill struct {
	RemoteEntry
	Content  string         `json:"content"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Section struct {
	Title       string       `json:"title"`
	Content     string       `json:"content,omitempty"`
	Subsections []Subsection `json:"subsections,omitempty"`
}

type Service = LocalManager

type Subsection struct {
	Title   string `json:"title"`
	Content string `json:"content,omitempty"`
}

type UnsupportedRemoteManager struct{}