opctx

type Cmd interface {
	// Starts the command.
	Start(ctx context.Context) error
	// Waits for the running command to exit.
	Wait(ctx context.Context) error
	// Starts and then synchronously waits for the command.
	Run(ctx context.Context) error
	// Runs the command, retrieving the command's stdout output in string form.
	// Trims the string for whitespace and removes ANSI/VT100-style escape
	// sequences.
	RunAndGetOutput(ctx context.Context) (string, error)

	// Associates a human-readable description with the command.
	SetDescription(description string) Cmd
	// Provides a hint that the command will run for a human-perceivable length
	// of time. Associates the command's long-running execution with a specific
	// caption that may be used by a UI with an indeterminate progress indicator.
	SetLongRunning(progressTitle string) Cmd

	// Registers a function that will be invoked with each line written to the given
	// file during the execution of the command.
	AddRealTimeFileListener(path string, listener LineListener) error
	// Registers a function that will be invoked with each line of text written
	// to stderr by the command.
	SetRealTimeStderrListener(listener LineListener) error
	// Registers a function that will be invoked with each line of text written
	// to stdout by the command.
	SetRealTimeStdoutListener(listener LineListener) error

	// Sets the command's standard input stream.
	SetStdin(stdin io.Reader)
	// Sets the command's standard output stream.
	SetStdout(stdout io.Writer)
	// Sets the command's standard error stream.
	SetStderr(stderr io.Writer)

	// GetArgs returns the command-line arguments for the command.
	GetArgs() []string
}

type CmdFactory interface {
	// Constructs an executable [Cmd] from a standard [exec.Cmd] object.
	Command(cmd *exec.Cmd) (Cmd, error)
	// Looks for the given command filename in the current environment's default search path.
	CommandInSearchPath(name string) bool
}

type Ctx interface {
	// Standard golang context
	context.Context

	// User experience interfaces
	Prompter
	EventListener
	Verbosity

	// External interaction
	CmdFactory
	FileSystemFactory
	OSEnvFactory

	// Other basic behaviors
	DryRunnable
}

type DryRunnable interface {
	// DryRun returns true if the operation is running in dry-run mode, meaning that no actual
	// changes are intended to be made to the host system.
	DryRun() bool
}

type Event interface {
	// Marks the event as a long-running operation, as a hint to the user experience. Provides a title
	// string that could be used for a textual progress indicator.
	SetLongRunning(title string)
	// Updates the last-known quantitative progress made toward completing the event. Provides a discrete
	// number of units completed toward a total number of units.
	SetProgress(unitsComplete int64, totalUnits int64)
	// Marks the event as completed.
	End()
}

type EventListener interface {
	// Reports an event without duration or span. Once called, the event is considered complete.
	// Provides a name for the event and arbitrary matched pairs of string/any values, exactly
	// like slog.
	Event(name string, args ...any)
	// Reports the start of an event with duration, taking the same arguments as Event().
	// Returns an [Event] object that the caller is responsible for calling .End() on
	// when the event is complete. This is often done through a defer statement.
	StartEvent(name string, args ...any) Event
}

type FS interface {
	afero.Fs
}

type File interface {
	afero.File
}

type FileSystemFactory interface {
	// Retrieves the base filesystem interface.
	FS() FS
}

type LineListener = func(ctx context.Context, line string)

type OSEnv interface {
	// Retrieve the process's current working directory.
	Getwd() (string, error)
	// Change the process's current working directory.
	Chdir(path string) error
	// Retrieve the value of the environment variable named by the key.
	Getenv(key string) string
	// Checks if the current user is a member of the given group.
	IsCurrentUserMemberOf(groupName string) (bool, error)
	// Looks up the group ID for the given group name.
	LookupGroupID(groupName string) (gid int, err error)
}

type OSEnvFactory interface {
	// Retrieves the base OS environment interface.
	OSEnv() OSEnv
}

type Prompter interface {
	// Are blocking prompts allowed?
	PromptsAllowed() bool
	// Should all prompts be auto-accepted without being displayed?
	AllPromptsAccepted() bool
	// Prompt the user to confirm auto-resolution of a problem.
	ConfirmAutoResolution(text string) bool
}

type Verbosity interface {
	// Queries whether the verbosity level is set to "verbose".
	Verbose() bool
}