runset 0.0.0

package/dist/index.mjs

@@ -0,0 +1,1665 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { inspect, styleText } from "node:util";
+import cp from "node:child_process";
+//#region src/types.ts
+const EXIT_ACTIONS = /* @__PURE__ */ new Set([
+	"continue",
+	"restart",
+	"stop"
+]);
+/** True for an object written without a `command` — a settings entry. */
+function isCommandSettings(definition) {
+	return !("command" in definition);
+}
+function isStreamDestination(destination) {
+	return destination === "stdout" || destination === "stderr";
+}
+//#endregion
+//#region src/utils/errors.ts
+/** Any failure runset reports itself; `exitCode` is what the CLI exits with. */
+var RunsetError = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1) {
+		super(message);
+		this.name = new.target.name;
+		this.exitCode = exitCode;
+	}
+};
+/** A command line runset cannot read. */
+var CliError = class extends RunsetError {};
+/** A run-wide option or config file runset cannot use. */
+var ConfigError = class extends RunsetError {};
+/** A command that cannot be resolved. */
+var NormalizeError = class extends RunsetError {};
+//#endregion
+//#region src/utils/fs.ts
+const require = createRequire(import.meta.url);
+/** The sync counterpart of `import()`: CJS, JSON, and ESM/TS via `require(esm)`. */
+function importSync(modulePath) {
+	return require(modulePath);
+}
+/** The nearest `package.json` at or above `cwd`. */
+function readPackageJson(cwd) {
+	for (const dir of ancestors(cwd)) {
+		const filePath = path.join(dir, "package.json");
+		if (!fs.existsSync(filePath)) continue;
+		const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		return {
+			filePath,
+			name: raw.name ?? "",
+			scripts: raw.scripts ?? {},
+			version: raw.version ?? ""
+		};
+	}
+	return {
+		filePath: "",
+		name: "",
+		scripts: {},
+		version: ""
+	};
+}
+//#endregion
+//#region src/config/loadConfig.ts
+/**
+* Loads `runset.config.*` — the `explicitPath`, or the first one found walking
+* up from `cwd` — and unwraps a default export or a factory function.
+*/
+function loadConfigJs({ argv, cwd, env, explicitPath }) {
+	const filePath = explicitPath === void 0 ? findConfigFile(cwd) : path.resolve(cwd, explicitPath);
+	if (filePath === void 0) return {};
+	if (!fs.existsSync(filePath)) throw new ConfigError(`Config file not found: ${explicitPath}`);
+	return unwrapConfigJs(importSync(filePath), {
+		argv,
+		cwd,
+		env
+	});
+}
+function unwrapConfigJs(source, context) {
+	const unwrapped = source.default ?? source;
+	return typeof unwrapped === "function" ? unwrapped(context) : unwrapped;
+}
+/** `dir` and every directory above it, up to the root. */
+function ancestors(dir) {
+	const dirs = [path.resolve(dir)];
+	for (;;) {
+		const current = dirs.at(-1);
+		const parent = path.dirname(current);
+		if (parent === current) return dirs;
+		dirs.push(parent);
+	}
+}
+function findConfigFile(cwd) {
+	for (const dir of ancestors(cwd)) for (const extension of [
+		"ts",
+		"js",
+		"mjs",
+		"cjs",
+		"json"
+	]) {
+		const candidate = path.join(dir, `runset.config.${extension}`);
+		if (fs.existsSync(candidate)) return candidate;
+	}
+}
+//#endregion
+//#region src/utils/string.ts
+function toCamelCase(name) {
+	return name.replaceAll(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function toKebabCase(name) {
+	return name.replaceAll(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+//#endregion
+//#region src/config/winArgv.ts
+/**
+* Windows only: rejoins `'single quoted'` tokens that `cmd.exe` leaves split,
+* joined by single spaces. The identity everywhere else.
+*/
+function regroupQuoted(argv, platform = process.platform) {
+	if (platform !== "win32") return argv;
+	const result = [];
+	let open;
+	for (const token of argv) {
+		if (open === void 0) {
+			if (token.startsWith("'") && token.endsWith("'") && token.length > 1) result.push(token.slice(1, -1));
+			else if (token.startsWith("'")) open = [token.slice(1)];
+			else result.push(token);
+			continue;
+		}
+		if (token.endsWith("'")) {
+			open.push(token.slice(0, -1));
+			result.push(open.join(" "));
+			open = void 0;
+		} else open.push(token);
+	}
+	if (open !== void 0) throw new CliError(`Unterminated quote in "'${open.join(" ")}".`);
+	return result;
+}
+//#endregion
+//#region src/config/parseCli.ts
+const FLAGS = [
+	{
+		name: "parallel",
+		short: "p",
+		takesValue: false
+	},
+	{
+		name: "serial",
+		short: "s",
+		takesValue: false
+	},
+	{
+		name: "jobs",
+		short: "j",
+		takesValue: true
+	},
+	{
+		name: "killTimeout",
+		takesValue: true
+	},
+	{
+		name: "onSuccess",
+		takesValue: true
+	},
+	{
+		name: "onFailure",
+		takesValue: true
+	},
+	{
+		name: "config",
+		short: "c",
+		takesValue: true
+	},
+	{
+		name: "cwd",
+		takesValue: true
+	},
+	{
+		name: "color",
+		takesValue: false
+	},
+	{
+		name: "logLevel",
+		takesValue: true
+	},
+	{
+		name: "dryRun",
+		takesValue: false
+	},
+	{
+		name: "stdout",
+		takesValue: true
+	},
+	{
+		name: "stderr",
+		takesValue: true
+	},
+	{
+		name: "output",
+		short: "o",
+		takesValue: true
+	},
+	{
+		name: "labels",
+		takesValue: true
+	},
+	{
+		name: "help",
+		short: "h",
+		takesValue: false
+	},
+	{
+		name: "version",
+		short: "v",
+		takesValue: false
+	}
+];
+/**
+* Splits argv into options, commands, and the literal arguments after `--`.
+* Each `-p`/`-s` becomes a settings entry where it was typed, the same object
+* a config file would write.
+*/
+function parseCli(rawArgv) {
+	const argv = regroupQuoted(rawArgv);
+	const options = {};
+	const commands = [];
+	const positional = [];
+	let help = false;
+	let version = false;
+	let afterDoubleDash = false;
+	let cursor = 0;
+	function setOption(spec, raw) {
+		switch (spec.name) {
+			case "help":
+				help = true;
+				break;
+			case "jobs":
+			case "killTimeout":
+				options[spec.name] = Number(raw);
+				break;
+			case "parallel":
+			case "serial":
+				commands.push({ parallel: spec.name === "parallel" });
+				break;
+			case "version":
+				version = true;
+				break;
+			default: if (typeof raw === "boolean") options[spec.name] = raw;
+			else options[spec.name] = raw;
+		}
+	}
+	function takeValue(label) {
+		const value = argv[cursor + 1];
+		if (value === void 0) throw new CliError(`Option "${label}" needs a value.`);
+		cursor += 1;
+		return value;
+	}
+	function readLong(body) {
+		const eq = body.indexOf("=");
+		const name = eq === -1 ? body : body.slice(0, eq);
+		const inlineValue = eq === -1 ? void 0 : body.slice(eq + 1);
+		const flag = findLongFlag(name);
+		if (flag === void 0 && /^no-?[A-Za-z]/.test(name)) {
+			const negated = findLongFlag(name.replace(/^no-?/, ""));
+			if (negated && !negated.takesValue) {
+				setOption(negated, false);
+				return;
+			}
+		}
+		if (flag === void 0) throw new CliError(`Unknown option "--${name}".`);
+		if (flag.takesValue) setOption(flag, inlineValue ?? takeValue(`--${name}`));
+		else setOption(flag, true);
+	}
+	function readShortCluster(body) {
+		for (let position = 0; position < body.length; position += 1) {
+			const letter = body[position];
+			const flag = findShortFlag(letter);
+			if (flag === void 0) throw new CliError(`Unknown option "-${letter}".`);
+			if (!flag.takesValue) {
+				setOption(flag, true);
+				continue;
+			}
+			const rest = body.slice(position + 1);
+			setOption(flag, rest === "" ? takeValue(`-${letter}`) : rest);
+			return;
+		}
+	}
+	for (; cursor < argv.length; cursor += 1) {
+		const token = argv[cursor];
+		if (afterDoubleDash) positional.push(token);
+		else if (token === "--") afterDoubleDash = true;
+		else if (token.startsWith("--") && token.length > 2) readLong(token.slice(2));
+		else if (token.startsWith("-") && token.length > 1) readShortCluster(token.slice(1));
+		else commands.push(token);
+	}
+	return {
+		argv,
+		commands,
+		help,
+		options,
+		positional,
+		version
+	};
+}
+function findLongFlag(name) {
+	const camel = toCamelCase(name);
+	return FLAGS.find((flag) => flag.name === camel);
+}
+function findShortFlag(letter) {
+	return FLAGS.find((flag) => flag.short === letter);
+}
+//#endregion
+//#region src/config/std.ts
+const TIMINGS = /* @__PURE__ */ new Set(["realtime", "grouped"]);
+/**
+* Parses `<timing>+<destination>` (either order, either optional) into the
+* axes it names. Unnamed axes are left out so settings can be layered.
+*/
+function parsePartialStd(value) {
+	const result = {};
+	for (const part of value.split("+")) {
+		const token = part.trim();
+		if (token === "") continue;
+		if (TIMINGS.has(token)) result.timing = token;
+		else result.destination = token;
+	}
+	return result;
+}
+function toPartialStd(value) {
+	return typeof value === "string" ? parsePartialStd(value) : value;
+}
+/** Layers a stream setting, in either form, over `base` one axis at a time. */
+function mergeStd(base, value) {
+	return value === void 0 ? base : {
+		...base,
+		...toPartialStd(value)
+	};
+}
+function defaultStd(destination) {
+	return {
+		destination,
+		timing: "realtime"
+	};
+}
+//#endregion
+//#region src/config/validate.ts
+function formatValue(value) {
+	return typeof value === "string" ? `"${value}"` : String(value);
+}
+function numberError(name, value, minimum) {
+	if (typeof value !== "number" || Number.isNaN(value) || value < minimum) return `${name} must be a number of ${minimum} or more, got ${formatValue(value)}.`;
+}
+function booleanError(name, value) {
+	return typeof value === "boolean" ? void 0 : `${name} must be true or false, got ${formatValue(value)}.`;
+}
+function stringError(name, value) {
+	return typeof value === "string" ? void 0 : `${name} must be a string, got ${formatValue(value)}.`;
+}
+function oneOfError(name, value, allowed) {
+	return allowed.has(value) ? void 0 : `${name} is one of ${[...allowed].join(", ")}, got ${formatValue(value)}.`;
+}
+function actionError(name, value) {
+	return oneOfError(name, value, EXIT_ACTIONS);
+}
+function stdError(name, value) {
+	if (typeof value !== "object" || value === null) return `${name} must be a stream setting.`;
+	if (!TIMINGS.has(value.timing)) return `Invalid timing ${formatValue(value.timing)} for ${name}; one of ${[...TIMINGS].join(", ")}.`;
+	if (typeof value.destination !== "string" || value.destination === "") return `${name} needs a destination to write to.`;
+}
+/** Throws `message` as an `ErrorClass`, if there is one. */
+function check(message, ErrorClass) {
+	if (message !== void 0) throw new ErrorClass(message);
+}
+//#endregion
+//#region src/config/Config.ts
+const DEFAULT_KILL_TIMEOUT = 5e3;
+const LOG_LEVELS = /* @__PURE__ */ new Set([
+	"error",
+	"warn",
+	"info",
+	"debug"
+]);
+const LABEL_MODES = /* @__PURE__ */ new Set([
+	"none",
+	"auto",
+	"custom",
+	"all"
+]);
+const KNOWN_KEYS = /* @__PURE__ */ new Set([
+	"color",
+	"commandDictionary",
+	"commands",
+	"cwd",
+	"dryRun",
+	"formatLabel",
+	"jobs",
+	"killTimeout",
+	"labels",
+	"logLevel",
+	"onFailure",
+	"onSuccess",
+	"parallel",
+	"stderr",
+	"stdout"
+]);
+/** Parses, loads and validates; anything left out comes from the process. */
+function createConfig({ cli = parseCli(process.argv.slice(2)), configJs, cwd = process.cwd(), destinations = process, env = process.env } = {}) {
+	const config = new Config({
+		cli,
+		configJs,
+		cwd,
+		destinations,
+		env
+	});
+	config.validate();
+	return config;
+}
+/** The resolved run-wide configuration: CLI flag → config file → default. */
+var Config = class {
+	commands;
+	commandDictionary;
+	/** Everything after `--`, for placeholders. */
+	args;
+	cwd;
+	env;
+	jobs;
+	killTimeout;
+	onSuccess;
+	onFailure;
+	color;
+	parallel;
+	labels;
+	logLevel;
+	dryRun;
+	formatLabel;
+	stdout;
+	stderr;
+	destinations;
+	/** Printed by the run once it is built. */
+	warnings = [];
+	constructor({ cli, configJs, cwd, destinations, env }) {
+		const { options } = cli;
+		this.cwd = path.resolve(cwd, options.cwd ?? ".");
+		this.destinations = destinations;
+		this.env = env;
+		const context = {
+			argv: cli.argv,
+			cwd: this.cwd,
+			env
+		};
+		const file = configJs === void 0 ? loadConfigJs({
+			...context,
+			explicitPath: options.config
+		}) : unwrapConfigJs(configJs, context);
+		for (const key of Object.keys(file)) if (!KNOWN_KEYS.has(key)) this.warnings.push(`Unknown config key "${key}" was ignored.`);
+		if (file.cwd !== void 0 && options.cwd === void 0) this.cwd = path.resolve(cwd, file.cwd);
+		this.commands = [...file.commands ?? [], ...cli.commands].filter(Boolean);
+		this.commandDictionary = file.commandDictionary ?? {};
+		this.args = cli.positional;
+		this.jobs = options.jobs ?? file.jobs ?? Number.POSITIVE_INFINITY;
+		this.killTimeout = options.killTimeout ?? file.killTimeout ?? DEFAULT_KILL_TIMEOUT;
+		this.parallel = file.parallel ?? false;
+		this.labels = options.labels ?? file.labels ?? "auto";
+		this.onSuccess = options.onSuccess ?? file.onSuccess ?? "continue";
+		this.onFailure = options.onFailure ?? file.onFailure ?? "stop";
+		this.dryRun = options.dryRun ?? file.dryRun ?? false;
+		this.logLevel = options.logLevel ?? file.logLevel ?? "info";
+		this.color = resolveColor(options.color ?? file.color, env, destinations);
+		this.formatLabel = file.formatLabel;
+		const std = (stream) => mergeStd(mergeStd(defaultStd(stream), file[stream] ?? options.output), options[stream] ?? options.output);
+		this.stdout = std("stdout");
+		this.stderr = std("stderr");
+	}
+	/** Throws on the first invalid value; types too, as config files are arbitrary JS. */
+	validate() {
+		check([
+			oneOfError("logLevel", this.logLevel, LOG_LEVELS),
+			numberError("jobs", this.jobs, 1),
+			numberError("killTimeout", this.killTimeout, 0),
+			booleanError("color", this.color),
+			booleanError("parallel", this.parallel),
+			booleanError("dryRun", this.dryRun),
+			oneOfError("labels", this.labels, LABEL_MODES),
+			stdError("stdout", this.stdout),
+			stdError("stderr", this.stderr),
+			this.formatLabel !== void 0 && typeof this.formatLabel !== "function" ? "formatLabel must be a function." : void 0,
+			typeof this.commandDictionary !== "object" || this.commandDictionary === null || Array.isArray(this.commandDictionary) ? "commandDictionary must be an object." : void 0,
+			actionError("onSuccess", this.onSuccess),
+			actionError("onFailure", this.onFailure)
+		].find((error) => error !== void 0), ConfigError);
+	}
+	/** True when `commands` holds something to run, not just settings entries. */
+	hasCommands() {
+		return this.commands.some((command) => typeof command === "object" && command !== null ? !isCommandSettings(command) : Boolean(command));
+	}
+};
+function isTerminal(stream) {
+	return stream.isTTY === true;
+}
+/** Flag, then `NO_COLOR`/`FORCE_COLOR`, then whether both streams are TTYs. */
+function resolveColor(flag, env, destinations) {
+	if (flag !== void 0) return flag;
+	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0") return true;
+	return isTerminal(destinations.stdout) && isTerminal(destinations.stderr);
+}
+//#endregion
+//#region src/plan/stages.ts
+const EMPTY_SEGMENT = {
+	commands: [],
+	parallel: false
+};
+/** A `-p`/`-s`: what follows starts a new group past everything before it. */
+const BOUNDARY = {
+	boundary: true,
+	commands: [],
+	parallel: false
+};
+/**
+* Lays segments out into stages. A parallel segment joins the open stage;
+* anything else starts past every stage in use, and so does what follows it.
+* A segment's commands keep their relative stages, shifted onto its own.
+*/
+function link(segments) {
+	const commands = [];
+	/** The stage a parallel segment joins. */
+	let open = 0;
+	/** The last stage in use; -1 while none is. */
+	let used = -1;
+	for (const segment of segments) {
+		if (segment.boundary) {
+			open = used + 1;
+			continue;
+		}
+		if (segment.commands.length === 0) continue;
+		const base = segment.parallel ? open : used + 1;
+		for (const command of segment.commands) {
+			command.stage += base;
+			used = Math.max(used, command.stage);
+			commands.push(command);
+		}
+		open = segment.parallel ? open : used + 1;
+	}
+	return commands;
+}
+/** Splits a stage-sorted list into its stages. */
+function groupByStage(items, stageOf) {
+	const stages = [];
+	let current;
+	let stage;
+	for (const item of items) {
+		const own = stageOf(item);
+		if (current === void 0 || own !== stage) {
+			current = [];
+			stage = own;
+			stages.push(current);
+		}
+		current.push(item);
+	}
+	return stages;
+}
+//#endregion
+//#region src/plan/labels.ts
+const PALETTE = [
+	{
+		bgColor: "bgGreen",
+		color: "black"
+	},
+	{
+		bgColor: "bgBlue",
+		color: "white"
+	},
+	{
+		bgColor: "bgMagenta",
+		color: "white"
+	},
+	{
+		bgColor: "bgCyan",
+		color: "black"
+	},
+	{
+		bgColor: "bgYellow",
+		color: "black"
+	},
+	{
+		bgColor: "bgRed",
+		color: "white"
+	},
+	{
+		bgColor: "bgGray",
+		color: "white"
+	},
+	{
+		bgColor: "bgGreenBright",
+		color: "black"
+	},
+	{
+		bgColor: "bgBlueBright",
+		color: "black"
+	},
+	{
+		bgColor: "bgMagentaBright",
+		color: "black"
+	},
+	{
+		bgColor: "bgCyanBright",
+		color: "black"
+	},
+	{
+		bgColor: "bgYellowBright",
+		color: "black"
+	}
+];
+/**
+* Settles who is labelled, per `config.labels`. Under `auto`, a command
+* sharing a stage is named after itself — or gets a blank label holding the
+* column when someone in its stage has a label of their own.
+*/
+function assignAutoLabels({ commands, config }) {
+	const mode = config.labels;
+	if (mode === "none") {
+		for (const command of commands) command.label = "";
+		return;
+	}
+	const named = [];
+	for (const stage of groupByStage(commands, (command) => command.stage)) {
+		const shared = stage.length > 1;
+		const labeled = stage.some((command) => command.label !== "");
+		for (const command of stage) {
+			if (command.label !== "") continue;
+			if (mode === "all" || mode === "auto" && shared && !labeled) {
+				command.label = nameOf(command);
+				named.push(command);
+			} else if (shared && labeled) command.label = " ";
+		}
+	}
+	numberRepeats(named);
+}
+/**
+* Gives each labelled command without colors of its own a palette pair: the
+* one its label hashes to, or the next free when that is taken.
+*/
+function colorLabels({ commands }) {
+	const labeled = commands.filter((command) => command.label !== "");
+	const taken = new Set(labeled.map((command) => PALETTE.findIndex((pair) => pair.bgColor === command.bgColor)).filter((index) => index !== -1));
+	for (const command of labeled) {
+		if (command.color !== "" || command.bgColor !== "" || command.label.trim() === "") continue;
+		const index = claim(paletteIndex(command.label), taken);
+		taken.add(index);
+		const pair = PALETTE[index];
+		command.bgColor = pair.bgColor;
+		command.color = pair.color;
+	}
+}
+/** Pads every label to the widest one. */
+function alignLabels({ commands }) {
+	const labeled = commands.filter((command) => command.label !== "");
+	const width = Math.max(0, ...labeled.map((command) => command.label.length));
+	for (const command of labeled) command.label = command.label.padEnd(width);
+}
+/** A stable palette index for a label. */
+function paletteIndex(label) {
+	/** The largest modulus that keeps `hash * 31 + code` an exact integer. */
+	const HASH_MODULUS = 2147483647;
+	let hash = 0;
+	for (const character of label) hash = (hash * 31 + (character.codePointAt(0) ?? 0)) % HASH_MODULUS;
+	return hash % PALETTE.length;
+}
+/** The script name, or the program a shell command runs. */
+function nameOf(command) {
+	return command.scriptName ?? command.command.split(/\s/, 1)[0] ?? "";
+}
+/** `serve`, `serve` → `serve#1`, `serve#2`. */
+function numberRepeats(named) {
+	const totals = /* @__PURE__ */ new Map();
+	for (const command of named) totals.set(command.label, (totals.get(command.label) ?? 0) + 1);
+	const counters = /* @__PURE__ */ new Map();
+	for (const command of named) {
+		if ((totals.get(command.label) ?? 0) < 2) continue;
+		const index = (counters.get(command.label) ?? 0) + 1;
+		counters.set(command.label, index);
+		command.label = `${command.label}#${index}`;
+	}
+}
+function claim(preferred, taken) {
+	if (taken.size >= PALETTE.length) return preferred;
+	let index = preferred;
+	while (taken.has(index)) index = (index + 1) % PALETTE.length;
+	return index;
+}
+//#endregion
+//#region src/utils/glob.ts
+function isGlob(pattern) {
+	return pattern.includes("*");
+}
+/** The `names` a glob matches, in declared order; none is not an error. */
+function matchGlob(pattern, names) {
+	const regexp = toRegExp(pattern);
+	return names.filter((name) => regexp.test(name));
+}
+function escape(literal) {
+	return literal.replaceAll(/[$()+.?[\\\]^{|}]/g, String.raw`\$&`);
+}
+/**
+* `*` matches within one `:`-separated segment, `**` spans one or more.
+* `build:**:*` means `build:**`.
+*/
+function toRegExp(pattern) {
+	const segments = pattern.split(":");
+	const source = [];
+	for (const [index, segment] of segments.entries()) {
+		if (segment === "*" && segments[index - 1] === "**") continue;
+		if (segment === "**") source.push(String.raw`[^:]+(?::[^:]+)*`);
+		else source.push(segment.split("*").map((part) => escape(part)).join("[^:]*"));
+	}
+	return new RegExp(`^${source.join(":")}$`);
+}
+//#endregion
+//#region src/utils/os.ts
+/** 128 + the signal's number, the way a shell reports it: 130, 143, … */
+function signalExitCode(signal) {
+	return 128 + (os.constants.signals[signal] ?? 15);
+}
+/**
+* Quotes a value so the platform's shell passes it on as literal text —
+* double quotes are not enough, since `$(…)` still runs inside them.
+*/
+function quoteForShell(value, platform = process.platform) {
+	return platform === "win32" ? quoteForCmd(value) : quoteForPosix(value);
+}
+/** Single quotes are fully literal; each `'` inside closes, escapes, reopens. */
+function quoteForPosix(value) {
+	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}
+/**
+* Quoted for the C runtime first, then every `cmd.exe` metacharacter
+* `^`-escaped (see <https://qntm.org/cmd>). Newlines cannot survive `cmd.exe`,
+* so they become spaces.
+*/
+function quoteForCmd(value) {
+	return `"${value.replaceAll("\r\n", " ").replaceAll(/[\n\r]/g, " ").replaceAll(/(\\*)"/g, String.raw`$1$1\"`).replace(/(\\*)$/, "$1$1")}"`.replaceAll(/["%&()<>^|]/g, (character) => `^${character}`);
+}
+//#endregion
+//#region src/plan/placeholders.ts
+/**
+* Fills `{1}`, `{@}`, `{*}` and `{name}` from the arguments after `--`.
+*
+* In a command line values are shell-quoted and unknown names left as written
+* (`${HOME}`); in an option (`forOption`) values are raw and unknown names
+* are empty, so `disabled={noTest}` is false when nothing was passed.
+*/
+function substitutePlaceholders(text, args, forOption = false) {
+	const PLACEHOLDER = /\{([^\s{}]*)\}/g;
+	const wrap = forOption ? (value) => value : quoteForShell;
+	return text.replaceAll(PLACEHOLDER, (match, key) => {
+		if (key === "@") return args.map((arg) => wrap(arg)).join(" ");
+		if (key === "*") return args.length === 0 ? "" : wrap(args.join(" "));
+		if (/^[1-9]\d*$/.test(key)) {
+			const value = args[Number(key) - 1];
+			return value === void 0 ? "" : wrap(value);
+		}
+		const named = namedValue(key, args);
+		if (named !== void 0) return wrap(named);
+		return forOption ? "" : match;
+	});
+}
+/**
+* The value of `--name=value` or `--name value` (camel or kebab); a bare
+* `--name` is `'true'`.
+*/
+function namedValue(key, args) {
+	for (const [index, token] of args.entries()) {
+		if (!token.startsWith("--") || token.length === 2) continue;
+		const equals = token.indexOf("=");
+		if (toCamelCase(equals === -1 ? token.slice(2) : token.slice(2, equals)) !== key) continue;
+		if (equals !== -1) return token.slice(equals + 1);
+		const next = args[index + 1];
+		return next !== void 0 && !next.startsWith("-") ? next : "true";
+	}
+}
+//#endregion
+//#region src/plan/token.ts
+const BOOLEAN_OPTIONS = /* @__PURE__ */ new Set(["disabled", "parallel"]);
+const ACTION_OPTIONS = /* @__PURE__ */ new Set(["onFailure", "onSuccess"]);
+/** Keys a `::` suffix may set. */
+const INLINE_OPTIONS = /* @__PURE__ */ new Set([
+	"bgColor",
+	"color",
+	"cwd",
+	"label",
+	"stderr",
+	"stdout",
+	...BOOLEAN_OPTIONS,
+	...ACTION_OPTIONS
+]);
+/**
+* Splits `"name args::options"` at the last `::`. The options run to the end
+* of the string, so a trailing space stays part of the last value.
+*/
+function splitToken(raw) {
+	const trimmed = raw.trimStart();
+	const marker = trimmed.lastIndexOf("::");
+	const command = (marker === -1 ? trimmed : trimmed.slice(0, marker)).trim();
+	const space = command.search(/\s/);
+	return {
+		args: space === -1 ? "" : command.slice(space + 1).trim(),
+		name: space === -1 ? command : command.slice(0, space),
+		options: marker === -1 ? "" : trimmed.slice(marker + 2)
+	};
+}
+/**
+* Parses `key=value,flag`. Split before placeholders are filled, so a `,` or
+* `=` arriving in a value cannot inject another option.
+*/
+function parseInlineOptions(text, args) {
+	const options = {};
+	for (const entry of text.split(",")) {
+		if (entry.trim() === "") continue;
+		const eq = entry.indexOf("=");
+		const key = toCamelCase((eq === -1 ? entry : entry.slice(0, eq)).trim());
+		const written = eq === -1 ? "true" : entry.slice(eq + 1);
+		const value = substitutePlaceholders(key === "label" ? written : written.trim(), args, true);
+		if (!INLINE_OPTIONS.has(key)) throw new NormalizeError(`Unknown command option "${toKebabCase(key)}" in "::${text.trim()}".`);
+		if (key === "stderr" || key === "stdout") options[key] = parsePartialStd(value);
+		else if (BOOLEAN_OPTIONS.has(key)) options[key] = value !== "false" && value !== "";
+		else if (ACTION_OPTIONS.has(key)) {
+			check(actionError(`"${toKebabCase(key)}"`, value), NormalizeError);
+			options[key] = value;
+		} else options[key] = value;
+	}
+	return options;
+}
+//#endregion
+//#region src/plan/normalize.ts
+/** Keys a settings entry may set. */
+const SETTINGS_OPTIONS = /* @__PURE__ */ new Set([
+	...INLINE_OPTIONS,
+	"env",
+	"serial"
+]);
+/**
+* Turns `config.commands` into the run's commands: flat, validated, numbered
+* by stage and sorted by it.
+*/
+function normalize(config, packageInfo) {
+	const scriptNames = Object.keys(packageInfo.scripts);
+	const packageRoot = packageInfo.filePath === "" ? config.cwd : path.dirname(packageInfo.filePath);
+	const defaults = {
+		bgColor: "",
+		color: "",
+		command: "",
+		cwd: config.cwd,
+		disabled: false,
+		env: {},
+		label: "",
+		line: "",
+		onFailure: config.onFailure,
+		onSuccess: config.onSuccess,
+		parallel: config.parallel,
+		stage: 0,
+		stderr: config.stderr,
+		stdout: config.stdout,
+		type: "shell"
+	};
+	function makeLeaf(token, rawOptions, script) {
+		const options = {
+			...rawOptions,
+			stderr: mergeStd(defaults.stderr, rawOptions.stderr),
+			stdout: mergeStd(defaults.stdout, rawOptions.stdout)
+		};
+		const args = substitutePlaceholders(token.args, config.args);
+		const command = [token.name, args].filter((part) => part !== "").join(" ");
+		const line = script === void 0 ? command : [packageInfo.scripts[script], args].filter((part) => part !== "").join(" ");
+		const leaf = {
+			...defaults,
+			...options,
+			command,
+			line,
+			stage: 0,
+			type: script === void 0 ? "shell" : "npm",
+			...script === void 0 ? {} : { scriptName: script }
+		};
+		if (script !== void 0 && options.cwd === void 0) leaf.cwd = packageRoot;
+		validateCommand(leaf);
+		return leaf;
+	}
+	/** Links one token's commands (e.g. glob matches) by their own `parallel`. */
+	function toSegment(leaves, settled) {
+		return {
+			commands: link(leaves.filter((leaf) => !leaf.disabled).map((leaf) => ({
+				commands: [leaf],
+				parallel: leaf.parallel
+			}))),
+			parallel: settled.parallel ?? defaults.parallel
+		};
+	}
+	function resolveToken(raw, inherited, overrides, seen) {
+		const token = splitToken(raw);
+		const inline = resolveCwd(parseInlineOptions(token.options, config.args), inherited.cwd ?? config.cwd);
+		if (Object.hasOwn(config.commandDictionary, token.name)) {
+			if (seen.has(token.name)) throw new NormalizeError(`Command "${token.name}" refers to itself.`);
+			const resolved = resolveEntry(config.commandDictionary[token.name], inherited, layer(inline, overrides), /* @__PURE__ */ new Set([...seen, token.name]));
+			return token.args === "" ? resolved : appendArgs(resolved, token);
+		}
+		const settled = layer(inherited, inline, overrides);
+		if (isGlob(token.name)) return toSegment(matchGlob(token.name, scriptNames).map((name) => makeLeaf({
+			...token,
+			name
+		}, settled, name)), settled);
+		return toSegment([makeLeaf(token, settled, Object.hasOwn(packageInfo.scripts, token.name) ? token.name : void 0)], settled);
+	}
+	function appendArgs(segment, token) {
+		const [leaf] = segment.commands;
+		if (segment.commands.length !== 1 || leaf === void 0) throw new NormalizeError(`Cannot pass arguments to "${token.name}": it expands to more than one command.`);
+		const args = substitutePlaceholders(token.args, config.args);
+		const extended = {
+			...leaf,
+			command: `${leaf.command} ${args}`,
+			line: `${leaf.line} ${args}`
+		};
+		return {
+			...segment,
+			commands: [extended]
+		};
+	}
+	/** One list entry other than a settings entry. */
+	function resolve(definition, inherited, overrides, seen) {
+		if (!definition) return EMPTY_SEGMENT;
+		if (typeof definition === "string") return resolveToken(definition, inherited, overrides, seen);
+		if (Array.isArray(definition)) throw new NormalizeError("A list of commands belongs in \"commands\" or in a \"commandDictionary\" entry, not inside one.");
+		if (isCommandSettings(definition)) throw new NormalizeError("A command definition needs a \"command\" field.");
+		const entry = definition;
+		if (typeof entry.command !== "string") throw new NormalizeError("A command's \"command\" must be a string.");
+		const { command, ...raw } = entry;
+		return resolveToken(command, layer(inherited, resolveCwd(raw, inherited.cwd ?? config.cwd)), overrides, seen);
+	}
+	/**
+	* `commands`, or a dictionary entry that is a list. The list's own
+	* `parallel` places the list as a whole and is not passed to its members.
+	*/
+	function resolveList(definitions, inherited, overrides, seen) {
+		const { parallel: inheritedParallel, ...passedDown } = inherited;
+		const { parallel: overriddenParallel, ...passedOver } = overrides;
+		const parallel = overriddenParallel ?? inheritedParallel ?? defaults.parallel;
+		check(booleanError("\"parallel\" on a list of commands", parallel), NormalizeError);
+		const segments = [];
+		let settled = passedDown;
+		for (const definition of definitions) {
+			if (isSettingsEntry(definition)) {
+				const written = readSettings(definition, settled.cwd ?? config.cwd);
+				settled = layer(settled, written);
+				if (written.parallel !== void 0) segments.push(BOUNDARY);
+				continue;
+			}
+			segments.push(resolve(definition, settled, passedOver, seen));
+		}
+		return {
+			commands: link(segments),
+			parallel
+		};
+	}
+	function resolveEntry(entry, inherited, overrides, seen) {
+		return Array.isArray(entry) ? resolveList(entry, inherited, overrides, seen) : resolve(entry, inherited, overrides, seen);
+	}
+	const { commands } = resolveList(config.commands, {}, {}, /* @__PURE__ */ new Set());
+	commands.sort((first, second) => first.stage - second.stage);
+	return commands;
+}
+function isSettingsEntry(definition) {
+	return typeof definition === "object" && definition !== null && !Array.isArray(definition) && isCommandSettings(definition);
+}
+/** Resolves a relative `cwd` against the inherited one, so directories nest. */
+function resolveCwd(options, base) {
+	return options.cwd === void 0 ? options : {
+		...options,
+		cwd: path.resolve(base, options.cwd)
+	};
+}
+/**
+* Reads a settings entry into the options the rest of its list inherits.
+* Keys are checked strictly: `{ paralel: true }` would otherwise do nothing.
+*/
+function readSettings(entry, base) {
+	const keys = Object.keys(entry);
+	if (keys.length === 0) throw new NormalizeError("A settings entry must set at least one option.");
+	for (const key of keys) if (!SETTINGS_OPTIONS.has(key)) throw new NormalizeError(`Unknown option "${toKebabCase(key)}" in a settings entry.`);
+	const { serial, ...options } = entry;
+	if (serial !== void 0) {
+		check(booleanError("\"serial\"", serial), NormalizeError);
+		if (options.parallel !== void 0) throw new NormalizeError("A settings entry takes \"parallel\" or \"serial\", not both.");
+		options.parallel = !serial;
+	}
+	return resolveCwd(options, base);
+}
+/** Layers option bags, later over earlier; stream settings merge per axis. */
+function layer(...bags) {
+	const result = {};
+	for (const { stderr, stdout, ...rest } of bags) {
+		Object.assign(result, rest);
+		if (stdout !== void 0) result.stdout = mergeStd(toPartialStd(result.stdout ?? {}), stdout);
+		if (stderr !== void 0) result.stderr = mergeStd(toPartialStd(result.stderr ?? {}), stderr);
+	}
+	return result;
+}
+/** Checks what a config file could have written by hand. */
+function validateCommand(command) {
+	const where = (key) => `"${toKebabCase(key)}" on "${command.command}"`;
+	check([
+		...["onFailure", "onSuccess"].map((key) => actionError(where(key), command[key])),
+		...["disabled", "parallel"].map((key) => booleanError(where(key), command[key])),
+		...[
+			"bgColor",
+			"color",
+			"cwd",
+			"label"
+		].map((key) => stringError(where(key), command[key])),
+		...["stderr", "stdout"].map((key) => stdError(where(key), command[key])),
+		typeof command.env === "object" && command.env !== null ? void 0 : `${where("env")} must be an object.`
+	].find((error) => error !== void 0), NormalizeError);
+}
+//#endregion
+//#region src/plan/plan.ts
+/** Resolves a config into the commands a run will spawn. */
+function createPlan({ config }) {
+	if (!config.hasCommands()) throw new ConfigError("No commands to run.");
+	const packageInfo = readPackageJson(config.cwd);
+	const plan = {
+		commands: normalize(config, packageInfo),
+		config,
+		packageInfo
+	};
+	assignAutoLabels(plan);
+	colorLabels(plan);
+	alignLabels(plan);
+	return plan;
+}
+//#endregion
+//#region src/plan/describe.ts
+/** The resolved run and every option in force, as `--dry-run` prints it. */
+function describeRun(config, commands) {
+	return [
+		...describeOptions(config),
+		"",
+		"Commands:",
+		...describeCommands(commands)
+	].join("\n");
+}
+function describeStd(std) {
+	return `${std.timing} -> ${std.destination}`;
+}
+function amount(value) {
+	return Number.isFinite(value) ? String(value) : "unlimited";
+}
+/** `name  value` lines, names padded into a column. */
+function settings(rows) {
+	const width = Math.max(...rows.map(([name]) => name.length));
+	return rows.map(([name, value]) => `${name.padEnd(width)}  ${value}`);
+}
+function describeOptions(config) {
+	return ["Options:", ...settings([
+		["cwd", config.cwd],
+		["jobs", amount(config.jobs)],
+		["parallel", String(config.parallel)],
+		["on-success", config.onSuccess],
+		["on-failure", config.onFailure],
+		["kill-timeout", `${config.killTimeout}ms`],
+		["stdout", describeStd(config.stdout)],
+		["stderr", describeStd(config.stderr)],
+		["labels", config.labels],
+		["color", String(config.color)],
+		["log-level", config.logLevel]
+	]).map((line) => `  ${line}`)];
+}
+function describeCommand(command) {
+	const rows = [];
+	if (command.line !== command.command) rows.push(["line", command.line]);
+	rows.push(["cwd", command.cwd], ["on-success", command.onSuccess], ["on-failure", command.onFailure], ["stdout", describeStd(command.stdout)], ["stderr", describeStd(command.stderr)]);
+	if (command.label !== "") {
+		rows.push(["label", `"${command.label}"`]);
+		const colors = [command.bgColor, command.color].filter((name) => name !== "");
+		if (colors.length > 0) rows.push(["color", colors.join(" on ")]);
+	}
+	for (const [name, value] of Object.entries(command.env)) rows.push([`env ${name}`, String(value)]);
+	return rows;
+}
+function describeCommands(commands) {
+	const lines = [];
+	for (const [index, stage] of groupByStage(commands, (command) => command.stage).entries()) {
+		lines.push(`  stage ${index + 1}:`);
+		for (const command of stage) lines.push(`    - ${command.command} (${command.type})`, ...settings(describeCommand(command)).map((line) => `        ${line}`));
+	}
+	return lines;
+}
+//#endregion
+//#region src/run/FileRegistry.ts
+/** One shared write stream per file path, for the lifetime of a run. */
+var FileRegistry = class {
+	/** The first failure any file reported. */
+	error;
+	streams = /* @__PURE__ */ new Map();
+	cwd;
+	handler;
+	constructor(cwd) {
+		this.cwd = cwd;
+	}
+	/** Called once, with the first failure. */
+	onFailure(handler) {
+		this.handler = handler;
+	}
+	open(destination) {
+		const filePath = path.resolve(this.cwd, destination);
+		let stream = this.streams.get(filePath);
+		if (stream === void 0) {
+			stream = fs.createWriteStream(filePath);
+			stream.on("error", (error) => {
+				this.fail(destination, error);
+			});
+			this.streams.set(filePath, stream);
+		}
+		return stream;
+	}
+	/** Ends every file and waits for `close`, which follows errors too. */
+	async closeAll() {
+		const streams = [...this.streams.values()];
+		this.streams.clear();
+		await Promise.all(streams.map(async (stream) => closed(stream)));
+	}
+	fail(destination, error) {
+		if (this.error !== void 0) return;
+		this.error = /* @__PURE__ */ new Error(`cannot write to "${destination}": ${error.message}`);
+		this.handler?.(this.error);
+	}
+};
+function closed(stream) {
+	return new Promise((resolve) => {
+		if (stream.closed) {
+			resolve();
+			return;
+		}
+		stream.once("close", resolve);
+		stream.end();
+	});
+}
+//#endregion
+//#region src/utils/colors.ts
+const KNOWN = new Set(Object.keys(inspect.colors));
+/** A color name `node:util`'s `styleText` knows. */
+function isColorName(name) {
+	return KNOWN.has(name);
+}
+/** Styles `text` with the known names among `colors`, if any. */
+function paint(text, colors) {
+	const formats = colors.filter((name) => isColorName(name));
+	return formats.length === 0 ? text : styleText(formats, text, { validateStream: false });
+}
+//#endregion
+//#region src/run/Logger.ts
+const RANK = {
+	debug: 3,
+	error: 0,
+	info: 2,
+	warn: 1
+};
+const COLORS = {
+	debug: ["gray"],
+	error: ["red"],
+	info: [],
+	warn: ["yellow"]
+};
+/** runset's own messages — never the commands' output. */
+var Logger = class {
+	level;
+	stream;
+	color;
+	constructor(level, stream, color = false) {
+		this.level = level;
+		this.stream = stream;
+		this.color = color;
+	}
+	warn(message) {
+		this.write("warn", message);
+	}
+	info(message) {
+		this.write("info", message);
+	}
+	debug(message) {
+		this.write("debug", message);
+	}
+	write(level, message) {
+		if (RANK[level] > RANK[this.level]) return;
+		const text = this.color ? paint(message, COLORS[level]) : message;
+		this.stream.write(`${text}\n`);
+	}
+};
+//#endregion
+//#region src/run/env.ts
+/**
+* The environment a command runs in: every `node_modules/.bin` up from `cwd`
+* on `PATH`, plus the `npm_*` variables scripts most often read.
+*/
+function createEnv({ base, cwd, packageInfo, scriptName }) {
+	const PATH_KEY = process.platform === "win32" ? "Path" : "PATH";
+	const pathKey = Object.keys(base).find((key) => key.toUpperCase() === "PATH") ?? PATH_KEY;
+	const binDirs = ancestors(cwd).map((dir) => path.join(dir, "node_modules", ".bin"));
+	const env = {
+		...base,
+		[pathKey]: [...binDirs, base[pathKey]].filter(Boolean).join(path.delimiter)
+	};
+	if (packageInfo.name !== "") env.npm_package_name = packageInfo.name;
+	if (packageInfo.version !== "") env.npm_package_version = packageInfo.version;
+	if (scriptName !== void 0) {
+		env.npm_lifecycle_event = scriptName;
+		env.npm_lifecycle_script = packageInfo.scripts[scriptName] ?? "";
+	}
+	return env;
+}
+//#endregion
+//#region src/run/OutputSink.ts
+/**
+* Routes one command stream by its {@link Std}: `realtime` writes through,
+* `grouped` holds everything until {@link flush}, `none` discards.
+*/
+var OutputSink = class {
+	buffered = "";
+	/** A prefixed stream's unfinished line, held until its newline. */
+	pending = "";
+	opened;
+	std;
+	prefix;
+	destinations;
+	files;
+	constructor(std, prefix, destinations, files) {
+		this.std = std;
+		this.prefix = prefix;
+		this.destinations = destinations;
+		this.files = files;
+	}
+	/** Opened on first use, so a command that never writes truncates nothing. */
+	get target() {
+		if (isStreamDestination(this.std.destination)) return this.destinations[this.std.destination];
+		this.opened ??= this.files.open(this.std.destination);
+		return this.opened;
+	}
+	write(chunk) {
+		if (this.std.destination === "none") return;
+		if (this.std.timing === "grouped") {
+			this.buffered += chunk;
+			return;
+		}
+		if (this.prefix === "") {
+			this.target.write(chunk);
+			return;
+		}
+		this.pending += chunk;
+		const end = this.pending.lastIndexOf("\n");
+		if (end === -1) return;
+		const complete = this.pending.slice(0, end + 1);
+		this.pending = this.pending.slice(end + 1);
+		this.target.write(this.applyPrefix(complete));
+	}
+	/** Emits what is held back: a `grouped` stream, or a partial line. */
+	flush() {
+		const held = [this.pending, this.buffered].filter((text) => text !== "");
+		this.pending = "";
+		this.buffered = "";
+		for (const text of held) this.target.write(this.applyPrefix(text));
+	}
+	applyPrefix(chunk) {
+		const { prefix } = this;
+		if (prefix === "") return chunk;
+		const endsWithNewline = chunk.endsWith("\n");
+		return (endsWithNewline ? chunk.slice(0, -1) : chunk).split("\n").map((line) => (typeof prefix === "string" ? prefix : prefix()) + line).join("\n") + (endsWithNewline ? "\n" : "");
+	}
+};
+//#endregion
+//#region src/run/prefix.ts
+/**
+* The prefix of a command's output lines: `''` without a label, a function
+* when `formatLabel` may answer differently per line.
+*/
+function makePrefix(command, color, formatLabel, stream) {
+	if (command.label === "") return "";
+	const defaultPrefix = defaultLabel(command, color);
+	if (formatLabel === void 0) return defaultPrefix;
+	return () => String(formatLabel({
+		color,
+		command,
+		defaultPrefix,
+		stream
+	}));
+}
+/** A colored block with color; `[label]` without. */
+function defaultLabel(command, color) {
+	if (color && command.label.trim() === "") return `${command.label} `;
+	const formats = [command.bgColor, command.color].filter((name) => isColorName(name));
+	if (!color || formats.length === 0) return `[${command.label}] `;
+	return `${paint(command.label, formats)} `;
+}
+//#endregion
+//#region src/run/Process.ts
+const USE_PROCESS_GROUPS = process.platform !== "win32";
+/** One command, running in one shell, restarted as its exit policy says. */
+var Process = class {
+	/** `undefined` when killed by a signal. */
+	exitCode;
+	signal;
+	started = false;
+	/** True when runset stopped this command rather than letting it finish. */
+	terminated = false;
+	finished = false;
+	command;
+	child;
+	context;
+	stdout;
+	stderr;
+	constructor(command, context) {
+		this.command = command;
+		this.context = context;
+		const { color, destinations, formatLabel } = context.config;
+		const sink = (stream) => new OutputSink(command[stream], makePrefix(command, color, formatLabel, stream), destinations, context.files);
+		this.stdout = sink("stdout");
+		this.stderr = sink("stderr");
+	}
+	/** Ran and did not end cleanly; a command runset killed doesn't count. */
+	isFailed() {
+		return this.started && !this.terminated && (this.exitCode !== 0 || this.signal !== void 0);
+	}
+	/** What runset reports for this command: a signal as 128 + its number. */
+	getReportedExitCode() {
+		return this.signal === void 0 ? this.exitCode ?? 0 : signalExitCode(this.signal);
+	}
+	/** Runs the command, again and again while its exit policy says `restart`. */
+	async start() {
+		if (this.terminated) return;
+		let stopTheRun = false;
+		for (;;) {
+			this.started = true;
+			await this.spawn();
+			this.stdout.flush();
+			this.stderr.flush();
+			this.context.logger.debug(`< ${this.command.line} ${this.report()}`);
+			if (this.terminated) break;
+			const action = this.isFailed() ? this.command.onFailure : this.command.onSuccess;
+			if (action !== "restart") {
+				stopTheRun = action === "stop";
+				break;
+			}
+			this.context.logger.info(`runset: restarting "${this.command.command}"`);
+		}
+		this.finished = true;
+		if (stopTheRun) this.context.requestStop();
+	}
+	terminate({ force = false, signal = "SIGTERM" } = {}) {
+		if (this.finished) return;
+		this.terminated = true;
+		const sent = force ? "SIGKILL" : signal;
+		if (this.child?.pid !== void 0) this.context.logger.debug(`! ${sent} ${this.command.line}`);
+		this.kill(sent);
+	}
+	report() {
+		return this.signal === void 0 ? `exited with ${this.exitCode ?? 0}` : `was killed by ${this.signal}`;
+	}
+	/** One attempt: resolves when the child is gone. */
+	async spawn() {
+		const { command, context } = this;
+		this.exitCode = void 0;
+		this.signal = void 0;
+		context.logger.debug(`> ${command.line}`);
+		await new Promise((resolve) => {
+			let settled = false;
+			const child = cp.spawn(command.line, {
+				cwd: command.cwd,
+				detached: USE_PROCESS_GROUPS,
+				env: createEnv({
+					base: {
+						...context.config.env,
+						...command.env
+					},
+					cwd: command.cwd,
+					packageInfo: context.packageInfo,
+					scriptName: command.scriptName
+				}),
+				shell: true,
+				stdio: [
+					"inherit",
+					"pipe",
+					"pipe"
+				]
+			});
+			this.child = child;
+			child.stdout?.setEncoding("utf8").on("data", (chunk) => this.stdout.write(chunk));
+			child.stderr?.setEncoding("utf8").on("data", (chunk) => this.stderr.write(chunk));
+			child.on("error", (error) => {
+				if (settled) return;
+				settled = true;
+				this.stderr.write(`${error.message}\n`);
+				this.exitCode = 1;
+				resolve();
+			});
+			child.on("close", (code, signal) => {
+				if (settled) return;
+				settled = true;
+				this.exitCode = this.terminated || signal !== null ? void 0 : code ?? 0;
+				this.signal = signal ?? void 0;
+				resolve();
+			});
+			if (this.terminated) this.kill("SIGTERM");
+		});
+		this.child = void 0;
+	}
+	kill(signal) {
+		const pid = this.child?.pid;
+		if (pid === void 0) return;
+		try {
+			if (USE_PROCESS_GROUPS) process.kill(-pid, signal);
+			else killTree(pid, signal);
+		} catch {}
+	}
+};
+/**
+* Windows has no process groups, and `child.kill` would reach only `cmd.exe`;
+* `taskkill /T /F` ends the tree (always forcefully). Falls back to the shell.
+*/
+function killTree(pid, signal) {
+	const killed = cp.spawnSync("taskkill", [
+		"/pid",
+		String(pid),
+		"/T",
+		"/F"
+	], {
+		stdio: "ignore",
+		windowsHide: true
+	});
+	if (killed.error !== void 0 || killed.status !== 0) process.kill(pid, signal);
+}
+//#endregion
+//#region src/run/schedule.ts
+/**
+* Runs the stages in order, everything in a stage at once — or, when `jobs`
+* is narrower, in batches of that many. A stopped run starts no new batch.
+*/
+async function schedule(processes, stopped, jobs) {
+	for (const stage of groupByStage(processes, (p) => p.command.stage)) {
+		const size = Math.min(jobs, stage.length);
+		for (let start = 0; start < stage.length; start += size) {
+			if (stopped()) return;
+			const batch = stage.slice(start, start + size);
+			await Promise.all(batch.map((process) => process.start()));
+		}
+	}
+}
+//#endregion
+//#region src/run/Run.ts
+/** One run: the processes built from a plan, and what stops them. */
+var Run = class Run {
+	config;
+	/** @internal */
+	processes;
+	logger;
+	files;
+	stopping;
+	constructor({ commands, config, packageInfo }) {
+		this.config = config;
+		this.files = new FileRegistry(config.cwd);
+		this.logger = new Logger(config.logLevel, config.destinations.stderr, config.color);
+		for (const warning of config.warnings) this.logger.warn(`runset: ${warning}`);
+		const context = {
+			config,
+			files: this.files,
+			logger: this.logger,
+			packageInfo,
+			requestStop: () => this.stopEverything({ reason: "policy" })
+		};
+		this.processes = commands.map((command) => new Process(command, context));
+		this.files.onFailure(() => this.stopEverything({ reason: "policy" }));
+	}
+	/** A library caller's config object, through the same pipeline as the CLI. */
+	static fromConfigJs(configJs) {
+		const config = createConfig({
+			cli: parseCli([]),
+			configJs
+		});
+		return new Run(createPlan({ config }));
+	}
+	isFailed() {
+		return this.failed().length > 0;
+	}
+	getExitCode() {
+		return this.failed()[0]?.getReportedExitCode() ?? 0;
+	}
+	/** The resolved run, and every option in force, as `--dry-run` prints it. */
+	describe() {
+		return describeRun(this.config, this.processes.map((process) => process.command));
+	}
+	/** Rejects with a {@link RunsetError} when the run did not succeed. */
+	async start() {
+		if (this.config.dryRun) {
+			this.config.destinations.stdout.write(`${this.describe()}\n`);
+			return this;
+		}
+		const onSigint = this.onSignal("SIGINT");
+		const onSigterm = this.onSignal("SIGTERM");
+		process.on("SIGINT", onSigint);
+		process.on("SIGTERM", onSigterm);
+		try {
+			await schedule(this.processes, () => this.stopping !== void 0, this.config.jobs);
+		} finally {
+			process.off("SIGINT", onSigint);
+			process.off("SIGTERM", onSigterm);
+			this.clearKillTimer();
+			await this.files.closeAll();
+		}
+		const failed = this.failed();
+		const exitCode = failed[0]?.getReportedExitCode();
+		const { stopping } = this;
+		if (this.files.error) throw new RunsetError(this.files.error.message, exitCode ?? 1);
+		if (stopping?.signal) throw new RunsetError(`the run was stopped by ${stopping.signal}`, signalExitCode(stopping.signal));
+		if (stopping?.reason === "terminate") throw new RunsetError("the run was terminated", signalExitCode("SIGTERM"));
+		if (exitCode !== void 0) throw new RunsetError(`${failed.length} command${failed.length === 1 ? "" : "s"} failed: ${failed.map((item) => `"${item.command.command}"`).join(", ")}`, exitCode);
+		return this;
+	}
+	terminate(options = {}) {
+		this.stopEverything({ reason: "terminate" }, options);
+	}
+	failed() {
+		return this.processes.filter((process) => process.isFailed());
+	}
+	/** Says a signal arrived before any command's parting words, then stops. */
+	onSignal(signal) {
+		return () => {
+			const { stderr } = this.config.destinations;
+			if (this.stopping !== void 0) {
+				this.logger.warn(`runset: ${signal} again, killing what is left`);
+				this.forceKill();
+				return;
+			}
+			if (signal === "SIGINT" && isTerminal(stderr)) stderr.write(" ");
+			this.logger.warn(`runset: ${signal} received, stopping the run`);
+			this.stopEverything({
+				reason: "signal",
+				signal
+			}, { signal });
+		};
+	}
+	stopEverything(state, options = {}) {
+		this.stopping ??= state;
+		for (const process of this.processes) process.terminate(options);
+		if (this.stopping.killTimer !== void 0) return;
+		const { killTimeout } = this.config;
+		if (killTimeout <= 0) {
+			this.forceKill();
+			return;
+		}
+		const killTimer = setTimeout(() => this.forceKill(), killTimeout);
+		killTimer.unref();
+		this.stopping.killTimer = killTimer;
+	}
+	forceKill() {
+		this.clearKillTimer();
+		for (const process of this.processes) process.terminate({ force: true });
+	}
+	clearKillTimer() {
+		if (this.stopping === void 0) return;
+		clearTimeout(this.stopping.killTimer);
+		this.stopping.killTimer = void 0;
+	}
+};
+//#endregion
+//#region src/cli.ts
+const HELP = `Usage: runset [options] <command...>
+
+  Runs npm scripts and shell commands in sequence or in parallel.
+
+Run mode:
+  -p, --parallel <commands>  run the following commands together
+  -s, --serial <commands>    run the following commands one after another
+  -j, --jobs <n>             max commands running at once (default: unlimited)
+
+On exit:
+      --on-success <action>  what a clean exit does   (default: continue)
+      --on-failure <action>  what a non-zero exit does (default: stop)
+                             action: continue | restart | stop
+      --kill-timeout <ms>    grace period before a SIGKILL (default: 5000)
+
+Output:
+      --stdout <value>       configure stdout: <timing>[+<destination>]
+      --stderr <value>       configure stderr
+  -o, --output <value>       apply <value> to both streams
+                             timing: realtime | grouped
+                             destination: stdout | stderr | none | <file path>
+      --labels <mode>        label each output line with its command:
+                             none | auto | custom | all (default: auto)
+
+General:
+  -c, --config <path>        load a config file, skipping the default lookup
+      --cwd <dir>            working directory for the commands
+      --color, --no-color    force color on or off
+      --log-level <level>    error | warn | info | debug (default: info)
+      --dry-run              print the resolved stages and run nothing
+  -h, --help                 show this help
+  -v, --version              show the version
+
+Command syntax:
+  cmd args::opt=value,flag   per-command options, after the last "::":
+                             "npm start::on-failure=restart"
+                             "serve --port 80::label=api,color=cyan"
+  "build:*"                  glob over package.json script names
+  "serve -- --port {1}"      placeholders drawn from arguments after --
+
+Examples:
+  runset clean lint "build:**"
+  runset -p "watch:**"
+  runset clean -p lint test -s deploy
+`;
+/** Runs the CLI and returns its exit code. */
+async function main(rawArgv) {
+	try {
+		const cli = parseCli(rawArgv);
+		if (cli.version) {
+			process.stdout.write(`${version()}\n`);
+			return 0;
+		}
+		if (cli.help) {
+			process.stdout.write(HELP);
+			return 0;
+		}
+		const config = createConfig({ cli });
+		if (cli.argv.length === 0 && !config.hasCommands()) {
+			process.stdout.write(HELP);
+			return 0;
+		}
+		await new Run(createPlan({ config })).start();
+		return 0;
+	} catch (error) {
+		if (!(error instanceof RunsetError)) throw error;
+		process.stderr.write(`runset: ${error.message}\n`);
+		return error.exitCode;
+	}
+}
+function version() {
+	return `v${readPackageJson(fileURLToPath(new URL("..", import.meta.url))).version}`;
+}
+//#endregion
+//#region src/index.ts
+async function runset(first, second) {
+	return Run.fromConfigJs(toConfigJs(first, second)).start();
+}
+if (import.meta.main) process.exitCode = await main(process.argv.slice(2));
+/** A lone object carrying `commands` is a config; anything else is commands. */
+function toConfigJs(first, second) {
+	if (second === void 0 && isConfigObject(first)) return first;
+	const commands = Array.isArray(first) ? first : [first];
+	return {
+		...second,
+		commands
+	};
+}
+function isConfigObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Array.isArray(value.commands);
+}
+//#endregion
+export { CliError, ConfigError, EXIT_ACTIONS, NormalizeError, Run, RunsetError, runset as default, runset, isCommandSettings, isStreamDestination };