feat: Artisan checklist for application commands, hints and coverage gate

- migrate, migrate:rollback and deferred:purge gain --pretend and --force;
  they and queue:clear confirm only in production on an interactive
  terminal, so deploys over SSH proceed as before
- result lines: Applied N migrations, Rolled back <id> of <plugin>,
  Cleared N jobs from <queue>
- --json for migrate:status, key:generate, route:list, admin:token:create,
  admin:token:list, admin:token:scopes and websockets:health; -q keeps the
  key and the token
- hints for an empty DSN, an unreachable database, an invalid app.key, a
  missing uploads bucket and an application binary run below its root
- flare and websockets:health return bonfire.Reported after printing
- long help and examples for every application command, greeter:hello and
  blog:publish; cmd/summer TestCommandsDocumented fails on any gap

modules/surf/README.md

@@ -197,7 +197,7 @@ The `serve` command also opens the database through [lagoon](../lagoon/README.md
 | Command | Flags | Description |
 |---------|-------|-------------|
 | `serve` | `--addr` (default `:8080`) | Opens the database and uploads bucket, installs cooler (the shared rate-limit store when `http.rate_limit.store` is `redis`), assembles the router, binds the address, starts the in-process job worker (see `queue.work_in_serve`) and serves HTTP until SIGINT or SIGTERM. Once it listens it prints the startup summary on a terminal (unless `-q`), with the admin URL and a warning naming `summer admin:create` when no administrator exists yet, or `off` with the steps to add an admin controller; off a terminal it logs the summary and `listening on <addr>` as records. On a signal it drains requests and the worker within 10 seconds, prints and logs the shutdown report, and exits 0, or 1 when draining fails. |
-| `route:list` | none | Builds the router the same way `serve` does, without opening the database or listening, and prints a table of method, pattern, plugin, middleware and raw flag for every route, followed by the admin status line (`admin: mounted at <prefix>` or `admin: off`). |
+| `route:list` | `--json` | Builds the router the same way `serve` does, without opening the database or listening, and prints a table of method, pattern, plugin, middleware and raw flag for every route, followed by the admin status line (`admin: mounted at <prefix>` or `admin: off`). `--json` prints a JSON array of `method`, `pattern`, `plugin`, `middleware` and `raw` instead. A missing uploads bucket makes `serve` fail with a hint naming `config/storage.yaml`. |
 
 ## Dependencies
 

modules/surf/routelist_command.go

@@ -2,6 +2,7 @@ package surf
 
 import (
 	"context"
+	"encoding/json"
 	"strconv"
 	"strings"
 
@@ -10,6 +11,18 @@ import (
 	"git.golem15.com/golem15/summercms/modules/party"
 )
 
+// jsonFlagName is route:list's --json flag.
+const jsonFlagName = "json"
+
+// routeJSON is one route of route:list --json.
+type routeJSON struct {
+	Method     string   `json:"method"`
+	Pattern    string   `json:"pattern"`
+	Plugin     string   `json:"plugin"`
+	Middleware []string `json:"middleware"`
+	Raw        bool     `json:"raw"`
+}
+
 // RouteListCommand builds the router the same way ServeCommand does, then
 // renders Routes() as a table instead of serving, followed by the admin
 // status line.
@@ -17,12 +30,40 @@ func RouteListCommand(app *backpack.App, plugins []party.Plugin) bonfire.Command
 	return bonfire.Command{
 		Name:        "route:list",
 		Description: "List registered HTTP routes",
+		Long: `Builds the router the way serve does, without opening the database or
+listening, and prints every route: method, pattern, the plugin that
+registered it, its named middleware and whether it is raw (no JSON envelope).
+The admin status line follows. --json prints the routes as a JSON array for
+scripts.`,
+		Flags: []bonfire.Flag{{Name: jsonFlagName, Description: "Print the routes as JSON", Bare: true}},
+		Examples: []bonfire.Example{
+			{Command: "route:list", Description: "Show every route as a table"},
+			{Command: "route:list --json", Description: "Machine-readable route list"},
+		},
 		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
 			r, err := BuildRouter(app, plugins)
 			if err != nil {
 				return err
 			}
 			infos := r.Routes()
+			if in != nil {
+				if v, _ := in.Flag(jsonFlagName); v == "true" {
+					list := make([]routeJSON, 0, len(infos))
+					for _, rt := range infos {
+						mw := rt.Middleware
+						if mw == nil {
+							mw = []string{}
+						}
+						list = append(list, routeJSON{Method: rt.Method, Pattern: rt.Pattern, Plugin: rt.PluginID, Middleware: mw, Raw: rt.Raw})
+					}
+					b, err := json.MarshalIndent(list, "", "  ")
+					if err != nil {
+						return err
+					}
+					out.Println(string(b))
+					return nil
+				}
+			}
 			rows := make([][]string, 0, len(infos))
 			for _, rt := range infos {
 				rows = append(rows, []string{

modules/surf/serve.go

@@ -212,7 +212,9 @@ func publishUploads(ctx context.Context, app *backpack.App) (*blob.Bucket, error
 	}
 	bucket, err := attach.OpenBucket(ctx, app.Config)
 	if err != nil {
-		return nil, err
+		return nil, bonfire.WithHint(err,
+			"serve stores uploads in the bucket named by storage.uploads.bucket_url in config/storage.yaml (or SUMMER_STORAGE__UPLOADS__BUCKET_URL).",
+			"SUMMER_STORAGE__UPLOADS__BUCKET_URL=file://./storage/app/uploads {bin} serve")
 	}
 	if err := attach.Publish(app, bucket); err != nil {
 		_ = bucket.Close()