"Task" API: Simplified usage and "normalized" naming scheme

examples/custom_runner/runners.go

@@ -0,0 +1,141 @@
+// +build mage
+
+package main
+
+import (
+	"fmt"
+	"os/exec"
+
+	"github.com/magefile/mage/sh"
+	glFS "github.com/svengreb/golib/pkg/io/fs"
+
+	"github.com/svengreb/wand/pkg/task"
+)
+
+const (
+	// DefaultRunnerExec is the default name of the runner executable.
+	DefaultRunnerExec = "fruitctl"
+
+	// RunnerName is the name of the runner.
+	RunnerName = "fruit_mixer"
+)
+
+// FruitMixerOption is a fruit mixer runner option.
+type FruitMixerOption func(*FruitMixerOptions)
+
+// FruitMixerOptions are fruit mixer runner options.
+type FruitMixerOptions struct {
+	// Env is the runner specific environment.
+	Env map[string]string
+
+	// Exec is the name or path of the runner command executable.
+	Exec string
+
+	// Quiet indicates whether the runner output should be minimal.
+	Quiet bool
+}
+
+// FruitMixerRunner is a task runner for the fruit mixer.
+type FruitMixerRunner struct {
+	opts *FruitMixerOptions
+}
+
+// FilePath returns the path to the runner executable.
+func (r *FruitMixerRunner) FilePath() string {
+	return r.opts.Exec
+}
+
+// Handles returns the supported task kind.
+func (r *FruitMixerRunner) Handles() task.Kind {
+	return task.KindExec
+}
+
+// Run runs the command.
+// It returns an error of type *task.ErrRunner when any error occurs during the command execution.
+func (r *FruitMixerRunner) Run(t task.Task) error {
+	tExec, ok := t.(task.Exec)
+	if t.Kind() != task.KindExec || !ok {
+		return &task.ErrRunner{
+			Err:  fmt.Errorf("expected %q but got %q", r.Handles(), t.Kind()),
+			Kind: task.ErrUnsupportedTaskKind,
+		}
+	}
+
+	runFn := sh.RunWithV
+	if r.opts.Quiet {
+		runFn = sh.RunWith
+	}
+
+	for k, v := range tExec.Env() {
+		r.opts.Env[k] = v
+	}
+
+	return runFn(r.opts.Env, r.opts.Exec, tExec.BuildParams()...)
+}
+
+// Validate validates the command executable.
+// It returns an error of type *task.ErrRunner when the executable does not exist and when it is also not available in
+// the executable search path(s) of the current environment.
+func (r *FruitMixerRunner) Validate() error {
+	// Check if the executable exists,...
+	execExits, fsErr := glFS.RegularFileExists(r.opts.Exec)
+	if fsErr != nil {
+		return &task.ErrRunner{
+			Err:  fmt.Errorf("command runner %q: %w", RunnerName, fsErr),
+			Kind: task.ErrRunnerValidation,
+		}
+	}
+	// ...otherwise try to look up the executable search path(s).
+	if !execExits {
+		path, pathErr := exec.LookPath(r.opts.Exec)
+		if pathErr != nil {
+			return &task.ErrRunner{
+				Err:  fmt.Errorf("command runner %q: %q not found in PATH: %w", RunnerName, r.opts.Exec, pathErr),
+				Kind: task.ErrRunnerValidation,
+			}
+		}
+		r.opts.Exec = path
+	}
+
+	return nil
+}
+
+// NewFruitMixerRunner creates a new fruit mixer command runner.
+func NewFruitMixerRunner(opts ...FruitMixerOption) *FruitMixerRunner {
+	return &FruitMixerRunner{opts: NewFruitMixerRunnerOptions(opts...)}
+}
+
+// NewFruitMixerRunnerOptions creates new fruit mixer runner options.
+func NewFruitMixerRunnerOptions(opts ...FruitMixerOption) *FruitMixerOptions {
+	opt := &FruitMixerOptions{
+		Env:  make(map[string]string),
+		Exec: DefaultRunnerExec,
+	}
+	for _, o := range opts {
+		o(opt)
+	}
+
+	return opt
+}
+
+// WithEnv sets the runner specific environment.
+func WithEnv(env map[string]string) FruitMixerOption {
+	return func(o *FruitMixerOptions) {
+		o.Env = env
+	}
+}
+
+// WithExec sets the name or path of the runner command executable.
+// Defaults to DefaultRunnerExec.
+func WithExec(nameOrPath string) FruitMixerOption {
+	return func(o *FruitMixerOptions) {
+		o.Exec = nameOrPath
+	}
+}
+
+// WithQuiet indicates whether the runner output should be minimal.
+func WithQuiet(quiet bool) FruitMixerOption {
+	return func(o *FruitMixerOptions) {
+		o.Quiet = quiet
+	}
+}

examples/custom_task/tasks.go

@@ -0,0 +1,104 @@
+// +build mage
+
+package main
+
+import (
+	"github.com/svengreb/wand"
+	"github.com/svengreb/wand/pkg/app"
+	"github.com/svengreb/wand/pkg/task"
+)
+
+// MixOption is a mix task option.
+type MixOption func(*MixOptions)
+
+// MixOptions are mix task options.
+type MixOptions struct {
+	// env is the task specific environment.
+	env map[string]string
+
+	// extraArgs are additional arguments passed to the command.
+	extraArgs []string
+
+	// fruits are the fruits.
+	fruits []string
+
+	// verbose indicates whether the output should be verbose.
+	verbose bool
+}
+
+// MixTask is a mix task for the fruit CLI.
+type MixTask struct {
+	ac   app.Config
+	opts *MixOptions
+}
+
+// BuildParams builds the parameters.
+func (t *MixTask) BuildParams() []string {
+	var params []string
+
+	// Toggle verbose output.
+	if t.opts.verbose {
+		params = append(params, "-v")
+	}
+
+	// Include additionally configured arguments.
+	params = append(params, t.opts.extraArgs...)
+
+	// Append all fruits.
+	params = append(params, t.opts.fruits...)
+
+	return params
+}
+
+// Env returns the task specific environment.
+func (t *MixTask) Env() map[string]string {
+	return t.opts.env
+}
+
+// Kind returns the task kind.
+func (t *MixTask) Kind() task.Kind {
+	return task.KindExec
+}
+
+// Options returns the task options.
+func (t *MixTask) Options() task.Options {
+	return *t.opts
+}
+
+// NewMixTask creates a new mix task for the fruit CLI.
+func NewMixTask(wand wand.Wand, ac app.Config, opts ...MixOption) (*MixTask, error) {
+	return &MixTask{ac: ac, opts: NewMixOptions(opts...)}, nil
+}
+
+// NewMixOptions creates new mix task options.
+func NewMixOptions(opts ...MixOption) *MixOptions {
+	opt := &MixOptions{
+		env: make(map[string]string),
+	}
+	for _, o := range opts {
+		o(opt)
+	}
+
+	return opt
+}
+
+// WithEnv sets the mix task specific environment.
+func WithEnv(env map[string]string) MixOption {
+	return func(o *MixOptions) {
+		o.env = env
+	}
+}
+
+// WithFruits adds fruits.
+func WithFruits(fruits ...string) MixOption {
+	return func(o *MixOptions) {
+		o.fruits = append(o.fruits, fruits...)
+	}
+}
+
+// WithVerboseOutput indicates whether the output should be verbose.
+func WithVerboseOutput(verbose bool) MixOption {
+	return func(o *MixOptions) {
+		o.verbose = verbose
+	}
+}

examples/monorepo/apps/cli/cli.go

@@ -0,0 +1,9 @@
+package main
+
+import (
+	"github.com/svengreb/wand/examples/monorepo/pkg/cmd/cli"
+)
+
+func main() {
+	cli.Main()
+}

examples/monorepo/apps/daemon/daemon.go

@@ -0,0 +1,9 @@
+package main
+
+import (
+	"github.com/svengreb/wand/examples/monorepo/pkg/cmd/daemon"
+)
+
+func main() {
+	daemon.Main()
+}

examples/monorepo/apps/promexp/promexp.go

@@ -0,0 +1,9 @@
+package main
+
+import (
+	"github.com/svengreb/wand/examples/monorepo/pkg/cmd/promexp"
+)
+
+func main() {
+	promexp.Main()
+}

examples/monorepo/magefile.go

@@ -0,0 +1,99 @@
+// +build mage
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/magefile/mage/mg"
+	"github.com/svengreb/nib"
+	"github.com/svengreb/nib/inkpen"
+
+	appCLI "github.com/svengreb/wand/examples/monorepo/pkg/cmd/cli"
+	appDaemon "github.com/svengreb/wand/examples/monorepo/pkg/cmd/daemon"
+	appPromExp "github.com/svengreb/wand/examples/monorepo/pkg/cmd/promexp"
+	"github.com/svengreb/wand/pkg/elder"
+	wandProj "github.com/svengreb/wand/pkg/project"
+	wandProjVCS "github.com/svengreb/wand/pkg/project/vcs"
+	taskGo "github.com/svengreb/wand/pkg/task/golang"
+	taskGoBuild "github.com/svengreb/wand/pkg/task/golang/build"
+)
+
+const (
+	projectDisplayName = "Fruit Mixer"
+	projectName        = "fruit-mixer"
+)
+
+var elderWand *elder.Elder
+
+func init() {
+	// Create a new "elder wand".
+	ew, ewErr := elder.New(
+		// Provide information about the project.
+		elder.WithProjectOptions(
+			wandProj.WithName(projectName),
+			wandProj.WithDisplayName(projectDisplayName),
+			wandProj.WithVCSKind(wandProjVCS.KindNone),
+			wandProj.WithModulePath("github.com/svengreb/wand/examples/monorepo"),
+		),
+		// Use "github.com/svengreb/nib/inkpen" module as line printer for human-facing messages.
+		elder.WithNib(inkpen.New()),
+	)
+	if ewErr != nil {
+		fmt.Printf("Failed to initialize elder wand: %v\n", ewErr)
+		os.Exit(1)
+	}
+
+	// Register any amount of project applications (monorepo layout).
+	apps := []struct {
+		name, displayName, pathRel string
+	}{
+		{appCLI.Name, appCLI.DisplayName, "apps/cli"},
+		{appDaemon.Name, appDaemon.DisplayName, "apps/daemon"},
+		{appPromExp.Name, appPromExp.DisplayName, "apps/promexp"},
+	}
+	for _, app := range apps {
+		if regErr := ew.RegisterApp(app.name, app.displayName, app.pathRel); regErr != nil {
+			ew.ExitPrintf(1, nib.ErrorVerbosity, "Failed to register application %q: %v", app.name, regErr)
+		}
+	}
+
+	elderWand = ew
+}
+
+func baseGoBuild(appName string) {
+	buildErr := elderWand.GoBuild(
+		appName,
+		taskGoBuild.WithBinaryArtifactName(appName),
+		taskGoBuild.WithOutputDir("out"),
+		taskGoBuild.WithGoOptions(
+			taskGo.WithTrimmedPath(true),
+		),
+	)
+	if buildErr != nil {
+		fmt.Printf("Build incomplete: %v\n", buildErr)
+	}
+	elderWand.Successf("Build completed")
+}
+
+func Build(mageCtx context.Context) {
+	mg.SerialDeps(
+		CLI.Build,
+		Daemon.Build,
+		PrometheusExporter.Build,
+	)
+}
+
+type CLI mg.Namespace
+
+func (CLI) Build(mageCtx context.Context) { baseGoBuild(appCLI.Name) }
+
+type Daemon mg.Namespace
+
+func (Daemon) Build(mageCtx context.Context) { baseGoBuild(appDaemon.Name) }
+
+type PrometheusExporter mg.Namespace
+
+func (PrometheusExporter) Build(mageCtx context.Context) { baseGoBuild(appPromExp.Name) }