platforms

type CmdEnv struct {
	Playlist      playlists.PlaylistController
	Cfg           *config.Instance
	Database      *database.Database
	ExprEnv       *parser.ArgExprEnv
	Cmd           parser.Command
	TotalCommands int
	CurrentIndex  int
	Unsafe        bool
}

type CmdResult struct {
	// Playlist is the result of the playlist change.
	Playlist *playlists.Playlist
	// 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 []parser.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 LaunchOptions struct {
	// 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
}

type LaunchParams struct {
	Platform       Platform
	Config         *config.Instance
	SetActiveMedia func(*models.ActiveMedia)
	Launcher       *Launcher
	DB             *database.Database
	Options        *LaunchOptions
	Path           string
}

type Launcher struct {
	// 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)
	// 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
	// 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
	// Folders to scan for files, relative to the root folders of the platform.
	// TODO: Support absolute paths?
	// TODO: rename RootDirs
	Folders []string
	// Accepted schemes for URI-style launches.
	Schemes []string
	// Extensions to match for files during a standard scan.
	Extensions []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
}

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 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.
	StartPost(
		*config.Instance,
		LauncherContextManager,
		func() *models.ActiveMedia,
		func(*models.ActiveMedia),
		*database.Database,
	) 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 a list of root folders to scan for media files.
	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
	// 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
	// ShowNotice displays a string on-screen of the platform device. Returns
	// a function that may be used to manually hide the notice and a minimum
	// amount of time that should be waited until trying to close the notice,
	// for platforms where initializing a notice takes time.
	// TODO: can this just block instead of returning a delay?
	ShowNotice(
		*config.Instance,
		widgetmodels.NoticeArgs,
	) (func() error, time.Duration, error)
	// ShowLoader displays a string on-screen of the platform device alongside
	// an animation indicating something is in progress. Returns a function
	// that may be used to manually hide the loader and an optional delay to
	// wait before hiding.
	// TODO: does this need a close delay returned as well?
	ShowLoader(*config.Instance, widgetmodels.NoticeArgs) (func() error, error)
	// ShowPicker displays a list picker on-screen of the platform device with
	// a list of Zap Link Cmds to choose from. The chosen action will be
	// forwarded to the local API instance to be run. Returns a function that
	// may be used to manually cancel and hide the picker.
	// TODO: it appears to not return said function
	ShowPicker(*config.Instance, widgetmodels.PickerArgs) error
	// ConsoleManager returns the platform's console manager for TTY/console switching.
	// Platforms without console switching return NoOpConsoleManager.
	ConsoleManager() ConsoleManager
}

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

type StopIntent int