plugin

type CmdInfo struct {
	// RequiredEnv holds the set of environment variable names that the
	// command needs passed to it. Only these variables are sent to the
	// plugin when the command is run.
	RequiredEnv map[string]bool

	// WritesOutput indicates whether the command sets
	// standard error and standard output.
	WritesOutput bool
}

type CmdParams struct {
	// Name is the name of the command being run.
	Name string

	// Args holds the command's arguments (not including the command name).
	Args []string

	// Dir is the absolute path of the working directory the command should
	// run in.
	Dir string

	// Env holds the values of the variables named in the command's
	// [CmdInfo.RequiredEnv], as resolved in the test environment.
	Env map[string]string

	// Stdin holds the standard input for the command.
	Stdin []byte
}

type CmdResult struct {
	// Stdout and Stderr hold the command's standard output and standard
	// error respectively.
	Stdout []byte
	Stderr []byte

	// Env holds environment variables that the command wants to set in
	// the test environment. Every key must be present in
	// [PluginInfo.ResultEnv].
	Env map[string]string

	// Err, if non-empty, holds the error message from a failure of the
	// command itself (for example a non-zero exit status). It is distinct
	// from the error returned by [TestInstance.RunCmd], which indicates a
	// failure of the plugin.
	Err string
}

type Interface interface {
	// Info returns static information about the plugin: the environment
	// variables it requires and provides, and the commands it makes
	// available to test scripts.
	Info() PluginInfo

	// NewTestInstance creates a new instance of the plugin for a single
	// running test. Multiple instances may exist concurrently.
	NewTestInstance(TestParams) (TestInstance, error)

	// Close shuts the plugin down, releasing any global resources.
	Close()
}

type PluginInfo struct {
	// RequiredEnv holds the set of environment variable names that the
	// plugin needs to be passed when creating a test instance. Only these
	// variables are sent to the plugin.
	RequiredEnv map[string]bool

	// ResultEnv holds the set of environment variable names that the
	// plugin is allowed to set in the test environment. The host rejects
	// any attempt to set a variable not in this set.
	ResultEnv map[string]bool

	// Cmds holds the set of commands provided by the plugin, keyed by
	// command name. These commands become available to a test script after
	// it runs the "plugin" command for this plugin.
	Cmds map[string]CmdInfo
}

type TestInstance interface {
	// Env returns the environment variables that the instance wants to set
	// in the test environment. Every key must be present in
	// [PluginInfo.ResultEnv].
	Env() map[string]string

	// RunCmd runs one of the commands provided by the plugin. The returned
	// error indicates a failure of the plugin itself (for example, the
	// command could not be started); a failure of the command being run is
	// reported via [CmdResult.Err].
	RunCmd(CmdParams) (CmdResult, error)

	// Close shuts the instance down, releasing any resources held for the
	// test.
	Close()
}

type TestParams struct {
	// TestName is the name of the test that the instance is for.
	TestName string

	// PluginParamsDir is the absolute path of the directory holding
	// plugin-specific parameters for the test, or empty if none was given.
	PluginParamsDir string

	// Env holds the values of the variables named in
	// [PluginInfo.RequiredEnv], as resolved in the test environment.
	Env map[string]string
}