platforms

type BackupDefinition struct {
	SourceRoot  string
	RestoreRoot string
	// RestoreTargetRoot optionally maps RestoreRoot to a platform-discovered
	// physical category root. It must never be derived from backup contents.
	RestoreTargetRoot  string
	Category           string
	Include            []BackupPattern
	Exclude            []BackupPattern
	SourceTrustedRoots []string
	NonRecursive       bool
}

type BackupPattern struct {
	Glob     string
	Contains string
	All      bool
}

type BackupPlan struct {
	Definitions []BackupDefinition
	Warnings    []BackupWarning
}

type BackupPlanningProvider interface {
	BackupPlan() BackupPlan
}

type BackupPreparingProvider interface {
	// PrepareBackup returns a non-nil, idempotent cleanup callback on success.
	// When it returns an error, cleanup is nil and must not be called.
	PrepareBackup() (BackupPlan, func() error, error)
}

type BackupProvider interface {
	BackupDefinitions() []BackupDefinition
}

type BackupRestorePreparer interface {
	PrepareBackupRestore() (func(bool) error, error)
}

type BackupRestoreRootProvider interface {
	BackupRestoreRoot() string
}

type BackupWarning struct {
	Category string
	Path     string
	Reason   string
}

type CmdEnv struct {
	// LauncherCtx is canceled when a new launcher starts and replaces the current one.
	LauncherCtx context.Context
	// ServiceCtx is canceled during full service shutdown or process stop. Use it
	// for work tied to service lifetime rather than the current launcher lifetime.
	ServiceCtx         context.Context
	WaitForMediaReady  func(context.Context) error
	AcquireMediaLaunch func() (MediaLaunchAccess, error)
	SkipMediaLaunch    func(ResolvedLaunch) bool
	PrepareMediaLaunch func(ResolvedLaunch) (bool, error)
	AcquireLaunch      func() (func(), error)
	// LaunchInProgress reports whether another launch holds the exclusive
	// launch lock. Nil when there is no launcher manager to ask.
	LaunchInProgress func() bool
	// BeforeExit runs the outgoing media's before_exit script. The launch path
	// calls it once the replacement has been resolved but before it takes the
	// media launch gate, so a launch that never happens cannot fire it and the
	// script is still free to run its own ZapScript. Nil when the hook must not
	// run, such as inside a hook script.
	BeforeExit func()
	// RefreshOwnedDeck asks wherever an owned deck syncs to look for changes
	// in the background as the deck opens. It returns at once and never
	// blocks the open; nil when no sync is configured.
	RefreshOwnedDeck func(ctx context.Context, deckID string)
	PlaybackManager  audio.PlaybackManager
	// LauncherCache resolves the launcher behind the active media. It holds
	// launchers the platform cannot build itself, so it is the only complete
	// source; never resolve a launcher ID from Platform.Launchers alone.
	LauncherCache LauncherResolver
	// Launchers memoises Platform.Launchers for this command. Nil asks the
	// platform each time.
	Launchers *LauncherSnapshot
	UI        *uievents.Service
	Playlist  playlists.PlaylistController
	// AllowedCommands is the bound the running token carries. It is forwarded
	// so a playlist opened by this command keeps the same bound, the way
	// Unsafe does.
	AllowedCommands tokens.CommandPolicy
	Cfg             *config.Instance
	Database        *database.Database
	ExprEnv         *zapscript.ArgExprEnv
	Source          string
	// PathRoot is an optional per-token root for resolving relative filesystem paths.
	PathRoot      string
	Cmd           zapscript.Command
	TotalCommands int
	CurrentIndex  int
	Unsafe        bool
}

type CmdResult struct {
	// Playlist is the result of the playlist change.
	Playlist *playlists.Playlist
	// ProfileSwitch requests the active profile be changed. Commands return
	// the request as intent; the service layer applies it (same pattern as
	// Playlist). The scan path activates without a PIN check — possession
	// of the card is the authorization.
	ProfileSwitch *ProfileSwitchRequest
	// PlaytimeExtension requests extra time for the current playtime
	// session. Like ProfileSwitch this is intent only: the service layer
	// verifies the authorizing credential and applies the grant.
	PlaytimeExtension *PlaytimeExtensionRequest
	// Strategy indicates which matching strategy was used for title-based launches.
	// Empty for non-title commands. Used for testing and debugging title resolution.
	Strategy string
	// NewCommands instructs the script runner to prepend these additional
	// commands to the current script's remaining command list.
	NewCommands []zapscript.Command
	// Confidence is a float from 0.0 to 1.0 indicating how confident the
	// a launch command was in its media resolution.
	Confidence float64
	// MediaChanged is true if a command may have started or stopped running
	// media, and could affect handling of the hold mode feature. This doesn't
	// include playlist changes, which manage running media separately.
	MediaChanged bool
	// PlaylistChanged is true if a command started/changed/stopped a playlist.
	PlaylistChanged bool
	// Unsafe flags that a token has been generate by a remote/untrusted source
	// and can no longer be considered safe. This flag will flow on to any
	// remaining commands.
	Unsafe bool
}

type ConsoleManager interface {
	// Open switches to console mode on the specified VT.
	// The provided context can be used to cancel the operation if the launcher is superseded.
	Open(ctx context.Context, vt string) error

	// Close exits console mode and returns to normal display
	Close() error

	// Clean prepares a console for use (clears screen, hides cursor)
	Clean(vt string) error

	// Restore restores console cursor state
	Restore(vt string) error
}

type Control struct {
	Func   ControlFunc // Native Go implementation
	Script string      // ZapScript string executed via RunControlScript
}

type ControlFunc func(context.Context, *config.Instance, ControlParams) error

type ControlParams struct {
	Args map[string]string
}

type InputSession interface {
	KeyboardPressSequence(context.Context, []string, time.Duration) error
	GamepadPressSequence(context.Context, []string, time.Duration) error
	ReleaseAll() error
}

type InputSessionProvider interface {
	NewInputSession() InputSession
}

type LaunchCommand struct {
	Executable string
	Dir        string
	Args       []string
	Env        []string
}

type LaunchOptions struct {
	// ActiveMediaPublisher is the launch-scoped publication callback supplied
	// by Core. Launchers must not retain or invoke it directly.
	ActiveMediaPublisher func(*models.ActiveMedia)
	// RenderScale is the preferred internal rendering size as a percentage of
	// available output dimensions. It does not change physical display mode.
	RenderScale *int
	// Action specifies the launch action. Common values:
	// - "": Automatic behavior (may open details if media is not installed)
	// - "run": Explicitly launch/play the media
	// - "details": Show media details/info page instead of launching
	// Launchers may update Action to reflect a successful automatic redirect;
	// Core uses the effective action when deciding whether to publish ActiveMedia.
	Action string
	// RenderResolution is the preferred fixed internal rendering size in
	// WIDTHxHEIGHT form. It is mutually exclusive with RenderScale.
	RenderResolution string
	// SetName specifies a platform-defined launch profile/core name override.
	// On MiSTer this maps to the MGL <setname> tag.
	SetName string
	// SetNameSameDir is a raw optional platform-defined flag controlling whether
	// SetName should keep the original game directory. On MiSTer this maps to the
	// MGL setname same_dir attribute. Unsupported platforms may ignore it.
	SetNameSameDir string
	// Slot selects the media slot for launch routing. Empty means primary.
	Slot string
}

type LaunchParams struct {
	// Context scopes best-effort post-launch metadata lookups.
	Context        context.Context
	Platform       Platform
	Config         *config.Instance
	SetActiveMedia func(*models.ActiveMedia)
	Launcher       *Launcher
	DB             *database.Database
	Options        *LaunchOptions
	Path           string
}

type LaunchPathNormalizer interface {
	NormalizeLaunchPath(string) string
}

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

type LaunchRepairReason string

type Launcher struct {
	Controls                 map[string]Control
	Scanner                  func(context.Context, *config.Instance, string, []ScanResult) ([]ScanResult, error)
	Test                     func(*config.Instance, string) bool
	Availability             func(*config.Instance) error
	Preflight                func(*config.Instance, string, *LaunchOptions) error
	Kill                     func(*config.Instance) error
	Launch                   func(*config.Instance, string, *LaunchOptions) (*os.Process, error)
	BuildLaunchCommand       func(*config.Instance, string, *LaunchOptions) (*LaunchCommand, error)
	WaitForReady             func(context.Context, *config.Instance, *models.ActiveMedia) error
	ID                       string
	SystemID                 string
	UsesRunningInstance      string
	AvailabilityReason       string
	Detected                 *bool
	Folders                  []string
	Groups                   []string
	Extensions               []string
	ScanExcludes             []string
	ScanDirectoryExcludes    []string
	Schemes                  []string
	Lifecycle                LauncherLifecycle
	SupportsDetails          bool
	AllowListOnly            bool
	SkipFilesystemScan       bool
	ScanSkipInternalSymlinks bool
	ScanOnly                 bool
	Available                bool
}

type LauncherContextManager interface {
	// GetContext returns the current launcher context
	GetContext() context.Context
	// NewContext cancels the current context and creates a new one
	NewContext() context.Context
}

type LauncherLifecycle int

type LauncherRefreshProvider interface {
	RefreshLauncherDependencies() error
}

type LauncherResolver interface {
	GetLauncherByID(id string) *Launcher
}

type LauncherRuntimeProvider interface {
	LauncherRuntime(cfg *config.Instance, l *Launcher) models.LauncherRuntime
}

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

type MediaHistoryHooks struct {
	// ActiveProfileID returns the profile a launch is attributed to, or "".
	ActiveProfileID func() string
	// Changed tells API clients to refetch history. It never blocks.
	Changed func()
}

type MediaHistoryRecorder interface {
	SetMediaHistoryHooks(MediaHistoryHooks)
}

type MediaLaunchAccess struct {
	SetActiveMedia func(*models.ActiveMedia)
	Release        func()
}

type MediaReadyPlatform interface {
	WaitForMediaReady(context.Context, *config.Instance, *models.ActiveMedia) error
}

type MediaSource struct {
	Path  string
	Root  string
	Kind  MediaSourceKind
	Group string
}

type MediaSourceKind string

type NoOpConsoleManager struct{}

type Platform interface {
	// ID returns the unique ID of this platform.
	ID() string
	// StartPre runs any necessary platform setup BEFORE the main service has
	// started running.
	StartPre(*config.Instance) error
	// StartPost runs any necessary platform setup AFTER the main service has
	// started running. The ctx is the service-scoped context: any background
	// work the platform spawns (idle-scheduled tasks, network polls, etc.)
	// should honour it so it exits promptly on shutdown. The scheduler may be
	// nil; platforms that defer work to idle should nil-check before using it.
	StartPost(
		context.Context,
		*config.Instance,
		LauncherContextManager,
		func() *models.ActiveMedia,
		func(*models.ActiveMedia),
		*database.Database,
		*idle.Scheduler,
	) error
	// Stop runs any necessary cleanup tasks before the rest of the service
	// starts shutting down.
	Stop() error
	// Settings returns all simple platform-specific settings such as paths.
	// NOTE: Some values on the Settings struct should be accessed using helper
	// functions in the utils package instead of directly. Check comments.
	Settings() Settings
	// ScanHook is run immediately AFTER a successful scan, but BEFORE it is
	// processed for launching.
	ScanHook(*tokens.Token) error
	// SupportedReaders returns a list of supported reader modules for platform.
	SupportedReaders(*config.Instance) []readers.Reader
	// RootDirs returns root folders to scan for media files, ordered from
	// highest to lowest priority. Consumers resolving duplicate relative names
	// must prefer the first matching root.
	RootDirs(*config.Instance) []string
	// StopActiveLauncher kills/exits the currently running launcher process
	// and clears the active media if it was successful.
	// intent indicates whether this is a preemption (new launcher starting)
	// or a termination (returning to menu).
	// Returns nil when nothing was running or the stop is confirmed, and an
	// error wrapping ErrStopFailed when the media is known to still be
	// running. Active media is only cleared when the stop succeeded.
	StopActiveLauncher(intent StopIntent) error
	// ReturnToMenu returns the platform to its main UI/launcher/frontend.
	// For platforms with a menu system (MiSTer OSD, EmulationStation, Steam Big Picture),
	// this launches the menu/frontend. For platforms without a menu concept, this is a no-op.
	// This is separate from StopActiveLauncher to allow optimized transitions where
	// returning to the menu is not always necessary (e.g., MGL to MGL on MiSTer).
	ReturnToMenu() error
	// SetTrackedProcess stores a process handle for lifecycle management.
	// Used by DoLaunch to track processes that can be killed later.
	SetTrackedProcess(*os.Process)
	// LaunchSystem launches a system by ID. This generally means, if a
	// platform even has the capability, attempt to launch the default or most
	// appropriate launcher for a given system, without any media loaded.
	LaunchSystem(*config.Instance, string) error
	// LaunchMedia launches some media by path and sets the active media if it
	// was successful. Pass nil for launcher to auto-detect, or a specific Launcher.
	// The opts parameter is optional and may be nil.
	LaunchMedia(*config.Instance, string, *Launcher, *database.Database, *LaunchOptions) error
	// KeyboardPress presses and then releases a single keyboard button on a
	// virtual keyboard, using a key name from the ZapScript format.
	KeyboardPress(string) error
	// GamepadPress presses and then releases a single gamepad button on a
	// virtual gamepad, using a button name from the ZapScript format.
	GamepadPress(string) error
	// Screenshot captures a screenshot of the current platform display,
	// saves it to disk, and returns the file path and raw image bytes.
	Screenshot() (*ScreenshotResult, error)
	// ForwardCmd processes a platform-specific ZapScript command.
	ForwardCmd(*CmdEnv) (CmdResult, error)
	// LookupMapping is a platform-specific method of matching a token to a
	// mapping. It takes last precedence when checking mapping sources.
	LookupMapping(*tokens.Token) (string, bool) // DEPRECATED
	// Launchers is the complete list of all launchers available on this
	// platform.
	Launchers(*config.Instance) []Launcher
	// ConsoleManager returns the platform's console manager for TTY/console switching.
	// Platforms without console switching return NoOpConsoleManager.
	ConsoleManager() ConsoleManager
	// ManagedByPackageManager returns true if this install is managed by an
	// external package manager (e.g. MiSTer Downloader, Batocera pacman).
	// Used to default auto-update off for package-managed installs.
	ManagedByPackageManager() bool
	// Scrapers returns the metadata scrapers available on this platform,
	// keyed by scraper ID. The map may be empty if no scrapers are supported.
	Scrapers(*config.Instance) map[string]Scraper
}

type PlaytimeExtensionRequest struct {
	// Mode is models.PlaytimeExtendModeDuration or ...ModeToday.
	Mode string
	// AuthorizerSwitchID is the switch ID of the authorizing profile.
	AuthorizerSwitchID string
	// Duration is the time to add, for duration mode only.
	Duration time.Duration
}

type PowerStatusProvider interface {
	PowerStatus() (power.Status, error)
}

type ProfileDataSwapper interface {
	// ProfileItems reports what a profile change can affect on this
	// platform.
	ProfileItems() []ProfileItem
	// ApplyProfile makes the platform's profile-scoped data current for
	// the given profile, applying only the enabled item IDs. It is called
	// only while no media is running, must be idempotent, and must leave
	// existing data intact on failure.
	ApplyProfile(ref ProfileRef, enabledItems []string) error
}

type ProfileDataWatcher interface {
	// WatchProfileData invokes onChange (possibly from another goroutine)
	// whenever platform storage state changes, until ctx is done.
	WatchProfileData(ctx context.Context, onChange func())
}

type ProfileItem struct {
	ID    string // stable identity, e.g. "saves", "savestates"
	Label string // for client UI, e.g. "Save files"
	Owner string // one of the ProfileItemOwner* constants
}

type ProfileRef struct {
	ID   string
	Name string
}

type ProfileSwitchRequest struct {
	SwitchID string
	Clear    bool
}

type ResolvedLaunch struct {
	Launcher *Launcher
	Options  *LaunchOptions
	Path     string
	SystemID string
}

type ScanResult struct {
	// Source is optional local metadata provenance for a virtual launch URI.
	Source *MediaSource
	// Path is the absolute path or virtual launch URI for this media.
	Path string
	// Name is the display name of the media, shown to the users and used for
	// search queries.
	Name string
	// NoExt indicates this is a virtual path with no file extension.
	// When true, filepath.Ext() extraction is skipped to avoid extracting
	// garbage from paths like "/games/file.txt/Game (v1.0)" or "kodi://123/Dr. Strange".
	NoExt bool
}

type Scraper struct {
	CustomOpts ScraperCustomOptions
	Scrape     func(
		ctx context.Context,
		cfg *config.Instance,
		pl Platform,
		fs afero.Fs,
		db *database.Database,
		opts scraper.ScrapeOptions,
		custom ScraperCustomOptions,
		ch chan<- scraper.ScrapeUpdate,
	) error
	ID                 string
	Name               string
	SupportedSystemIDs []string
	// AutoScrapeLaunchers opts successful index contributions into ordinary
	// fill-missing jobs. Empty leaves this scraper manual-only.
	AutoScrapeLaunchers []string
	SupportsFillMissing bool
}

type ScraperCustomOption struct {
	Name  string
	Value string
}

type ScraperCustomOptions map[string][]ScraperCustomOption

type ScreenshotResult struct {
	// Path is the absolute path where the screenshot was saved on disk.
	Path string
	// Data is the raw image bytes of the screenshot.
	Data []byte
}

type ServiceReadyPlatform interface {
	WaitForServiceReady(context.Context, *config.Instance) error
}

type Settings struct {
	// DataDir returns the root folder where things like databases and
	// downloaded assets are permanently stored. WARNING: This value should be
	// accessed using the DataDir function in the utils package.
	DataDir string
	// ConfigDir returns the directory where the config file is stored.
	// WARNING: This value should be accessed using the ConfigDir function in
	// the utils package.
	ConfigDir string
	// TempDir returns a temporary directory for files used for inter-process
	// communication such as PID files and temporary binaries. Expect it to be
	// deleted.
	TempDir string
	// LogDir returns the directory where persistent log files are stored.
	LogDir string
	// HostManagedPaths makes the supplied directories authoritative instead of probing
	// for a portable user directory next to the current executable.
	HostManagedPaths bool
	// DisableSelfUpdate means the host updates this component as part of its own package.
	// Neither automatic nor manually requested executable updates may run.
	DisableSelfUpdate bool
	// ZipsAsDir returns true if this platform treats .zip files as if they
	// were directories for the purpose of launching media.
	ZipsAsDirs bool
	// DisableZapScriptInTUI prevents token scans from launching media while
	// the main TUI occupies the platform's primary display. Utility widgets do
	// not apply this policy because their controls can trigger ZapScript.
	DisableZapScriptInTUI bool
	// ResourceConstrained indicates the platform has limited CPU and I/O
	// capacity. Core uses lower-cost audio processing and cooperatively paces
	// expensive background media work on these platforms.
	ResourceConstrained bool
	// ThrottleBackground paces indexing and scraping the same way as
	// ResourceConstrained, so an interactive host keeps CPU time for its UI,
	// without the other ResourceConstrained effects (audio quality, scanner
	// walkers, import limits, thumbnail concurrency).
	ThrottleBackground bool
}

type SourceEntry struct {
	// Name is the entry's own name, never a path.
	Name string
	// Size is the file size in bytes, or -1 when unknown.
	Size int64
	Dir  bool
}

type SourceFileReader interface {
	// ReadSourceFile returns up to limit+1 bytes of the file at path (a
	// source root path below a root, never a bare root), so a caller can
	// detect an oversized file without reading all of it.
	ReadSourceFile(ctx context.Context, path string, limit int64) ([]byte, error)
}

type SourceRootReader interface {
	// SourceRoots returns the source roots Core may index now, each made by
	// SourceRootPath. It is called once at the start of an index run.
	SourceRoots(ctx context.Context) ([]string, error)
	// ReadSourceDir lists one directory. path is a source root or a
	// directory below one, as a canonical multi-segment virtual path.
	ReadSourceDir(ctx context.Context, path string) ([]SourceEntry, error)
}

type StopIntent int

type SystemLauncherSelector interface {
	LaunchSystemLauncher(cfg *config.Instance, systemID string, launcher *Launcher) error
}

type TrackedProcessMediaClearer interface {
	ClearTrackedProcessMedia(*os.Process) bool
}

type TrackedProcessWaiter interface {
	WaitTrackedProcess(*os.Process) error
}

type UpdatePayloadProvider interface {
	UpdatePayload() []updatepayload.File
}