skills

type AgentDefinition struct {
	Name        string
	Description string
	// Extra holds every frontmatter key other than name and description,
	// in document order, as raw YAML nodes.
	Extra []AgentExtraField
	// Body is the markdown after the frontmatter block.
	Body string
	// Raw is the file exactly as read; imports write it verbatim.
	Raw []byte
}

type AgentExtraField struct {
	Key   string
	Value *yaml.Node
}

type AuthConfig struct {
	Method         string // "", "none", "token", "ssh-agent", "ssh-key"
	Token          string // resolved plaintext — transient, never persisted
	CredentialRef  string // e.g. "${vault:GIT_TOKEN}" — persisted
	SSHUser        string // defaults to "git" when empty
	SSHKeyPath     string // required for method "ssh-key"
	SSHPassphrase  string // transient
	KnownHostsPath string // reserved for future host-key policy work
}

type CloneResult struct {
	RepoPath  string
	CommitSHA string
	Skills    []DiscoveredSkill
	Malformed []MalformedSkill
	// Agents are agent definitions discovered under the agents/*.md
	// convention; MalformedAgents records files in agents/ directories
	// that are not parseable agent definitions.
	Agents          []DiscoveredAgent
	MalformedAgents []MalformedAgent
}

type CredentialResolver func(ref string) (string, error)

type DiffResult struct {
	Skill    string `json:"skill"`
	Local    string `json:"local"`    // current on-disk full SKILL.md text
	Upstream string `json:"upstream"` // content an update would install
	Drifted  bool   `json:"drifted"`  // on-disk file diverges from InstalledHash
}

type DiscoveredAgent struct {
	Name        string
	Path        string // Relative path from repo root to the .md file
	Definition  *AgentDefinition
	ContentHash string
}

type DiscoveredSkill struct {
	Name        string
	Path        string // Relative path from repo root to SKILL.md directory
	Skill       *registry.AgentSkill
	ContentHash string
}

type Fingerprint struct {
	ContentHash string   `json:"contentHash" yaml:"content_hash"`
	ToolsHash   string   `json:"toolsHash" yaml:"tools_hash"`
	Tools       []string `json:"tools,omitempty" yaml:"tools,omitempty"`
}

type ImportOptions struct {
	Repo       string
	Ref        string
	Path       string
	Trust      bool     // Skip security scan confirmation
	NoActivate bool     // Import as draft instead of active
	Force      bool     // Overwrite existing skills
	Rename     string   // Rename the skill on import
	Selected   []string // Only import skills with these names (empty = import all)
	// SelectedAgents imports exactly these agent names. When empty, the
	// legacy behavior holds: all agents when Selected is also empty, no
	// agents when a skill selection is present (the web UI picker's
	// contract). Pack imports always pass fully resolved lists.
	SelectedAgents []string
	// Discovered supplies a pre-cloned discovery result so callers that
	// already ran CloneAndDiscover (pack add reads the manifest first)
	// do not clone twice. Nil means Import clones itself.
	Discovered *CloneResult
	Auth       AuthConfig
	// PreserveState carries over the existing skill's State (draft/active/
	// disabled) instead of resetting it. Used by Update so that re-syncing
	// a source does not silently re-activate skills the user disabled.
	PreserveState bool
}

type ImportResult struct {
	Imported []ImportedSkill `json:"imported"`
	Skipped  []SkippedSkill  `json:"skipped"`
	Warnings []string        `json:"warnings"`
	// ImportedAgents and SkippedAgents record agent definitions the same
	// import discovered under the agents/*.md convention.
	ImportedAgents []ImportedAgent `json:"importedAgents,omitempty"`
	SkippedAgents  []SkippedAgent  `json:"skippedAgents,omitempty"`
}

type ImportedAgent struct {
	Name     string            `json:"name"`
	Path     string            `json:"path"`
	Origin   *Origin           `json:"origin,omitempty"`
	Findings []SecurityFinding `json:"findings,omitempty"`
}

type ImportedSkill struct {
	Name   string  `json:"name"`
	Path   string  `json:"path"`
	Origin *Origin `json:"origin,omitempty"`
	// FilesCopied counts supporting files installed alongside SKILL.md
	// (scripts/, references/, assets/, and package metadata).
	FilesCopied int               `json:"filesCopied"`
	Findings    []SecurityFinding `json:"findings,omitempty"`
}

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

type InstalledAgent struct {
	Name       string
	Definition *AgentDefinition
	// Dir is the agent's canonical directory (holds AGENT.md and its
	// .origin.json sidecar).
	Dir string
}

type LockFile struct {
	Version int                     `yaml:"version"`
	Sources map[string]LockedSource `yaml:"sources"`
}

type LockedAgent struct {
	Path        string `yaml:"path"`
	ContentHash string `yaml:"content_hash"`
}

type LockedPack struct {
	Name    string `yaml:"name"`
	Version string `yaml:"version,omitempty"`
	// Description and Author persist the manifest metadata a list view
	// needs, so no consumer ever has to re-clone the repo to show it.
	// Additive fields: files without them keep loading, and version 2
	// (which every pack record already stamps) covers them.
	Description string   `yaml:"description,omitempty"`
	Author      string   `yaml:"author,omitempty"`
	Wiring      bool     `yaml:"wiring,omitempty"`
	Clients     []string `yaml:"clients,omitempty"`
	Skills      []string `yaml:"skills,omitempty"`
	Agents      []string `yaml:"agents,omitempty"`
	// Rules lists context rule fragments imported from the pack repo.
	// Superseded by RuleFiles, which adds per-rule provenance; retained so
	// lockfiles written before that keep loading, and kept in sync on write
	// so a downgrade still sees the selection.
	Rules []string `yaml:"rules,omitempty"`
	// RuleFiles records per-rule provenance keyed by fragment name. An entry
	// with an empty ContentHash means provenance is unknown (migrated from a
	// Rules-only lockfile), and callers must fall back to byte comparison
	// rather than treating the empty hash as a match.
	RuleFiles map[string]LockedRule `yaml:"rule_files,omitempty"`
	// Unresolved lists manifest-selected names discovery could not find,
	// so status can keep reporting them until the upstream repo (or the
	// manifest) is fixed.
	Unresolved []string `yaml:"unresolved,omitempty"`
}

type LockedRule struct {
	Path        string `yaml:"path"`
	ContentHash string `yaml:"content_hash"`
}

type LockedSkill struct {
	Path        string       `yaml:"path"`
	ContentHash string       `yaml:"content_hash"`
	Fingerprint *Fingerprint `yaml:"fingerprint,omitempty"`
}

type LockedSource struct {
	Repo        string                 `yaml:"repo"`
	Ref         string                 `yaml:"ref"`
	ResolvedRef string                 `yaml:"resolved_ref,omitempty"`
	CommitSHA   string                 `yaml:"commit_sha"`
	FetchedAt   time.Time              `yaml:"fetched_at"`
	ContentHash string                 `yaml:"content_hash"`
	Skills      map[string]LockedSkill `yaml:"skills"`
	// Agents records agent definitions imported from this source.
	Agents map[string]LockedAgent `yaml:"agents,omitempty"`
	// CredentialRef is an opaque reference like "${vault:GIT_TOKEN}" used to
	// re-resolve credentials on source update. Raw tokens are never stored.
	CredentialRef string `yaml:"credential_ref,omitempty"`
	// Pack records the pack manifest this source was imported through,
	// with its resolved selection. Nil for plain skill/agent sources.
	Pack *LockedPack `yaml:"pack,omitempty"`
}

type MalformedAgent = MalformedSkill

type MalformedSkill struct {
	Path string `json:"path"` // Relative path from repo root
	Err  string `json:"error"`
}

type Origin struct {
	Repo        string    `json:"repo"`
	Ref         string    `json:"ref"`
	Path        string    `json:"path,omitempty"`
	CommitSHA   string    `json:"commitSha"`
	ImportedAt  time.Time `json:"importedAt"`
	ContentHash string    `json:"contentHash"`
	// InstalledHash is the SHA-256 of the SKILL.md as written to disk
	// immediately after the last import. DetectDrift compares the current
	// on-disk hash against this to surface local user edits. Distinct from
	// ContentHash, which records the upstream file as fetched (and which
	// diverges from the installed file because of frontmatter render
	// normalization and state injection).
	InstalledHash string       `json:"installedHash,omitempty"`
	Fingerprint   *Fingerprint `json:"fingerprint,omitempty"`
	// CredentialRef is an opaque reference like "${vault:GIT_TOKEN}" used to
	// re-resolve credentials on skill update. Raw token values are never
	// persisted — only the reference string.
	CredentialRef string `json:"credentialRef,omitempty"`
}

type ScanResult struct {
	SkillName string            `json:"skillName"`
	Findings  []SecurityFinding `json:"findings"`
	Safe      bool              `json:"safe"`
}

type SecurityFinding struct {
	StepID      string `json:"stepId"`
	Pattern     string `json:"pattern"`
	Description string `json:"description"`
	Severity    string `json:"severity"` // "warning" or "danger"
}

type SkillDefaults struct {
	AutoUpdate     bool   `yaml:"auto_update" json:"autoUpdate"`
	UpdateInterval string `yaml:"update_interval" json:"updateInterval"`
}

type SkillInfo struct {
	Name        string    `json:"name"`
	Origin      *Origin   `json:"origin,omitempty"`
	IsRemote    bool      `json:"isRemote"`
	UpdateAvail bool      `json:"updateAvailable"`
	LatestSHA   string    `json:"latestSha,omitempty"`
	LastChecked time.Time `json:"lastChecked,omitempty"`
}

type SkillSource struct {
	Name           string      `yaml:"name" json:"name"`
	Repo           string      `yaml:"repo" json:"repo"`
	Ref            string      `yaml:"ref,omitempty" json:"ref,omitempty"`
	Path           string      `yaml:"path,omitempty" json:"path,omitempty"`
	AutoUpdate     *bool       `yaml:"auto_update,omitempty" json:"autoUpdate,omitempty"`
	UpdateInterval string      `yaml:"update_interval,omitempty" json:"updateInterval,omitempty"`
	Auth           *SourceAuth `yaml:"auth,omitempty" json:"auth,omitempty"`
}

type SkillUpdate struct {
	CurrentSHA string `yaml:"current_sha"`
	LatestSHA  string `yaml:"latest_sha"`
	Repo       string `yaml:"repo"`
	Ref        string `yaml:"ref"`
}

type SkillsConfig struct {
	Defaults SkillDefaults `yaml:"defaults,omitempty" json:"defaults,omitempty"`
	Sources  []SkillSource `yaml:"sources" json:"sources"`
}

type SkippedAgent = SkippedSkill

type SkippedSkill struct {
	Name   string `json:"name"`
	Reason string `json:"reason"`
}

type SourceAuth struct {
	Method        string `yaml:"method,omitempty" json:"method,omitempty"`
	CredentialRef string `yaml:"credential_ref,omitempty" json:"credentialRef,omitempty"`
	SSHUser       string `yaml:"ssh_user,omitempty" json:"sshUser,omitempty"`
	SSHKeyPath    string `yaml:"ssh_key_path,omitempty" json:"sshKeyPath,omitempty"`
}

type UpdateStatus struct {
	CheckedAt time.Time              `yaml:"checked_at"`
	Updates   map[string]SkillUpdate `yaml:"updates,omitempty"`
	Errors    []string               `yaml:"errors,omitempty"`
}