@runa-cmd/core 0.2.0-beta.6 → 0.2.0-beta.7

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # @runa-cmd/core
 
+## 0.2.0-beta.7
+
+### Minor Changes
+
+- 3d8584a: An alias that can't work stops the CLI at startup, with `INVALID_OPTION_ALIAS` and the way to write it:
+
+  ```
+  Alias 'e' of option 'env' of command 'deploy' must be '-e'.
+  ```
+
+  An alias is one character as `-e`, or a word as `--environment`. Before, `alias: ['e']` or `['-ab']` showed in the help, and `-e` was an unknown option, with nothing saying why.
+
+  **Breaking:** a CLI with such an alias doesn't start until it's fixed. The alias never worked, and the error shows up the first time its author runs it.
+
+- 277d21d: **Breaking:** a `z.boolean()` option without `.default()` or `.optional()` stops the CLI at startup, with `INVALID_BOOLEAN_OPTION`:
+
+  ```
+  Boolean option 'shout' of command 'hello' has no default: a flag that isn't passed needs one. Use z.boolean().default(false), or .optional().
+  ```
+
+  Before, it was required: `greet hello Ana` failed with `Missing required option: --shout` on every run, and the person running the CLI couldn't fix it. Now its author sees it the first time it runs, with the fix.
+
+- 7fd5dd6: Error codes are now a list you can import. `ERROR_CODES` from `@runa-cmd/core` has every code core throws, and the README says when each one comes up. `isRunaError(error, code?)` tells if something is a `RunaError` with that code, and works even when two copies of `@runa-cmd/core` are installed, where `instanceof` fails. It takes your own codes too, as a `CommandError`'s:
+
+  ```ts
+  if (isRunaError(error, ERROR_CODES.INVALID_CONFIG)) {
+    /* the config file is wrong */
+  }
+  if (isRunaError(error, "DEPLOY_FAILED")) {
+    /* your own code */
+  }
+  ```
+
+  `@runa-cmd/mcp` exports `ERROR_CLASSES`, the `class` values of a failed call, and `MCP_ERROR_CODES`, its own startup codes. Its README lists each class with its `effect`.
+
+  **Breaking:** three codes are renamed, before they're fixed for 1.0.
+
+  | Before                                                            | Now                                 |
+  | ----------------------------------------------------------------- | ----------------------------------- |
+  | `CONFIG_INVALID` (a `ConfigError`)                                | `INVALID_CONFIG`                    |
+  | `OPTION_NAME`, when two keys give the same flag                   | `OPTION_COLLISION`, as with globals |
+  | `OPTION_NAME`, when a boolean `noCache` clashes with `--no-cache` | `INVALID_OPTION_NAME`               |
+
+  **Migration:** compare against the new names, or against `ERROR_CODES`. Messages and exit codes don't change.
+
+- 2c5e9f0: An error from another copy of `@runa-cmd/core`, as one a plugin brings, ends as one of ours. A `CommandError` keeps its exit code and its message, at the terminal and through MCP, and a `ValidationError` is a usage error. `isRunaError` already recognized them, but the exit code and the message were decided by `instanceof`.
+
+  **Breaking:** a `CommandError` with exit code 3 from another copy used to come out as `Unexpected error in 'boom': …` with exit 1. It now exits with 3 and its message as written, as the docs always said.
+
+- 485220a: `RunResult` is exported: the type of what `format` receives, so a `format` written apart from `defineCommand` can name both of its parameters, with `FormatContext`.
+- 447f156: `help` works where a command goes, as in commander, yargs, cac and oclif. `tool help` is `tool --help`, `tool help db migrate` is `tool db migrate --help`, and `tool db help` shows the help of the group, on stdout with exit 0. Before, `tool help` exited with 127 and suggested another command, and a model that tried it lost a turn.
+
+  A command of yours named `help` still runs, and inside a command `help` is a value: `tool greet help` passes it to the argument. With `runCLI` nothing changes, since the command is the CLI. A name that doesn't exist after it is reported as any other: `tool help deplo` exits with 127 and suggests `deploy`. It isn't a command, so it's not in the list, nor an MCP tool.
+
+- 11818a4: The help of a command lists its own options first, and the global ones, as `--help`, `--version` or `--mcp`, apart under `GLOBAL OPTIONS`. `OptionSchema` gains an optional `inherited` that marks them, so a custom renderer still gets every option and can tell them apart. With `runCLI` nothing moves: the command is the CLI.
+
+  Also:
+
+  - A usage error points to the help of its command: `Run 'tool build --help' for usage.`, instead of the CLI's.
+  - The core help shows the values of a positional enum, as the help plugin does: `target  What to build for (web | node)`.
+  - `bold()`, `fg()` and the other ANSI helpers of `@runa-cmd/help` say in their docs that they always write codes; `styled()` respects the output.
+
+- 4ecfba3: A middleware that forgets `next()`, or calls it without `await`, now fails instead of passing in silence:
+
+  - Returning without calling `next()` fails with `MIDDLEWARE_DID_NOT_CALL_NEXT`, exit 1. Before, the command didn't run and the CLI exited with 0. Through MCP, such a call now reports `class: 'rejected'` instead of `'not_run'`, with the same `effect: 'none'`, and its text says why.
+  - Calling `next()` without `await` fails with `MIDDLEWARE_DID_NOT_AWAIT_NEXT`, after the command ends. Before, `afterRun` and `cleanup` ran while the command still worked.
+
+  To skip a command on purpose, throw: `new CommandError('Dry run: would deploy api', { exitCode: 0 })`. `RunaError` also takes a `cause`.
+
+- f69c9fc: **Breaking:** a command that doesn't exist exits with 127 even when a required global option is missing, and nothing to run shows the help on stderr with exit 2. Before, with a required global, `tool nope`, `tool db nope` and `tool` all said `Missing required option: --token`, with exit 2. A command that exists still says the global is missing, with exit 2.
+- 597a8fd: Inside a command, two options that claim the same token stop the CLI at startup with `OPTION_COLLISION`, as its docs always said:
+
+  ```
+  Options 'extra' and 'env' of command 'deploy' both use '-e'.
+  Option 'env' of command 'deploy' has '--env' as an alias, which is already its flag. Remove the alias.
+  ```
+
+  Before, only collisions with a global option were caught. Two options with `-e` kept the first one; an alias equal to another option's flag, or to the `--no-` of a boolean, took it over; and an alias equal to its own option's flag threw the typed value away, so `--env prod` gave the default, with exit 0.
+
+  **Breaking:** a CLI with one of those aliases doesn't start until it's fixed. None of them worked as written.
+
+- db60a2d: A tool call that's missing a value only the operator gives, as an option's env var, now fails with `class: "not_configured"`, not `invalid_input`. Its text starts with `The operator of this server has to set NOTES_FILE. It isn't a value you can send.`, so a model doesn't take it as its own mistake, nor ask the user for it. The server also says it at startup, on stderr, one line per tool, and keeps serving:
+
+  ```
+  mcpPlugin: tool 'add' can't run until the operator sets NOTES_FILE (--file).
+  ```
+
+  An input error the model can fix names the key it sent, as `Invalid value for 'limit': must be greater than 0`, instead of `--limit`, a flag it never saw. The line about an operator's value still names the flag and the variable, for whoever runs the server.
+
+  **Breaking:** a plain `Error` thrown from `run()` is now `class: "crashed"`, with `The command did not finish.`, instead of `command_failed`. Only a `CommandError` is `command_failed`, with its message as you wrote it. A client can now tell a failure you foresaw from a bug, as the README always said.
+
+  **Migration:** to have the model read your message as is, throw a `CommandError`.
+
+- 52ef44c: A command of `defineCLI` with `meta.version` stops the CLI at startup, with `INVALID_COMMAND_VERSION`:
+
+  ```
+  Command 'deploy' declares meta.version: 'version' only applies with runCLI; set it in defineCLI's meta.
+  ```
+
+  There it did nothing, without a word: `--version` prints the CLI's version, from `defineCLI`'s `meta`. On the command of `runCLI`, which is the CLI, it still works as before.
+
+  **Breaking:** a CLI with a command like that doesn't start until the version moves to `defineCLI`'s `meta`.
+
+### Patch Changes
+
+- 402ef3f: A wrong config file says what's wrong the same way in every case, and with the words the terminal uses. Each error names the file first:
+
+  ```
+  my-tool.config.json: invalid value for 'clear.limit': must be greater than 0
+  my-tool.config.json: unknown key 'clear.limt'. Did you mean 'limit'?
+  my-tool.config.json: invalid JSON: Unexpected token '}', ..."force":tru}}" is not valid JSON
+  ```
+
+  Before, a value said `Too small: expected number to be >0`, and broken JSON came in another format, over several lines. A boolean that gets anything else now says `expected true or false`, from the file, from env or from the terminal, instead of `expected boolean`. The README says which values a file takes: its JSON type, or the text you'd type at the terminal, as `"5"` or `"true"`.
+
+- 1ba1f73: Every public type, function and option now has a description, so your editor shows what each one is for. `HookContext.rawArgs` says what it holds at each step: the whole argv in `beforeParse`, and only the command's part from `onGlobalFlags` on. No code changed.
+- ff89521: Help and errors without noise:
+
+  - A boolean whose default is `true` shows as `--[no-]cache`, so people see how to turn it off.
+  - An empty list as a default no longer shows `(default: )`.
+  - A value that breaks a rule of its schema names the flag in plain words: `Invalid value for --limit: must be greater than 0`, instead of `limit: Too small: expected number to be >0`.
+  - Shell completions offer `--no-x` only for a boolean that starts on: `--no-help`, `--no-version` and `--no-mcp` are gone.
+  - The custom renderer example of the help README compiles, and handles the help of a command too.
+
+- 53208e9: The help README said a command's own `-h` stops the CLI with `OPTION_COLLISION`, and that `db migrate --help` shows the help of `db`. Neither is true: a command keeps its `-h`, and nested commands get their own help at any depth. The core README now explains what `ctx.rawArgs` holds in each hook, and `ctx.invocation`.
+- a8edd77: A required value that's missing says so, whatever its type. A missing `z.enum` or `z.literal` said `Invalid value for --env. Expected one of: staging, production`, so the main example of the README didn't give the error the same page promises. Now it's `Missing required option: --env, or set DEPLOY_ENV`, as for any other type, and a missing enum argument, as the shell of `completions`, is `Missing required argument: <shell>`. A wrong value is still an invalid value.
+- 23c3c19: A command without `meta.description` has one type error, the one that says so. TypeScript also reported `Type 'string' is not assignable to type 'void | Promise<void>'` on `run`, which looked like a problem with what the command returns: when a field fails, TypeScript can't infer the types of `defineCommand` and uses their defaults, and the default of what `run()` returns was `void`. It's `unknown` now. `description` is still required: it's what a model reads to choose a tool.
+- ba4bdee: **Breaking:** a tool call that fails because a value the operator gave breaks its schema, in env or in the config file, now comes with `class: "not_configured"`, as a missing value does, instead of `invalid_input`. Its text says what the operator has to fix, never the value, so a model doesn't take it as its own mistake:
+
+  ```
+  The operator of this server has to fix 'deploy.replicas' in the config file. It isn't a value you can send.
+  ```
+
+  The server also says it at startup, on stderr, with the reason, and keeps serving the other tools:
+
+  ```
+  mcpPlugin: tool 'deploy' can't run until the operator fixes DEPLOY_ENV (--env): expected one of: staging, production.
+  ```
+
+  Values are checked with the rules the CLI uses, so `"5"` for a number in the config file is fine.
+
+- 1304aa0: A wrong value is repeated in its error, as commander and oclif do, so you see what you typed:
+
+  ```
+  Invalid value 'abc' for --times: expected number
+  Invalid value 'mars' for --env. Expected one of: staging, production
+  ```
+
+  Only a value typed at the terminal or sent by a model, cut after 40 characters and kept on one line. A value from env or from the config file is never shown, nor the value of an option that declares `env`, even typed, since those often hold a secret and an error can end up in a CI log.
+
+- 5e21a16: `testCLI()` rejects when given `config` for a CLI that doesn't declare `config` in `defineCLI`, instead of applying the values. The real program would read no file, so the test passed while the CLI didn't work. The message says what to add. For a single command, `config` still stands for the file of `runCLI(command, { config })`.
+
 ## 0.2.0-beta.6
 
 ### Minor Changes
@@ -8,6 +160,8 @@
 
   If `run()` ends well after the signal, it's no longer reported as an error: no `Interrupted.` and no `onError`. A command that fails because of the abort, or doesn't end in time, still prints `Interrupted.`.
 
+  **Breaking for code that starts a Runa CLI with `spawn` and reads `code`:** after a signal it's now `null`, with the signal in `signal`. To get the number a shell shows, use `code ?? 128 + os.constants.signals[signal]`. Scripts that read `$?` are not affected. (Added after the release: the published entry didn't say it.)
+
 ## 0.2.0-beta.5
 
 ### Minor Changes

package/README.md

@@ -96,7 +96,7 @@ Operational metadata lives in `meta.options`, separate from the Zod schema:
 
 | Property | Type | Description |
 |---|---|---|
-| `alias` | `string[]` | Short flags, e.g. `['-e']` (must include dash prefix) |
+| `alias` | `string[]` | Other flags for the option: one character as `'-e'`, or a word as `'--environment'`. Any other form, as `'e'` or `'-ab'`, stops the CLI at startup and says how to write it |
 | `env` | `string` | Environment variable name, e.g. `'DEPLOY_ENV'`. If a required option is missing, the error names it: `Missing required option: --env, or set DEPLOY_ENV` |
 | `configurable` | `boolean` | `false` if a config file can't set it, as with a guardrail. Default: `true` |
 | `group` | `string` | Group name for help display, e.g. `'Scaling'` |
@@ -273,10 +273,24 @@ Write `darkColor` in code and `--dark-color` at the terminal. `run()`, config fi
 | `outputURL` | `--output-url` |
 | `dark-color` | `--dark-color`, a key with hyphens stays as written |
 
-`--darkColor` is a usage error that points to `--dark-color`. `--no-dark-mode` negates `darkMode`.
+`--darkColor` is a usage error that points to `--dark-color`. `--no-dark-mode` negates `darkMode`. A boolean whose default is `true` shows in help as `--[no-]dark-mode`, and is the only kind that shell completions offer a `--no-` for: one that starts off has nothing to turn off.
+
+A value that breaks a rule of its schema names the flag, repeats what was typed, and says what's wrong: `.positive()` gives `Invalid value '0' for --limit: must be greater than 0`, and `.min(3)` on a string `must have at least 3 characters`. Write your own message for other rules, as with `.regex(re, '--color must start with #')`, and it's shown as you wrote it.
+
+The value is only repeated if it was typed at the terminal or sent by a model, and cut after 40 characters. A value from env or from the config file is never shown, nor the value of an option that declares `env`, even typed: those often hold a secret, and an error can end up in a CI log.
 
 A boolean named `noCache` stops the CLI at startup, because `--no-cache` already negates `cache`. Declare `cache` with `.default(true)` instead.
 
+A boolean needs `.default()` or `.optional()`, or the CLI stops at startup: a flag that isn't passed would fail every run. To make someone confirm with `--yes`, let it default to `false` and check it in `run()`, with a message of yours:
+
+```ts
+options: { yes: z.boolean().default(false).describe('Confirm the deletion') },
+run({ options }) {
+  if (!options.yes) throw new CommandError('This deletes everything. Pass --yes to confirm.', { exitCode: 2 });
+  // ...
+},
+```
+
 ### Environment variables
 
 An option reads a variable only if it declares one, in `meta.options`. Nothing is read by a prefix, so the environment can't turn on an option you didn't mean it to, like `--force`:
@@ -298,7 +312,11 @@ You choose the name. A convention that helps:
 
 ### `--help`
 
-Every CLI has `--help` and `-h`, with no plugin: `tool --help` shows the CLI or the root command, and `tool db migrate --help` shows that command, with the global options that work on it.
+Every CLI has `--help` and `-h`, with no plugin: `tool --help` shows the CLI or the root command, and `tool db migrate --help` shows that command. Its own options come first, and the global options that work on it, as `--help` or `--mcp`, go apart under `GLOBAL OPTIONS`; a custom renderer tells them apart by `inherited` on each option. With `runCLI`, the command is the CLI, so they're its own options.
+
+`help` works where a command goes, as people and models often type it: `tool help` is `tool --help`, `tool help db migrate` is `tool db migrate --help`, and `tool db help` shows the group. A command of yours named `help` wins, and inside a command `help` is a value: `tool greet help` passes it to the argument. It isn't a command, so it doesn't show in the list, nor as an MCP tool.
+
+After a usage error, the hint points to the help that answers it: `tool build --limit 0` ends with `Run 'tool build --help' for usage.`
 
 Each flag yields separately. If a command declares `-h`, for `--host` say, it keeps it and `--help` still shows help. For themes and layout, add `@runa-cmd/help`. To show help your own way from a plugin, declare the `replaceHelp` capability:
 
@@ -316,7 +334,7 @@ definePlugin({
 
 With nothing to run, as in `tool` on a CLI with several commands or `tool db` on a group, help goes to stderr and the exit code is 2. A script with an empty command fails instead of passing. A name that doesn't exist is still a 127, with a suggestion.
 
-`--help` and `--version` work even if a required global option is missing.
+`--help` and `--version` work even if a required global option is missing. So does any run where nothing would run: a command that doesn't exist is still a 127, and nothing to run still shows the help with exit 2. A command that exists says the global is missing.
 
 ### `--version`
 
@@ -358,6 +376,8 @@ const auth = defineMiddleware(async ({ next, globalOptions }) => {
 });
 ```
 
+A middleware must `await next()`, or throw to stop the command. Returning without calling it fails with `MIDDLEWARE_DID_NOT_CALL_NEXT`, because the command would not run and the CLI would still exit 0. Calling it without `await` fails with `MIDDLEWARE_DID_NOT_AWAIT_NEXT`, after the command ends, so `afterRun` and `cleanup` never run while it still works. To skip a command on purpose, as a dry run does, throw `new CommandError('Dry run: would deploy api', { exitCode: 0 })`.
+
 Middleware, hooks and `run()` get the command that runs as `command`. `command.name` is its own name, and `command.path` the whole path, which is what a permissions or audit check needs: `tag add` and `add` share the name `add`.
 
 ```ts
@@ -444,7 +464,17 @@ A key at the root is a global option, or a command. Groups nest, and an option u
 
 A value only reaches the command it's under. With `runCLI` there's no command to name, so its options go at the root.
 
-Nothing is ignored. An unknown key exits with 2, naming the file and the key, and `$schema` is the only exception. A global option can't share a name with a command when the CLI has a config file: that fails at startup, for you to rename one.
+A value can be its JSON type, or the text you'd type at the terminal: `"limit": 5` and `"limit": "5"` are the same, and so are `"force": true` and `"force": "true"`. Text is accepted because a loader may only produce text, as one for an INI file. A number is not a boolean: `"force": 1` is an error that says `expected true or false`.
+
+Nothing is ignored. Every error names the file first, and says what's wrong with the words the terminal uses:
+
+```
+my-tool.config.json: invalid value for 'clear.limit': must be greater than 0
+my-tool.config.json: unknown key 'clear.limt'. Did you mean 'limit'?
+my-tool.config.json: invalid JSON: Unexpected token '}', ..."force":tru}}" is not valid JSON
+```
+
+All exit with 2. The code says what failed, and the message says where: a value that breaks its schema is a `VALIDATION_ERROR`, as it would be from the terminal or from env, and a file that can't be read as config, with broken JSON or an unknown key, is an `INVALID_CONFIG`. `$schema` is the only key that isn't checked. A global option can't share a name with a command when the CLI has a config file: that fails at startup, for you to rename one.
 
 **The current directory comes first:** a file in `.` can set options, like `force` above, for anyone who runs your CLI there. To protect one option, set `meta.options.force.configurable` to `false`: only the terminal can set it, and the file gets an error. To protect them all, use `searchPaths: ['~']`.
 
@@ -463,6 +493,54 @@ import {
 throw new CommandError('Deployment failed', { code: 'DEPLOY_FAILED', exitCode: 3 });
 ```
 
+#### Error codes
+
+Tell errors apart by their `code`, not by the message: codes are part of the [contract](../../VERSIONING.md), and messages change. `isRunaError(error, code?)` checks both, and works even when two copies of `@runa-cmd/core` are installed, where `instanceof` fails. `ERROR_CODES` lists Runa's codes, and a `CommandError` takes your own:
+
+```ts
+import { ERROR_CODES, isRunaError } from '@runa-cmd/core';
+
+if (isRunaError(error, ERROR_CODES.INVALID_CONFIG)) { /* the config file is wrong */ }
+if (isRunaError(error, 'DEPLOY_FAILED')) { /* your own code */ }
+```
+
+The value that's wrong has one code wherever it comes from, terminal, env or config file, and the message says where. These come up while someone runs the CLI:
+
+| Code | Exit | When |
+|---|---|---|
+| `VALIDATION_ERROR` | 2 | An argument or option is missing, or breaks its schema. `ValidationError` |
+| `INVALID_CONFIG` | 2 | The config file can't be used: broken JSON, an unknown key, or a value where an object goes. `ConfigError` |
+| `COMMAND_NOT_FOUND` | 127 | No command has that name. `CommandNotFoundError` |
+| `COMMAND_ERROR` | 1 | A `CommandError` without its own code |
+| `INTERRUPTED` | The signal's | `SIGINT` or `SIGTERM` stopped the run, and `run()` failed because of it or didn't end in time |
+| `INVALID_OUTPUT` | 1 | `run()` returned a value its `output` schema rejects |
+| `MISSING_RESULT` | 1 | The command declares `format`, and `run()` returned nothing |
+| `MIDDLEWARE_DID_NOT_CALL_NEXT` | 1 | A middleware returned without calling `next()`, so the command didn't run |
+| `MIDDLEWARE_DID_NOT_AWAIT_NEXT` | 1 | A middleware called `next()` without awaiting it |
+
+These stop the CLI at startup, all with exit 1. They point at the CLI's code, so its author sees them the first time it runs:
+
+| Code | When |
+|---|---|
+| `OPTION_COLLISION` | Two options end up as the same flag or alias: two keys or two aliases of a command, an alias equal to another option's flag or `--no-` negation, two globals, a global and a command's option, or an option where `format` adds `--json`. Also an alias equal to its own option's flag |
+| `INVALID_OPTION_NAME` | A boolean `noCache` would clash with `--no-cache`, which already negates `cache` |
+| `INVALID_BOOLEAN_OPTION` | A `z.boolean()` without `.default()` or `.optional()`: a flag that isn't passed would fail every run. The message says how to fix it |
+| `INVALID_OPTION_ALIAS` | An alias isn't `-x`, one character, nor `--word`, as `'e'` or `'-ab'`: the message says how to write it |
+| `INVALID_META_OPTIONS` | `meta.options` names a key that `options` doesn't have |
+| `INVALID_VARIADIC_ARGS` | A command has more than one list argument |
+| `INVALID_VARIADIC_POSITION` | The list argument isn't the last one |
+| `INVALID_COMMAND_NAME` | A command key isn't lowercase words joined by dashes, or doesn't match its `meta.name` |
+| `INVALID_COMMAND_VERSION` | A command of `defineCLI` declares `meta.version`, which only applies to the command of `runCLI`: the CLI's version goes in `defineCLI`'s `meta` |
+| `CONFIG_COLLISION` | A global option and a command share a name, so a config file can't tell them apart |
+| `INVALID_PLUGIN` | A plugin without `meta.name` or `setup()` |
+| `PLUGIN_LOAD_ERROR` | A lazy plugin failed to load, or its module has no default export |
+| `PLUGIN_MISSING_DEPENDENCY` | A plugin depends on one that isn't registered |
+| `PLUGIN_CIRCULAR_DEPENDENCY` | Plugins depend on each other in a cycle |
+| `PLUGIN_CAPABILITY_VIOLATION` | A plugin used part of the API without declaring its capability |
+| `HELP_ALREADY_REPLACED` | Two plugins replace the help |
+
+`@runa-cmd/mcp` adds its own, listed in [its README](../mcp/README.md#errors).
+
 #### How a failed run ends
 
 No failure exits silently. The reason goes to stderr, `cleanup` runs, and then the process exits.
@@ -487,7 +565,7 @@ On `SIGINT` or `SIGTERM`, Runa aborts `ctx.signal` and runs `cleanup`, and the p
 
 If `run()` ends well after the signal, as a server that closes when told to, that's not an error: nothing is printed and `onError` doesn't run. If it fails because of the abort, or doesn't end in time, stderr says `Interrupted.`.
 
-Ending by the signal, instead of with exit code 143, is what makes a stop clean for a service manager: systemd counts death by `SIGTERM` as clean, and exit 143 as a failure. A program that starts your CLI with `spawn` sees `signal: 'SIGTERM'`, not `code: 143`. On Windows, which has no signals, it exits with the code. Under launchd, stop a service with `launchctl bootout`: with `KeepAlive` → `SuccessfulExit: false`, a `launchctl kill` restarts it, as it does with any daemon that dies by the signal.
+Ending by the signal, instead of with exit code 143, is what makes a stop clean for a service manager: systemd counts death by `SIGTERM` as clean, and exit 143 as a failure. A program that starts your CLI with `spawn` sees `signal: 'SIGTERM'`, not `code: 143`, and gets the number a shell shows with `code ?? 128 + os.constants.signals[signal]`. On Windows, which has no signals, it exits with the code. Under launchd, stop a service with `launchctl bootout`: with `KeepAlive` → `SuccessfulExit: false`, a `launchctl kill` restarts it, as it does with any daemon that dies by the signal.
 
 Pass `signal` to whatever the command starts, so the stop reaches it too:
 
@@ -502,7 +580,9 @@ A command that blocks the event loop can't react to a signal until it yields. Us
 ### Constants
 
 ```ts
-import { HOOK_NAMES, PARAM_TYPES } from '@runa-cmd/core';
+import { ERROR_CODES, HOOK_NAMES, PARAM_TYPES } from '@runa-cmd/core';
+
+ERROR_CODES.VALIDATION_ERROR // 'VALIDATION_ERROR', and every code in Error codes
 
 HOOK_NAMES.BEFORE_PARSE   // 'beforeParse'
 HOOK_NAMES.ON_GLOBAL_FLAGS // 'onGlobalFlags'
@@ -521,7 +601,7 @@ PARAM_TYPES.ARRAY    // 'array'
 
 ### Testing: `testCLI()`
 
-Run a command through its real lifecycle, without ending the process:
+Run a command through its real lifecycle, without ending the process. [Testing a CLI](https://github.com/jrodrigopuca/runa-cmd/blob/main/guides/testing.md) shows it test by test, and what needs a real process instead.
 
 ```ts
 import { testCLI } from '@runa-cmd/core/testing';
@@ -556,6 +636,8 @@ A value from env is left out, because it can be a secret. The shape of `trace` i
 
 **What's isolated:** the test doesn't read the real environment or config files, and several runs can share a process, as with `it.concurrent`.
 
+**`config` needs a CLI that reads one:** if the CLI doesn't declare `config` in `defineCLI`, `testCLI()` rejects with a message saying so, because the real program would read no file. For a single command, `config` stands for the file of `runCLI(command, { config })`.
+
 **What isn't:** a command that reads `process.env` by itself sees the real one. A child process, or a write straight to a file descriptor, isn't captured. `process.exitCode` is global, so it isn't reliable with concurrent runs: exit or throw instead.
 
 A `process.exit` inside a command ends the run with its code and skips `cleanup`, as in a real run.
@@ -599,6 +681,11 @@ cleanup  ← (Runs on errors and on signals, within the stop deadline)
 On error → onError hook fires before cleanup
 ```
 
+What a hook gets grows as the run goes on: `globalOptions` from `onGlobalFlags`, and `command`, `args` and `options` from `afterParse`. Two fields differ from what `run()` gets:
+
+- **`ctx.rawArgs`** is the whole argv in `beforeParse`, where a hook may rewrite it before parsing. From `onGlobalFlags` on, it's only the command's part, without the global options and without what follows `--`. `run()` gets the original argv as it was.
+- **`ctx.invocation`** says who started the run: `{ surface: 'cli' }` for a person or a script, and `{ surface: 'tool', tool }` for a call through MCP, where everything written reaches the model. `run()` doesn't get it, on purpose: a command does the same work for both, and what only people read goes in `format`, which doesn't run for a tool.
+
 ## Value Resolution
 
 Options are resolved in this priority order:
@@ -626,7 +713,7 @@ import type {
   HookContext, HookHandler, HookName,
   Middleware, MiddlewareContext, MiddlewareFn,
   PluginAPI, PluginCapabilities, PluginConfig, PluginMeta,
-  RunContext, RunReturn,
+  RunContext, RunReturn, RunResult, FormatContext,
   ArgSchema, OptionSchema, OptionMeta,
   InferArgs, InferOptions,
   ConfigLoader, ParamMetadata, ParamType,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA4DA,OAAO,EAA2B,KAAK,UAAU,EAAoB,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EACX,GAAG,EACH,SAAS,EAET,OAAO,EAUP,aAAa,EACb,MAAM,YAAY,CAAC;AAoLpB,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACxB,uDAAuD;IACvD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA4RD;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AA2eD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,GAAG,CAQhD;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWzF;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CACzB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,GAC1C,SAAS,CAGX;AAkBD;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiEA,OAAO,EAA2B,KAAK,UAAU,EAAoB,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EACX,GAAG,EACH,SAAS,EAET,OAAO,EAUP,aAAa,EACb,MAAM,YAAY,CAAC;AA8NpB,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACxB,uDAAuD;IACvD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA4RD;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AA2hBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,GAAG,CAQhD;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWzF;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CACzB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,GAC1C,SAAS,CAGX;AAkBD;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/cli.js

@@ -14,7 +14,7 @@ import { parseArgs } from 'node:util';
 import { JSON_OPTION, JSON_SCHEMA } from './command.js';
 import { loadConfigFile } from './config/merge.js';
 import { assertConfigNames, assertValidConfig, commandValues, } from './config/scope.js';
-import { CommandNotFoundError, describeFailure, failureReason, isDebugEnabled, isUsageError, ProcessExit, RunaError, ValidationError, } from './errors.js';
+import { CommandError, CommandNotFoundError, describeFailure, ERROR_CODES, failureReason, isDebugEnabled, isRunaError, isUsageError, ProcessExit, RunaError, ValidationError, } from './errors.js';
 import { flagName } from './flag-name.js';
 import { commandClaims, findHelpTarget, HELP_TOKENS, renderHelp } from './help.js';
 import { getSchema } from './introspect.js';
@@ -24,7 +24,7 @@ import { buildParseArgsConfig } from './parse/parseargs-bridge.js';
 import { distributeRest, resolveToolInput, resolveValues } from './parse/resolve.js';
 import { walkSchema } from './parse/schema-walker.js';
 import { assertKnownOptions, assertOptionValues } from './parse/strict.js';
-import { resolvePlugins, runPluginCleanup, runPluginSetup, STATIC_GLOBAL_OPTION_SOURCE, topologicalSort, validateCommandNames, validateOptionCollisions, validateOptionNames, } from './plugin.js';
+import { resolvePlugins, runPluginCleanup, runPluginSetup, STATIC_GLOBAL_OPTION_SOURCE, topologicalSort, validateCommandNames, validateCommandTokens, validateOptionAliases, validateOptionCollisions, validateOptionNames, } from './plugin.js';
 import { watchForStop } from './stop.js';
 import { findSuggestion } from './suggest.js';
 import { sendToolReport, takeToolRequest, } from './tool-channel.js';
@@ -90,19 +90,18 @@ function resolveCommand(commands, tokens) {
     throw new RouteNotFoundError([...path, next].join(' '), suggestion, path, false, flag);
 }
 // ─── Output Validation ──────────────────────────────────────
-/** A command returning the wrong shape is an author defect, reported by field. */
-const INVALID_OUTPUT = 'INVALID_OUTPUT';
 /** The key names a command, so that's its name once a run reaches it (ADR-0043). */
 function namedMeta(command, path) {
     return { ...command.meta, name: path.at(-1), path: [...path] };
 }
+/** A command returning the wrong shape is an author defect, reported by field. */
 function assertValidOutput(name, output, result) {
     const parsed = output.safeParse(result);
     if (parsed.success)
         return;
     const issues = parsed.error.issues.map((issue) => `  ${issue.path.join('.') || '(root)'}: ${issue.message}`);
     throw new RunaError(`Command '${name}' returned invalid output:\n${issues.join('\n')}`, {
-        code: INVALID_OUTPUT,
+        code: ERROR_CODES.INVALID_OUTPUT,
         exitCode: 1,
     });
 }
@@ -113,7 +112,7 @@ function resultText(command, result, run) {
         if (!command.format)
             return undefined;
         throw new RunaError(`Command '${run.name}' declares format but returned nothing.`, {
-            code: 'MISSING_RESULT',
+            code: ERROR_CODES.MISSING_RESULT,
             exitCode: 1,
         });
     }
@@ -132,7 +131,11 @@ function printResult(command, result, run) {
 function toolFailureReason(error) {
     if (isUsageError(error))
         return 'input';
-    return error instanceof RunaError && error.code === INVALID_OUTPUT ? 'output' : 'other';
+    if (isRunaError(error, ERROR_CODES.INVALID_OUTPUT))
+        return 'output';
+    // By name too: a CommandError from another copy of core isn't an instance of this one
+    const wrote = error instanceof CommandError || (isRunaError(error) && error.name === 'CommandError');
+    return wrote ? 'command' : 'other';
 }
 // ─── Middleware Composition ─────────────────────────────────
 /**
@@ -141,8 +144,23 @@ function toolFailureReason(error) {
  * Innermost next() calls the command execution function.
  */
 function composeMiddleware(middlewareList, globalOptions, command, innerFn) {
+    if (middlewareList.length === 0)
+        return innerFn;
+    // Know whether a middleware ran the command, and whether it waited for it:
+    // either mistake would otherwise pass in silence
+    let running;
+    let settled = false;
+    const inner = () => {
+        running = innerFn();
+        running.then(() => {
+            settled = true;
+        }, () => {
+            settled = true;
+        });
+        return running;
+    };
     // Build the chain from inside out
-    let chain = innerFn;
+    let chain = inner;
     for (let i = middlewareList.length - 1; i >= 0; i--) {
         const mw = middlewareList[i];
         if (!mw)
@@ -159,7 +177,22 @@ function composeMiddleware(middlewareList, globalOptions, command, innerFn) {
             return mw.handler(ctx);
         };
     }
-    return chain;
+    const name = command.path.join(' ');
+    const outer = chain;
+    return async () => {
+        await outer();
+        if (!running) {
+            throw new RunaError(`A middleware returned without calling next(): '${name}' didn't run. Call await next(), or throw an error to stop the command.`, { code: ERROR_CODES.MIDDLEWARE_DID_NOT_CALL_NEXT, exitCode: 1 });
+        }
+        if (!settled) {
+            // Wait for it, so afterRun and cleanup don't run while it still works
+            let cause;
+            await running.catch((error) => {
+                cause = error;
+            });
+            throw new RunaError(`A middleware didn't await next(): '${name}' was still running when it returned. Use await next().`, { code: ERROR_CODES.MIDDLEWARE_DID_NOT_AWAIT_NEXT, exitCode: 1, cause });
+        }
+    };
 }
 function reportDeprecations(input) {
     for (const warning of deprecationWarnings(input)) {
@@ -507,6 +540,8 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report, harne
         // any parsing on every invocation; throws RunaError OPTION_COLLISION.
         validateCommandNames(mutableCommands, rootName);
         validateOptionNames(mutableCommands, mutableGlobalOptions);
+        validateOptionAliases(mutableCommands, mutableGlobalMeta);
+        validateCommandTokens(mutableCommands);
         validateOptionCollisions(mutableCommands, mutableGlobalOptions, mutableGlobalMeta, globalOptionSources);
         if (config.config || harness?.configValues)
             assertConfigNames(configTarget);
@@ -592,6 +627,8 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report, harne
                     i++;
                 }
             }
+            // Once, on the words left without globals: `tool --verbose help` too
+            commandArgv.splice(0, commandArgv.length, ...helpAsFlag(mutableCommands, commandArgv, rootName));
             // Now parse ONLY the extracted global tokens with parseArgs
             const globalParseResult = parseArgs({
                 ...parseArgsConfig,
@@ -606,7 +643,10 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report, harne
                 optionMeta: mutableGlobalMeta.options,
             });
             // Asking how to use a CLI can't require already knowing its options.
-            const answer = findBuiltInAnswer(config, findRoute(mutableCommands, commandArgv, rootName), commandArgv);
+            const route = findRoute(mutableCommands, commandArgv, rootName);
+            const answer = findBuiltInAnswer(config, route, commandArgv);
+            // Nor a command that doesn't exist: nothing runs, and its 127 is the answer (T-253)
+            const leadsNowhere = !toolCall && !route.command && !route.isIncomplete && !route.flag;
             // With a tool call, the command comes from the call, not from argv.
             const { configValues, configSource } = answer && !toolCall ? {} : await loadConfig([]);
             try {
@@ -624,8 +664,9 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report, harne
                 optionEvents('global', names, parsedOptions, optionSources).forEach(trace);
             }
             catch (err) {
-                const isQuestion = answer === 'help' || answer === 'version';
-                if (!isQuestion || !(err instanceof ValidationError))
+                // 'usage' too: with nothing to run, the help on stderr is the answer
+                const runsNothing = answer !== undefined || leadsNowhere;
+                if (!runsNothing || !(err instanceof ValidationError))
                     throw err;
             }
             reportDeprecations({
@@ -638,6 +679,9 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report, harne
             // Pass remaining argv (command tokens only) to command parsing
             hookCtx.rawArgs = commandArgv;
         }
+        else {
+            hookCtx.rawArgs = helpAsFlag(mutableCommands, head, rootName);
+        }
         hookCtx.globalOptions = parsedGlobalOptions;
         // ─── onGlobalFlags ────────────────────────────────
         const globalFlagsResult = await emitHook('onGlobalFlags');
@@ -731,13 +775,16 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report, harne
             // The ORIGINAL error still drives exit behavior below.
             console.error('runa: onError handler threw:', hookErr);
         }
-        failureExitCode = lifecycleError instanceof RunaError ? lifecycleError.exitCode : 1;
+        failureExitCode = isRunaError(lifecycleError) ? lifecycleError.exitCode : 1;
         // Report BEFORE cleanup: the reason stays visible even if cleanup hangs.
         // `handled` means the plugin owns the output, not that the run succeeded.
         if (!hookCtx.handled) {
             const subject = hookCtx.command?.name ?? config.meta.name;
             // An agent cannot use a hint for people, unless the operator asked for details.
-            const helpCommand = report ? undefined : config.meta.name;
+            // The help that answers it is the command's, unless the command is the CLI.
+            const path = hookCtx.command?.path;
+            const ownHelp = path && path[0] !== rootName ? [config.meta.name, ...path] : undefined;
+            const helpCommand = report ? undefined : (ownHelp?.join(' ') ?? config.meta.name);
             console.error(report && !debug
                 ? failureReason(lifecycleError, subject)
                 : describeFailure(lifecycleError, subject, debug, helpCommand));
@@ -770,6 +817,43 @@ function resolveCommandFromTree(commands, argv, rootName) {
     }
     return resolveCommand(commands, argv);
 }
+/**
+ * `help` where a command name goes is `--help` (ADR-0048): `tool help db
+ * migrate` is `tool db migrate --help`, and `tool db help` is `tool db --help`.
+ * A command named help wins, and inside a command help is a value. With
+ * runCLI, the command takes every word, so nothing changes.
+ */
+function helpAsFlag(commands, argv, rootName) {
+    if (rootName !== undefined)
+        return argv;
+    let current = commands;
+    for (const [index, token] of argv.entries()) {
+        if (token.startsWith('-'))
+            return argv;
+        if (token === 'help' && !Object.hasOwn(current, 'help')) {
+            const target = [...argv.slice(0, index), ...argv.slice(index + 1)];
+            let command;
+            try {
+                command = resolveCommand(commands, target).command;
+            }
+            catch (err) {
+                if (!(err instanceof RouteNotFoundError))
+                    throw err;
+                // `tool nope --help` shows the root's help: let the 127 name `nope`
+                if (!err.isIncomplete && !err.flag)
+                    return target;
+            }
+            // A command that took --help as an option yields -h, if it's free
+            const flag = HELP_TOKENS.find((token) => !(command && commandClaims(command, token)));
+            return flag ? [...target, flag] : argv;
+        }
+        const entry = current[token];
+        if (!entry || isCommand(entry))
+            return argv;
+        current = entry;
+    }
+    return argv;
+}
 function findRoute(commands, argv, rootName) {
     try {
         const { command, path } = resolveCommandFromTree(commands, argv, rootName);