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/lighthouse/README.md

@@ -237,7 +237,7 @@ for _, pub := range mem.Publications() {
 
 | Command | Description |
 |---------|-------------|
-| `websockets:health` | With an empty `realtime.centrifugo.api_key` it prints `Centrifugo not configured (API key missing)` and exits 1 without sending a request. Otherwise it prints the API URL and calls the Centrifugo `info` API method. On success it prints `Configuration OK` and a Setting/Value table (API URL, Enabled, API Key Set); on any failure it prints `Connection check failed: …` and exits 1. The API key is never printed, only whether it is set. |
+| `websockets:health` | With an empty `realtime.centrifugo.api_key` it prints `Centrifugo not configured (API key missing)` and exits 1 without sending a request. Otherwise it prints the API URL and calls the Centrifugo `info` API method. On success it prints `Configuration OK` and a Setting/Value table (API URL, Enabled, API Key Set); on any failure it prints `Connection check failed: …` and exits 1. With `--json` it prints only `{"healthy", "api_url", "enabled", "api_key_set", "error"}` and exits 1 when unhealthy. The API key is never printed, only whether it is set. |
 
 ## Dependencies
 

modules/lighthouse/centrifugo/commands.go

@@ -2,6 +2,7 @@ package centrifugo
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 
 	"git.golem15.com/golem15/summercms/modules/backpack"
@@ -11,9 +12,21 @@ import (
 // HealthCommandName is the name of the Centrifugo health check command.
 const HealthCommandName = "websockets:health"
 
-// errHealthFailed is returned by the health command after it has printed
-// why the check failed, so the binary exits 1.
-var errHealthFailed = errors.New(HealthCommandName + ": check failed")
+// healthFailed is returned by the health command after it has printed why
+// the check failed: bonfire.Reported makes the binary exit 1 without
+// repeating the message.
+func healthFailed() error {
+	return bonfire.Reported(errors.New(HealthCommandName + ": check failed"))
+}
+
+// healthJSON is websockets:health --json. The API key is never included.
+type healthJSON struct {
+	Healthy   bool   `json:"healthy"`
+	APIURL    string `json:"api_url"`
+	Enabled   bool   `json:"enabled"`
+	APIKeySet bool   `json:"api_key_set"`
+	Error     string `json:"error,omitempty"`
+}
 
 // Commands returns the Centrifugo console commands for an application
 // binary: the HealthCommandName check. An application appends them to the
@@ -30,7 +43,17 @@ func healthCommand(app *backpack.App) bonfire.Command {
 	return bonfire.Command{
 		Name:        HealthCommandName,
 		Description: "Check Centrifugo connection health",
-		Run: func(ctx context.Context, _ bonfire.Input, out bonfire.Output) error {
+		Long: `Reads the Centrifugo settings (realtime.centrifugo.*) and calls the Centrifugo
+info API with them, so a wrong URL or API key fails the check. The API key is
+never printed. It exits 1 when Centrifugo is not configured or does not
+answer. --json prints {healthy, api_url, enabled, api_key_set, error} for
+monitoring scripts.`,
+		Flags: []bonfire.Flag{{Name: "json", Description: "Print the result as JSON", Bare: true}},
+		Examples: []bonfire.Example{
+			{Command: HealthCommandName, Description: "Check the connection"},
+			{Command: HealthCommandName + " --json", Description: "Machine-readable result for a monitoring check"},
+		},
+		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
 			var cfg Config
 			if app != nil {
 				cfg = LoadConfig(app.Config)
@@ -38,16 +61,41 @@ func healthCommand(app *backpack.App) bonfire.Command {
 				cfg = LoadConfig(nil)
 			}
 			client := NewClient(cfg, nil)
+			asJSON := false
+			if in != nil {
+				v, _ := in.Flag("json")
+				asJSON = v == "true"
+			}
+			if asJSON {
+				info := client.DebugInfo()
+				res := healthJSON{APIURL: info.APIURL, Enabled: info.Enabled, APIKeySet: info.APIKeySet}
+				if !client.Enabled() {
+					res.Error = "Centrifugo not configured (API key missing)"
+				} else if _, err := client.Info(ctx); err != nil {
+					res.Error = err.Error()
+				} else {
+					res.Healthy = true
+				}
+				b, err := json.MarshalIndent(res, "", "  ")
+				if err != nil {
+					return err
+				}
+				out.Println(string(b))
+				if !res.Healthy {
+					return healthFailed()
+				}
+				return nil
+			}
 			if !client.Enabled() {
 				out.Error("Centrifugo not configured (API key missing)")
 				out.Println("Set SUMMER_REALTIME__CENTRIFUGO__API_KEY in the environment")
-				return errHealthFailed
+				return healthFailed()
 			}
 			out.Info("Checking Centrifugo connection...")
 			out.Println("API URL: " + cfg.APIURL)
 			if _, err := client.Info(ctx); err != nil {
 				out.Error("Connection check failed: " + err.Error())
-				return errHealthFailed
+				return healthFailed()
 			}
 			info := client.DebugInfo()
 			out.Success("Configuration OK")