fix(summer): delegate admin, route and key commands and pass all delegate flags through

- delegateCommands() builds every delegate from one table of name,
  description and common-flags hint; toolCommands appends it
- route:list, key:generate, admin:create and admin:reset-password are new
  delegates; the child keeps summer's stdin, so the password prompts work
- migrate:rollback, queue:work and schedule:run lose their hand-written
  flag copies: --plugin, --queue and --once now pass through verbatim
- the command list marks delegates with "(flags pass to the app binary)"
  and the help command prints a Long text with the common flags
- console introduction, setup-and-maintenance and the root README
  describe the passthrough behaviour and the new delegates

cmd/summer/runtime.go

@@ -6,7 +6,6 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
-	"strconv"
 	"strings"
 
 	"git.golem15.com/golem15/summercms/internal/build"
@@ -16,10 +15,44 @@ import (
 // appRunner runs the app binary with argv; tests replace it.
 var appRunner = runAppBinary
 
-func delegateCommand(name, description string) bonfire.Command {
+// delegateCommands returns every command summer runs on the app binary. One
+// table is the single source: name, base description and a hint naming the
+// common flags or arguments the app binary accepts.
+func delegateCommands() []bonfire.Command {
+	rows := []struct{ name, description, hint string }{
+		{"migrate", "Run plugin migrations in the app binary", ""},
+		{"migrate:rollback", "Roll back the last migration of a plugin in the app binary", "--plugin <id>"},
+		{"migrate:status", "Show per-plugin migration history in the app binary", ""},
+		{"serve", "Run the app HTTP server", "--addr <host:port> (default :8080)"},
+		{"queue:work", "Run background job workers in the app binary", "--queue <name> (repeatable)"},
+		{"queue:clear", "Clear pending queued jobs in the app binary", `[queue] argument (default "default")`},
+		{"schedule:run", "Run the scheduler in the app binary (or once for system cron)", "--once"},
+		{"route:list", "List the app's routes from the app binary", ""},
+		{"key:generate", "Print a fresh application key from the app binary", ""},
+		{"admin:create", "Create a backend administrator in the app binary", "--email <email> (required), --login, --role <code>, --superuser; the password is prompted or read from stdin"},
+		{"admin:reset-password", "Reset a backend administrator's password in the app binary", "<identifier> (login or email); the password is prompted or read from stdin"},
+	}
+	cmds := make([]bonfire.Command, 0, len(rows))
+	for _, r := range rows {
+		cmds = append(cmds, delegateCommand(r.name, r.description, r.hint))
+	}
+	return cmds
+}
+
+// delegateCommand returns a passthrough command that runs name on the app
+// binary with every argument summer was given.
+func delegateCommand(name, description, hint string) bonfire.Command {
+	long := description + ".\n\nsummer runs bin/<binary> " + name +
+		" in the application directory, building the binary first when it is missing. Every flag and argument after " +
+		name + ", including --help, is passed to the app binary unchanged."
+	if hint != "" {
+		long += "\n\nCommon flags: " + hint + "."
+	}
+	long += "\n\nRun summer " + name + " --help inside an application to list all of them."
 	return bonfire.Command{
 		Name:        name,
-		Description: description,
+		Description: description + " (flags pass to the app binary)",
+		Long:        long,
 		Passthrough: true,
 		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
 			args := in.Args()
@@ -34,67 +67,6 @@ func delegateCommand(name, description string) bonfire.Command {
 	}
 }
 
-func delegateRollbackCommand() bonfire.Command {
-	return bonfire.Command{
-		Name:        "migrate:rollback",
-		Description: "Roll back the last migration of a plugin in the app binary",
-		Flags: []bonfire.Flag{{
-			Name:        "plugin",
-			Description: "Plugin ID whose last migration to roll back",
-		}},
-		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
-			argv := []string{"migrate:rollback"}
-			if plugin, ok := in.Flag("plugin"); ok && plugin != "" {
-				argv = append(argv, "--plugin", plugin)
-			}
-			argv = append(argv, in.Args()...)
-			return runAppBinary(ctx, argv, out)
-		},
-	}
-}
-
-func delegateQueueWorkCommand() bonfire.Command {
-	return bonfire.Command{
-		Name:        "queue:work",
-		Description: "Run background job workers in the app binary",
-		Flags: []bonfire.Flag{{
-			Name:        "queue",
-			Description: "Queue to work (repeatable; default all known queues)",
-			Repeatable:  true,
-		}},
-		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
-			argv := []string{"queue:work"}
-			for _, q := range in.Flags("queue") {
-				argv = append(argv, "--queue", q)
-			}
-			argv = append(argv, in.Args()...)
-			return runAppBinary(ctx, argv, out)
-		},
-	}
-}
-
-func delegateScheduleRunCommand() bonfire.Command {
-	return bonfire.Command{
-		Name:        "schedule:run",
-		Description: "Run the scheduler in the app binary (or once for system cron)",
-		Flags: []bonfire.Flag{{
-			Name:        "once",
-			Description: "Run the entries due this minute and exit (for system cron)",
-			Bare:        true,
-		}},
-		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
-			argv := []string{"schedule:run"}
-			if v, ok := in.Flag("once"); ok {
-				if once, _ := strconv.ParseBool(v); once {
-					argv = append(argv, "--once")
-				}
-			}
-			argv = append(argv, in.Args()...)
-			return runAppBinary(ctx, argv, out)
-		},
-	}
-}
-
 func runAppBinary(ctx context.Context, argv []string, out bonfire.Output) error {
 	if len(argv) == 0 {
 		return fmt.Errorf("summer: missing app command")