source

type AuthInstructionsProvider interface{ AuthInstructions() string }

type Capabilities struct {
	Search       bool
	Dependencies bool
	Updates      bool
	Auth         bool
	// Versions: the source CAN carry per-file Version strings usable for
	// exact version->file resolution (#96). Advisory, not a guarantee:
	// resolution itself degrades dynamically per mod - a file list with no
	// version data yields ErrNotSupported even when this is true (see
	// core.ResolveVersionFiles).
	Versions bool
}

type CapabilityReporter interface {
	Capabilities() Capabilities
}

type DownloadHeaderProvider interface {
	DownloadHeaders(fileURL string) map[string]string
}

type EnvKeyProvider interface{ EnvKey() string }

type GameCatalog interface {
	ListGames(ctx context.Context) ([]GameEntry, error)
}

type GameEntry struct{ ID, Name, Slug string }

type KeyValidator interface {
	ValidateKey(ctx context.Context, key string) error
}

type MergeCompiler interface {
	// ValidateSource parses/validates sourceFilePath (the retained,
	// not-yet-merged source archive) without compiling anything - called at
	// ingest time (download/import) so a malformed archive fails loud
	// immediately rather than at the next merge.
	ValidateSource(sourceFilePath string) error

	// MergeCompile applies every entry in sources, in order (profile load
	// order), against the base artifact's tables, and writes the merged
	// result to outputPath. Returns non-fatal warnings (e.g. same-path
	// asset collisions - last-applied wins) alongside a nil error; a nil
	// error with warnings is still a fully-written, deployable artifact.
	// Convertible-kind sources that cannot be converted are skipped per-mod
	// and reported in failed (#221) - only native-source errors and I/O
	// failures are fatal.
	MergeCompile(ctx context.Context, baseArtifactPath string, sources []MergeSource, outputPath string) (warnings []string, failed []MergeFailure, err error)

	// ResolveBaseArtifact locates the installed game's base artifact - the
	// input every merge applies against (Icarus: the game's own
	// Content/Data/data.pak). Errors when the artifact cannot be found
	// under the game's install path.
	ResolveBaseArtifact(game *domain.Game) (string, error)

	// FingerprintBase returns an opaque fingerprint of the base artifact at
	// baseArtifactPath: cheap to compute, changing exactly when the base
	// content changes. Core stores it in merge fingerprints to detect a
	// game-update-invalidated merge; it never interprets the value.
	FingerprintBase(baseArtifactPath string) (string, error)

	// IsNativeMergeSource reports whether fileName names this source's
	// NATIVE merge-source format (Icarus: a ".exmodz" archive) - the diff
	// format MergeCompile consumes directly, with no other valid
	// interpretation at ingest. Pure format test, the mirror of
	// IsConvertibleArtifact - core owns the DeployCompile policy gates and
	// routes native files into validate+retain instead of extract/copy.
	IsNativeMergeSource(fileName string) bool

	// IsConvertibleArtifact reports whether fileName names a raw, prebuilt
	// game artifact this source can convert into a merge source (#221;
	// Icarus: a ".pak" file). Pure format test - core owns the
	// DeployCompile/ConvertPaks policy gates that decide whether such a
	// file actually enters the merge-convert pipeline.
	IsConvertibleArtifact(fileName string) bool

	// ClassifyMergeSource maps a retained-source identity - a fileID, an
	// imported archive's filename, or a Kind string previously recorded on
	// a merge fingerprint - to the source-defined kind string core
	// round-trips (MergeSource.Kind, fingerprint entries) and whether that
	// kind is a convertible raw artifact (subject to the ConvertPaks
	// opt-out and per-mod conversion outcomes) as opposed to the source's
	// native mergeable format. Must accept the empty string (legacy
	// fingerprints recorded no Kind) and classify it as the native kind.
	ClassifyMergeSource(id string) (kind string, convertible bool)

	// MergedArtifactName names the single merged output artifact core
	// deploys into the game's mod directory. The name is a deploy contract:
	// it must stay stable across merges (core stats/replaces it by name),
	// and any load-order significance it carries (Icarus: sorts last so it
	// wins) is entirely the source's concern.
	MergedArtifactName() string

	// MergedArtifactLabel is the user-facing display name for the merged
	// artifact's synthetic mod row (verify/update output).
	MergedArtifactLabel() string

	// RestoredArtifactName names the deployable raw-fallback copy core
	// synthesizes when healing a prune-damaged cache entry whose original
	// artifact name is unrecoverable (#250; Icarus: "<modID>_P.pak").
	// Deterministic per mod - the same mod must always restore to the same
	// name, since the name is on-disk state existing installs depend on.
	// Core passes a path-safe (Base'd) modID and uses the result as a
	// filename within the mod's own cache entry.
	RestoredArtifactName(modID string) string
}

type MergeFailure struct {
	ModRef string
	Reason string
}

type MergeSource struct {
	ModRef     string // "sourceID:modID" - machine identity (MergeFailure, ownership tracking)
	ModName    string // display name preferred over ModRef in user-facing warnings; may be empty
	SourcePath string // the retained source archive to read (native diff, or a convertible raw artifact - #221)
	Kind       string // source-defined kind from ClassifyMergeSource; empty means the source's native kind (#256)
}

type ModSource interface {
	// Identity
	ID() string
	Name() string

	// Authentication
	AuthURL() string
	ExchangeToken(ctx context.Context, code string) (*Token, error)

	// Discovery
	Search(ctx context.Context, query SearchQuery) (SearchResult, error)
	GetMod(ctx context.Context, gameID, modID string) (*domain.Mod, error)
	GetDependencies(ctx context.Context, mod *domain.Mod) ([]domain.ModReference, error)

	// Downloads
	GetModFiles(ctx context.Context, mod *domain.Mod) ([]domain.DownloadableFile, error)
	GetDownloadURL(ctx context.Context, mod *domain.Mod, fileID string) (string, error)

	// Updates
	CheckUpdates(ctx context.Context, installed []domain.InstalledMod) ([]domain.Update, error)
}

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

type SearchQuery struct {
	GameID   string
	Query    string
	Category string   // Optional category filter (source-specific: ID or name)
	Tags     []string // Optional tag filters (source-specific)
	Page     int
	PageSize int
}

type SearchResult struct {
	Mods       []domain.Mod
	TotalCount int // Total results available (0 if unknown)
	Page       int
	PageSize   int
}

type Token struct {
	AccessToken  string
	RefreshToken string
	ExpiresAt    time.Time
}

type TypeLabeler interface{ TypeLabel() string }