zuke.tools.node

class NodeEvalSettings(NodeSettings)

• code(source: str) -> Self

  The JavaScript source to evaluate (required).

• require_module(*modules: str) -> Self

  Preload a CommonJS module before evaluating (--require <m>); repeatable.

• import_module(*modules: str) -> Self

  Preload an ES module before evaluating (--import <m>); repeatable.

• print() -> Self

  Print the result of the evaluated code (--print instead of --eval).

class NodeEvaluateSettings(NodeSettings)

• export(name: str) -> Self

  The named export to take, instead of the default one. The export is awaited; when it is a function it is called first, with callWith's arguments.

• call_with(*values: object) -> Self

  Arguments for the exported function, in order. Each must be JSON-serialisable — they cross a process boundary as JSON. Named callWith rather than args because ToolSettings.args already means "append raw arguments to the node command line", which is a different thing.

• exit_after_result() -> Self

  End the Node process as soon as the result has been written, instead of waiting for the module to let Node exit on its own. A module that leaves a live handle on the event loop — an HTTP server, a database pool, a timer — never exits, and the evaluation then blocks forever on a value it has *already* produced and written. This makes the driver exit once that write has flushed, so such a module can be evaluated as it is, without a process.exit of its own. What the module does *after* handing back its value does not happen. The process ends at the write, so anything it would still print is cut off, anything it would still do — a beforeExit handler, a teardown scheduled on the next tick, a flush that has not been awaited — does not run, and its own exit code is no longer observed (the driver exits 0). That is the trade the option makes, and why it is opt-in rather than the default: choose it for a module whose value is the whole point of running it, and whose remaining work is process teardown the operating system is about to do anyway. A module whose after-the-value work *matters* — one that writes a file, commits a transaction, or reports its own failure through an exit code — should keep the default and be given a way to exit on its own. Two shapes are unaffected either way: a module that throws before producing a result still rejects the evaluation, since the driver never reaches its final write, and a module that exits on its own never notices the option.

class NodeRunSettings(NodeSettings)

• script(path: str) -> Self

  The script to execute (required).

• script_args(*args: str | float) -> Self

  Arguments passed to the script (after the script path).

• require_module(*modules: str) -> Self

  Preload a CommonJS module before the script (--require <m>); repeatable.

• import_module(*modules: str) -> Self

  Preload an ES module before the script (--import <m>); repeatable.

• conditions(*names: str) -> Self

  Custom export conditions to resolve (--conditions <c>); repeatable.

• env_file(path: str) -> Self

  Load environment variables from a file (--env-file=<p>).

• watch() -> Self

  Restart the process on file changes (--watch).

• watch_path(*paths: str) -> Self

  Additional paths to watch (--watch-path <p>); repeatable.

• enable_source_maps() -> Self

  Enable Source Map V3 support for stack traces (--enable-source-maps).

• inspect() -> Self

  Activate the inspector (--inspect).

• inspect_brk() -> Self

  Activate the inspector and break before user code starts (--inspect-brk).

• max_old_space_size(megabytes: float) -> Self

  Set the V8 old-space memory limit in MiB (--max-old-space-size=<n>).

class NodeSettings(ToolSettings)

class NodeTasks

• static async run(ctx: ServiceContext, configure: Callable[[NodeRunSettings], NodeRunSettings] | None=None) -> ExecResult

  Run a script: node [options] <script> [args].

• static async eval(ctx: ServiceContext, configure: Callable[[NodeEvalSettings], NodeEvalSettings] | None=None) -> ExecResult

  Evaluate inline code: node --eval <code>.

• static async test(ctx: ServiceContext, configure: Callable[[NodeTestSettings], NodeTestSettings] | None=None) -> ExecResult

  Run the built-in test runner: node --test.

• static async evaluate(ctx: ServiceContext, module: str, configure: Callable[[NodeEvaluateSettings], NodeEvaluateSettings] | None=None) -> object

  Import a Node module and resolve to one of its exports' JSON value — the way a target reads something *out* of the Node side of a project (an OpenAPI document, a resolved config) instead of shelling out to a script that has to write it somewhere first. module is a path, resolved against the working directory. The export (default unless NodeEvaluateSettings.export names another) is awaited; when it is a function it is called with NodeEvaluateSettings.callWith's arguments first. `ts // tools/openapi.mjs: export default async () => document const spec = await NodeTasks.evaluate("tools/openapi.mjs"); The evaluation waits for the Node process to exit, so a module that leaves a live handle on the event loop (a server, a pool, a timer) would block on a value it has already produced. NodeEvaluateSettings.exitAfterResult ends the process as soon as the result has been written, for modules in that shape. The module runs as a real Node process with the build's own permissions — the same trust level as a script handed to NodeTasks.run, and the reason this is a build-authoring API rather than an input-processing one. module` is code: build it from a literal or from the project's own layout, never from an untrusted source (a pull request title, a webhook payload), exactly as for every other command a build spawns. Values passed through NodeEvaluateSettings.callWith cannot inject into the driver — they are embedded as JSON literals — but they do reach the module, so whatever the module does with them is the module's contract to uphold.

class NodeTestSettings(NodeSettings)

• paths(*values: str) -> Self

  Test files or directories to run (positional); repeatable.

• test_name_pattern(value: str) -> Self

  Run only tests whose name matches the pattern (--test-name-pattern <v>).

• test_reporter(value: str) -> Self

  Select the test reporter (--test-reporter <v>).

• test_concurrency(value: float) -> Self

  Maximum number of test files to run concurrently (--test-concurrency <n>).

• only() -> Self

  Run only tests marked with the only option (--test-only).

• watch() -> Self

  Re-run tests on file changes (--watch).

• experimental_test_coverage() -> Self

  Collect and report test coverage (--experimental-test-coverage).