Implicit program "name", deep dive

[shadowspawn]

The user can set the program name. If they don't, Commander has a go at finding a name to use. This turns out to be quite hard and less consistent than you might expect! (In practice a user will only be using a subset of all the possibilities, but still some potential for getting caught out.)

constructor

const program = new Command('constructor');
program.parse();

% node example -h
Usage: constructor [options]

.name()

const program = new Command();
program.name('name');
program.parse();

% node example -h
Usage: name [options]

Implicit, from args

A commonly used method for command-line scripts to find the name of the currently running scripts is to examine the passed arguments. The Node.js documentation for process.argv says:

The process.argv property returns an array containing the command-line arguments passed when the Node.js process was launched. The first element will be process.execPath. See process.argv0 if access to the original value of argv[0] is needed. The second element will be the path to the JavaScript file being executed. The remaining elements will be any additional command-line arguments.

Commander uses the parsed arguments to determine the default name if they (should) include the script name. The problem is there are so many ways to launch a node application and not all pass the script name, and platform differences as well.

#!/usr/local/bin/node
const program = new Command();
program.parse(process.args);

Passing script directly:

% node script.js -h
Usage: script [options]

Running script as an executable:

$ ./executable-file -h
Usage: executable-file [options]

For running via package.json in directory package-dir:

  "main": "main-file.js",
  "bin": {
    "bin-executable": "executable-file.js"
  },

Running a package returns the name of the package directory (not the script name):

% node . -h
Usage: package-dir [options]

Running an installed binary on Mac and Linux gets the bin name (not the script name):

% npm link
...
% bin-executable -h
Usage: bin-executable [options]

Running an installed binary on Windows gets the script name (not the bin name):

> npm link
...
> bin-executable -h
Usage: executable-file [options]

Implicit, not from args

Since Commander v5, we support parsing arguments which do not include the script name. In this case we fallback to using the main module, from Commander 8 using require.main.filename. This does give consistent behaviour for all the launch methods with CommonJs.

const program = new Command();
program.parse(process.argv.slice(2), { from: 'user' });

% node script.js -h
Usage: script [options]

% ./executable-file -h
Usage: executable-file [options]

% node . -h
Usage: main-file [options]

% npm link
...
% bin-executable -h
Usage: executable-file [options]

There is a defect I discovered though, not available when main script is ECMAScript!

% node script.mjs -h
Usage: null [options]

Summary

In Commander v8 the default program name may turn out to be the script name, the package directory name, the package.json "bin" name, or even null. The default program name from the arguments is different for an npm installed binary on Windows and non-Windows.

An additional caveat is that default program name derived from the arguments may not be sensible when running unit tests or other launches when the normal entry script is not in the launch arguments. And the non-arguments approach uses some Node.js state which may not be defined by other applications (e.g. iisnode).

The safe approach is of course to set the name yourself! So Commander does not have to solve all the problems.

[shadowspawn]

I was liking require.main.filename, but there is simply no equivalent in ECMAScript. Many of the work-arounds or helper modules use processs.argv[1], so that is potentially still the best approach despite the short-comings!

References:

• https://stackoverflow.com/questions/20456876/why-is-require-main-filename-different-on-azure-that-it-is-on-my-local-windows-m
• https://www.npmjs.com/package/require-main-filename
• https://stackoverflow.com/questions/10265798/determine-project-root-from-a-running-node-js-application
• https://github.com/inxilpro/node-app-root-path
• https://github.com/yargs/yargs/blob/b6286d7269f3b20fd00da6e7326d3852a162deea/lib/yargs-factory.ts#L1475 (args)
• https://github.com/tapjs/libtap/pull/21/files
• https://github.com/tschaub/es-main
• nuxt/telemetry@5d8024f
• import.meta.main nodejs/node#49440

[shadowspawn]

Why care so much about the name, which is arguably just cosmetic?
We also use the full path of the main module to find stand-alone executable subcommands. See #714.

[shadowspawn]

The open issue that prompted this research is #714
The PR inspired by this issue is #1571

Closing this issue as having captured existing Commander behaviour, and investigated what is used elsewhere.