@cldmv/vitest-runner 1.1.0 → 1.4.2

package/package.json

@@ -1,36 +1,46 @@
 {
 	"name": "@cldmv/vitest-runner",
-	"version": "1.1.0",
+	"version": "1.4.2",
 	"description": "Sequential Vitest runner to avoid OOM issues with large test suites",
 	"type": "module",
-	"main": "index.cjs",
-	"module": "index.mjs",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
 	"types": "./types/index.d.mts",
 	"exports": {
 		".": {
+			"vitest-runner-dev": {
+				"types": "./types/index.d.mts",
+				"import": "./src/runner.mjs"
+			},
 			"types": "./types/index.d.mts",
-			"import": "./index.mjs",
-			"require": "./index.cjs"
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
 		}
 	},
 	"bin": {
-		"vitest-runner": "./bin/vitest-runner.mjs"
+		"vitest-runner": "bin/vitest-runner.mjs"
 	},
 	"files": [
-		"index.mjs",
-		"index.cjs",
+		"dist/",
+		"!dist/**/*.map",
 		"types/",
-		"src/",
-		"bin/"
+		"bin/",
+		"!bin/**/*.map"
 	],
 	"scripts": {
-		"lint": "eslint src/ bin/ index.mjs",
+		"lint": "eslint --config .configs/eslint.config.mjs .",
+		"format": "prettier --write . --config .configs/.prettierrc",
+		"format:check": "prettier --check . --config .configs/.prettierrc",
 		"test": "vitest run --config .configs/vitest.config.mjs",
 		"test:watch": "vitest --config .configs/vitest.config.mjs",
 		"test:coverage": "vitest run --coverage --config .configs/vitest.config.mjs",
 		"ci:coverage": "vitest run --coverage --reporter=dot --maxWorkers=1 --config .configs/vitest.config.mjs",
 		"types:build": "tsc -p .configs/tsconfig.json",
-		"types:check": "tsc -p .configs/tsconfig.json --noEmit"
+		"types:check": "tsc -p .configs/tsconfig.json --noEmit",
+		"build": "tsup",
+		"build:ci": "npm run lint && npm run format:check && npm run types:build && npm run build",
+		"prepack": "node -e \"const fs=require('node:fs');const hasTsup=fs.existsSync('node_modules/.bin/tsup')||fs.existsSync('node_modules/.bin/tsup.cmd');if(hasTsup){require('node:child_process').execSync('npm run build',{stdio:'inherit'})}else if(!fs.existsSync('dist/index.mjs')){throw new Error('dist/ is missing and tsup is unavailable to build it (expected in a bare package-contents publish dir with a prebuilt dist/; unexpected anywhere else)')}\"",
+		"fix:headers": "node tools/fix-headers.mjs"
 	},
 	"keywords": [
 		"vitest",
@@ -39,10 +49,18 @@
 		"oom"
 	],
 	"devDependencies": {
+		"@cldmv/fix-headers": "^1.3.12",
+		"@eslint/js": "^10.0.1",
+		"@eslint/json": "^2.0.0",
+		"@eslint/markdown": "^8.0.2",
 		"@types/node": "^25.3.0",
-		"@vitest/coverage-v8": "^4.0.18",
+		"@vitest/coverage-v8": "^5.0.2",
+		"eslint": "^10.5.0",
+		"globals": "^17.6.0",
+		"prettier": "^3.8.4",
+		"tsup": "^8.5.1",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.18"
+		"vitest": "^5.0.1"
 	},
 	"dependencies": {
 		"chalk": "^5.4.1"
@@ -51,10 +69,18 @@
 		"vitest": ">=1.0.0"
 	},
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=20.19.0"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/CLDMV/vitest-runner.git"
+	},
+	"bugs": {
+		"url": "https://github.com/CLDMV/vitest-runner/issues"
+	},
+	"homepage": "https://github.com/CLDMV/vitest-runner#readme",
 	"license": "MIT"
 }

package/types/src/bin/vitest-runner.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/src/cli/args.d.mts

@@ -45,6 +45,14 @@ export type ParsedArgs = {
      * - Emit a JSON run report instead of text output (`--json`).
      */
     json: boolean;
+    /**
+     * - Directory for per-file coverage blobs (`--blobs-dir`); defaults to `<cwd>/.vitest-coverage-blobs`.
+     */
+    blobsDir: string | undefined;
+    /**
+     * - `false` when `--no-merge-reports` was passed; leaves blobs in `blobsDir` without merging.
+     */
+    mergeReports: boolean;
     /**
      * - Whether `--help` / `-h` was passed.
      */
@@ -69,4 +77,12 @@ export type ParsedArgs = {
      * - Non-flag positional arguments (file / folder patterns).
      */
     testPatterns: string[];
+    /**
+     * - Keep the run's scratch directory instead of removing it on completion (`--keep-tmp`).
+     */
+    keepTmp: boolean;
+    /**
+     * - Per-run scratch root, relative to `cwd` (`--scratch-dir`); defaults to `tmp/vitest-runner`.
+     */
+    scratchDir: string | undefined;
 };

package/types/src/core/discover.d.mts

@@ -21,6 +21,29 @@ export function discoverFilesInDir(dir: string, cwd: string, pattern?: RegExp):
  * sortWithPriority(files, ['listener-cleanup/']);
  */
 export function sortWithPriority(files: string[], earlyRunPatterns?: string[]): string[];
+/**
+ * Compute, for every file in `files`, the set of *other* files that Vitest's
+ * own CLI filter would spuriously also match when that file's path is passed
+ * as the filter argument.
+ *
+ * Vitest's `vitest run <filter>` matches any discovered test file whose path
+ * *contains* `<filter>` as a substring — not just an exact-path match. Two
+ * files that share the same basename (and immediate parent directory) at
+ * different depths — e.g. `tests/contract.test.vitest.mjs` and
+ * `packages/a/tests/contract.test.vitest.mjs` — collide because the shorter
+ * path is a trailing substring of the longer one, so filtering on the shorter
+ * path's exact string also matches the longer path's file. Passing an
+ * absolute path does not help: Vitest normalises to a root-relative path
+ * before matching.
+ *
+ * @param {string[]} files - File paths relative to the project root, as returned by discovery.
+ * @returns {Map<string, string[]>} Map from each file to the other files it would spuriously match (empty array when unambiguous).
+ * @example
+ * const conflicts = computeFilterConflicts(["tests/a.mjs", "pkg/tests/a.mjs"]);
+ * conflicts.get("tests/a.mjs"); // ["pkg/tests/a.mjs"]
+ * conflicts.get("pkg/tests/a.mjs"); // []
+ */
+export function computeFilterConflicts(files: string[]): Map<string, string[]>;
 /**
  * @typedef {Object} DiscoverOptions
  * @property {string} cwd - Project root directory.

package/types/src/core/scratch.d.mts

@@ -0,0 +1,64 @@
+/**
+ * Check whether a process is still alive.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isPidAlive(pid: number): boolean;
+/**
+ * Remove scratch roots left behind by runs whose owning process is no longer alive
+ * (a crash or `kill -9` skips the normal exit-time cleanup).
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} scratchDir - Scratch base directory, relative to `cwd` (or absolute).
+ * @returns {Promise<void>}
+ */
+export function sweepStaleScratchRoots(cwd: string, scratchDir: string): Promise<void>;
+/**
+ * Create this run's scratch root: `<cwd>/<scratchDir>/<pid>-<timestamp>/`.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} scratchDir - Scratch base directory, relative to `cwd` (or absolute).
+ * @returns {Promise<string>} Absolute path to the created root.
+ */
+export function createRunScratchRoot(cwd: string, scratchDir: string): Promise<string>;
+/**
+ * Create a scratch subdirectory under the run root for one file invocation.
+ *
+ * @param {string} runRoot - This run's scratch root, from `createRunScratchRoot`.
+ * @param {number} index - A unique index for this invocation within the run.
+ * @returns {Promise<string>} Absolute path to the created directory.
+ */
+export function createFileScratchDir(runRoot: string, index: number): Promise<string>;
+/**
+ * Remove a run's scratch root (async, best-effort).
+ *
+ * @param {string} root
+ * @returns {Promise<void>}
+ */
+export function removeScratchRoot(root: string): Promise<void>;
+/**
+ * Remove a run's scratch root synchronously (best-effort) — used from a signal
+ * handler right before `process.exit()`, where async cleanup can't be awaited.
+ *
+ * @param {string} root
+ * @returns {void}
+ */
+export function removeScratchRootSync(root: string): void;
+/**
+ * Create a fresh, uniquely-named scratch subdirectory for the calling test file.
+ *
+ * Reads the run's scratch directory from `process.env.VITEST_RUNNER_TMP`, which
+ * vitest-runner sets in every spawned child. Call this from a test file to get
+ * isolated scratch space per test case without managing your own `mkdtemp` base.
+ *
+ * @param {string} label - A short, human-readable label used as the directory name prefix.
+ * @returns {string} Absolute path to the newly created directory.
+ * @throws {Error} When `VITEST_RUNNER_TMP` is not set (not running under vitest-runner).
+ * @example
+ * import { makeRunTmpDir } from "@cldmv/vitest-runner";
+ * const dir = makeRunTmpDir("my-fixture");
+ */
+export function makeRunTmpDir(label: string): string;
+/** Default scratch root, relative to `cwd`. */
+export const DEFAULT_SCRATCH_DIR: "tmp/vitest-runner";

package/types/src/core/spawn.d.mts

@@ -16,7 +16,7 @@
  * Run a single Vitest test file in a child process and return parsed results.
  *
  * @param {string} filePath - Test file path (relative to `cwd` or absolute).
- * @param {SpawnBaseOptions & { vitestArgs?: string[], streamOutput?: boolean }} opts
+ * @param {SpawnBaseOptions & { vitestArgs?: string[], streamOutput?: boolean, excludePaths?: string[], extraEnv?: NodeJS.ProcessEnv }} opts
  * @returns {Promise<SingleFileResult>}
  * @example
  * const result = await runSingleFile('src/tests/foo.test.vitest.mjs', {
@@ -28,6 +28,8 @@
 export function runSingleFile(filePath: string, opts: SpawnBaseOptions & {
     vitestArgs?: string[];
     streamOutput?: boolean;
+    excludePaths?: string[];
+    extraEnv?: NodeJS.ProcessEnv;
 }): Promise<SingleFileResult>;
 /**
  * Run Vitest directly (all files in one process) with inherited stdio.

package/types/src/runner.d.mts

@@ -2,12 +2,19 @@
  * Run all discovered Vitest test files sequentially (with a configurable worker
  * pool for the non-solo phase) and return an exit code.
  *
+ * Owns the run's scratch directory lifecycle (`scratchDir`/`keepTmp`): sweeps stale
+ * roots from dead prior runs, creates this run's root, and removes it on every exit
+ * path — normal completion, a thrown error, or SIGINT/SIGTERM — unless `keepTmp` is
+ * set. The actual run logic lives in {@link runImpl}; this wrapper only exists to
+ * guarantee that cleanup regardless of how `runImpl` returns or throws.
+ *
  * @param {RunOptions} opts
  * @returns {Promise<number|object>} `0`/`1` by default; JSON report object when `opts.json` is true.
  */
 export function run(opts: RunOptions): Promise<number | object>;
 export { formatDuration } from "./utils/duration.mjs";
 export { buildNodeOptions } from "./utils/env.mjs";
+export { makeRunTmpDir } from "./core/scratch.mjs";
 export type PerFileHeapOverride = {
     /**
      * - Substring matched against the normalised file path.
@@ -79,6 +86,14 @@ export type RunOptions = {
      * - Rows in the worst-coverage table (0 = disable).
      */
     worstCoverageCount?: number;
+    /**
+     * - Directory for per-file coverage blobs (default `<cwd>/.vitest-coverage-blobs`). Relative paths resolve against `cwd`. Always cleared at the start of a coverage run.
+     */
+    blobsDir?: string;
+    /**
+     * - When `true`, blobs are merged via `vitest --mergeReports`, the coverage summary is printed, and `blobsDir` is deleted at the end. When `false`, the run stops after producing blobs: no merge, no summary, and `blobsDir` is left populated for an external merge step.
+     */
+    mergeReports?: boolean;
     /**
      * - Global `--max-old-space-size` ceiling; per-file overrides may raise it.
      */
@@ -99,6 +114,14 @@ export type RunOptions = {
      * - Value for `NODE_ENV` in child processes.
      */
     nodeEnv?: string;
+    /**
+     * - Per-run scratch root, relative to `cwd` (or absolute). A subdirectory is created per file invocation and exposed to it via `VITEST_RUNNER_TMP`.
+     */
+    scratchDir?: string;
+    /**
+     * - Keep the run's scratch root instead of removing it on completion (normal exit, failure, or SIGINT/SIGTERM).
+     */
+    keepTmp?: boolean;
     /**
      * -
      */

package/types/src/utils/ansi.d.mts

@@ -1,3 +1,15 @@
+/**
+ *	@Project: @cldmv/vitest-runner
+ *	@Filename: /src/utils/ansi.mjs
+ *	@Date: 2026-02-24T22:33:55-08:00 (1772001235)
+ *	@Author: Shinrai <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Shinrai <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-09-27 08:51:31 -07:00 (1790524291)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
 /**
  * @fileoverview ANSI escape-code helpers.
  * @module vitest-runner/src/utils/ansi

package/types/src/utils/duration.d.mts

@@ -1,3 +1,15 @@
+/**
+ *	@Project: @cldmv/vitest-runner
+ *	@Filename: /src/utils/duration.mjs
+ *	@Date: 2026-02-24T22:33:55-08:00 (1772001235)
+ *	@Author: Shinrai <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Shinrai <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-09-27 08:51:31 -07:00 (1790524291)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
 /**
  * @fileoverview Duration formatting utilities.
  * @module vitest-runner/src/utils/duration

package/types/src/utils/env.d.mts

@@ -1,3 +1,15 @@
+/**
+ *	@Project: @cldmv/vitest-runner
+ *	@Filename: /src/utils/env.mjs
+ *	@Date: 2026-02-24T22:33:55-08:00 (1772001235)
+ *	@Author: Shinrai <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Shinrai <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-09-27 08:51:31 -07:00 (1790524291)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
 /**
  * @fileoverview NODE_OPTIONS / environment helpers.
  * @module vitest-runner/src/utils/env

package/index.cjs

@@ -1,17 +0,0 @@
-/**
- * @fileoverview CJS shim — dynamically imports the ESM entry point so that
- * CommonJS callers can `require('vitest-runner')`.
- *
- * Because the package is pure ESM (`"type": "module"`) we cannot use `module.exports =`
- * directly; instead we export a promise and re-attach named exports once resolved.
- *
- * @example
- * // CommonJS usage
- * const { run } = await require('vitest-runner');
- */
-
-"use strict";
-
-// Async shim: re-export everything from the ESM module.
-// Callers must await the result or use .then().
-module.exports = import("./index.mjs");

package/index.mjs

@@ -1,5 +0,0 @@
-/**
- * @fileoverview ESM entry-point — re-exports the public API from src/runner.mjs.
- * @module vitest-runner
- */
-export * from "./src/runner.mjs";

package/src/cli/args.mjs

@@ -1,134 +0,0 @@
-/**
- * @fileoverview CLI argument parsing for the vitest-runner binary.
- * @module vitest-runner/src/cli/args
- */
-
-/**
- * @typedef {Object} ParsedArgs
- * @property {string|undefined} testListFile - Path to a JSON file of test paths to run (`--test-list`).
- * @property {boolean} showErrorDetails - `false` when `--no-error-details` was passed.
- * @property {boolean} coverageQuiet - Whether `--coverage-quiet` was passed.
- * @property {string|undefined} logFile - Path for the coverage run log (`--log-file`); defaults to `coverage/coverage-run.log`.
- * @property {boolean} suppressFileOutput - Suppress per-file runner output blocks (`--suppress-file-output`).
- * @property {boolean} suppressPassingFiles - Suppress the passed-files section in the final summary (`--suppress-passing-files`).
- * @property {boolean} topSummary - Show top-summary sections for memory and duration (`true` by default, disabled by `--no-top-summary`).
- * @property {boolean} json - Emit a JSON run report instead of text output (`--json`).
- * @property {boolean} help - Whether `--help` / `-h` was passed.
- * @property {number|undefined} workers - Worker count from `--workers <n>`, or undefined.
- * @property {string[]} soloPatterns - Path substrings from `--solo-pattern <pattern>` (repeatable).
- * @property {RegExp|undefined} testFilePattern - Compiled regex from `--file-pattern <regex>`, or undefined.
- * @property {string[]} vitestPassthroughArgs - Flags forwarded verbatim to vitest.
- * @property {string[]} testPatterns - Non-flag positional arguments (file / folder patterns).
- */
-
-/** Runner-owned flags that must not be forwarded to vitest. */
-const RUNNER_FLAGS = new Set([
-	"--test-list",
-	"--no-error-details",
-	"--coverage-quiet",
-	"--log-file",
-	"--suppress-file-output",
-	"--suppress-passing-files",
-	"--no-top-summary",
-	"--json",
-	"--workers",
-	"--solo-pattern",
-	"--file-pattern",
-	"--help",
-	"-h"
-]);
-
-/**
- * Parse raw CLI arguments into structured runner options.
- *
- * Runner-specific flags are extracted; everything else (flags and their
- * optional values) is forwarded to vitest as passthrough args.
- * A flag that takes a value (where the next token does not start with `-`)
- * consumes that token too.
- *
- * @param {string[]} args - Raw argument array (typically `process.argv.slice(2)`).
- * @returns {ParsedArgs}
- * @example
- * parseArguments(['--test-list', 'tests.json', '--workers', '2', '--reporter=verbose']);
- */
-export function parseArguments(args) {
-	const vitestPassthroughArgs = [];
-	const testPatterns = [];
-	const soloPatterns = [];
-	let testListFile;
-	let showErrorDetails = true;
-	let coverageQuiet = false;
-	let logFile;
-	let suppressFileOutput = false;
-	let suppressPassingFiles = false;
-	let topSummary = true;
-	let json = false;
-	let workers;
-	let help = false;
-	let testFilePattern;
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-
-		if (arg === "--test-list") {
-			testListFile = args[++i];
-		} else if (arg.startsWith("--test-list=")) {
-			testListFile = arg.slice("--test-list=".length);
-		} else if (arg === "--no-error-details") {
-			showErrorDetails = false;
-		} else if (arg === "--coverage-quiet") {
-			coverageQuiet = true;
-		} else if (arg === "--log-file") {
-			logFile = args[++i];
-		} else if (arg.startsWith("--log-file=")) {
-			logFile = arg.slice("--log-file=".length);
-		} else if (arg === "--suppress-file-output") {
-			suppressFileOutput = true;
-		} else if (arg === "--suppress-passing-files") {
-			suppressPassingFiles = true;
-		} else if (arg === "--no-top-summary") {
-			topSummary = false;
-		} else if (arg === "--json") {
-			json = true;
-		} else if (arg === "--workers") {
-			workers = parseInt(args[++i], 10);
-		} else if (arg.startsWith("--workers=")) {
-			workers = parseInt(arg.slice("--workers=".length), 10);
-		} else if (arg === "--solo-pattern") {
-			soloPatterns.push(args[++i]);
-		} else if (arg.startsWith("--solo-pattern=")) {
-			soloPatterns.push(arg.slice("--solo-pattern=".length));
-		} else if (arg === "--file-pattern") {
-			testFilePattern = new RegExp(args[++i], "i");
-		} else if (arg.startsWith("--file-pattern=")) {
-			testFilePattern = new RegExp(arg.slice("--file-pattern=".length), "i");
-		} else if (arg === "--help" || arg === "-h") {
-			help = true;
-		} else if ((arg.startsWith("--") || arg.startsWith("-")) && !RUNNER_FLAGS.has(arg)) {
-			vitestPassthroughArgs.push(arg);
-			// Consume the next token if it looks like a value (not another flag)
-			if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
-				vitestPassthroughArgs.push(args[++i]);
-			}
-		} else {
-			// Any remaining token (cannot start with '-'; those are caught above)
-			testPatterns.push(arg);
-		}
-	}
-
-	return {
-		testListFile,
-		showErrorDetails,
-		coverageQuiet,
-		logFile,
-		suppressFileOutput,
-		suppressPassingFiles,
-		topSummary,
-		json,
-		help,
-		workers,
-		soloPatterns,
-		testFilePattern,
-		vitestPassthroughArgs,
-		testPatterns
-	};
-}

package/src/cli/help.mjs

@@ -1,84 +0,0 @@
-/**
- * @fileoverview CLI help text for the vitest-runner binary.
- * @module vitest-runner/src/cli/help
- */
-
-import chalk from "chalk";
-
-/**
- * Print the full CLI help message to stdout.
- * @returns {void}
- * @example
- * showHelp();
- */
-export function showHelp() {
-	console.log(`
-${chalk.bold("Vitest Sequential Runner")}
-Runs each test file in its own Vitest process to avoid OOM issues.
-
-${chalk.bold("USAGE:")}
-  vitest-runner [OPTIONS] [PATTERNS]
-
-${chalk.bold("SPECIAL FLAGS:")}
-  --test-list <file>      Run only the files listed in a JSON array file
-  --file-pattern <regex>  Override the file discovery regex (default: \.test\.vitest\.(?:js|mjs|cjs)$)
-  --workers <n>           Number of parallel workers (default: 4 or VITEST_WORKERS)
-  --solo-pattern <pat>    Run files matching this path substring solo first (repeatable)
-  --no-error-details      Hide detailed error output (show only counts)
-  --coverage-quiet        Implies --coverage; show progress bar + final summaries only
-  --log-file <path>       Path for mirrored runner output (default: coverage/coverage-run.log with --coverage-quiet)
-  --suppress-file-output  Suppress per-file runner output blocks
-  --suppress-passing-files  Hide the PASSED TEST FILES section in the final summary
-  --no-top-summary        Hide TOP MEMORY USERS and TOP DURATION sections
-  --json                  Emit JSON summary output instead of text logs
-  --help, -h              Show this help message
-
-${chalk.bold("TEST PATTERNS:")}
-  [file]                  Run a specific test file (supports partial paths)
-  [folder]                Run all tests in a folder
-
-  Examples:
-    src/tests/config/background.test.vitest.mjs
-    src/tests/metadata
-    background.test.vitest.mjs
-
-${chalk.bold("VITEST FLAGS:")}
-  All standard Vitest CLI flags are supported and passed through:
-  -t, --testNamePattern   Filter tests by name pattern (regex)
-  --reporter              Change reporter (verbose, dot, json, etc.)
-  --coverage              Run full-suite coverage (blob-per-file + mergeReports)
-  --bail                  Stop on first failure
-
-  See the Vitest documentation for the full list.
-
-${chalk.bold("ENVIRONMENT VARIABLES:")}
-  VITEST_HEAP_MB         Set max heap size per test (default: Node.js default)
-  VITEST_WORKERS         Number of parallel workers (default: 4, overridden by --workers)
-  # Run all tests
-  vitest-runner
-
-  # Run a specific file (partial path ok)
-  vitest-runner src/tests/config/background.test.vitest.mjs
-
-  # Run only the files listed in a JSON file
-  vitest-runner --test-list my-tests.json
-
-  # Filter by test name
-  vitest-runner src/tests/metadata -t "lazy materialization"
-
-  # Run with 2 workers
-  vitest-runner --workers 2
-
-  # Run files matching a pattern solo first, then the rest in parallel
-  vitest-runner --solo-pattern listener-cleanup/ --solo-pattern heavy/
-
-  # Hide detailed errors
-  vitest-runner --no-error-details
-
-  # Coverage with quiet output + progress bar
-  vitest-runner --coverage --coverage-quiet
-
-  # Custom heap and workers
-  VITEST_HEAP_MB=8192 vitest-runner --workers 2 src/tests/heavy
-`);
-}