feat(conga,dev): worker and scheduler reports, summer dev runs serve

- queue:work and schedule:run print a startup summary and a shutdown
  report on a terminal, log them as records otherwise, and return nil
  after a clean stop
- schedule:run --once ends with 'Ran N due entries (M failed)'
- summer dev runs bin/<app> serve with the forwarded global options,
  reports through Output, stops the old server before starting the new
  one and prints a dev report on Ctrl+C (exit 0)
- lagoon.DatabaseLabel describes a DSN without its secrets
- Long help and examples for queue:work, schedule:run, dev, docs:serve

internal/dev/watch.go

@@ -14,23 +14,44 @@ import (
 	"github.com/fsnotify/fsnotify"
 
 	"git.golem15.com/golem15/summercms/internal/build"
+	"git.golem15.com/golem15/summercms/modules/bonfire"
 )
 
 const defaultDebounce = 200 * time.Millisecond
 
 // Options customizes the watch loop. Tests inject Build and Start.
 type Options struct {
-	Build    func(ctx context.Context, appDir string, out io.Writer) error
-	Start    func(ctx context.Context, binPath string, stdout, stderr io.Writer) (*exec.Cmd, error)
+	Build func(ctx context.Context, appDir string, out io.Writer) error
+	// Start runs binPath with args ("serve" followed by the forwarded
+	// global options).
+	Start    func(ctx context.Context, binPath string, args []string, stdout, stderr io.Writer) (*exec.Cmd, error)
 	Debounce time.Duration
 }
 
-// Watch rebuilds the app on source changes and restarts the child binary.
-func Watch(ctx context.Context, appDir string, out io.Writer) error {
-	return watch(ctx, appDir, out, Options{})
+// Watch builds the app, runs bin/<binary> serve with args (the global
+// options summer dev was given, such as -v) and rebuilds and restarts it on
+// source changes. When ctx ends it stops the child with SIGTERM (serve
+// prints its own shutdown report), prints the dev report (rebuilds, failed
+// builds, restarts, uptime) and returns nil.
+func Watch(ctx context.Context, appDir string, out bonfire.Output, args []string) error {
+	return watch(ctx, appDir, out, args, Options{})
 }
 
-func watch(ctx context.Context, appDir string, out io.Writer, opts Options) error {
+// devReport counts what a watch session did.
+type devReport struct {
+	rebuilds, failed, restarts int
+	started                    time.Time
+}
+
+func (r devReport) details() []bonfire.Detail {
+	return []bonfire.Detail{
+		{Label: "Rebuilds", Value: fmt.Sprintf("%d (%d failed)", r.rebuilds+r.failed, r.failed), Warn: r.failed > 0},
+		{Label: "Restarts", Value: fmt.Sprint(r.restarts)},
+		{Label: "Uptime", Value: time.Since(r.started).Round(time.Second).String()},
+	}
+}
+
+func watch(ctx context.Context, appDir string, out bonfire.Output, args []string, opts Options) error {
 	if appDir == "" {
 		return fmt.Errorf("dev: app directory is empty")
 	}
@@ -40,7 +61,7 @@ func watch(ctx context.Context, appDir string, out io.Writer, opts Options) erro
 	}
 	appDir = abs
 	if out == nil {
-		out = os.Stdout
+		out = bonfire.NewOutput(os.Stdin, os.Stdout, os.Stderr)
 	}
 	if opts.Build == nil {
 		opts.Build = build.App
@@ -57,6 +78,14 @@ func watch(ctx context.Context, appDir string, out io.Writer, opts Options) erro
 		return err
 	}
 	binPath := filepath.Join(appDir, "bin", m.Binary)
+	childArgs := append([]string{"serve"}, args...)
+	// On a terminal the child gets the process's own stdout and stderr, so
+	// serve sees a terminal and prints its styled summary and report.
+	childOut, childErr := io.Writer(out), io.Writer(out)
+	if bonfire.IsTerminal(out) {
+		childOut, childErr = os.Stdout, os.Stderr
+	}
+	report := devReport{started: time.Now()}
 
 	watcher, err := fsnotify.NewWatcher()
 	if err != nil {
@@ -70,26 +99,35 @@ func watch(ctx context.Context, appDir string, out io.Writer, opts Options) erro
 	var current *child
 	defer func() { current.stop() }()
 
+	out.Info(fmt.Sprintf("Watching %s; running bin/%s %s", appDir, m.Binary, strings.Join(childArgs, " ")))
 	rebuild := func() {
 		if ctx.Err() != nil {
 			return
 		}
 		start := time.Now()
 		if err := opts.Build(ctx, appDir, out); err != nil {
-			fmt.Fprintf(out, "build error: %v\n", err)
+			report.failed++
+			out.Error(fmt.Sprintf("Build failed: %v", err))
 			return
 		}
-		fmt.Fprintf(out, "rebuild: %s\n", time.Since(start).Round(time.Millisecond))
+		report.rebuilds++
+		out.Success(fmt.Sprintf("Rebuilt in %s", time.Since(start).Round(time.Millisecond)))
 		if ctx.Err() != nil {
 			return
 		}
-		next, err := startChild(ctx, opts, binPath, out)
+		restart := current != nil
+		current.stop()
+		current = nil
+		next, err := startChild(ctx, opts, binPath, childArgs, childOut, childErr)
 		if err != nil {
-			fmt.Fprintf(out, "start error: %v\n", err)
+			out.Error(fmt.Sprintf("Start failed: %v", err))
 			return
 		}
-		current.stop()
 		current = next
+		if restart {
+			report.restarts++
+			out.Info("Restarted bin/" + m.Binary)
+		}
 	}
 
 	rebuild()
@@ -145,9 +183,10 @@ func watch(ctx context.Context, appDir string, out io.Writer, opts Options) erro
 		case <-ctx.Done():
 			current.stop()
 			current = nil
-			return ctx.Err()
+			bonfire.Details(out, "Dev report", report.details())
+			return nil
 		case err := <-watchErrs:
-			fmt.Fprintf(out, "watch error: %v\n", err)
+			out.Warning(fmt.Sprintf("Watch error: %v", err))
 		case <-events:
 			if timer == nil {
 				timer = time.NewTimer(opts.Debounce)
@@ -172,8 +211,8 @@ type child struct {
 	wait <-chan error
 }
 
-func startChild(ctx context.Context, opts Options, binPath string, out io.Writer) (*child, error) {
-	cmd, err := opts.Start(ctx, binPath, out, out)
+func startChild(ctx context.Context, opts Options, binPath string, args []string, stdout, stderr io.Writer) (*child, error) {
+	cmd, err := opts.Start(ctx, binPath, args, stdout, stderr)
 	if err != nil {
 		return nil, err
 	}
@@ -198,8 +237,10 @@ func (c *child) stop() {
 	}
 }
 
-func startBin(_ context.Context, binPath string, stdout, stderr io.Writer) (*exec.Cmd, error) {
-	cmd := exec.Command(binPath)
+// startBin runs binPath with args, which watch builds as "serve" followed
+// by the forwarded global options.
+func startBin(_ context.Context, binPath string, args []string, stdout, stderr io.Writer) (*exec.Cmd, error) {
+	cmd := exec.Command(binPath, args...)
 	cmd.Stdout = stdout
 	cmd.Stderr = stderr
 	cmd.Stdin = os.Stdin