runset 0.0.0 → 0.0.2

package/README.md

@@ -1,10 +1,16 @@
 # runset
 
-Run npm scripts in sequence or in parallel. Based on ideas from
-[`npm-run-all`](https://github.com/mysticatea/npm-run-all), with reusable
-pipelines, colored labels, and grouped output.
-
-Requires Node.js 24.2 or later. No runtime dependencies.
+Run npm scripts and shell commands in parallel or sequence, with glob matching,
+reusable pipelines, colored labels, and grouped output. Inspired by
+`npm-run-all`, with more control over execution and output.
+
+- **Flexible execution** — mix parallel and sequential steps, with concurrency
+  limits
+- **Readable output** — colored labels, grouped logs, and output redirection
+- **Process control** — stop, continue, or restart on exit, clean up process
+  trees on interruption
+- **Workspace support**
+- **Zero dependencies**
 
 ```sh
 npm install --save-dev runset
@@ -22,6 +28,9 @@ npx runset -p "watch:**"                # all watch scripts together
 Each `-p` or `-s` starts a new group. Groups run in order, so in the mixed
 example above, build waits for both lint and test to finish.
 
+Use `-j 2` to limit concurrency. Commands in a group run in batches of at most
+two, with each batch waiting for all its commands before the next starts.
+
 By default, a failed command stops the run. Ctrl+C stops all running commands
 and their child processes.
 
@@ -48,26 +57,21 @@ npx runset "serve --port {1}" -- 8080
 npx runset "test {@}" -- --watch --verbose
 ```
 
-`{1}`, `{2}`, etc. insert individual arguments. `{@}` inserts all arguments.
-Placeholder values are quoted automatically for the shell.
+`{1}`, `{2}`, etc. insert individual arguments. `{@}` inserts all arguments
+separately; `{*}` joins them into one argument. Placeholder values in command
+arguments are quoted automatically for the shell.
 
-## Options
+Named placeholders read options after `--`: `{port}` takes its value from
+`--port 8080` or `--port=8080`. A bare option supplies `true`, which is useful
+for conditional commands:
 
-| Option                  | What it does                                  |
-| ----------------------- | --------------------------------------------- |
-| `-p, --parallel`        | Run the following commands together           |
-| `-s, --serial`          | Run the following commands one after another  |
-| `-j, --jobs <n>`        | Limit how many commands run at once           |
-| `--on-failure <action>` | `stop` (default), `continue`, or `restart`    |
-| `--on-success <action>` | `continue` (default), `stop`, or `restart`    |
-| `-o, --output grouped`  | Buffer each command's output until it exits   |
-| `--stdout <file>`       | Write stdout to a file                        |
-| `--labels <mode>`       | `auto` (default), `all`, `custom`, or `none`  |
-| `--cwd <dir>`           | Set the working directory                     |
-| `--dry-run`             | Show what would run without starting anything |
-| `-c, --config <path>`   | Use a specific config file                    |
+```sh
+npx runset "serve --port {port}" -- --port=8080
+npx runset lint "test::disabled={noTest}" -- --no-test
+```
 
-Use `--help` for all options.
+Without `--no-test`, the missing value makes `disabled` false. Placeholders work
+in command arguments and `::` option values, not command names.
 
 Add `::` to set options for one command:
 
@@ -76,14 +80,83 @@ npx runset -p "api::label=server,color=cyan" web
 npx runset "lint::on-failure=continue" build
 ```
 
+See the [command options](#command-options) and [CLI flags](#cli-flags) at the
+bottom for the full reference.
+
+## Workspaces
+
+Use `-r, --recursive` to run a script in every workspace package that has it:
+
+```sh
+npx runset -r build                   # packages in sequence
+npx runset -rp "test:*" -j 4          # workspace tests, up to four at once
+npx runset clean "build::recursive"  # only build expands across packages
+```
+
+runset finds the nearest `pnpm-workspace.yaml` or `package.json` with
+`workspaces`, starting at the working directory. Workspace patterns support `!`
+exclusions. The root package is excluded; packages run in path order, from their
+own directories, with package names used for automatic labels. Packages without
+the script are skipped. If no workspace package matches, the command resolves
+normally as a local script, glob, or shell command.
+
+## Exit behavior
+
 `stop` ends the whole run. `continue` lets it carry on. `restart` runs the
 command again without a delay or retry limit.
 
+`--on-failure continue` runs the remaining commands but still exits non-zero if
+any command fails. `--on-success stop` ends the run when a command succeeds,
+stopping any others still running. Failures produce a summary identifying the
+failed commands.
+
+Ctrl+C and SIGTERM stop the command process trees. `--kill-timeout` sets the
+grace period before forceful termination (5000 ms by default); a second Ctrl+C
+forces termination immediately. A run interrupted by SIGINT exits with 130, or
+143 for SIGTERM, unless it was already ending with another result.
+
 ## Output
 
 Commands running together get colored labels automatically, so you can tell
-which command wrote each line. Set your own with `::label=api,color=cyan`. Use
-`--no-color` for plain text or `--labels none` to hide labels.
+which command wrote each line. Automatic labels use the script, program, or
+workspace package name; repeated names get suffixes such as `#1` and `#2`. Set
+your own with `::label=api,color=cyan`. Use `--color none` for plain text or
+`--labels none` to hide labels.
+
+| Label mode | What gets a label                                                               |
+| ---------- | ------------------------------------------------------------------------------- |
+| `auto`     | Commands sharing a parallel stage, plus any custom labels (default)             |
+| `all`      | Every command, including sequential commands                                    |
+| `custom`   | Only custom labels; other commands in the same stage leave a blank label column |
+| `none`     | Nothing, including commands with custom labels                                  |
+
+runset has 36 label backgrounds for 256-color terminals: 24 soft, vivid shades
+with charcoal text and 12 deeper shades with off-white text. `--color <mode>`
+(or `color` in a config file) picks how many of them automatic labels use:
+
+| Mode    | Automatic labels                                                                            |
+| ------- | ------------------------------------------------------------------------------------------- |
+| `auto`  | `soft` on 256-color terminals, `basic` on other color terminals, otherwise `none` (default) |
+| `none`  | no color, `[label]`                                                                         |
+| `basic` | the terminal's 16 theme colors                                                              |
+| `soft`  | the 24 soft shades                                                                          |
+| `all`   | the soft and the deeper shades                                                              |
+
+`auto` reads the terminal environment, so `FORCE_COLOR` and `NO_COLOR` apply.
+Without an environment override, both stdout and stderr must be terminals for
+color to be enabled. Explicit modes override detection. Label colors are chosen
+from the label text, with collisions adjusted to distinguish commands.
+
+You can also choose a shade: `"api::label=server,color=ink,bg-color=bgCoral"`.
+Available shades are `mint`, `sky`, `rose`, `amber`, `lavender`, `aqua`,
+`coral`, `sage`, `periwinkle`, `peach`, `teal`, `lilac`, `lime`, `steel`,
+`pink`, `seafoam`, `apricot`, `mauve`, `jade`, `sand`, `iris`, `ice`, `salmon`,
+`olive`, `navy`, `plum`, `forest`, `wine`, `ocean`, `indigo`, `copper`, `pine`,
+`violet`, `brick`, `slate`, `cocoa`, `ink`, and `paper`. Pair the deeper shades
+with `paper`, as in `"api::label=server,color=paper,bg-color=bgNavy"`. For
+backgrounds, capitalize the shade and prefix it with `bg`, as in `bgMint`.
+Existing names such as `cyan` and `bgBlue` still use your terminal's theme. From
+a checkout, run `npm run preview:colors` to see all 36 label pairs.
 
 To keep each command's output together, use grouped output:
 
@@ -93,6 +166,35 @@ npx runset -p lint test -o grouped
 
 Each command's output is buffered and printed when it exits.
 
+`--stdout` and `--stderr` configure streams separately; `-o, --output` sets
+both. A value can name a timing (`realtime` or `grouped`), a destination
+(`stdout`, `stderr`, `none`, or a file path), or both joined with `+`:
+
+```sh
+npx runset -p lint test --stdout grouped+./checks.log
+npx runset build --stderr stdout
+npx runset "lint::output=none" build
+```
+
+The default is realtime output to each stream's usual destination. A value that
+sets only timing preserves the destination, and vice versa. Stream-specific
+options override `output` in the same scope, regardless of flag order. File
+paths resolve against the run's working directory. Each file is overwritten once
+per run, and commands writing to the same file share it.
+
+In a config, write `output: 'grouped'` or
+`output: { timing: 'grouped', destination: './checks.log' }` — for the whole
+run, in a settings entry, or on a single command.
+
+Use `--show-command` to print commands when they start and `--show-exit-code` to
+show their status and duration: `✓ 2.1s`, `✗ code 1 · 2.1s`, or
+`– stopped · 2.1s`. Failure and stop lines also name the command. These lines
+follow the command's stdout settings, including grouping and redirection.
+
+`-w, --wrap` wraps long labelled lines and repeats the label on every line. It
+uses the terminal width, or `COLUMNS` when no terminal width is available;
+without either, lines stay whole. Wrapping is off by default.
+
 ## Config
 
 Save a pipeline in `runset.config.ts`, then run `npx runset`:
@@ -115,26 +217,46 @@ export default {
 This runs clean, then lint and test together, then build. Settings entries apply
 to the commands that follow them.
 
-Use `commandDictionary` to give a command or pipeline a reusable name:
+The same object may live in a `runset` section of `package.json` instead; a
+`runset.config.*` file in the same directory wins over it.
+
+Use `scripts` to give a command or pipeline a reusable name:
 
 ```ts
 import type { ConfigJs } from 'runset';
 
 export default {
-  commandDictionary: {
+  scripts: {
     check: ['lint', 'test'],
     api: { command: 'node server.js', env: { PORT: '4000' } },
   },
 } satisfies ConfigJs;
 ```
 
-Run these with `npx runset check` or `npx runset api`. Dictionary names take
-priority over npm script names.
+Run these with `npx runset check` or `npx runset api`. Names in `scripts` take
+priority over the same names in `package.json`.
 
 Config files also support `.js`, `.mjs`, `.cjs`, and `.json`. runset looks in
 the working directory and its parents. CLI commands run **after** any `commands`
 listed in the config.
 
+Run-wide CLI flags override config values. Per-command options override the
+run-wide defaults. Config keys use camelCase, such as `onFailure`,
+`showExitCode`, and `killTimeout`; see the references below.
+
+Set environment variables for every command with a top-level `env` object or
+repeatable `-e NAME=value` flags. CLI values override config values for the same
+variable. A command can add its own `env` object, as `api` does above. These
+settings affect child commands; use `--color` to control runset's own colors.
+
+Config modules can also export a synchronous function receiving
+`{ argv, cwd, env }` and returning the config object. Falsy entries in
+`commands` are skipped, so lists can contain conditional commands.
+
+Named pipelines can run together: with `api: ['build:api', 'test:api']` and
+`web: ['build:web', 'test:web']` in `scripts`, `npx runset -p api web` runs both
+builds, then both tests. Both builds must finish before either test starts.
+
 ## Library
 
 ```ts
@@ -148,6 +270,94 @@ The promise resolves with a `Run`, or rejects with a `RunsetError` if the run
 fails. Use `Run.fromConfigJs(config)` to prepare a run, `describe()` to inspect
 it, `start()` to run it, and `terminate()` to stop it.
 
+## Command options
+
+Use `"command args::option=value,flag"` on the CLI or in config command strings.
+The last `::` starts the option list. Boolean options can be bare (`disabled`)
+or explicit (`disabled=false`). To pass a literal `::` in the command, append an
+empty option list, as in `"perl -MData::Dumper::"`.
+
+Config command objects use camelCase: for example,
+`{ command: 'lint', onFailure: 'continue' }`. Settings entries omit `command`
+and supply defaults for the following commands.
+
+| Inline option             | Config key  | Meaning                                                                                                                         |
+| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `label=<text>`            | `label`     | Set the output label; preserves spaces. Visibility follows `labels`.                                                            |
+| `color=<name>`            | `color`     | Label foreground, such as `cyan`, `ink`, or `paper`; this is a color name, while run-wide `color` is a mode.                    |
+| `bg-color=<name>`         | `bgColor`   | Label background, such as `bgBlue` or `bgCoral`. Colors alone do not add a label.                                               |
+| `cwd=<dir>`               | `cwd`       | Set the command's directory, relative to the inherited directory. Explicitly setting it overrides the npm package-root default. |
+| `disabled[=true\|false]`  | `disabled`  | Skip the command when true; default: `false`.                                                                                   |
+| `parallel[=true\|false]`  | `parallel`  | Run alongside adjacent parallel commands. On a named pipeline, run its stages alongside neighboring pipelines.                  |
+| `recursive[=true\|false]` | `recursive` | Expand npm scripts across workspace packages; inherits the run-wide setting (default: `false`).                                 |
+| `on-success=<action>`     | `onSuccess` | `continue`, `stop`, or `restart`; inherits the run-wide setting (default: `continue`).                                          |
+| `on-failure=<action>`     | `onFailure` | `continue`, `stop`, or `restart`; inherits the run-wide setting (default: `stop`).                                              |
+| `output=<value>`          | `output`    | Configure both streams using the output syntax above.                                                                           |
+| `stdout=<value>`          | `stdout`    | Configure stdout timing and/or destination.                                                                                     |
+| `stderr=<value>`          | `stderr`    | Configure stderr timing and/or destination.                                                                                     |
+| —                         | `env`       | Object of environment variables added to this command; config only.                                                             |
+
+Settings entries also accept `serial: true` as the opposite of `parallel: true`.
+Each settings entry that sets `parallel` or `serial` starts a new group.
+
+For a custom label renderer, set the run-wide, config-only `formatLabel`
+function. It receives `{ command, color, defaultPrefix, stream }` and returns
+the prefix string, for example:
+
+```ts
+formatLabel: ({ defaultPrefix }) => `${new Date().toISOString()} ${defaultPrefix}`,
+```
+
+## CLI flags
+
+```text
+runset [options] <command...> [-- <placeholder arguments...>]
+```
+
+Except for `-p` and `-s`, flags apply to the whole run wherever they appear.
+Long flags accept `--name value` or `--name=value`; short flags can be combined,
+such as `-rp` or `-j4`. Use `--no-recursive`, `--no-show-command`,
+`--no-show-exit-code`, `--no-wrap`, or `--no-dry-run` to disable a boolean
+setting from the config. `--no-color` is an alias for `--color none`.
+
+### Execution
+
+| Flag                    | Meaning and default                                                                     |
+| ----------------------- | --------------------------------------------------------------------------------------- |
+| `-p, --parallel`        | Start a group that runs the following commands together.                                |
+| `-s, --serial`          | Start a group that runs the following commands sequentially (the initial mode).         |
+| `-j, --jobs <n>`        | Maximum concurrent commands, run in batches; default: unlimited.                        |
+| `-r, --recursive`       | Run npm scripts in every workspace package that has them; default: off.                 |
+| `--on-success <action>` | Action after a clean exit: `continue` (default), `stop`, or `restart`.                  |
+| `--on-failure <action>` | Action after a failed exit: `stop` (default), `continue`, or `restart`.                 |
+| `--kill-timeout <ms>`   | Grace period before forceful termination; default: `5000`. Use `0` for no grace period. |
+
+### Output
+
+| Flag                   | Meaning and default                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `-o, --output <value>` | Set timing and/or destination for both command streams.                                                      |
+| `--stdout <value>`     | Set stdout timing and/or destination; default: `realtime+stdout`.                                            |
+| `--stderr <value>`     | Set stderr timing and/or destination; default: `realtime+stderr`.                                            |
+| `--labels <mode>`      | `auto` (default), `all`, `custom`, or `none`; see the label modes above.                                     |
+| `--color <mode>`       | `auto` (default), `none`, `basic`, `soft`, or `all`.                                                         |
+| `--show-command`       | Print each command when it starts; default: off.                                                             |
+| `--show-exit-code`     | Print each command's exit status and duration; default: off.                                                 |
+| `-w, --wrap`           | Wrap long labelled lines, repeating the label; default: off.                                                 |
+| `--log-level <level>`  | Filter runset's own messages: `error`, `warn`, `info` (default), or `debug`. Does not filter command output. |
+
+### Configuration and help
+
+| Flag                     | Meaning and default                                                                                                                                                                                        |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-c, --config <path>`    | Load a specific config file instead of searching for one.                                                                                                                                                  |
+| `--cwd <dir>`            | Set the run's directory for config/package lookup, shell commands, and relative output paths. Defaults to the current directory; npm scripts run from their package root unless given a per-command `cwd`. |
+| `-e, --env <NAME=value>` | Add an environment variable to every command; repeat for multiple variables.                                                                                                                               |
+| `--dry-run`              | Print resolved commands, stages, and effective options without running commands.                                                                                                                           |
+| `-h, --help`             | Show CLI help.                                                                                                                                                                                             |
+| `-v, --version`          | Show the installed version.                                                                                                                                                                                |
+| `--`                     | End runset options; remaining arguments supply placeholders. They are not automatically appended to commands.                                                                                              |
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.d.mts

@@ -9,6 +9,12 @@ export interface Std {
 export type ExitAction = 'continue' | 'restart' | 'stop';
 export declare const EXIT_ACTIONS: Set<ExitAction>;
 export type LogLevel = 'debug' | 'error' | 'info' | 'warn';
+/**
+ * How much color runset uses: `basic` is the terminal's 16 theme colors,
+ * `soft` the light 256-color shades, and `all` those plus the deep ones.
+ * `auto` is `basic` or `soft`, whichever the terminal shows, or `none`.
+ */
+export type ColorMode = 'all' | 'auto' | 'basic' | 'none' | 'soft';
 /** Which commands get a label in front of their output: see `--labels`. */
 export type LabelMode = 'all' | 'auto' | 'custom' | 'none';
 /** A resolved command, one per process a run spawns. */
@@ -24,7 +30,11 @@ export interface Command {
   line: string;
   onFailure: ExitAction;
   onSuccess: ExitAction;
+  /** The workspace package a `recursive` command was expanded into. */
+  packageName?: string;
   parallel: boolean;
+  /** Run an npm script in every workspace package that has it. */
+  recursive: boolean;
   /** The `package.json` script name, when `type` is `'npm'`. */
   scriptName?: string;
   /** Commands sharing a stage run together; stages run in order. */
@@ -44,9 +54,11 @@ export type LabelFormatter = (context: {
 }) => string;
 /** The parts of a {@link Command} a user may set by hand. */
 export type CommandOptions = {
+  /** Both streams at once; `stdout` / `stderr` in the same place outrank it. */
+  output?: Partial<Std> | string;
   stderr?: Partial<Std> | string;
   stdout?: Partial<Std> | string;
-} & Partial<Omit<Command, 'line' | 'scriptName' | 'stage' | 'stderr' | 'stdout' | 'type'>>;
+} & Partial<Omit<Command, 'line' | 'packageName' | 'scriptName' | 'stage' | 'stderr' | 'stdout' | 'type'>>;
 /** One command written as an object; `command` is what makes it one. */
 export type CommandEntry = {
   command: string;
@@ -62,12 +74,12 @@ export type CommandSettings = {
 export type CommandDefinition = CommandEntry | CommandSettings | false | null | string | undefined;
 /** What a user writes in `runset.config.*`, or hands to `runset({ … })`. */
 export interface ConfigJs {
-  color?: boolean;
-  /** Named commands, resolved before `package.json` scripts. An entry may be a list. */
-  commandDictionary?: Record<string, CommandDefinition | CommandDefinition[]>;
+  /** Default: `'auto'`. */
+  color?: ColorMode;
   commands?: CommandDefinition[];
   cwd?: string;
   dryRun?: boolean;
+  env?: Record<string, string>;
   /**
    * Renders the prefix of each labelled output line.
    *
@@ -87,10 +99,22 @@ export interface ConfigJs {
   onFailure?: ExitAction;
   /** What a clean exit does to the run. Default: `'continue'`. */
   onSuccess?: ExitAction;
+  /** Both streams at once; `stdout` / `stderr` outrank it. */
+  output?: Partial<Std> | string;
   /** The default `parallel` for every command. Default: `false`. */
   parallel?: boolean;
+  /** The default `recursive` for every command. Default: `false`. */
+  recursive?: boolean;
+  /** Named commands, resolved before `package.json` scripts. An entry may be a list. */
+  scripts?: Record<string, CommandDefinition | CommandDefinition[]>;
+  /** Print each command before it starts. Default: `false`. */
+  showCommand?: boolean;
+  /** Print how each command exited, green or red. Default: `false`. */
+  showExitCode?: boolean;
   stderr?: Partial<Std> | string;
   stdout?: Partial<Std> | string;
+  /** Wrap labelled lines to the terminal, labelling each piece. Default: `false`. */
+  wrap?: boolean;
 }
 /** A config module may export the object itself or a sync factory for it. */
 export type ConfigJsExport = ((context: {
@@ -113,13 +137,18 @@ export interface Destinations {
 export declare function isCommandSettings(definition: CommandEntry | CommandSettings): definition is CommandSettings;
 export declare function isStreamDestination(destination: string): destination is 'stderr' | 'stdout';
 //#endregion
+//#region src/utils/colors.d.ts
+/** A `ColorMode` once `auto` has been settled. */
+type ColorLevel = Exclude<ColorMode, 'auto'>;
+//#endregion
 //#region src/config/parseCli.d.ts
 /** Run-wide options a CLI flag can set. */
 interface CliOptions {
-  color?: boolean;
+  color?: string;
   config?: string;
   cwd?: string;
   dryRun?: boolean;
+  env?: Record<string, string>;
   jobs?: number;
   killTimeout?: number;
   labels?: string;
@@ -127,8 +156,12 @@ interface CliOptions {
   onFailure?: string;
   onSuccess?: string;
   output?: string;
+  recursive?: boolean;
+  showCommand?: boolean;
+  showExitCode?: boolean;
   stderr?: string;
   stdout?: string;
+  wrap?: boolean;
 }
 interface ParsedCli {
   /** The argv this is the parse of. */
@@ -145,7 +178,7 @@ interface ParsedCli {
 /** The resolved run-wide configuration: CLI flag → config file → default. */
 declare class Config {
   readonly commands: CommandDefinition[];
-  readonly commandDictionary: Record<string, CommandDefinition | CommandDefinition[]>;
+  readonly scripts: Record<string, CommandDefinition | CommandDefinition[]>;
   /** Everything after `--`, for placeholders. */
   readonly args: string[];
   readonly cwd: string;
@@ -154,8 +187,14 @@ declare class Config {
   readonly killTimeout: number;
   readonly onSuccess: ExitAction;
   readonly onFailure: ExitAction;
-  readonly color: boolean;
+  readonly color: ColorLevel;
   readonly parallel: boolean;
+  readonly recursive: boolean;
+  readonly showCommand: boolean;
+  readonly showExitCode: boolean;
+  readonly wrap: boolean;
+  /** `COLUMNS` as runset was started with it: the width where no TTY says. */
+  readonly envColumns: number | undefined;
   readonly labels: LabelMode;
   readonly logLevel: LogLevel;
   readonly dryRun: boolean;
@@ -214,6 +253,10 @@ export declare class Run {
   /** Rejects with a {@link RunsetError} when the run did not succeed. */
   start(): Promise<Run>;
   terminate(options?: TerminateOptions): void;
+  /** `1 of 5 commands failed, 2 stopped, 1 not started`. */
+  private tally;
+  /** The tally, then a row per failure, labelled as its output was. */
+  private failureReport;
   private failed;
   /** Says a signal arrived before any command's parting words, then stops. */
   private onSignal;
@@ -226,7 +269,9 @@ export declare class Run {
 /** Any failure runset reports itself; `exitCode` is what the CLI exits with. */
 export declare class RunsetError extends Error {
   readonly exitCode: number;
-  constructor(message: string, exitCode?: number);
+  /** What the CLI prints in place of `message`; empty when it already said so. */
+  readonly report: string | undefined;
+  constructor(message: string, exitCode?: number, report?: string);
 }
 /** A command line runset cannot read. */
 export declare class CliError extends RunsetError {}