fs: copy directory trees for fs.cp() on the thread pool

[codebytere]

Runs the directory walk of fs.cp() / fsPromises.cp() as one thread pool request using the C++ implementation fs.cpSync() already has, instead of a JavaScript walk with several awaited round trips per entry; the first commit fixes that implementation giving created directories default permissions instead of the source directory's mode.

	before	after
benchmark/fs/bench-cp.js (new, fsPromises.cp() of 500 files), 30 runs		+340 % ±14 %
fsPromises.cp() of a 2 100-file tree	~215 ms	~28 ms
main-thread time for that copy	~110 ms	< 1 ms
cpSync of a 0700 directory (umask 022)	comes out 0755	0700

The JavaScript walk does opendir batches, two stat()s, the copyFile() and a chmod() per entry, each awaited in sequence, with the bookkeeping on the main thread. fs.cpSync() without a filter has done the whole walk in C++ since #58461, but that walk creates directories with default permissions where the JavaScript walk (and cpSync before the port) gives them the source directory's mode; the first commit fixes that (the mode is applied once the directory's contents are copied, so read-only source directories still copy), with a test that fails on main.

The second commit factors the walk into CopyDirRecursive(), which records an error instead of throwing so it can run on any thread, and runs it as a ThreadPoolWork request when the destination directory does not exist yet and nothing has to run per entry (no filter, no dereference, no mode flags for copyFile(), permission model off); the request creates every destination directory itself with mkdir() and fails with EEXIST if anything has appeared in its place since the JavaScript check, so it never writes through a late symbolic link; copying into an existing tree keeps the JavaScript walk and every rule it has for what may already be there (#58869 lists where cpSync's walk differs). Sockets, FIFOs and unknown entries found by the request are handed back to JavaScript, which rejects them with the same SystemErrors as before (cpSync keeps skipping them), and relative link targets are made absolute lexically as path.resolve() does (cpSync canonicalizes them). The walk uses the error_code overloads of std::filesystem throughout, so an unreadable directory inside the tree is reported as EACCES by both cp() and cpSync() where cpSync() currently terminates the process; filesystem errors from inside the walk keep their codes and report cp as the syscall, as cpSync does.

Refs: #58461

Tests: new test-fs-cp-sync-directory-mode.mjs, test-fs-cp-async-special-files-in-tree.mjs (a socket and a FIFO inside the tree: rejected by cp(), skipped by cpSync(), same as on main) test-fs-cp-unreadable-directory.mjs (aborts on main for cpSync) test-fs-cp-async-destination-appears-late.mjs and test-fs-cp-async-symlink-targets.mjs; all test-fs-cp* pass; a differential run over the option matrix (dereference, verbatimSymlinks, preserveTimestamps, force/errorOnExist, fresh and pre-populated destinations, symlinks, a socket and a FIFO in the tree) produces the same trees and outcomes as before.

---

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

[nodejs-github-bot]

Review requested:

• @nodejs/performance

[codecov]

Codecov Report

❌ Patch coverage is 81.41593% with 63 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.16%. Comparing base (21f0f27) to head (45406cc).
⚠️ Report is 128 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_file.cc	79.25%	27 Missing and 34 partials ⚠️
lib/internal/fs/cp/cp.js	95.55%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65488      +/-   ##
==========================================
+ Coverage   90.12%   90.16%   +0.04%     
==========================================
  Files         752      751       -1     
  Lines      252315   253662    +1347     
  Branches    47444    47797     +353     
==========================================
+ Hits       227395   228725    +1330     
+ Misses      16217    16192      -25     
- Partials     8703     8745      +42     

Files with missing lines	Coverage Δ
lib/internal/fs/cp/cp.js	93.76% <95.55%> (+5.41%)	⬆️
src/node_file.cc	74.67% <79.25%> (+0.70%)	⬆️

... and 84 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.

[mcollina]

lgtm

[nodejs-github-bot]

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

[nodejs-github-bot]

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