runset 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Prokhorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# 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.
+
+```sh
+npm install --save-dev runset
+```
+
+Use `runset` in your npm scripts, or run it with `npx runset`:
+
+```sh
+npx runset lint test build              # one after another
+npx runset -p lint test                 # together
+npx runset clean -p lint test -s build  # clean, then lint + test, then build
+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.
+
+By default, a failed command stops the run. Ctrl+C stops all running commands
+and their child processes.
+
+## Commands
+
+Names are looked up in `package.json` scripts. Other commands run in the shell.
+Quote commands that contain spaces or patterns:
+
+```sh
+npx runset lint "node scripts/check.js"
+npx runset "build:*"    # build:api, build:web
+npx runset "build:**"   # also includes build:api:types
+```
+
+`*` matches one part of a script name between colons; `**` matches across
+colons. A pattern with no matches is skipped.
+
+Pass arguments to a script inside the quotes, or use placeholders for arguments
+after `--`:
+
+```sh
+npx runset "test --watch"
+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.
+
+## Options
+
+| 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                    |
+
+Use `--help` for all options.
+
+Add `::` to set options for one command:
+
+```sh
+npx runset -p "api::label=server,color=cyan" web
+npx runset "lint::on-failure=continue" build
+```
+
+`stop` ends the whole run. `continue` lets it carry on. `restart` runs the
+command again without a delay or retry limit.
+
+## 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.
+
+To keep each command's output together, use grouped output:
+
+```sh
+npx runset -p lint test -o grouped
+```
+
+Each command's output is buffered and printed when it exits.
+
+## Config
+
+Save a pipeline in `runset.config.ts`, then run `npx runset`:
+
+```ts
+import type { ConfigJs } from 'runset';
+
+export default {
+  commands: [
+    'clean',
+    { parallel: true },
+    'lint',
+    'test',
+    { serial: true },
+    'build',
+  ],
+} satisfies ConfigJs;
+```
+
+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:
+
+```ts
+import type { ConfigJs } from 'runset';
+
+export default {
+  commandDictionary: {
+    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.
+
+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.
+
+## Library
+
+```ts
+import runset from 'runset';
+
+await runset(['lint', 'test', 'build']);
+await runset({ commands: ['lint', 'test'], parallel: true, jobs: 2 });
+```
+
+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.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,243 @@
+//#region src/types.d.ts
+export type StdTiming = 'grouped' | 'realtime';
+/** How a command stream is handled. */
+export interface Std {
+  /** `stdout`, `stderr`, `none`, or a file path. */
+  destination: string;
+  timing: StdTiming;
+}
+export type ExitAction = 'continue' | 'restart' | 'stop';
+export declare const EXIT_ACTIONS: Set<ExitAction>;
+export type LogLevel = 'debug' | 'error' | 'info' | 'warn';
+/** 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. */
+export interface Command {
+  bgColor: string;
+  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. */
+  line: string;
+  onFailure: ExitAction;
+  onSuccess: ExitAction;
+  parallel: boolean;
+  /** The `package.json` script name, when `type` is `'npm'`. */
+  scriptName?: string;
+  /** Commands sharing a stage run together; stages run in order. */
+  stage: number;
+  stderr: Std;
+  stdout: Std;
+  type: 'npm' | 'shell';
+}
+export type LabelFormatter = (context: {
+  /** Whether runset is emitting ANSI color at all. */
+  color: boolean;
+  /** Its `label` is already padded. */
+  command: Command;
+  /** runset's own prefix, to decorate rather than replace. */
+  defaultPrefix: string;
+  stream: 'stderr' | 'stdout';
+}) => string;
+/** The parts of a {@link Command} a user may set by hand. */
+export type CommandOptions = {
+  stderr?: Partial<Std> | string;
+  stdout?: Partial<Std> | string;
+} & Partial<Omit<Command, 'line' | 'scriptName' | 'stage' | 'stderr' | 'stdout' | 'type'>>;
+/** One command written as an object; `command` is what makes it one. */
+export type CommandEntry = {
+  command: string;
+} & CommandOptions;
+/**
+ * Defaults for the entries after it — the config spelling of `-p`/`-s`:
+ * `commands: ['clean', { parallel: true }, 'lint', 'test']`.
+ */
+export type CommandSettings = {
+  serial?: boolean;
+} & Omit<CommandOptions, 'command'>;
+/** 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 {
+  color?: boolean;
+  /** Named commands, resolved before `package.json` scripts. An entry may be a list. */
+  commandDictionary?: Record<string, CommandDefinition | CommandDefinition[]>;
+  commands?: CommandDefinition[];
+  cwd?: string;
+  dryRun?: boolean;
+  /**
+   * Renders the prefix of each labelled output line.
+   *
+   * ```js
+   * formatLabel: ({ defaultPrefix }) => `${new Date().toISOString()} ${defaultPrefix}`,
+   * ```
+   */
+  formatLabel?: LabelFormatter;
+  /** Max commands running at once. Default: unlimited. */
+  jobs?: number;
+  /** Milliseconds from SIGTERM/SIGINT to SIGKILL; `0` for none. Default: 5000. */
+  killTimeout?: number;
+  /** Default: `'auto'`. */
+  labels?: LabelMode;
+  logLevel?: LogLevel;
+  /** What a non-zero exit does to the run. Default: `'stop'`. */
+  onFailure?: ExitAction;
+  /** What a clean exit does to the run. Default: `'continue'`. */
+  onSuccess?: ExitAction;
+  /** The default `parallel` for every command. Default: `false`. */
+  parallel?: boolean;
+  stderr?: Partial<Std> | string;
+  stdout?: Partial<Std> | string;
+}
+/** A config module may export the object itself or a sync factory for it. */
+export type ConfigJsExport = ((context: {
+  argv: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+}) => ConfigJs) | ConfigJs;
+export interface TerminateOptions {
+  /** Send SIGKILL. */
+  force?: boolean;
+  /** 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/config/parseCli.d.ts
+/** Run-wide options a CLI flag can set. */
+interface CliOptions {
+  color?: boolean;
+  config?: string;
+  cwd?: string;
+  dryRun?: boolean;
+  jobs?: number;
+  killTimeout?: number;
+  labels?: string;
+  logLevel?: string;
+  onFailure?: string;
+  onSuccess?: string;
+  output?: string;
+  stderr?: string;
+  stdout?: string;
+}
+interface ParsedCli {
+  /** The argv this is the parse of. */
+  argv: string[];
+  /** The tasks as written, with a settings entry where a `-p`/`-s` stood. */
+  commands: CommandDefinition[];
+  help: boolean;
+  options: CliOptions;
+  positional: string[];
+  version: boolean;
+}
+//#endregion
+//#region src/config/Config.d.ts
+/** The resolved run-wide configuration: CLI flag → config file → default. */
+declare class Config {
+  readonly commands: CommandDefinition[];
+  readonly commandDictionary: Record<string, CommandDefinition | CommandDefinition[]>;
+  /** Everything after `--`, for placeholders. */
+  readonly args: string[];
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+  readonly jobs: number;
+  readonly killTimeout: number;
+  readonly onSuccess: ExitAction;
+  readonly onFailure: ExitAction;
+  readonly color: boolean;
+  readonly parallel: boolean;
+  readonly labels: LabelMode;
+  readonly logLevel: LogLevel;
+  readonly dryRun: boolean;
+  readonly formatLabel: LabelFormatter | undefined;
+  readonly stdout: Std;
+  readonly stderr: Std;
+  readonly destinations: Destinations;
+  /** Printed by the run once it is built. */
+  readonly warnings: string[];
+  constructor({ cli, configJs, cwd, destinations, env }: ResolvedConfigOptions);
+  /** Throws on the first invalid value; types too, as config files are arbitrary JS. */
+  validate(): void;
+  /** True when `commands` holds something to run, not just settings entries. */
+  hasCommands(): boolean;
+}
+interface ResolvedConfigOptions {
+  /** Defaults to the process's own argv; a library caller passes `parseCli([])`. */
+  cli: ParsedCli;
+  /** Skips the config-file lookup; absent means "look for a file". */
+  configJs?: ConfigJsExport;
+  cwd: string;
+  /** Where the run writes; read for color autodetection. */
+  destinations: Destinations;
+  env: NodeJS.ProcessEnv;
+}
+//#endregion
+//#region src/utils/fs.d.ts
+interface PackageInfo {
+  filePath: string;
+  name: string;
+  scripts: Record<string, string>;
+  version: string;
+}
+//#endregion
+//#region src/plan/plan.d.ts
+interface Plan {
+  commands: Command[];
+  config: Config;
+  packageInfo: PackageInfo;
+}
+//#endregion
+//#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;
+  constructor({ commands, config, packageInfo }: Plan);
+  /** A library caller's config object, through the same pipeline as the CLI. */
+  static fromConfigJs(configJs: ConfigJs): Run;
+  isFailed(): boolean;
+  getExitCode(): number;
+  /** The resolved run, and every option in force, as `--dry-run` prints it. */
+  describe(): string;
+  /** Rejects with a {@link RunsetError} when the run did not succeed. */
+  start(): Promise<Run>;
+  terminate(options?: TerminateOptions): void;
+  private failed;
+  /** Says a signal arrived before any command's parting words, then stops. */
+  private onSignal;
+  private stopEverything;
+  private forceKill;
+  private clearKillTimer;
+}
+//#endregion
+//#region src/utils/errors.d.ts
+/** 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);
+}
+/** A command line runset cannot read. */
+export declare class CliError extends RunsetError {}
+/** A run-wide option or config file runset cannot use. */
+export declare class ConfigError extends RunsetError {}
+/** A command that cannot be resolved. */
+export declare class NormalizeError extends RunsetError {}
+//#endregion
+//#region src/index.d.ts
+/** Runs commands, or a whole config object, and resolves once they are done. */
+export declare function runset(config: ConfigJs): Promise<Run>;
+export declare function runset(commands: CommandDefinition | CommandDefinition[], configJs?: ConfigJs): Promise<Run>;
+//#endregion
+export { runset as default };