skills

type BuildOptions struct {
	// Path is the local directory path containing the skill definition.
	Path string `json:"path"`
	// Tag is the OCI tag to use for the built artifact.
	Tag string `json:"tag,omitempty"`
}

type BuildResult struct {
	// Reference is the OCI reference of the built skill artifact.
	Reference string `json:"reference"`
}

type Dependency struct {
	// Name is the dependency name.
	Name string `json:"name,omitempty"`
	// Reference is the OCI reference for the dependency.
	Reference string `json:"reference"`
	// Digest is the OCI digest for upgrade detection.
	Digest string `json:"digest,omitempty"`
}

type ExtractResult struct {
	// SkillDir is the absolute path where the skill was extracted.
	SkillDir string
	// Files is the number of files written.
	Files int
}

type InfoOptions struct {
	// Name is the skill name to look up.
	Name string `json:"name"`
	// Scope filters the lookup by installation scope.
	Scope Scope `json:"scope,omitempty"`
}

type InstallOptions struct {
	// Name is the skill name or OCI reference to install.
	Name string `json:"name"`
	// Version is the specific version to install. Empty means latest.
	Version string `json:"version,omitempty"`
	// Scope is the installation scope.
	Scope Scope `json:"scope,omitempty"`
	// Client is the target client (e.g., "claude-code"). Empty means first skill-supporting client.
	Client string `json:"client,omitempty"`
	// Force allows overwriting unmanaged skill directories.
	Force bool `json:"force,omitempty"`
	// ProjectRoot is the project root path for project-scoped installs.
	ProjectRoot string `json:"project_root,omitempty"`
	// LayerData is the tar.gz content from an OCI layer. Internal use only — NOT exposed via HTTP API.
	LayerData []byte `json:"-"`
	// Reference is the full OCI reference (e.g. ghcr.io/org/skill:v1).
	Reference string `json:"-"`
	// Digest is the OCI digest for upgrade detection.
	Digest string `json:"-"`
}

type InstallResult struct {
	// Skill is the installed skill.
	Skill InstalledSkill `json:"skill"`
}

type InstallStatus string

type InstalledSkill struct {
	// Metadata contains the skill's metadata.
	Metadata SkillMetadata `json:"metadata"`
	// Scope is the installation scope (user or project).
	Scope Scope `json:"scope"`
	// ProjectRoot is the project root path for project-scoped skills. Empty for user-scoped.
	ProjectRoot string `json:"project_root,omitempty"`
	// Reference is the full OCI reference (e.g. ghcr.io/org/skill:v1).
	Reference string `json:"reference,omitempty"`
	// Tag is the OCI tag (e.g. v1.0.0).
	Tag string `json:"tag,omitempty"`
	// Digest is the OCI digest (sha256:...) for upgrade detection.
	Digest string `json:"digest,omitempty"`
	// Status is the current installation status.
	Status InstallStatus `json:"status"`
	// InstalledAt is the timestamp when the skill was installed.
	InstalledAt time.Time `json:"installed_at"`
	// Clients is the list of client identifiers the skill is installed for.
	// TODO: Refactor client.ClientApp to a shared package so it can be used here instead of []string.
	Clients []string `json:"clients,omitempty"`
	// Dependencies is the list of external skill dependencies.
	Dependencies []Dependency `json:"dependencies,omitempty"`
}

type Installer interface {
	// Extract decompresses a tar.gz OCI layer and writes files to targetDir.
	Extract(layerData []byte, targetDir string, force bool) (*ExtractResult, error)
	// Remove safely removes a skill directory.
	Remove(skillDir string) error
}

type ListOptions struct {
	// Scope filters results by installation scope.
	Scope Scope `json:"scope,omitempty"`
}

type ParseResult struct {
	Name          string
	Description   string
	Version       string
	AllowedTools  []string
	License       string
	Compatibility string
	Metadata      map[string]string
	Requires      []Dependency
	Body          []byte
}

type PathResolver interface {
	// GetSkillPath returns the filesystem path where a skill should be installed.
	GetSkillPath(clientType, skillName string, scope Scope, projectRoot string) (string, error)
	// ListSkillSupportingClients returns all client identifiers that support skills.
	ListSkillSupportingClients() []string
}

type PushOptions struct {
	// Reference is the OCI reference to push.
	Reference string `json:"reference"`
}

type Scope string

type SkillFrontmatter struct {
	Name          string            `yaml:"name"`
	Description   string            `yaml:"description"`
	Version       string            `yaml:"version,omitempty"`
	AllowedTools  StringOrSlice     `yaml:"allowed-tools,omitempty"`
	Requires      StringOrSlice     `yaml:"toolhive.requires,omitempty"`
	License       string            `yaml:"license,omitempty"`
	Compatibility string            `yaml:"compatibility,omitempty"`
	Metadata      map[string]string `yaml:"metadata,omitempty"`
}

type SkillIndex struct {
	// Skills is the list of available skills.
	Skills []SkillIndexEntry `json:"skills"`
}

type SkillIndexEntry struct {
	// Metadata contains the skill's metadata.
	Metadata SkillMetadata `json:"metadata"`
	// Repository is the OCI repository reference for the skill.
	Repository string `json:"repository"`
}

type SkillInfo struct {
	// Metadata contains the skill's metadata.
	Metadata SkillMetadata `json:"metadata"`
	// InstalledSkill contains the full installation record.
	InstalledSkill *InstalledSkill `json:"installed_skill,omitempty"`
}

type SkillMetadata struct {
	// Name is the unique name of the skill.
	Name string `json:"name"`
	// Version is the semantic version of the skill.
	Version string `json:"version"`
	// Description is a human-readable description of the skill.
	Description string `json:"description"`
	// Author is the skill author or maintainer.
	Author string `json:"author"`
	// Tags is a list of tags for categorization.
	Tags []string `json:"tags,omitempty"`
}

type SkillService interface {
	// List returns all installed skills matching the given options.
	List(ctx context.Context, opts ListOptions) ([]InstalledSkill, error)
	// Install installs a skill from a remote source.
	Install(ctx context.Context, opts InstallOptions) (*InstallResult, error)
	// Uninstall removes an installed skill.
	Uninstall(ctx context.Context, opts UninstallOptions) error
	// Info returns detailed information about a skill.
	Info(ctx context.Context, opts InfoOptions) (*SkillInfo, error)
	// Validate checks whether a skill definition is valid.
	Validate(ctx context.Context, path string) (*ValidationResult, error)
	// Build builds a skill from a local directory into an OCI artifact.
	Build(ctx context.Context, opts BuildOptions) (*BuildResult, error)
	// Push pushes a built skill artifact to a remote registry.
	Push(ctx context.Context, opts PushOptions) error
}

type StringOrSlice []string

type UninstallOptions struct {
	// Name is the skill name to uninstall.
	Name string `json:"name"`
	// Scope is the scope from which to uninstall.
	Scope Scope `json:"scope,omitempty"`
	// ProjectRoot is the project root path for project-scoped skills.
	ProjectRoot string `json:"project_root,omitempty"`
}

type ValidationResult struct {
	// Valid indicates whether the skill definition is valid.
	Valid bool `json:"valid"`
	// Errors is a list of validation errors, if any.
	Errors []string `json:"errors,omitempty"`
	// Warnings is a list of non-blocking validation warnings, if any.
	Warnings []string `json:"warnings,omitempty"`
}