All jobs

Replace rimraf and mkdirp With fs.rm and fs.mkdir in a Node.js Package

Yes. An agent swaps rimraf and mkdirp for Node's built-in fs.rm and fs.mkdir, reruns the tests, raises the engines floor, and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Node has had recursive delete and recursive mkdir built in for years, as fs.rm with recursive and fs.mkdir with recursive. Small packages written before that still carry rimraf and mkdirp, and old pins of both now print deprecation notices on every install. andrewrk/node-mv, published as mv, is typical. Its package.json depends on mkdirp ~0.5.1, ncp ~2.0.0 and rimraf ~2.4.0. In index.js, mkdirp creates the destination's parent when the caller passes the mkdirp option, and rimraf runs twice in the cross-device folder move: once to clear the destination when clobber is on, and once to remove the source after ncp has copied it. test/test.js requires rimraf too, to clean up after one case.

The agent reads how each call is made before replacing it, because the options carry intent. Both rimraf calls pass { disableGlob: true }, and the suite has a case that moves a folder to a path named test/a-*, so the author wanted a literal path and never a pattern. fs.rm takes paths literally, so that option has nothing to map to. rimraf reported success when the path was already gone, and fs.rm raises ENOENT unless force is set, so each call becomes fs.rm(path, { recursive: true, force: true }, cb). The mkdirp call becomes fs.mkdir(dir, { recursive: true }, cb), which also succeeds when the directory exists.

Then it runs npm test, which is mocha test/test.js --reporter spec, nine cases. With the original code all nine pass on a current Node. After the swap, seven pass and the two cross-device folder cases time out, and the cause is not in index.js. The package pins mocha ~2.2.5, whose own dependencies load graceful-fs 2.0.3, a release that patches the fs module in ways current Node does not expect. With that patch loaded, the built-in recursive delete never calls back. Under a current mocha the same nine cases pass. So the agent raises the mocha pin in the same pull request and explains why a devDependency moved in a change about two runtime packages.

Last, it updates the manifest. rimraf and mkdirp leave dependencies, which removes everything rimraf 2.4 pulled in behind it: glob, inflight, minimatch and their own dependencies. engines.node says >=0.8.0, and fs.rm needs a far newer Node than that, so the agent raises the floor to a version that has both built-ins and flags it as a breaking change for the package's next major version. It leaves ncp alone and notes fs.cp as a separate follow-up.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Replace the rimraf and mkdirp packages in this project with Node's built-in fs.rm and fs.mkdir. First list every require or import of rimraf and mkdirp in the source, tests and scripts, and every npm script that calls their command-line binaries. For each call, note the options passed (glob handling, sync or async, promise or callback) and what the caller does with the result. Replace rimraf with fs.rm using recursive: true, and force: true where the old call tolerated a missing path; if a call relied on rimraf expanding a glob pattern, expand it explicitly and say so. Replace mkdirp with fs.mkdir using recursive: true, and check any caller that used mkdirp's return value. Keep the callback or promise style each call site already uses. Run the test suite before and after on the Node version available here. If tests that passed before now hang or fail, find out whether the cause is the new code or an old test tool that patches fs, and fix the real cause. Remove both packages from the manifest and lockfile, report which transitive packages disappear, and set engines.node to the lowest version that has the APIs you used, calling out the change as breaking if it raises the floor. Leave other dependencies alone and list any that have built-in replacements as follow-ups. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that changes index.js, test/test.js and package.json. In the source, two require lines go and three calls change. The description shows the mapping call by call: which rimraf options were dropped and why they are safe to drop, where force: true preserves the old tolerance of a missing path, and what mkdir returns compared with mkdirp.

It reports the tests in three states: the original code, the new code under the old test runner with the two timeouts, and the new code under the updated runner. That middle state is in the description on purpose. It tells a reviewer that the mocha bump is required by the change and what breaks without it.

The reviewer's decision is the engines line. For an application it is a formality. For a published library with a floor of Node 0.8 it is a major version, and the description says which releases of Node the new code needs and lists the production packages no longer installed.

Run it on every Monday morning

One package at a time is a slow way to remove helpers the runtime has replaced. Save a broader version of the prompt as an automation on the repository's Project, asking the agent to find one dependency per run that a Node built-in now covers, replace it and open a pull request, and give it a schedule trigger with cron set to 0 8 * * 1 and your timezone. Each Monday starts one run, and each pull request stays small enough to review in a sitting.

For many repositories, drive it from a script instead: list the repositories whose package.json names rimraf or mkdirp, and send POST /o/{org}/sessions once for each with the body above. A request_id that is a UUID v5 of the repository name and the package keeps a second pass from starting the same job again.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

The swap looks mechanical, and on this package it stops being mechanical at the first test run. Two cases hang, the changed file looks correct, and the cause sits three levels down in the test runner's dependency tree. Finding it takes running the suite several ways and reading what is loaded. The agent does that in its own sandbox, where installing a second mocha to compare costs nothing, and keeps each command with its output in the session for the reviewer.

It also holds the line on scope. A sweep like this invites replacing ncp, rewriting callbacks as promises and modernising the tests in one pass. The agent changes what the prompt names, touches the test runner only because the evidence requires it, and writes the rest down as follow-ups, which keeps the pull request reviewable and the breaking change limited to one line of package.json.

Frequently asked questions

Is fs.rm a drop-in replacement for rimraf?

For deleting one known path, nearly: pass recursive: true, and force: true if a missing path should not be an error. It does not expand glob patterns, which older rimraf versions did by default, and it has no command-line binary, so npm scripts that call rimraf dist need another approach.

What about rimraf's retries on Windows?

rimraf retried when Windows reported a file as busy. fs.rm can do the same but does not by default: set maxRetries, and optionally retryDelay, in the options. The agent adds them where the code deletes directories that another process may still hold open, and says where it did.

Which Node.js version do I need?

fs.mkdir has accepted recursive since Node 10 and fs.rm arrived in Node 14. Any release line still supported today has both. The agent sets engines.node from the APIs it used and tells you when that is higher than what the package declared.

Why would tests hang after such a small change?

Very old test tools can load a package that patches Node's fs module. In node-mv, mocha ~2.2.5 brings in graceful-fs 2.0.3, and with it loaded the built-in recursive delete never completes. The code is fine and the test runner needs an update, which the agent includes.

More jobs like this: Upgrade dependencies weekly

Keep reading