feat(diary): boot list, help and completion requests quietly (quick-261028-rqc)

- helpOnly also counts no command word, list, help, cobra's shell
  completion requests and --help=<bool>, read the way pflag does
- TestHelpOnlyAgreesWithCobra pins the classification against bonfire's
  real dispatch, with the passthrough --help case as the exception
- console and logging docs describe which invocations boot quietly
This commit is contained in:
Jakub Zych
2026-10-28 21:47:42 +01:00
parent 6b9becd994
commit 6c606c666b
7 changed files with 231 additions and 24 deletions

View File

@@ -91,8 +91,11 @@ The application binary reads these options before it loads `config/` and starts
```sh
./bin/acme -vv migrate
./bin/acme migrate:status --env staging
./bin/acme -v serve --help
```
An invocation that only lists or describes commands (no command, `list`, `help`, `--help` or `-h`, and shell completion requests) starts the plugins with the console log at warnings, as `-q` would, so the info lines plugins log while they register and boot do not print above the help; `-v` shows them, as in the last line above. `serve`, `queue:work`, `migrate` and every other command boot at the configured levels, and log files keep their levels. It works for both programs and needs no rebuild of the generated `main.go`, only the framework version. A command that passes its arguments through unparsed counts as asking for help when `--help` follows it, but its console log is back at the configured levels before it runs.
### Exit codes
| Code | Meaning |

View File

@@ -142,6 +142,8 @@ var blogLog = diary.For("blog")
Its records carry `component=blog`, follow `log.components.blog` and go through the redacting channels.
`Register` and `Boot` run before every command, so a plugin logs what it registered or collected at Debug (visible with `-vv`) rather than Info. Only the invocations that just ask for help (no command, `list`, `help`, `--help` or `-h`, shell completion) boot with the console at warnings; `migrate`, `queue:work` and one-off commands print every Info record a plugin logs while it boots.
Redaction is a safety net for mistakes, not a way to log secrets on purpose. Log identifiers and outcomes: the record id, the vendor, the status code, how long it took. Never log request arguments, tokens, credentials or request and response bodies, which can carry personal data the patterns do not recognise.
## Request log