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)
	// 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()
	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
	UI            *uievents.Service
	Playlist      playlists.PlaylistController
	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:
	// - "" or "run": Default behavior (launch/play the media)
	// - "details": Show media details/info page instead of launching
	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 Launcher struct {
	// Kill function provides custom termination logic for the launcher.
	// If defined, this function is called instead of signal-based termination
	// (SIGTERM/SIGKILL). Use this for launchers that require special exit methods
	// such as keyboard shortcuts, IPC commands, or other non-signal mechanisms.
	// Example: ScummVM uses keyboard input (Ctrl+q) to avoid VT lock issues.
	Kill func(*config.Instance) error
	// Optional function to perform custom media scanning. Takes the list of
	// results from the standard scan, if any, and returns the final list.
	Scanner func(context.Context, *config.Instance, string, []ScanResult) ([]ScanResult, error)
	// Test function returns true if file looks supported by this launcher.
	// It's checked after all standard extension and folder checks.
	Test func(*config.Instance, string) bool
	// Availability checks runtime dependencies. Nil means always available.
	Availability func(*config.Instance) error
	// Launch function, takes a direct as possible path/ID media file.
	// Returns process handle for tracked processes, nil for fire-and-forget.
	// The opts parameter is optional and may be nil.
	Launch func(*config.Instance, string, *LaunchOptions) (*os.Process, error)
	// BuildLaunchCommand optionally describes the same launch as an executable
	// and argv for platform runtimes that must own the launched process tree.
	BuildLaunchCommand func(*config.Instance, string, *LaunchOptions) (*LaunchCommand, error)
	// WaitForReady optionally blocks until launched media is ready for controls
	// or raw input. If nil, platform-level readiness is used, then immediate ready.
	WaitForReady func(context.Context, *config.Instance, *models.ActiveMedia) error
	// Controls maps control action identifiers to control actions that execute
	// on active media (e.g., save state, load state, open menu).
	Controls map[string]Control
	// AvailabilityReason is populated by LauncherCache when runtime dependencies are missing.
	AvailabilityReason string
	// UsesRunningInstance identifies which running application instance this launcher
	// communicates with (e.g., "kodi", "plex"). Empty string means the launcher starts
	// its own process. When non-empty, platforms should not kill the running app if both
	// current and new launchers share the same instance identifier. Example: All Kodi
	// launchers use "kodi" to indicate they send JSON-RPC commands to the same running
	// Kodi instance rather than launching separate processes.
	UsesRunningInstance string
	// Unique ID of the launcher, visible to user.
	ID string
	// System associated with this launcher.
	SystemID string
	// Groups this launcher belongs to. Used for configuration lookup - when a config
	// entry's launcher field matches a group name, it applies to all launchers in that
	// group. Example: ["Kodi", "KodiTV"] means this launcher matches config entries for
	// both "Kodi" and "KodiTV".
	Groups []string
	// Extensions to match for files during a standard scan.
	Extensions []string
	// ScanExcludes are case-insensitive slash-normalized glob patterns that
	// prevent matched files from being indexed. Patterns without a slash match
	// the base filename; patterns with a slash can match any path suffix. They
	// only affect media scanning; direct path launches can still match the launcher.
	ScanExcludes []string
	// ScanDirectoryExcludes are case-insensitive slash-normalized glob patterns
	// relative to this launcher's Folders. Matching directories are not traversed.
	// Patterns without a slash match a directory basename; patterns with a slash
	// can match any relative path suffix. Direct path launches remain unaffected.
	ScanDirectoryExcludes []string
	// Folders to scan for files, relative to the root folders of the platform.
	Folders []string
	// Accepted schemes for URI-style launches.
	Schemes []string
	// Lifecycle determines how the launcher process is managed.
	Lifecycle LauncherLifecycle
	// If true, all resolved paths must be in the allow list before they
	// can be launched.
	AllowListOnly bool
	// SkipFilesystemScan prevents the mediascanner from walking this launcher's
	// folders during indexing. The launcher's Scanner (if any) still runs.
	// Use for launchers that rely entirely on custom scanners (e.g., Batocera
	// gamelist.xml, Kodi API queries) and don't need filesystem scanning.
	SkipFilesystemScan bool
	// ScanSkipInternalSymlinks skips symlinks whose target resolves inside this
	// launcher's Folders during media scanning. The target is indexed under its
	// own path, so the alias would only duplicate it. Applies to symlinked files
	// and directories. Direct path launches remain unaffected.
	ScanSkipInternalSymlinks bool
	// Available is populated by LauncherCache.
	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 MediaLaunchAccess struct {
	SetActiveMedia func(*models.ActiveMedia)
	Release        func()
}

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

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).
	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 ScanResult struct {
	// Path is the absolute path to 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
}

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
	// 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
}

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
}