plugin

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

type GoalDescription interface {
	// Name is the top-level name of the task. This is preferable a single,
	// short verb. It must be all lowercase letters or may contain a hyphen.
	// This will be the default command-name to use to execute this task and
	// associated sub-tasks and also must match the first path element of a
	// SubTaskDescription Name.
	Name() string

	// Short is the short description of the task to show the user when showing
	// usage information for the task.
	Short() string

	// Aliases returns other names (possibly shortened names) to grant
	// implementations of this task.
	Aliases() []string
}

type Interface interface {
	// Implements will list the tasks that this plugin implements. It may return
	// an empty list if no task is implemented. A task is only permitted to
	// implement a single task with a given name.
	Implements(ctx context.Context) (tasks []TaskDescription, err error)

	// Goal will return the GoalDefinition for the given goal name, which
	// provides documentation for the named top-level goal. This method should
	// return ErrUnsupportedGoal when no such top-level task is defined by this
	// plugin.
	Goal(ctx context.Context, name string) (def GoalDescription, err error)

	// Prepare should return an initialized Task object that is configured using
	// the given global configuration as well as the task configuration. The
	// object passed for task configuration is specific to the given taskName.
	//
	// The lifecycle of this method needs to be handled such that the return
	// value from this method must be handled similar to the following:
	//
	//  task, err := taskInterface.Prepare(ctx, taskName, globalCfg)
	//  if err != nil {
	//    if task != nil {
	//      cancelErr := taskInterface.Cancel(ctx, task)
	//      if cancelErr != nil {
	//        log.Print(cancelErr)
	//      }
	//    }
	//    return err
	//  }
	//
	// Once a task is returned from this method, you must either call Cancel
	// or Close on the Interface with the given task object or risk leaking
	// resources or having other unfinished working and unexpected results.
	//
	// This should return ErrUnsupportedTask if the given taskName does not
	// match a supported task.
	Prepare(
		ctx context.Context,
		taskName string,
	) (task Task, err error)

	// Cancel must be called when a task is not going to be completed in full.
	// The implementation will use this opportunity to call teardown and perform
	// any cleanup actions that have been queued up to try to undo the work done
	// so far.
	Cancel(ctx context.Context, task Task) (err error)

	// Complete must be called when a task has been run to completion. This
	// allows the task to perform any final teardown and cleanup resources.
	Complete(ctx context.Context, task Task) (err error)
}

type Operation struct {
	Order  Ordering
	Action OperationHandler
}

type OperationFunc func(ctx context.Context) error

type OperationHandler interface {
	// Call performs the operation. An error will typically result in
	// termination of the entire task with the given error.
	Call(ctx context.Context) error
}

type Operations []Operation

type Ordering int

type SimpleTask func()

type Task interface {
	// Setup should be used exclusively for initial setup of the Task, such as
	// acquiring resources, setting clients and connections, and other
	// housekeeping tasks. No operations related to performing the task should
	// be performed here.
	Setup(context.Context) error

	// Check should only execute initial validation and guard functions to
	// prevent the operation from continuing. No writes or modifications ought
	// to be performed here. This can also be a reasonable stage at which to
	// detect and setup property values for later use.
	Check(context.Context) error

	// Begin should be used to prepare early stage operations for the task.
	Begin(context.Context) (Operations, error)

	// Run should be used to prepare middle stage operations for the task.
	Run(context.Context) (Operations, error)

	// End should be used to prepare late stage operations for the task.
	End(context.Context) (Operations, error)

	// Finish should be used for any final checks to ensure the task has been
	// performed correctly and sanely. Modifications should not be performed
	// at this late stage.
	Finish(context.Context) error

	// Teardown should only be used to releasing resources, closing connections,
	// and internal cleanup. No operations realted to performing the task should
	// be performed here.
	Teardown(context.Context) error
}

type TaskBoilerplate struct{}

type TaskDescription interface {
	// Name is a path starting with a leading slash naming the sub-task. The
	// first element of this path must match a TaskDescription defined by the
	// given Plugin (or a built-in task). The remaining path elements define a
	// sub-task of the level above. This is usually of the form of /verb/noun
	// where short words a preferred and the names must be lowercase and may
	// contain hyphens.
	//
	// The path elements here will become the names of the sub-commands on the
	// command-line if a user wants to execute a sub-step of a larger task.
	Name() string

	// Short is the short description of what this sub-task does. It will be
	// combined with all other like-named sub-tasks to from the description text
	// shown when usage help is requested. This description should be very
	// concise.
	Short() string

	// Requires names zero or more sub-task names on which this task depends.
	// Usually, these will be other sub-tasks that are defined by this plugin.
	//
	// Actual sub-task dependencies are calculated by calculating the
	// requirements of all like-named sub-tasks together. For example, if
	// /release/publish in plugin A depends on /release/mint and it dapends on
	// /release/wait in plugin B and both plugins will be executed, then this
	// task will not be executed until after both /release/wait and
	// /release/mint have been executed.
	Requires() []string
}

type Tasks []Task