runset 0.0.1 → 0.0.3

package/README.md

@@ -1,10 +1,25 @@
 # 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.
+[![Tests](https://github.com/megahertz/runset/actions/workflows/tests.yml/badge.svg)](https://github.com/megahertz/runset/actions/workflows/tests.yml)
+[![NPM version](https://badge.fury.io/js/runset.svg)](https://badge.fury.io/js/runset)
+
+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**
+
+<p align="center">
+  <img src="docs/screenshot.png" alt="runset output: realtime on the left, grouped on the right">
+  <br>
+  <sub>Realtime output (default) on the left, grouped (<code>-o grouped</code>) on the right</sub>
+</p>
 
 ```sh
 npm install --save-dev runset
@@ -214,21 +229,21 @@ to the commands that follow them.
 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 `commandDictionary` to give a command or pipeline a reusable name:
+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`
@@ -248,9 +263,8 @@ Config modules can also export a synchronous function receiving
 `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 `commandDictionary`, `npx runset -p api web`
-runs both builds, then both tests. Both builds must finish before either test
-starts.
+`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
 

package/dist/index.d.mts

@@ -7,7 +7,6 @@ export interface Std {
   timing: StdTiming;
 }
 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,
@@ -23,7 +22,6 @@ export interface Command {
   color: string;
   command: string;
   cwd: string;
-  disabled: boolean;
   env: NodeJS.ProcessEnv;
   label: string;
   /** What is handed to the shell: for an npm command, the script's body. */
@@ -32,9 +30,6 @@ export interface Command {
   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. */
@@ -52,13 +47,26 @@ export type LabelFormatter = (context: {
   defaultPrefix: string;
   stream: 'stderr' | 'stdout';
 }) => string;
-/** The parts of a {@link Command} a user may set by hand. */
-export type CommandOptions = {
+/** What a user may set about a command, by hand. */
+export interface CommandOptions {
+  bgColor?: string;
+  color?: string;
+  cwd?: string;
+  /** Leave the command out of the run. */
+  disabled?: boolean;
+  env?: NodeJS.ProcessEnv;
+  label?: string;
+  onFailure?: ExitAction;
+  onSuccess?: ExitAction;
   /** Both streams at once; `stdout` / `stderr` in the same place outrank it. */
   output?: Partial<Std> | string;
+  /** Join the group of commands beside it rather than open a stage of its own. */
+  parallel?: boolean;
+  /** Run an npm script in every workspace package that has it. */
+  recursive?: boolean;
   stderr?: Partial<Std> | string;
   stdout?: Partial<Std> | string;
-} & 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;
@@ -69,15 +77,13 @@ export type CommandEntry = {
  */
 export type CommandSettings = {
   serial?: boolean;
-} & Omit<CommandOptions, 'command'>;
+} & CommandOptions;
 /** A command before normalization; falsy entries are skipped. */
 export type CommandDefinition = CommandEntry | CommandSettings | false | null | string | undefined;
 /** What a user writes in `runset.config.*`, or hands to `runset({ … })`. */
 export interface ConfigJs {
   /** Default: `'auto'`. */
   color?: ColorMode;
-  /** Named commands, resolved before `package.json` scripts. An entry may be a list. */
-  commandDictionary?: Record<string, CommandDefinition | CommandDefinition[]>;
   commands?: CommandDefinition[];
   cwd?: string;
   dryRun?: boolean;
@@ -107,6 +113,8 @@ export interface ConfigJs {
   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`. */
@@ -128,14 +136,6 @@ export interface TerminateOptions {
   /** Default: SIGTERM. Ignored under `force`. */
   signal?: NodeJS.Signals;
 }
-/** Where a run writes. */
-export interface Destinations {
-  stderr: NodeJS.WritableStream;
-  stdout: NodeJS.WritableStream;
-}
-/** True for an object written without a `command` — a settings entry. */
-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. */
@@ -144,17 +144,17 @@ type ColorLevel = Exclude<ColorMode, 'auto'>;
 //#region src/config/parseCli.d.ts
 /** Run-wide options a CLI flag can set. */
 interface CliOptions {
-  color?: string;
+  color?: ColorMode;
   config?: string;
   cwd?: string;
   dryRun?: boolean;
   env?: Record<string, string>;
   jobs?: number;
   killTimeout?: number;
-  labels?: string;
-  logLevel?: string;
-  onFailure?: string;
-  onSuccess?: string;
+  labels?: LabelMode;
+  logLevel?: LogLevel;
+  onFailure?: ExitAction;
+  onSuccess?: ExitAction;
   output?: string;
   recursive?: boolean;
   showCommand?: boolean;
@@ -178,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;
@@ -210,6 +210,11 @@ declare class Config {
   /** True when `commands` holds something to run, not just settings entries. */
   hasCommands(): boolean;
 }
+/** Where a run writes. */
+interface Destinations {
+  stderr: NodeJS.WritableStream;
+  stdout: NodeJS.WritableStream;
+}
 interface ResolvedConfigOptions {
   /** Defaults to the process's own argv; a library caller passes `parseCli([])`. */
   cli: ParsedCli;
@@ -239,7 +244,6 @@ interface Plan {
 //#region src/run/Run.d.ts
 /** One run: the processes built from a plan, and what stops them. */
 export declare class Run {
-  readonly config: Config;
   private readonly logger;
   private readonly files;
   private stopping;
@@ -269,8 +273,6 @@ 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;
-  /** 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. */