Runner: added, which runs the program in the process: help, version, usage errors and the exit code

It adds --help with -h and, given a version, --version with -V, placed with the
options of the program, a flag of that name the program has being answered as
it is. A usage error is printed with the help of its command and returns 2 by
default. On request it prints the help for an empty line (helpWhenEmpty, before
the required arguments are demanded), adds --no-color, read before parsing so
that a mistake of the line is plain too (colorFlag), and reports an exception
of the handler by its message (errorExitCode). A version may be a closure
writing it for the console it goes to.

Author: dg

AGENTS.md

@@ -20,7 +20,8 @@ three phases of `parse()` with the command selection and the sentinel, `get()` o
 command line as a tree of the program and its commands, `Parser` reads a command
 line against it and returns a `ParseResult`, `HelpRenderer` draws the help of any
 command and a usage error, `Console` writes to a stream in color, `Prompt` asks the
-user at a terminal and `Ansi` measures text the way a terminal shows it. The parameters live in the
+user at a terminal, `Ansi` measures text the way a terminal shows it and `Runner` runs the
+program in the process: help, version, usage errors and the exit code. The parameters live in the
 `Parameters` namespace: `Flag` extends `Parameter`, while `Option` and `Argument`
 extend it through `ValueParameter`. `Section` and `Text` in the `Help` namespace
 shape the help. The attributes `Command`, `Flag`, `Option` and `Argument` in the
@@ -51,9 +52,10 @@ composer phpstan
 
 ## Working in this repo
 
-- **Definition, parsing, help and output are four classes.** `Command` never
+- **Definition, parsing, help, output and running are five classes.** `Command` never
   touches `argv`, the environment or a stream; `Parser` and `HelpRenderer` take
-  the command as an argument and keep no state; `Console` knows no `Command`.
+  the command as an argument and keep no state; `Console` knows no `Command`;
+  `Runner` alone holds the process, `argv`, the consoles and the exit code.
   Each node keeps one ordered list of items and the help is always drawn from it.
 - **Every setting is a named argument of `add*()` and cannot change afterwards**, so
   everything is refused at once, the rules over several arguments included, and the

docs/internals.md

@@ -3,7 +3,7 @@
 Small classes, mostly clear from their signatures. This is the thin "invariants & traps"
 layer, the facts that are expensive to rediscover.
 
-## Four roles, four classes
+## Five roles, five classes
 
 - **`Command`** is the definition: a tree whose root is the program and whose nodes are its
   commands. It knows nothing of `argv`, the environment or the output.
@@ -14,6 +14,22 @@ layer, the facts that are expensive to rediscover.
   Like `Parser`, it takes the node as an argument and keeps nothing between calls.
 - **`Console`** writes to a stream and knows no `Command`. The renderer colors and writes
   through it; `renderToString()` without a console is plain text.
+- **`Runner`** is the only one that runs the program in the process: it reads `argv`, owns the
+  two consoles, answers `--help`, `--version` and `--no-color`, reports a usage error and returns
+  the exit code. The other four stay free of the process because it holds all of that.
+
+**The runner adds its flags to the program it is given**, so the definition is changed, and a
+second runner over it finds them there; a node cannot be copied, so this is the price of the flags
+being ordinary ones, listed, parsed and inherited as any other. They are placed before the first
+command, section or text by the internal `Command::moveBeforeCommands()`, since a finished
+definition usually ends with them and the help would draw the flags as a block of their own after
+its texts. A flag of that name the program has is answered as it is; an alias it took is left out.
+**`--no-color` is read from the tokens before parsing** (up to `--`, after which nothing is an
+option, and a value starting with a dash takes `=`, so a bare `--no-color` is never a value), so that
+a mistake of the line is reported plain too; the empty line of `helpWhenEmpty` is decided before
+parsing as well, which would demand the required arguments. `errorExitCode` catches what the handler
+throws as `\Exception` and never an `\Error`, a bug, nor what `parse()` throws besides a usage
+error: an `\InvalidArgumentException` from the binding of handlers is a mistake of the definition.
 
 The parameters live in the `Parameters` namespace and split by **whether they take a value**,
 the axis most settings follow. `Flag` takes none; `ValueParameter` holds the enum and the