app

type AddRequest struct {
	Root    string
	Source  string
	Version string
	Ref     string
	Commit  string
	Agents  []string
	Force   bool
	Scope   string
	Mode    string

	// Selection (US2). Selectors are raw --skill values (incl. "*"); All maps
	// --all; Path is the --path disambiguator; ListOnly maps --list.
	Selectors   []string
	All         bool
	Path        string
	ListOnly    bool
	Interactive bool

	// Discovery filters (FR-012).
	MaxDepth int
	Include  []string
	Exclude  []string

	// Chooser, when set and Interactive, picks among multiple discovered skills.
	// It receives every in-scope skill (invalid ones shown but not selectable)
	// and returns the chosen subset. The CLI wires this to the TUI picker; the
	// app stays independent of the view layer (FR-021).
	Chooser func([]discovery.DiscoveredSkill) ([]discovery.DiscoveredSkill, error)

	// Progress, when non-nil, receives install lifecycle events (spec 014,
	// contracts/install-progress-events.md); nil keeps the run unobserved.
	Progress func(InstallProgressEvent)
}

type AddResult struct {
	Installed []InstalledSkill
	Listed    []discovery.DiscoveredSkill // populated for --list (no install)
	Warnings  []string
}

type AgentChoice struct {
	ID          string
	DisplayName string
	Detected    bool
	Preselected bool
}

type AgentHealthEntry struct {
	ID     string `json:"id"`
	Mode   string `json:"mode"`
	Health string `json:"health"`
}

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

type CheckReport struct {
	Skills   []SkillCheck
	HasDrift bool
}

type ConflictError struct {
	Skill string
	Kind  string
	// contains filtered or unexported fields
}

type DiffEntry struct {
	Name   string
	Status string
}

type DiscoverRequest struct {
	Root    string
	Source  string
	Version string
	Ref     string
	Commit  string
	Scope   string
	Mode    string

	// Discovery filters (FR-012 of spec 006).
	MaxDepth int
	Include  []string
	Exclude  []string
}

type DiscoverResult struct {
	Ref      source.Ref
	Revision resolver.Revision
	Scan     discovery.Result
	Skills   []discovery.DiscoveredSkill
	Warnings []string
}

type DoctorReport struct {
	GitAvailable   bool
	DetectedAgents []string
	Requirements   []RequirementCheck
	Warnings       []string
}

type FailureCategory string

type FindScope struct {
	Source string
	Owner  string
	Root   string
}

type InitResult struct {
	LockPath string
	Created  []string
}

type InstallFailure struct {
	Category FailureCategory
	Phase    InstallPhase
	Message  string
	Hint     string
	Expected string // optional: recorded value (integrity mismatches)
	Actual   string // optional: observed value (integrity mismatches)
	Cause    error  // not serialized; kept for errors.Is/As in tests
}

type InstallFromLockRequest struct {
	Root string
	// Agents distinguishes "no explicit selection" (nil — FR-002a: use each
	// entry's recorded gskill.agents unchanged) from "explicit selection"
	// (non-nil, including a non-nil empty slice — FR-001/FR-002/FR-012: the
	// exact target set for every processed entry, replacing what's recorded).
	// This nil-vs-empty distinction is load-bearing; do not normalize it away
	// with a len()==0 check (research.md Decision 6).
	Agents      []string
	InstallMode string // auto | symlink | copy ("" = per-entry gskill.installMode)
	NoInit      bool   // refuse instead of auto-initializing
	Force       bool   // accept changed upstream content, rewrite computedHash
	DryRun      bool   // report the plan, write nothing
	Offline     bool   // restore from local store/cache only
	Frozen      bool   // never modify the lock file; fail closed on drift
	Prune       bool   // afterwards, remove managed installs the lock no longer declares
	// Progress, when non-nil, receives install lifecycle events synchronously
	// and strictly sequentially (contracts/install-progress-events.md). A nil
	// Progress makes the run behaviorally identical to an unobserved one.
	Progress func(InstallProgressEvent)
}

type InstallFromLockResult struct {
	Initialized bool
	Agents      []string
	Skills      []LockSkillResult
	Pruned      []string
	Changed     bool
}

type InstallOutcome string

type InstallPhase string

type InstallPlan struct {
	Root   string `json:"-"`
	Source string `json:"source"`

	// Requested pins (manifest intent).
	Version         string `json:"version,omitempty"`
	RequestedRef    string `json:"ref,omitempty"`
	RequestedCommit string `json:"commit,omitempty"`

	SourceRef source.Ref        `json:"-"`
	Revision  resolver.Revision `json:"resolved"`

	Scope string `json:"scope,omitempty"`
	Mode  string `json:"mode,omitempty"`
	Force bool   `json:"force,omitempty"`

	// InitProject marks that no manifest exists yet: ExecutePlan scaffolds the
	// project first, and the preview lists the manifest as created (FR-023).
	InitProject bool `json:"init_project,omitempty"`

	Selected []discovery.DiscoveredSkill `json:"-"`
	// ExplicitAgents is the raw agent selection (manifest intent); AgentIDs is
	// the resolved target set.
	ExplicitAgents []string `json:"-"`
	AgentIDs       []string `json:"agents"`

	Actions   []PlannedAction `json:"actions"`
	Conflicts []PlanConflict  `json:"conflicts,omitempty"`
	Warnings  []string        `json:"warnings,omitempty"`
}

type InstallProgressEvent struct {
	SkillIndex int // 1-based position in the run
	SkillTotal int // total skills in the run
	SkillName  string
	Source     string
	SourceType string
	Version    string // resolved version when known
	Ref        string // requested ref when known
	Commit     string // resolved commit when known

	Phase   InstallPhase
	Status  InstallStatus
	Message string
	Err     error // set only on failed/cancelled terminal events
}

type InstallRequest struct {
	Root           string
	Scope          string
	Mode           string
	Frozen         bool
	Offline        bool
	NoCache        bool
	UpdateLockfile bool
}

type InstallResult struct {
	Skills  []SkillChange
	Changed bool
}

type InstallStatus string

type InstallSummary struct {
	Total        int
	Installed    int
	Repaired     int
	UpToDate     int
	Skipped      int
	Failed       int
	Cancelled    int
	NotAttempted int
	Planned      int
	Outcome      InstallOutcome
}

type InstalledSkill struct {
	Name        string            `json:"name"`
	Path        string            `json:"path"`
	ContentHash string            `json:"content_hash"`
	Targets     map[string]string `json:"targets"`
}

type ListedSkill struct {
	Name        string
	Source      string
	Version     string
	Status      string
	Agents      []string
	Commit      string
	ContentHash string
	Active      string
	AgentHealth []AgentHealthEntry
}

type LockPreview struct {
	Path   string
	Skills []LockPreviewSkill
}

type LockPreviewSkill struct {
	Name   string
	Source string
	// Agents is the entry's currently recorded gskill.agents (nil for a raw,
	// unmanaged entry) — used by the TUI to compute the kept/added/removed
	// plan before the user confirms an agent selection (spec 013 FR-006).
	Agents []string
}

type LockSkillResult struct {
	Name         string
	Source       string
	Status       string
	ComputedHash string
	// AgentsKept, AgentsAdded, AgentsRemoved are populated only when the run
	// had an explicit agent selection (req.Agents != nil) — never based on
	// whether the resulting slice happens to be non-empty (spec 013 FR-014).
	AgentsKept    []string
	AgentsAdded   []string
	AgentsRemoved []string
	Err           error

	// Provenance and failure detail (spec 014): populated for successes and
	// failures alike whenever known; empty strings render as "—", never as
	// fabricated data (FR-014). Failure is non-nil exactly when the entry
	// failed (or was cancelled with a cause).
	SourceType      string
	SkillPath       string
	RequestedRef    string
	ResolvedVersion string
	ResolvedRef     string
	Commit          string
	Agents          []string
	InstallMode     string
	Phase           InstallPhase
	PlannedAction   string // dry-run only: would-install|would-repair|would-remove-target|would-update-lock|blocked
	Failure         *InstallFailure

	// StoreReuse reports whether the content store satisfied this skill
	// ("reused") or its source was fetched ("downloaded") — spec 015 FR-007.
	// Empty when the entry never reached the store (failures, plans).
	StoreReuse string
	// StoreScope names the physical store that served the skill: "global" or
	// "project".
	StoreScope string
}

type MigrateReport struct {
	DryRun bool
	// NothingToDo reports an already-migrated project (no legacy store).
	NothingToDo bool
	Plan        migrate.Plan
	Result      migrate.Result
}

type Options struct {
	Config *config.Config
	Logger *slog.Logger
	Agents *agent.Registry
	Git    git.Runner
	Repos  RepoLister
	// GskillHome overrides the resolved gskill home directory (default:
	// GSKILL_HOME env, else ~/.gskill). Tests use it for isolated stores.
	GskillHome string
}

type OutdatedReport struct {
	Skills       []OutdatedSkill
	AnyAvailable bool
}

type OutdatedSkill struct {
	Name      string
	Current   string
	Latest    string
	Available bool
}

type PlanConflict struct {
	Skill  string `json:"skill"`
	Kind   string `json:"kind"`
	Detail string `json:"detail"`
	Err    error  `json:"-"`
}

type PlanLine struct {
	Kind string
	Text string
}

type PlanRequest struct {
	Root     string
	Source   string
	Version  string
	Ref      string
	Commit   string
	Discover DiscoverResult
	Selected []discovery.DiscoveredSkill
	// AgentIDs is the explicit agent selection ([] = resolve via manifest
	// defaults, then detection, then the default agent — same as --agent).
	AgentIDs []string
	Scope    string
	Mode     string
	Force    bool

	// Discovery filters, mirrored from the original DiscoverRequest so a
	// version re-pin re-discovers under the SAME constraints the user set
	// (review finding: dropping them could remap onto an excluded skill).
	MaxDepth int
	Include  []string
	Exclude  []string
}

type PlannedAction struct {
	Skill       string          `json:"skill"`
	AgentID     string          `json:"agent"`
	Destination string          `json:"destination"`
	MergeInto   bool            `json:"merge_into,omitempty"` // agent-add into an existing install
	FileOps     []PlannedFileOp `json:"file_ops,omitempty"`
}

type PlannedFileOp struct {
	Path string `json:"path"`
	Op   string `json:"op"` // "create" or "update"
}

type ProjectInfo struct {
	ProjectID string
	Root      string
	Skills    int
	LastSeen  time.Time
	// Missing reports a recorded root that no longer exists on disk.
	Missing bool
}

type RemoveResult struct {
	Removed    []string
	StoreGCed  int
	NotPresent []string
}

type RepairResult struct {
	Repaired       []string
	StagingCleaned int
}

type RepoLister interface {
	ListOwnerRepos(ctx context.Context, owner string) ([]registry.RepoRef, error)
}

type RequirementCheck struct {
	Skill     string
	Kind      string // command | environment | skill | mcp
	Name      string
	Satisfied bool
	Checked   bool // false for kinds gskill cannot verify (e.g. mcp)
}

type ScanOptions struct {
	Ref      string
	MaxDepth int
	Include  []string
	Exclude  []string
}

type SearchHit struct {
	ID          string `json:"id"`
	DisplayName string `json:"display_name"`
	Description string `json:"description"`
	Source      string `json:"source"`
	RepoPath    string `json:"repo_path"`
	Installed   bool   `json:"installed"`
	Score       int    `json:"score"`
}

type SkillChange struct {
	Name        string
	ContentHash string
	Changed     bool
}

type SkillCheck struct {
	Name   string
	Status string
}

type SkillHealth struct {
	Name         string
	Scope        string
	StorePresent bool
	Hashed       bool // whether store/copy content was hash-verified this evaluation
	StoreHashOK  bool // only meaningful when Hashed
	StorePath    string
	ActiveState  active.Health
	ActivePath   string // project-relative active entry
	Agents       map[string]TargetState
	Modes        map[string]string
}

type SkillInfo struct {
	Name        string
	Source      string
	Version     string
	Commit      string
	ContentHash string
	Description string
	License     string
	Requires    skillslock.Requires
	Agents      []string
	Targets     map[string]string
}

type SkillInspection struct {
	Skill  discovery.DiscoveredSkill
	Source string   // source identity (host/owner/repo or local path)
	Agents []string // agents the skill would install into at the given root
}

type SkillVerify struct {
	Name     string
	OK       bool
	Expected string
	Actual   string
	Issue    string // ok | missing | mismatch
}

type SourceCheckReport struct {
	Invalid    []discovery.DiscoveredSkill
	Duplicates []discovery.DuplicateConflict
}

type StoreGCReport struct {
	Applied bool
	globalstore.GCReport
}

type StoreInspectReport struct {
	Key       string
	Integrity string // "verified" | the failure detail
	SizeBytes int64
	Origins   []globalstore.Origin
	UsedBy    []string
	Pinned    bool
}

type StoreListItem struct {
	Key       string
	Skill     string
	Version   string
	SizeBytes int64
	Projects  int
}

type StoreStatusReport struct {
	Path      string
	Objects   int
	SizeBytes int64
	Projects  int
	Unused    int
	Corrupted int
}

type StoreVerifyResult struct {
	Path     string
	Checked  int
	Healthy  int
	Findings []globalstore.ScanFinding
}

type SyncChange struct {
	Name        string   `json:"name"`
	ContentHash string   `json:"content_hash"`
	Changed     bool     `json:"changed"`
	AgentsAdded []string `json:"agents_added,omitempty"`
}

type SyncRequest struct {
	Root    string
	Prune   bool
	Offline bool
}

type SyncResult struct {
	Reconciled []SyncChange
	Pruned     []string
	Orphans    []string
	UpToDate   bool
}

type TargetState string

type UnlinkResult struct {
	Skill           string
	UnlinkedAgent   string
	RemainingAgents []string
	Pruned          bool
	Unreferenced    bool
}

type VerifyReport struct {
	Skills []SkillVerify
	OK     bool
}

type VersionCandidate struct {
	Kind     string // VersionLatest | VersionRelease | VersionBranch | VersionCommit
	Label    string // display text, e.g. "v1.4.0", "main", "latest → v1.4.0"
	Version  string // bare semver for releases, when parseable
	Ref      string // tag or branch name to request
	Commit   string // exact SHA for commit candidates
	Metadata string // optional annotation shown next to the label
}

type VersionList struct {
	Candidates     []VersionCandidate
	Degraded       bool
	DegradedReason string
}