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 ContentOptions struct {
	// Reference is an OCI reference (e.g. ghcr.io/org/skill:v1) or a local build tag.
	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 FailureReason string

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"`
	// ProjectRoot filters the lookup by project root path.
	ProjectRoot string `json:"project_root,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"`
	// Clients lists target clients (e.g., "claude-code"). Empty means first skill-supporting client.
	Clients []string `json:"clients,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"`
	// Group is the group name to add the skill to after installation.
	Group string `json:"group,omitempty"`
	// AllowUnsigned permits installing a project-scoped skill whose artifact
	// carries no Sigstore signature. Without it, unsigned artifacts are
	// rejected; with it, the lock entry records the exception as
	// "unsigned: true". Skill content is AI-executed instructions, so this
	// is an explicit per-install trust decision, never a default.
	AllowUnsigned bool `json:"allow_unsigned,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:"-"`
	// LockSource overrides the value recorded as the lock entry's Source. When
	// empty, the entry's Source is Name as given by the caller before any
	// internal resolution. Set by Sync/Upgrade, which pass an already-resolved
	// Name that must not overwrite the entry's original Source. Internal use
	// only — NOT exposed via HTTP API.
	LockSource string `json:"-"`
	// LockResolvedReference overrides the value recorded as the lock entry's
	// ResolvedReference. When empty, the entry's ResolvedReference is
	// whatever this install actually resolved to. Set by Sync when
	// reinstalling at a pinned reference: without this override, a drift
	// repair would overwrite ResolvedReference with the internal pinned
	// form (e.g. a digest or commit hash spliced into the reference)
	// instead of preserving what Source originally resolved to. Internal
	// use only — NOT exposed via HTTP API.
	LockResolvedReference string `json:"-"`
	// RequiredByParent is set when this install is a transitively materialized
	// dependency (toolhive.requires) of another skill, naming that parent.
	// Empty means the user explicitly requested this install. Internal use
	// only — NOT exposed via HTTP API.
	RequiredByParent string `json:"-"`
	// Visited tracks skill names already materialized in this dependency
	// tree, preventing infinite recursion on a requires cycle. Left nil by
	// external callers; Install initializes it on first entry and threads it
	// through recursive dependency installs. Internal use only — NOT exposed
	// via HTTP API.
	Visited map[string]struct{} `json:"-"`
	// SyncRestore forces re-extraction to every existing client even when
	// Digest matches the currently-installed digest. Set by Sync when
	// reinstalling at a pinned reference: the whole point is repairing
	// on-disk drift that happened without the pinned digest changing, so the
	// normal "same digest means content is already correct" fast path must
	// not apply. Internal use only — NOT exposed via HTTP API.
	SyncRestore bool `json:"-"`
	// Provenance carries the verified signer identity established during
	// install-time verification, for recording into the lock entry. Set by
	// the verification step, nil when the artifact is unsigned or
	// verification did not run. Internal use only — NOT exposed via HTTP API.
	Provenance *ProvenanceInfo `json:"-"`
	// SigstoreBundle is the serialized Sigstore bundle backing Provenance,
	// persisted alongside the install record so sync can re-verify offline.
	// Internal use only — NOT exposed via HTTP API.
	SigstoreBundle []byte `json:"-"`
}

type InstallResult struct {
	// Skill is the installed skill.
	Skill InstalledSkill `json:"skill"`
	// PreExisting is the store record as it was before this install, or nil
	// when this install created the record. Rollback uses it to restore the
	// previous state instead of destructively deleting a record this call
	// did not create. Internal use only — NOT exposed via HTTP API.
	PreExisting *InstalledSkill `json:"-"`
}

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"`
	// Managed indicates this install is tracked in the project's
	// toolhive.lock.yaml. Only ever true for project-scoped installs. No
	// omitempty: false is an observable state (unmanaged), not an absence.
	Managed bool `json:"managed"`
	// SigstoreBundle is the serialized Sigstore bundle captured at install
	// time, used for offline re-verification during sync. Nil for unsigned
	// installs. Never serialized to API responses.
	SigstoreBundle []byte `json:"-"`
}

type Installer interface {
	// Extract decompresses a tar.gz OCI layer and writes files to targetDir.
	Extract(layerData []byte, targetDir string, force bool) (*ExtractResult, error)
	// ExtractPlugin is like Extract but preserves the executable bit (cap 0755)
	// so plugin hook scripts keep +x. Used by plugin adapters.
	ExtractPlugin(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"`
	// ClientApp filters results by client application.
	ClientApp string `json:"client,omitempty"`
	// ProjectRoot filters results by project root path.
	ProjectRoot string `json:"project_root,omitempty"`
	// Group filters results to only skills that belong to the specified group.
	Group string `json:"group,omitempty"`
}

type LocalBuild struct {
	// Tag is the OCI tag or name used to reference the artifact.
	Tag string `json:"tag"`
	// Digest is the OCI digest of the artifact (sha256:...).
	Digest string `json:"digest"`
	// Name is the skill name extracted from the artifact metadata, if available.
	Name string `json:"name,omitempty"`
	// Description is the skill description extracted from the artifact metadata, if available.
	Description string `json:"description,omitempty"`
	// Version is the skill version extracted from the artifact metadata, if available.
	Version string `json:"version,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 ProvenanceInfo struct {
	// SignerIdentity is the certificate subject identity (workflow path for
	// GitHub Actions certificates, SAN verbatim otherwise).
	SignerIdentity string `json:"-"`
	// CertIssuer is the OIDC issuer that authenticated the signer.
	CertIssuer string `json:"-"`
	// RepositoryURI is the source repository from the certificate
	// extensions, when present.
	RepositoryURI string `json:"-"`
	// SigstoreURL is the Sigstore instance the signature chains to.
	SigstoreURL string `json:"-"`
}

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

type Scope string

type SkillContent struct {
	// Name is the skill name from the OCI config labels.
	Name string `json:"name"`
	// Description is the skill description from the OCI config labels.
	Description string `json:"description"`
	// Version is the skill version from the OCI config labels.
	Version string `json:"version,omitempty"`
	// License is the SPDX license identifier from the OCI config labels.
	License string `json:"license,omitempty"`
	// Body is the raw SKILL.md markdown content.
	Body string `json:"body"`
	// Files is the list of all files in the artifact with their sizes.
	Files []SkillFileEntry `json:"files"`
}

type SkillFileEntry struct {
	// Path is the file path within the artifact.
	Path string `json:"path"`
	// Size is the uncompressed file size in bytes.
	Size int `json:"size"`
}

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"`
	// Group is the optional group this skill belongs to.
	Group string `json:"group,omitempty"`
}

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 SkillLockService interface {
	// Sync restores the project's installed skills to match its lock file.
	Sync(ctx context.Context, opts SyncOptions) (*SyncResult, error)
	// Upgrade re-resolves each lock entry's source and installs newer content
	// when the resolved digest has changed.
	Upgrade(ctx context.Context, opts UpgradeOptions) (*UpgradeResult, error)
}

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
	// ListBuilds returns all locally-built OCI skill artifacts in the local store.
	ListBuilds(ctx context.Context) ([]LocalBuild, error)
	// DeleteBuild removes a locally-built OCI skill artifact from the local store.
	DeleteBuild(ctx context.Context, tag string) error
	// GetContent retrieves the SKILL.md body and file listing from an OCI artifact
	// without installing it. Works for both remote registry references and local build tags.
	GetContent(ctx context.Context, opts ContentOptions) (*SkillContent, error)
}

type StringOrSlice []string

type SyncFailure struct {
	// Name is the skill name that failed.
	Name string `json:"name"`
	// Reason is a typed failure reason for CI and automation.
	Reason FailureReason `json:"reason,omitempty"`
	// Error is a human-readable description of the failure.
	Error string `json:"error"`
}

type SyncOptions struct {
	// ProjectRoot is the project root path whose lock file should be synced.
	ProjectRoot string `json:"project_root"`
	// Clients lists target clients (e.g., "claude-code"). Empty means every
	// skill-supporting client detected on this host.
	Clients []string `json:"clients,omitempty"`
	// Prune removes project-scoped skills that are installed but not present
	// in the lock file. When false, such skills are only reported.
	Prune bool `json:"prune,omitempty"`
	// Check verifies on-disk content against contentDigest without installing
	// or writing anything.
	Check bool `json:"check,omitempty"`
	// Adopt writes lock entries for existing unmanaged project-scope installs.
	Adopt bool `json:"adopt,omitempty"`
}

type SyncResult struct {
	// Installed lists skills that were installed or reinstalled to match the lock file.
	Installed []string `json:"installed,omitempty"`
	// Drifted lists skills whose on-disk contentDigest differed from the lock
	// file. Normally these are reinstalled to match it; when Check is set,
	// nothing is written and this field reports the drift only.
	Drifted []string `json:"drifted,omitempty"`
	// Missing lists lock entries with no corresponding install record at all
	// — the fresh-clone state. Normally these are installed at their pinned
	// reference; when Check is set, nothing is written and this field
	// reports the gap only.
	Missing []string `json:"missing,omitempty"`
	// AlreadyCurrent lists skills that already matched the lock file.
	AlreadyCurrent []string `json:"already_current,omitempty"`
	// NeverManaged lists project-scoped skills never recorded as lock-managed.
	NeverManaged []string `json:"never_managed,omitempty"`
	// RemovedFromLock lists previously managed skills absent from the lock file.
	RemovedFromLock []string `json:"removed_from_lock,omitempty"`
	// Pruned lists removed-from-lock skills that were uninstalled because Prune was set.
	Pruned []string `json:"pruned,omitempty"`
	// Failed lists skills that could not be synced, with the reason for each.
	// Drift alone is never reported here — see Drifted.
	Failed []SyncFailure `json:"failed,omitempty"`
}

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"`
	// Visited tracks skill names already removed in this cascade-uninstall
	// tree, preventing infinite recursion on a requiredBy cycle. Left nil by
	// external callers; Uninstall initializes it on first entry and threads
	// it through recursive cascade removals. Internal use only — NOT exposed
	// via HTTP API.
	Visited map[string]struct{} `json:"-"`
}

type UpgradeOptions struct {
	// ProjectRoot is the project root path whose lock file should be upgraded.
	ProjectRoot string `json:"project_root"`
	// Names restricts the upgrade to specific skill names. Empty means every
	// entry in the lock file.
	Names []string `json:"names,omitempty"`
	// Preview reports what would change without installing (still fetches
	// artifacts to compare digests).
	Preview bool `json:"preview,omitempty"`
	// FailOnChanges exits with an error when any mutable source would upgrade.
	FailOnChanges bool `json:"fail_on_changes,omitempty"`
	// AllowRefChange permits resolvedReference changes during upgrade.
	AllowRefChange bool `json:"allow_ref_change,omitempty"`
	// Clients lists target clients (e.g., "claude-code"). Empty means every
	// skill-supporting client detected on this host.
	Clients []string `json:"clients,omitempty"`
}

type UpgradeOutcome struct {
	// Name is the skill name.
	Name string `json:"name"`
	// Status is the outcome of the upgrade attempt.
	Status UpgradeStatus `json:"status"`
	// OldDigest is the digest pinned in the lock file before this operation.
	OldDigest string `json:"old_digest,omitempty"`
	// NewDigest is the digest the source currently resolves to. Equal to
	// OldDigest when Status is UpgradeStatusUpToDate.
	NewDigest string `json:"new_digest,omitempty"`
	// NewResolvedReference is the new resolvedReference when it changed.
	NewResolvedReference string `json:"new_resolved_reference,omitempty"`
	// Reason is a typed failure reason when Status is UpgradeStatusFailed.
	Reason FailureReason `json:"reason,omitempty"`
	// Error is a human-readable description of the failure, set only when Status is UpgradeStatusFailed.
	Error string `json:"error,omitempty"`
}

type UpgradeResult struct {
	// Outcomes contains one entry per skill considered for upgrade.
	Outcomes []UpgradeOutcome `json:"outcomes"`
}

type UpgradeStatus string

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"`
}