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 ClientCandidate struct {
	Kind       string
	Name       string
	Location   string
	Source     string
	Root       string
	RelPath    string
	Resolved   string
	Client     string
	ProvPath   string
	SkipReason string
	KnownName  string
}

type ClientImportEntry struct {
	Candidate ClientCandidate
	Action    string
	Reason    string
}

type ClientImportOptions struct {
	Trust      bool
	Force      bool
	NoActivate bool
	DryRun     bool
}

type ClientImportResult struct {
	Entries  []ClientImportEntry
	Warnings []string
	Roots    []string
}

type ClientLocation struct {
	Client     string
	Owner      string
	SourceName string
	Kind       string
	Path       string
	Dialect    string
	Docs       string
	SkipReason string
}

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
	// FilteredSkills are relative skill paths DiscoverLocal skipped because
	// they carry .origin.json. Git discovery leaves this nil.
	FilteredSkills []string
}

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 EntryProvenance struct {
	Client   string
	Location 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
	// Kind is SourceKindLocal for a directory import. Empty keeps git import.
	Kind string
	// SourceName overrides RepoToName. Required when a derived name collides.
	SourceName string
	// KnownName is the client-location source name for a new local root.
	KnownName string
	// Provenance maps a discovered relative path to client import metadata.
	// skill add leaves it nil.
	Provenance map[string]EntryProvenance
	// ResourceKind, when set to skill or agent, imports only that kind.
	ResourceKind string
	// PackImport fails before any registry write when a local source key or
	// a local-owned resource would be replaced. Packs have no force option.
	PackImport bool
	// ExactSelection makes Selected and SelectedAgents authoritative. An
	// empty Selected imports no skills and an empty SelectedAgents imports
	// no agents, regardless of ResourceKind and of the legacy empty-means-all
	// rules. Unset preserves those rules.
	ExactSelection bool
	// SelectionIsImportAll marks a non-empty Selected list that still means
	// import-all. An existing skill is skipped instead of overwritten.
	// ExactSelection still decides which names import. Pack add sets this
	// for the pack repository when skills: is empty, so declaring sources
	// does not change that import-all.
	SelectionIsImportAll 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.
	// An own-directory skill counts every installed file. A repository-root
	// skill counts the allowlisted trees plus 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 LocalDiscovery struct {
	Result   *CloneResult
	Warnings []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 LockedFragment struct {
	Base        string `yaml:"base,omitempty"`
	Path        string `yaml:"path,omitempty"`
	Name        string `yaml:"name,omitempty"`
	ContentHash string `yaml:"content_hash,omitempty"`
	CheckoutDir string `yaml:"checkout_dir,omitempty"`
}

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"`
	Variables  map[string]LockedVariableDeclaration `yaml:"variables,omitempty"`
	// Stack records a pinned checkout of a pack-carried stack. Nil when
	// the manifest has no stack, or the stack did not resolve at import.
	Stack *LockedStack `yaml:"stack,omitempty"`
	// UnresolvedDetails maps an unresolved token (for example
	// "stack:stack.yaml") to the reason it did not resolve, so status can
	// show the export or escape error without re-reading the repository.
	// A non-empty map stamps lockVersionStack. An older reader has no
	// field for the key and would drop it on the next write.
	UnresolvedDetails map[string]string `yaml:"unresolved_details,omitempty"`
	// Sources records each external git source pinned at import. A
	// non-empty map stamps lockVersionPackSources. An older reader has no
	// field for the key and would drop it on the next write.
	Sources map[string]LockedPackSource `yaml:"sources,omitempty"`
	// Lock records whether pack add honored, ignored, or found a stale or
	// absent gridctl-pack.lock.yaml. Nil when the manifest declares neither
	// sources nor stack.extends. A non-nil value stamps lockVersionPackLock.
	Lock *LockedPackLock `yaml:"lock,omitempty"`
	// Fragment records a booster's pinned stack fragment. Nil for a base
	// pack and for a booster whose fragment did not resolve. A non-nil
	// value stamps lockVersionPackLock.
	Fragment *LockedFragment `yaml:"fragment,omitempty"`
	// Requires is the manifest's requires.gridctl string, copied at import.
	// Additive: no new import-lock version. An older reader drops it on the
	// next write, which is acceptable because that reader is the version
	// the constraint would have excluded.
	Requires string `yaml:"requires,omitempty"`
}

type LockedPackLock struct {
	State  string `yaml:"state,omitempty"`
	Digest string `yaml:"digest,omitempty"`
	Path   string `yaml:"path,omitempty"`
}

type LockedPackSource struct {
	// Repo is the authored URL, stored as written, matching the primary
	// pack source. Printed lines and source summaries redact userinfo.
	Repo      string    `yaml:"repo"`
	Ref       string    `yaml:"ref,omitempty"`
	Path      string    `yaml:"path,omitempty"`
	CommitSHA string    `yaml:"commit_sha,omitempty"`
	FetchedAt time.Time `yaml:"fetched_at,omitempty"`
	// SourceKey is the member lock source key (<pack>/<source>).
	SourceKey string   `yaml:"source_key,omitempty"`
	Skills    []string `yaml:"skills,omitempty"`
	Agents    []string `yaml:"agents,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"`
	// TreeHash is the sha256:-prefixed hash of SKILL.md plus installed
	// supporting files. Set only for local sources.
	TreeHash    string       `yaml:"tree_hash,omitempty"`
	Fingerprint *Fingerprint `yaml:"fingerprint,omitempty"`
}

type LockedSource struct {
	Repo string `yaml:"repo"`
	// Kind is "local" for a directory source and empty for a git source.
	Kind        string                 `yaml:"kind,omitempty"`
	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"`
	// AuthMethod, SSHUser, and SSHKeyPath persist ssh-key authentication.
	// Only the path is stored, never key material or a passphrase.
	AuthMethod string `yaml:"auth_method,omitempty"`
	SSHUser    string `yaml:"ssh_user,omitempty"`
	SSHKeyPath string `yaml:"ssh_key_path,omitempty"`
	// Pack records the pack manifest this source was imported through,
	// with its resolved selection. Nil for plain skill/agent sources.
	// A member source keeps Pack nil so FindPackSource never treats it
	// as the pack record.
	Pack *LockedPack `yaml:"pack,omitempty"`
	// PackMember is the pack name when this source was imported as a
	// named external source of that pack. Empty for every other source.
	// <pack>/<source> cannot collide with RepoToName output, which is a
	// basename and never contains a slash. GuardSourceKey is what stops
	// an explicit --source-name from re-keying the member to another repo.
	PackMember string `yaml:"pack_member,omitempty"`
	// LockedBy is the pack whose committed lock pinned this member source.
	// Empty when the last add did not honor a lock. A non-empty value
	// stamps lockVersionPackLock.
	LockedBy string `yaml:"locked_by,omitempty"`
}

type LockedStack struct {
	Path        string `yaml:"path"`
	Name        string `yaml:"name"`
	ContentHash string `yaml:"content_hash"`
	CheckoutDir string `yaml:"checkout_dir"`
}

type LockedVariableDeclaration struct {
	Required    *bool  `yaml:"required,omitempty"`
	Secret      *bool  `yaml:"secret,omitempty"`
	Type        string `yaml:"type,omitempty"`
	Description string `yaml:"description,omitempty"`
	Docs        string `yaml:"docs,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"`
	// SupportingFilesInstalled records that the importer evaluated and
	// installed the complete supporting-file set, even when it was empty.
	// Its absence identifies imports created before supporting-file installs.
	SupportingFilesInstalled bool `json:"supportingFilesInstalled,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"`
	// AuthMethod, SSHUser, and SSHKeyPath persist ssh-key authentication so a
	// later update can rebuild it. Only the path is stored, never key material
	// or a passphrase.
	AuthMethod string `json:"authMethod,omitempty"`
	SSHUser    string `json:"sshUser,omitempty"`
	SSHKeyPath string `json:"sshKeyPath,omitempty"`
	// Kind is "local" for a directory import and empty for a git import.
	// Empty is the historical zero value so existing sidecars keep decoding
	// as git origins.
	Kind string `json:"kind,omitempty"`
	// Client and Location are optional client-import provenance. skill add
	// does not write them and does not clear a pair that still matches.
	Client   string `json:"client,omitempty"`
	Location string `json:"location,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 SnapshotResult struct {
	// CheckoutDir is the absolute directory the copy landed in.
	CheckoutDir string
	// Reused is true when an existing directory for this destination was
	// returned without copying.
	Reused bool
}

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 SourceConflictError struct {
	Name string
	Repo string
	Msg  string
}

type SourceNameInput struct {
	Kind         string
	Root         string
	Explicit     string
	KnownName    string
	ClientImport bool
}

type StoredAuth struct {
	Method        string
	SSHUser       string
	SSHKeyPath    string
	CredentialRef string
}

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