Support node --run (#1169)

Adds support for the new node --run feature which is available starting in Node 22 (basically npm run but faster, see https://nodejs.org/en/blog/announcements/v22-release-announce#running-packagejson-scripts and https://www.yagiz.co/developing-fast-builtin-task-runner/).

Note that node --run is stricter than the other runners when it comes to distinguishing between arguments for the runner vs the script, so an additional -- is needed to set wireit flags and script flags (explained in the README).

Thank you very much to @anonrig for adding the environment variables this required (nodejs/node#53032, nodejs/node#53058) and @justinfagnani for filing the issue (nodejs/node#52673)!

There is a problem with recursive invocations on Windows that I believe is a Node bug but need to double-check, tracking at #1168.

Fixes #1094

.github/workflows/tests.yml

@@ -6,26 +6,33 @@ jobs:
  tests:
  strategy:
  # We support Node Current, LTS, and Maintenance. See
- # https://nodejs.org/en/about/releases/ for release schedule.
+ # https://github.com/nodejs/release#release-schedule for release schedule
  #
  # We test all supported Node versions on Linux, and the oldest and newest
- # on macOS/Windows.
+ # on macOS/Windows. See
+ # https://github.com/actions/runner-images?tab=readme-ov-file#available-images
+ # for the latest available images.
  matrix:
  include:
+ # Maintenance
  - node: 18
  os: ubuntu-22.04
  - node: 18
  os: macos-13
  - node: 18
  os: windows-2022
+
+ # LTS
  - node: 20
  os: ubuntu-22.04
- - node: 20
+
+ # Current
+ - node: 22
+ os: ubuntu-22.04
+ - node: 22
  os: macos-13
- - node: 20
+ - node: 22
  os: windows-2022
- - node: 21
- os: ubuntu-22.04
 
  # Allow all matrix configurations to complete, instead of cancelling as
  # soon as one fails. Useful because we often have different kinds of

CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic
 Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- Added support for `node --run`, available in Node 22 and above (see
+ https://nodejs.org/en/blog/announcements/v22-release-announce#running-packagejson-scripts).
+
 ## [0.14.7] - 2024-08-05
 
 - When GitHub caching fails to initialize, more information is now shown about

README.md

@@ -104,9 +104,7 @@ and replace the original script with the `wireit` command.
 </table>
 
 Now when you run `npm run build`, Wireit upgrades the script to be smarter and
-more efficient. Wireit works with [yarn](https://yarnpkg.com/)
-(both 1.X "[Classic](https://classic.yarnpkg.com/)" and its successor "Berry")
-and [pnpm](https://pnpm.io/), too.
+more efficient. Wireit also works with [`node --run`](https://nodejs.org/en/blog/announcements/v22-release-announce#running-packagejson-scripts), [yarn](https://yarnpkg.com/), and [pnpm](https://pnpm.io/).
 
 You should also add `.wireit` to your `.gitignore` file. Wireit uses the
 `.wireit` directory to store caches and other data for your scripts.
@@ -238,6 +236,19 @@ npm or Wireit:
 npm run build -- --verbose
 ```
 
+Or in general:
+
+```sh
+npm run {script} {npm args} {wireit args} -- {script args}
+```
+
+An additional `--` is required when using `node --run` in order to distinguish
+between arguments intended for `node`, `wireit`, and the script itself:
+
+```sh
+node --run {script} {node args} -- {wireit args} -- {script args}
+```
+
 ## Input and output files
 
 The `files` and `output` properties of `wireit.<script>` tell Wireit what your
@@ -420,7 +431,15 @@ flag:
 npm run <script> --watch
 ```
 
-The benefit of Wireit's watch mode over built-in watch modes are:
+An additional `--` is required when using `node --run`, otherwise Node's
+built-in [watch](https://nodejs.org/docs/v20.17.0/api/cli.html#--watch) feature
+will be triggered instead of Wireit's:
+
+```sh
+node --run <script> -- --watch
+```
+
+The benefit of Wireit's watch mode over the built-in watch modes of Node and other programs are:
 
 - Wireit watches the entire dependency graph, so a single watch command replaces
  many built-in ones.
@@ -719,7 +738,7 @@ WIREIT_FAILURES=kill
 By default, Wireit automatically treats package manager lock files as input
 files
 ([`package-lock.json`](https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json)
-for npm,
+for npm and `node --run`,
 [`yarn.lock`](https://yarnpkg.com/configuration/yarnrc#lockfileFilename) for
 yarn, and [`pnpm-lock.yaml`](https://pnpm.io/git#lockfiles) for pnpm). Wireit
 will look for these lock files in the script's package, and all parent
@@ -921,13 +940,11 @@ input also affects the fingerprint:
 
 Wireit is supported on Linux, macOS, and Windows.
 
-Wireit is supported on Node Current (21), Active LTS (20), and Maintenance LTS
+Wireit is supported on Node Current (22), Active LTS (20), and Maintenance LTS
 (18). See [Node releases](https://nodejs.org/en/about/releases/) for the
 schedule.
 
-Wireit is supported on the npm versions that ship with the latest versions of
-the above supported Node versions (6 and 8), Yarn Classic (1), Yarn Berry (3),
-and pnpm (7).
+Wireit scripts can be launched via `npm`, `node --run`, `pnpm`, and `yarn`.
 
 ## Related tools
 

src/analyzer.ts

@@ -5,31 +5,31 @@
  */
 
 import * as pathlib from 'path';
+import {Dependency, scriptReferenceToString, ServiceConfig} from './config.js';
+import {findNodeAtLocation, JsonFile} from './util/ast.js';
 import * as fs from './util/fs.js';
 import {
  CachingPackageJsonReader,
  FileSystem,
 } from './util/package-json-reader.js';
-import {Dependency, scriptReferenceToString, ServiceConfig} from './config.js';
-import {findNodeAtLocation, JsonFile} from './util/ast.js';
 import {IS_WINDOWS} from './util/windows.js';
 
+import type {Agent} from './cli-options.js';
+import type {
+ ScriptConfig,
+ ScriptReference,
+ ScriptReferenceString,
+} from './config.js';
+import type {Diagnostic, MessageLocation, Result} from './error.js';
+import type {Cycle, DependencyOnMissingPackageJson, Failure} from './event.js';
+import {Logger} from './logging/logger.js';
 import type {
  ArrayNode,
  JsonAstNode,
  NamedAstNode,
  ValueTypes,
 } from './util/ast.js';
-import type {Diagnostic, MessageLocation, Result} from './error.js';
-import type {Cycle, DependencyOnMissingPackageJson, Failure} from './event.js';
 import type {PackageJson, ScriptSyntaxInfo} from './util/package-json.js';
-import type {
- ScriptConfig,
- ScriptReference,
- ScriptReferenceString,
-} from './config.js';
-import type {Agent} from './cli-options.js';
-import {Logger} from './logging/logger.js';
 
 export interface AnalyzeResult {
  config: Result<ScriptConfig, Failure[]>;
@@ -118,6 +118,7 @@ const DEFAULT_EXCLUDE_PATHS = [
 
 const DEFAULT_LOCKFILES: Record<Agent, string[]> = {
  npm: ['package-lock.json'],
+ nodeRun: ['package-lock.json'],
  yarnClassic: ['yarn.lock'],
  yarnBerry: ['yarn.lock'],
  pnpm: ['pnpm-lock.yaml'],

src/cli-options.ts

@@ -5,21 +5,22 @@
  */
 
 import * as os from 'os';
-import * as fs from './util/fs.js';
 import * as pathlib from 'path';
-import {Result} from './error.js';
-import {MetricsLogger} from './logging/metrics-logger.js';
 import {ScriptReference} from './config.js';
+import {Result} from './error.js';
 import {FailureMode} from './executor.js';
-import {unreachable} from './util/unreachable.js';
+import {DefaultLogger} from './logging/default-logger.js';
 import {Console, Logger} from './logging/logger.js';
+import {MetricsLogger} from './logging/metrics-logger.js';
 import {QuietCiLogger, QuietLogger} from './logging/quiet-logger.js';
-import {DefaultLogger} from './logging/default-logger.js';
+import * as fs from './util/fs.js';
+import {unreachable} from './util/unreachable.js';
 
 export const packageDir = await (async (): Promise<string | undefined> => {
- // Recent versions of npm set this environment variable that tells us the
- // package.
- const packageJsonPath = process.env.npm_package_json;
+ // Recent versions of npm, and node --run, set environment variables to tell
+ // us the current package.json.
+ const packageJsonPath =
+ process.env.npm_package_json ?? process.env.NODE_RUN_PACKAGE_JSON_PATH;
  if (packageJsonPath) {
  return pathlib.dirname(packageJsonPath);
  }
@@ -45,7 +46,7 @@ export const packageDir = await (async (): Promise<string | undefined> => {
  }
 })();
 
-export type Agent = 'npm' | 'pnpm' | 'yarnClassic' | 'yarnBerry';
+export type Agent = 'npm' | 'nodeRun' | 'pnpm' | 'yarnClassic' | 'yarnBerry';
 
 export interface Options {
  script: ScriptReference;
@@ -61,7 +62,8 @@ export interface Options {
 export const getOptions = async (): Promise<Result<Options>> => {
  // This environment variable is set by npm, yarn, and pnpm, and tells us which
  // script is running.
- const scriptName = process.env.npm_lifecycle_event;
+ const scriptName =
+ process.env.npm_lifecycle_event ?? process.env['NODE_RUN_SCRIPT_NAME'];
  // We need to handle "npx wireit" as a special case, because it sets
  // "npm_lifecycle_event" to "npx". The "npm_execpath" will be "npx-cli.js",
  // though, so we use that combination to detect this special case.
@@ -279,6 +281,9 @@ function getArgvOptions(
  extraArgs: process.argv.slice(2),
  };
  }
+ case 'nodeRun': {
+ return parseRemainingArgs(process.argv.slice(2));
+ }
  case 'yarnClassic': {
  // yarn 1.22.18
  // - If there is no "--", all arguments go to argv.
@@ -313,14 +318,16 @@ function getArgvOptions(
  * Try to find the npm user agent being used. If we can't detect it, assume npm.
  */
 function getNpmUserAgent(): Agent {
+ if (process.env['NODE_RUN_SCRIPT_NAME'] !== undefined) {
+ return 'nodeRun';
+ }
  const userAgent = process.env['npm_config_user_agent'];
  if (userAgent !== undefined) {
  const match = userAgent.match(/^(npm|yarn|pnpm)\//);
  if (match !== null) {
  if (match[1] === 'yarn') {
  return /^yarn\/[01]\./.test(userAgent) ? 'yarnClassic' : 'yarnBerry';
  }
-
  return match[1] as 'npm' | 'pnpm';
  }
  }

src/test/basic.test.ts

@@ -6,10 +6,10 @@
 
 import {suite} from 'uvu';
 import * as assert from 'uvu/assert';
-import {rigTest} from './util/rig-test.js';
 import {IS_WINDOWS} from '../util/windows.js';
-import {NODE_MAJOR_VERSION} from './util/node-version.js';
 import {checkScriptOutput} from './util/check-script-output.js';
+import {NODE_MAJOR_VERSION} from './util/node-version.js';
+import {rigTest} from './util/rig-test.js';
 
 const test = suite<object>();
 
@@ -766,6 +766,34 @@ test(
  }),
 );
 
+if (NODE_MAJOR_VERSION >= 22) {
+ test(
+ 'runs a script with node --run',
+ rigTest(async ({rig}) => {
+ const cmdA = await rig.newCommand();
+ await rig.write({
+ 'package.json': {
+ scripts: {
+ a: 'wireit',
+ },
+ wireit: {
+ a: {
+ command: cmdA.command,
+ },
+ },
+ },
+ });
+ const exec = rig.exec('node --run a');
+ await exec.waitForLog(/0% \[0 \/ 1\] \[1 running\] a/);
+ (await cmdA.nextInvocation()).exit(0);
+ const res = await exec.exit;
+ assert.equal(res.code, 0);
+ assert.equal(cmdA.numInvocations, 1);
+ assert.match(res.stdout, /Ran 1 script and skipped 0/s);
+ }),
+ );
+}
+
 test(
  'runs a script with yarn',
  rigTest(async ({rig}) => {
@@ -1062,9 +1090,21 @@ test(
  }),
 );
 
-for (const agent of ['npm', 'yarn', 'pnpm']) {
+for (const command of [
+ 'npm run',
+ 'node --run',
+ 'yarn run',
+ 'pnpm run',
+] as const) {
+ if (command === 'node --run' && NODE_MAJOR_VERSION < 22) {
+ // node --run was added in Node 22.
+ continue;
+ }
+ // node --run needs an extra set of "--" before arguments will be passed down
+ // to Wireit.
+ const extraDashes = command === 'node --run' ? '--' : '';
  test(
- `can pass extra args with using "${agent} run --"`,
+ `can pass extra args with using "${command} run --"`,
  rigTest(async ({rig}) => {
  const cmdA = await rig.newCommand();
  await rig.write({
@@ -1085,7 +1125,9 @@ for (const agent of ['npm', 'yarn', 'pnpm']) {
 
  // Initially stale.
  {
- const wireit = rig.exec(`${agent} run a -- foo -bar --baz`);
+ const wireit = rig.exec(
+ `${command} a -- ${extraDashes} foo -bar --baz`,
+ );
  const inv = await cmdA.nextInvocation();
  assert.equal((await inv.environment()).argv.slice(3), [
  'foo',
@@ -1099,15 +1141,19 @@ for (const agent of ['npm', 'yarn', 'pnpm']) {
 
  // Nothing changed, fresh.
  {
- const wireit = rig.exec(`${agent} run a -- foo -bar --baz`);
+ const wireit = rig.exec(
+ `${command} a -- ${extraDashes} foo -bar --baz`,
+ );
  assert.equal((await wireit.exit).code, 0);
  await wireit.waitForLog(/Ran 0 scripts and skipped 1/s); //
  }
 
  // Changing the extra args should change the fingerprint so that we're
  // stale.
  {
- const wireit = rig.exec(`${agent} run a -- FOO -BAR --BAZ`);
+ const wireit = rig.exec(
+ `${command} a -- ${extraDashes} FOO -BAR --BAZ`,
+ );
  const inv = await cmdA.nextInvocation();
  assert.equal((await inv.environment()).argv.slice(3), [
  'FOO',