@runa-cmd/core 0.2.0-beta.0 → 0.2.0-beta.2

package/README.md

@@ -1,16 +1,16 @@
 # @runa-cmd/core
 
-The engine of the Runa CLI framework. Schema-driven, TypeScript-first, zero runtime dependencies.
+The engine of the Runa CLI framework. Schema-driven, TypeScript-first, with zero runtime dependencies besides Zod as a required peer.
 
-Define your CLI with Zod schemas and get full type inference, validation, help text, and more — from a single source of truth.
+Define your CLI with Zod schemas and get full type inference, validation, and metadata for help, completions and MCP plugins — from a single source of truth.
 
 ## Install
 
 ```bash
-pnpm add @runa-cmd/core zod
+pnpm add @runa-cmd/core@beta zod
 ```
 
-> Requires Node 18.3+ (uses `util.parseArgs`). Zod v4 is a peer dependency.
+> Requires Node 24+. Zod v4 is a required peer dependency. Without `@beta`, npm installs the older `0.1.0`.
 
 ## Quick Start
 
@@ -30,7 +30,7 @@ runCLI(greet);
 ```
 
 ```
-$ my-cli greet world
+$ greet world
 Hello, world!
 ```
 
@@ -47,7 +47,7 @@ const deploy = defineCommand({
     description: 'Deploy to an environment',
     options: {
       env: { alias: ['-e'], env: 'DEPLOY_ENV' },
-      replicas: { group: 'Scaling', hint: '<count>' },
+      replicas: { group: 'Scaling' },
     },
   },
   args: {
@@ -80,7 +80,7 @@ const deploy = defineCommand({
 | `meta.name` | `string` | Yes | Command name |
 | `meta.description` | `string` | Yes | One-line description |
 | `meta.version` | `string` | No | Command version |
-| `meta.options` | `Record<string, OptionMeta>` | No | Per-option metadata (alias, env, group, deprecated, hint) |
+| `meta.options` | `Record<string, OptionMeta>` | No | Per-option metadata (alias, env, group, deprecated) |
 | `args` | `Record<string, ZodType>` | No | Positional arguments (insertion order matters) |
 | `options` | `Record<string, ZodType>` | No | Named options (--flag style) |
 | `output` | `ZodType` | No | Output schema — if set, `run()` must return matching data |
@@ -95,8 +95,8 @@ Operational metadata lives in `meta.options`, separate from the Zod schema:
 | `alias` | `string[]` | Short flags, e.g. `['-e']` (must include dash prefix) |
 | `env` | `string` | Environment variable name, e.g. `'DEPLOY_ENV'` |
 | `group` | `string` | Group name for help display, e.g. `'Scaling'` |
-| `deprecated` | `string \| boolean` | Deprecation notice |
-| `hint` | `string` | Value hint for help, e.g. `'<count>'` |
+| `valueName` | `string` | What help calls the value, e.g. `'hex'` for `--color <hex>`. Defaults to its type |
+| `deprecated` | `string` | Deprecation notice, shown in help and as a stderr warning when the option is used |
 
 #### Run Context
 
@@ -109,6 +109,8 @@ interface RunContext {
   globalOptions: Record<string, unknown>;
   command: CommandMeta;            // Current command metadata
   rawArgs: string[];               // Original argv
+  rest: string[];                  // With `rest: true`, what's left after `--`. Unvalidated
+  signal: AbortSignal;             // Aborted when the run must stop
 }
 ```
 
@@ -151,22 +153,101 @@ cli.run();
 | `plugins` | `PluginConfig[]` | No | Plugins to load |
 | `middleware` | `Middleware[]` | No | Global middleware chain |
 | `globalOptions` | `Record<string, ZodType>` | No | Options available to all commands |
-| `globalMeta` | `Record<string, OptionMeta>` | No | Metadata for global options |
+| `globalMeta` | `{ options?: Record<string, OptionMeta> }` | No | Metadata for global options |
 | `config` | `CLIConfigOptions` | No | Config file loading settings |
+| `strictOptions` | `boolean` | No | Reject unknown options. Default: `true` |
 
-### `runCLI(command, argv?)`
+### `runCLI(command, options?)`
 
-Shorthand for single-command CLIs. Wraps the command in `defineCLI` and runs it.
+The API for a CLI made of one command. It takes the same options as `defineCLI`, except `meta` and `commands`, which come from the command, plus `argv`.
 
 ```ts
-runCLI(myCommand);
-// Equivalent to:
-defineCLI({
-  meta: { name: command.meta.name },
-  commands: { [command.meta.name]: command },
-}).run();
+runCLI(myCommand, {
+  plugins: [helpPlugin(), mcpPlugin()],
+  argv: ['hello'], // Default: process.argv.slice(2)
+});
+```
+
+The command is the root of the CLI, so a value equal to its name is data: `tool tool` passes `"tool"`. If a plugin adds a subcommand, that name routes to it, and `--` passes it as data: `tool -- completions`.
+
+`defineCLI` with a single command also works, but it's deprecated: adding a plugin that registers a command silently changes how it routes.
+
+### Options that repeat
+
+A `z.array()` option repeats, and each element is converted to its type: `--port 80 --port 81` gives `[80, 81]` with `z.array(z.number())`.
+
+| Source | Form | Result |
+|---|---|---|
+| Terminal | `--tag a --tag b` | `['a', 'b']` |
+| Terminal | `--tag a,b` | `['a,b']` |
+| Env | `TAGS=a, b` | `['a', 'b']` |
+| Config | `{ "tag": ["a", "b"] }` | `['a', 'b']` |
+
+Each source replaces the ones below it, without adding up. A value with a comma can't go through env: use the config file.
+
+### Option names
+
+Write `darkColor` in code and `--dark-color` at the terminal. `run()`, config files and MCP tools keep the key.
+
+| Key | Flag |
+|---|---|
+| `darkColor` | `--dark-color` |
+| `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`.
+
+A boolean named `noCache` stops the CLI at startup, because `--no-cache` already negates `cache`. Declare `cache` with `.default(true)` instead.
+
+### `--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.
+
+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:
+
+```ts
+definePlugin({
+  meta: { name: 'my-help' },
+  capabilities: { replaceHelp: true },
+  setup(api) {
+    api.replaceHelp((target, output) => output.write(`${render(target)}\n`));
+  },
+});
+```
+
+`target` is a `CLISchema` or a `CommandSchema`. `output` is stdout, or stderr when there was nothing to run. Only one plugin can replace the help.
+
+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.
+
+### `--version`
+
+Printed when `meta.version` is set, from `defineCLI` or from the command in `runCLI`. It has no short alias. If the command declares its own `--version` option, that option wins.
+
+### The `--` separator
+
+Everything after the first `--` is never read as a flag. Those tokens fill the positionals still empty, where a variadic counts as one.
+
+What's left is a usage error, so nothing gets lost in silence. A command that wraps another one declares `rest: true` to receive it in `ctx.rest`:
+
+```ts
+const run = defineCommand({
+  meta: { name: 'run', description: 'Run a program' },
+  rest: true,
+  run({ rest }) {
+    spawn(rest[0], rest.slice(1));
+  },
+});
 ```
 
+| Input | Without `rest: true` | With `rest: true` |
+|---|---|---|
+| `tool -- -text` | `args.content` is `-text` | Same |
+| `lint -- -a -b` | `args.files` is `['-a', '-b']` | Same |
+| `copy a b -- -c` | Exit 2 | `ctx.rest` is `['-c']` |
+| `run -- npm test` (no positionals) | Exit 2 | `ctx.rest` is `['npm', 'test']` |
+
 ### `defineMiddleware(handler)`
 
 Creates middleware using the onion model (like Koa/Hono):
@@ -214,6 +295,7 @@ The `setup(api)` function receives:
 | `api.hook(name, handler)` | Register a lifecycle hook handler |
 | `api.getSchema()` | Get the introspected CLI schema |
 | `api.getCommands()` | Get the live command tree reference |
+| `api.getConfigValues()` | Get the values of the CLI's config file, if it has one |
 
 ### `getSchema(config)`
 
@@ -228,15 +310,15 @@ const schema = getSchema(cliConfig);
 
 ### `jsonLoader()`
 
-Built-in JSON config file loader:
+Built-in JSON config file loader, always active when `config` is set:
 
 ```ts
 const cli = defineCLI({
   // ...
   config: {
-    name: 'my-tool',          // Searches for my-tool.config.json, .my-toolrc.json, etc.
-    loaders: [jsonLoader()],
-    searchPaths: ['./'],       // Where to search
+    name: 'my-tool',          // Searches for my-tool.config.json
+    searchPaths: ['.', '~'],  // Where to search. This is the default
+    // loaders: [...]         // Extra formats. The first match wins
   },
 });
 ```
@@ -255,6 +337,36 @@ import {
 throw new CommandError('Deployment failed', { code: 'DEPLOY_FAILED', exitCode: 3 });
 ```
 
+#### How a failed run ends
+
+No failure exits silently. The reason goes to stderr, `cleanup` runs, and then the process exits.
+
+| Case | stderr | Exit code |
+|---|---|---|
+| `RunaError` with a message | The message, as written | The error's |
+| Any other error | `Unexpected error in '<command>': <message>` and a hint | 1 |
+| Error without a message | `'<command>' failed without an error message (<type>).` and a hint | The error's, or 1 |
+| `onError` sets `ctx.handled` | Nothing from Runa | The error's, or 1 |
+
+- Usage errors end with `Run '<cli> --help' for usage.`
+- Throw `CommandError` for messages meant for people using your CLI.
+- Set `RUNA_DEBUG=1` to add the stack trace, error code and cause.
+- `ctx.handled` only stops the default output. If a plugin truly recovered, it sets `process.exitCode = 0` in `onError`.
+
+#### How a run stops
+
+On `SIGINT` or `SIGTERM`, Runa aborts `ctx.signal` and runs `cleanup`, and the process exits with 130 or 143. A command that ignores the signal stops being waited for after 2 seconds, and the process ends after 5 at most. A second signal leaves at once.
+
+Pass `signal` to whatever the command starts, so the stop reaches it too:
+
+```ts
+async run({ signal }) {
+  await fetch(url, { signal });
+}
+```
+
+A command that blocks the event loop can't react to a signal until it yields. Use `Ctrl+\` to end it at once.
+
 ### Constants
 
 ```ts
@@ -309,7 +421,7 @@ beforeRun
     ↓
 afterRun
     ↓
-cleanup  ← (ALWAYS runs, even on error)
+cleanup  ← (Runs on errors and on signals, within the stop deadline)
 
 On error → onError hook fires before cleanup
 ```
@@ -328,6 +440,8 @@ For example, if an option has `env: 'PORT'` and `z.number().default(3000)`:
 3. Config file value wins over default
 4. `3000` is the fallback
 
+Boolean options accept `true`, `1`, `false` and `0`, in any case, from every source: `MINIFY=1`, `--minify=false`, or `"minify": true` in a config file. Any other value is a usage error.
+
 ## Types
 
 All types are exported for consumers who need them:

package/dist/cli.d.ts

@@ -1,12 +1,28 @@
-import type { CLI, CLIConfig, Command } from './types.js';
+import type { CLI, CLIConfig, Command, RunCLIOptions } from './types.js';
+/** A command to run from an object, with no argv to parse (ADR-0030). */
+export interface ToolCall {
+    /** Command path in the tree, e.g. ['config', 'set'] */
+    path: string[];
+    input: Record<string, unknown>;
+}
 /**
  * Create a CLI from a configuration.
  * Returns a branded CLI object with a .run() method.
  */
 export declare function defineCLI(config: CLIConfig): CLI;
 /**
- * Single-command shorthand.
- * Wraps a command in defineCLI() and runs it.
+ * Run a CLI made of one command. Accepts everything defineCLI() does except
+ * meta and commands, which come from the command: plugins, middleware, config.
  */
-export declare function runCLI(command: Command, argv?: string[]): Promise<void>;
+export declare function runCLI(command: Command, options?: RunCLIOptions): Promise<void>;
+/**
+ * Run a command from an object, through the same lifecycle as a CLI run.
+ * Internal, for @runa-cmd/mcp: not exported from the package barrel.
+ *
+ * @param options.argv - Startup arguments, read for global options only
+ */
+export declare function runToolCall(config: CLIConfig, call: ToolCall, options?: {
+    argv?: string[];
+    rootName?: string;
+}): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACX,GAAG,EACH,SAAS,EACT,OAAO,EAOP,MAAM,YAAY,CAAC;AAkdpB;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,GAAG,CAShD;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM7E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EACX,GAAG,EACH,SAAS,EAET,OAAO,EAOP,aAAa,EACb,MAAM,YAAY,CAAC;AA0IpB,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;AA4nBD;;;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,CASzF;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"}