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
This commit is contained in:
Jakub Zych
2026-10-08 16:03:24 +02:00
parent 9eb2a9237c
commit b9ef034272
7 changed files with 133 additions and 77 deletions

View File

@@ -26,6 +26,8 @@ summer make:model --help
./bin/acme migrate:rollback --help
```
A command that `summer` delegates to the application binary, such as `summer serve`, answers `--help` with the binary's own help, so run it inside an application directory. Asking the help command of `summer` about a delegated command instead prints a short description and its common flags without running the binary.
## Commands that summer delegates
During development you often work from the application directory with `summer` alone. These `summer` commands find the application's `summer.yaml`, build `bin/<binary>` when it does not exist yet, and run the same command of the binary with the same arguments:
@@ -39,8 +41,23 @@ During development you often work from the application directory with `summer` a
| `summer queue:work` | `./bin/acme queue:work` |
| `summer queue:clear` | `./bin/acme queue:clear` |
| `summer schedule:run` | `./bin/acme schedule:run` |
| `summer route:list` | `./bin/acme route:list` |
| `summer key:generate` | `./bin/acme key:generate` |
| `summer admin:create` | `./bin/acme admin:create` |
| `summer admin:reset-password` | `./bin/acme admin:reset-password` |
`summer` does not rebuild an existing binary before it delegates. Run `summer build` after you change code, or keep `summer dev` running. Every other runtime command, such as `route:list`, `key:generate` or `admin:create`, is run on the binary directly.
`summer` parses no flags of these commands: every flag and argument, including `--help`, goes to the binary unchanged, and the binary's input is your terminal, so the password prompts of `admin:create` and `admin:reset-password` work as usual:
```sh
summer serve --addr 127.0.0.1:8123
summer serve --help
summer migrate:rollback --plugin acme.blog
summer admin:create --email admin@example.com --superuser
```
One leading `--` is ignored, so `summer serve -- --addr 127.0.0.1:8123` behaves the same as `summer serve --addr 127.0.0.1:8123`.
`summer` does not rebuild an existing binary before it delegates. Run `summer build` after you change code, or keep `summer dev` running. Every other runtime command, such as `deferred:purge` or the commands your plugins add, is run on the binary directly.
## The sections of this chapter

View File

@@ -65,6 +65,8 @@ Copy the printed value into `SUMMER_APP__KEY`. When you rotate the key, keep the
The default `--addr` listens on every interface. Pass a loopback address during development, and put a reverse proxy in front of the binary in production. The routing options are in [surf](../../modules/surf/README.md).
From the application directory, `summer serve --addr 127.0.0.1:8123` passes the flag through to the built binary.
## Admin accounts
| Command | Arguments and flags | Purpose |
@@ -79,6 +81,8 @@ The default `--addr` listens on every interface. Pass a loopback address during
Both commands prompt for the password without echoing it. In a script, pipe it on stdin, for example `printf '%s\n' "$ADMIN_PASSWORD" | ./bin/acme admin:create --email admin@example.com --superuser`. The `--password` flag still works but is deprecated and prints a warning, because the value stays in your shell history and is visible in the process list. The admin is described in [cabana](../../modules/cabana/README.md).
From the application directory, `summer admin:create --email admin@example.com --superuser` runs the same command on the built binary, prompt included.
## Queues and the scheduler
| Command | Arguments and flags | Purpose |