feat: add NodeTask builtin task for running Node.js scripts (#521)

## Summary
- Add `NodeTask` builtin task type for running Node.js scripts (`node
<script> <args>`)
- Uses `script` (required) + `args` (optional) interface, distinct from
ExecTask/PnpxTask patterns
- Update ESLint plugin `prefer-builtin-task` rule to detect
`execa("node", ...)` and suggest `NodeTask`
- Update spec (bumped to 1.4.0), docs, type tests, and integration tests

## Test plan
- [x] Integration tests pass (3 tests: pass, info log level, fail exit
code)
- [x] Type-level tests pass (17 tests including 2 new NodeTask tests)
- [x] ESLint plugin tests pass (33 tests including new `preferNode`
detection)
- [x] Pre-commit checks pass (eslint, prettier, spell, knip, validate)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nam-hle

packages/docs/docs/getting-started/features.md

@@ -201,6 +201,18 @@ tasks.register("lint", ExecTask, {
 });
 ```
 
+### NodeTask
+
+Run Node.js scripts:
+
+```typescript
+import { tasks, NodeTask } from "nadle";
+
+tasks.register("seed", NodeTask, {
+	script: "scripts/seed-db.mjs"
+});
+```
+
 ### NpmTask
 
 Run npm commands:

packages/docs/docs/guides/defining-task.md

@@ -7,7 +7,7 @@ keywords: [nadle, defineTask, custom task, TypeScript, API, reusable]
 
 To create reusable and configurable task logic, use the `defineTask` API. This allows you to encapsulate behavior in a type-safe, shareable way that can be used across multiple task registrations.
 
-This is particularly useful for implementing tasks like `CopyTask`, `ExecTask`, `PnpxTask`, or any custom logic that accepts parameters and integrates cleanly with Nadle’s runtime.
+This is particularly useful for implementing tasks like `CopyTask`, `ExecTask`, `NodeTask`, `PnpxTask`, or any custom logic that accepts parameters and integrates cleanly with Nadle’s runtime.
 
 ---
 

packages/eslint-plugin/src/rules/prefer-builtin-task.ts

@@ -5,7 +5,7 @@ import { isInTaskAction } from "../utils/ast-helpers.js";
 
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/nadlejs/nadle/blob/main/packages/eslint-plugin/docs/rules/${name}.md`);
 
-type MessageId = "preferExec" | "preferNpm" | "preferNpx" | "preferPnpm" | "preferPnpx" | "preferCopy" | "preferDelete";
+type MessageId = "preferExec" | "preferNode" | "preferNpm" | "preferNpx" | "preferPnpm" | "preferPnpx" | "preferCopy" | "preferDelete";
 
 const EXEC_APIS = new Set(["execa", "exec", "execFile", "spawn"]);
 
@@ -95,6 +95,11 @@ function detectPattern(node: TSESTree.CallExpression): MessageId | undefined {
 		return "preferNpx";
 	}
 
+	// NodeTask: execa("node", ...)
+	if (name === "execa" && !isMember && hasFirstArg(node, "node")) {
+		return "preferNode";
+	}
+
 	// NpmTask: execa("npm", ...)
 	if (name === "execa" && !isMember && hasFirstArg(node, "npm")) {
 		return "preferNpm";
@@ -157,6 +162,7 @@ export default createRule({
 		messages: {
 			preferNpm: "Consider using NpmTask instead of calling npm via '{{name}}'.",
 			preferNpx: "Consider using NpxTask instead of calling npx via '{{name}}'.",
+			preferNode: "Consider using NodeTask instead of calling node via '{{name}}'.",
 			preferPnpm: "Consider using PnpmTask instead of calling pnpm via '{{name}}'.",
 			preferCopy: "Consider using CopyTask instead of '{{name}}' for file copying.",
 			preferPnpx: "Consider using PnpxTask instead of calling pnpm exec via '{{name}}'.",

packages/eslint-plugin/test/rules/prefer-builtin-task.test.ts

@@ -81,6 +81,11 @@ ruleTester.run("prefer-builtin-task", rule, {
 			errors: [{ messageId: "preferNpx", data: { name: "execa" } }],
 			code: 'tasks.register("build", async () => { await execa("npx", ["tsc"]); });'
 		},
+		// NodeTask: execa("node", ...)
+		{
+			errors: [{ messageId: "preferNode", data: { name: "execa" } }],
+			code: 'tasks.register("run", async () => { await execa("node", ["script.js"]); });'
+		},
 		// NpmTask: execa("npm", ...)
 		{
 			errors: [{ messageId: "preferNpm", data: { name: "execa" } }],

packages/nadle/index.api.md

@@ -116,6 +116,15 @@ export interface NadleFileOptions extends Partial<NadleBaseOptions> {
     readonly alias?: AliasOption;
 }
 
+// @public
+export const NodeTask: Task<NodeTaskOptions>;
+
+// @public
+export interface NodeTaskOptions {
+    readonly args?: MaybeArray<string>;
+    readonly script: string;
+}
+
 // @public
 export const NpmTask: Task<NpmTaskOptions>;
 

packages/nadle/src/builtin-tasks/index.ts

@@ -1,5 +1,6 @@
 export * from "./npm-task.js";
 export * from "./npx-task.js";
+export * from "./node-task.js";
 export * from "./pnpm-task.js";
 export * from "./pnpx-task.js";
 export * from "./exec-task.js";

packages/nadle/src/builtin-tasks/node-task.ts

@@ -0,0 +1,37 @@
+import { execa } from "execa";
+
+import type { MaybeArray } from "../core/index.js";
+import { defineTask } from "../core/registration/define-task.js";
+
+/**
+ * Options for the NodeTask.
+ */
+export interface NodeTaskOptions {
+	/** The script to execute via node. */
+	readonly script: string;
+	/** Arguments for the script. Defaults to none. */
+	readonly args?: MaybeArray<string>;
+}
+
+/**
+ * Task for running Node.js scripts.
+ *
+ * Executes `node <script> <args>` in the given working directory.
+ */
+export const NodeTask = defineTask<NodeTaskOptions>({
+	run: async ({ options, context }) => {
+		const args = options.args == null ? [] : typeof options.args === "string" ? [options.args] : options.args;
+
+		context.logger.info(`Running node script: node ${options.script} ${args.join(" ")}`);
+
+		const subprocess = execa("node", [options.script, ...args], { all: true, cwd: context.workingDir, env: { FORCE_COLOR: "1" } });
+
+		subprocess.all?.on("data", (chunk) => {
+			context.logger.log(chunk.toString());
+		});
+
+		await subprocess;
+
+		context.logger.info(`Node script completed successfully.`);
+	}
+});

packages/nadle/test/__fixtures__/node-task/nadle.config.ts

@@ -0,0 +1,5 @@
+import { tasks, NodeTask } from "nadle";
+
+tasks.register("pass", NodeTask, { script: "./src/pass.js" });
+tasks.register("fail", NodeTask, { script: "./src/fail.js" });
+tasks.register("echo", NodeTask, { args: "hello", script: "./src/echo.js" });

packages/nadle/test/__fixtures__/node-task/package.json

@@ -0,0 +1,11 @@
+{
+	"name": "@nadle/internal-nadle-test-fixtures-node-task",
+	"type": "module",
+	"private": true,
+	"dependencies": {
+		"nadle": "workspace:*"
+	},
+	"nadle": {
+		"root": true
+	}
+}

packages/nadle/test/__fixtures__/node-task/src/echo.js

@@ -0,0 +1 @@
+console.log(process.argv.slice(2).join(" "));