src: add --run-dir runtime flag

[mertcanaltin]

add --run-dir runtime flag

Fixes #57489

[nodejs-github-bot]

Review requested:

• @nodejs/config

[aduh95]

The commit message doesn't adhere to our guidelines, it should start with an imperative verb so e.g. src: add `--run-in` runtime flag

[anonrig]

cc @flakey5

[anonrig]

We need to also change the pull-request title and description to reflect the changes.

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @anonrig.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[anonrig]

LGTM if tests pass (and the new requested test is added)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.24%. Comparing base (38390e5) to head (1491a81).
Report is 16 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #57523      +/-   ##
==========================================
+ Coverage   90.22%   90.24%   +0.01%     
==========================================
  Files         629      629              
  Lines      184845   184955     +110     
  Branches    36205    36234      +29     
==========================================
+ Hits       166784   166915     +131     
+ Misses      11016    11014       -2     
+ Partials     7045     7026      -19     

Files with missing lines	Coverage Δ
src/node_options.cc	85.36% <100.00%> (+0.14%)	⬆️
src/node_options.h	98.33% <ø> (ø)
src/node_task_runner.cc	89.78% <100.00%> (+0.39%)	⬆️

... and 47 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[aduh95]

Can you add a test that uses --run-in without --run to validate the behavior?

[pmarchini]

I've seen that this has already been raised. While I don't have a better name in mind, I think the current name is misleading

[mertcanaltin]

I agree with @GeoffreyBooth suggestion

--run-path +1

[mertcanaltin]

I will wait for further advice for the collective decision; please feel free to give suggestion 🚀

[vmoroz]

@mertcanaltin , IMHO the most common term used in such context is working_directory or working_dir.
E.g. "cwd" stands for "current working directory", "pwd" - "print working directory", etc.

Another example is the WORKING_DIRECTORY attribute used by CMake.

The new code would read: cwd = node::per_process::cli_options->working_dir;
I believe it is more natural than cwd = node::per_process::cli_options->run_dir;

[vmoroz]

The --cwd is also a great name proposed above by @targos

[vmoroz]

Please disregard my previous posts. I read through the discussion in the linked issue and see why the "working directory" term is not used. I am actually puzzled why the new flag is needed at all. Users can always provide the full path for the --run parameter.

[mertcanaltin]

@vmoroz, thank you very much for your suggestions. I think adding this flag gives users an easy and clear way to specify the correct directory and ensures that commands work in the intended context. This extra flexibility can provide a good experience in scenarios where precise control over the working directory is needed, such as when running new API documentation tools.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/65841/

[GeoffreyBooth]

I'm not opposed to this feature, but there are multiple requests for renaming, from different people: #57523 (comment), #57523 (comment), #57523 (comment), #57523 (comment). There also seems to be some confusion/lack of consensus about whether this should only affect --run or the entire process.

I'd like to see this land in some form, so I don't want to block this, but I think the above should be resolved before someone lands this.

[anonrig]

I'd like to see this land in some form, so I don't want to block this, but I think the above should be resolved before someone lands this.

We can land this as experimental, and later iterate on this. New documentation infra changes require this to be implemented, so I recommend merging and iterating.

[GeoffreyBooth]

I recommend merging and iterating.

This flag currently lacks experimental in the name. It will be disruptive to users to land one name and then rename it. It won't take long to reach a consensus here; I think it's worth taking the time to do so to avoid the user disruption.