feat(summer): help, examples and hints for every tool command

- build runs go build under a spinner on a terminal and ends with
  'Built bin/<name> in <time>'; make:* print 'Created <path>' per file
- make:*, plugin:add, new, parity:*, docs:build, docs:sync and every
  delegate get long help and examples; delegates note that global options
  pass through to the application binary
- make:* failures (no summer.yaml, invalid plugin ID or name, existing
  artifact, unknown plugin) explain themselves and suggest a command
- docs:build and docs:sync return bonfire.Reported after the problem list
- TestCommandsDocumented covers the tool commands too
- docs: Upgrading to 0.4, delegates and global options, make: results and
  hints, the checklist for a finished command

docs/setup/upgrading.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrading
-description: Move an application to a newer framework release, what the version numbers promise, and the config to check before you take 0.2.
+description: Move an application to a newer framework release, what the version numbers promise, and what to check before you take 0.2 and 0.4.
 section: setup
 order: 60
 ---
@@ -24,6 +24,28 @@ SummerCMS is in the 0.x series, and the version tells you whether to read before
 
 Applications pin exact versions, so a new release never reaches an application until it moves its `go.mod` or its checkout.
 
+## Upgrading to 0.4
+
+0.4 rebuilds the console: Artisan-style `list` and help with examples, global options on every command, a logging pipeline with daily files, startup summaries and shutdown reports. Plugins compile unchanged. After you move the framework version, run `summer build` to regenerate `main.go`: the new generated main sets up logging before the configuration is read, parses the global options and returns the exit codes below. Then run `bin/<app> list` once with the new binary: it boots every plugin and runs the checks below.
+
+### Boot refusals
+
+**Duplicate command names.** Two commands with the same name, from two plugins or from a plugin and the framework, stop the binary at start-up with `bonfire.ErrDuplicateCommand` naming the command. Remove or rename one of them; a plugin that appends `centrifugo.Commands` or `flare.Commands` must be the only one that does.
+
+**Reserved flag names.** A command flag named like a global option (`verbose`, `quiet`, `ansi`, `no-ansi`, `no-interaction`, `env`, or the shorthands `v`, `q`, `n`) stops the binary with `bonfire.ErrReservedFlag`. Rename the flag.
+
+### Behaviour changes
+
+- **Daily log files.** Logs go to the console and, from warnings up, to `storage/logs/summer-YYYY-MM-DD.log`, kept for 14 days. The directory must be writable by the user that runs the binary; when it is not, the binary logs one warning and keeps logging to the console. To keep the old console-only behaviour, set `log.default` to `console` (`SUMMER_LOG__DEFAULT=console`). See [Logging](../services/logging.md).
+- **Component loggers.** Every log record carries a `component` attribute. GORM's lines move to component `db` and record-not-found is no longer logged; River's lines to component `river` (warnings and up by default). Raise or lower a component with `log.components`, for example `components: {db: debug}`.
+- **The request log is on by default.** Every request writes one Info record `http request` from component `http` with the route pattern (never the path), status, duration and `request_id`. Silence it with `components: {http: warn}` in `config/log.yaml`, or turn it off with `http.access_log: false`.
+- **`serve` prints a startup summary.** On a terminal it is a block; off a terminal `serve` prints nothing on stdout and logs a `startup summary` record and a `listening on <addr>` record on stderr instead, so a script that waits for `listening on 127.0.0.1:<port>` in the combined output still finds it. Ctrl+C prints a shutdown report and exits 0; a failed drain exits 1. `queue:work` and `schedule:run` do the same.
+- **Exit codes.** A failed command exits 1 and a usage error (an unknown command or flag, a wrong number of arguments) exits 2. Errors print as a block on stderr with a hint where the framework knows the fix, and `-v` shows the wrapped errors.
+- **`-q` keeps data.** `-q` hides information and success lines, spinners and progress bars, but still prints what a command exists to produce: the token of `admin:token:create`, the key of `key:generate` and every `--json` output.
+- **Production confirmation.** `migrate`, `migrate:rollback`, `deferred:purge` and `queue:clear` ask before they run when the environment is `production` and they run on an interactive terminal; `--force` skips the question. Off a terminal, as in deploy scripts over SSH, nothing changes.
+- **`summer dev` runs `serve`.** It used to start the binary without a command, which printed the help and stopped; it now runs `bin/<app> serve` with the global options you give `summer dev`.
+- **Result lines.** `summer build` ends with `Built bin/<app> in <time>`, the `make:` commands print `Created <path>` per file, `migrate` prints `Applied N migrations` or `Nothing to migrate`, and `queue:clear` prints `Cleared N jobs from <queue>`. Adjust scripts that matched the old lower-case lines.
+
 ## Upgrading to 0.2
 
 0.2 tightens two configuration checks so that settings which leaked credentials stop the start-up instead. Most applications are not affected: the first concerns applications that load an `auth.cookie` block, the second applications that send credentialed CORS answers. Start the new binary once in each environment before you switch traffic to it; a refused configuration fails `serve` at start-up with an error that names the key.