What the agent does
The aws-sdk package on npm now carries a deprecation notice saying v2 has reached end-of-support. The agent begins with what the app uses of it. In an app like adityajoshi12/s3-nodejs everything is in app.js: aws.config.update with a key, a secret and a region read from ACCESS_KEY, ACCESS_SECRET and REGION; one new aws.S3(); and four routes. POST /upload goes through multer-s3 with acl: "public-read". GET /list, GET /download/:filename and DELETE /delete/:filename call listObjectsV2, getObject and deleteObject with .promise(). package.json asks for aws-sdk ^2.1009.0 and multer-s3 ^2.10.0, and its test script is the npm placeholder that exits 1. There are no tests.
With no tests and no AWS account in the sandbox, the agent builds something to test against: a small HTTP server that speaks enough path-style S3 for these four operations, including an empty bucket and a missing key. Both SDK versions accept an endpoint override, so the same stand-in serves the old code and the new. On the old code it records the baseline. Listing works, download returns the bytes, delete answers 200. GET /download/ with a key that does not exist ends the Node process: the rejected NoSuchKey is never caught in the async handler. That is how the app behaves today, and the agent writes it down before changing anything.
The port has three traps, and the stand-in finds each. First, multer-s3 2.x calls s3.upload, which a v3 client does not have, so passing the new S3Client to it fails with this.s3.upload is not a function. multer-s3 3.0.1 declares @aws-sdk/client-s3 as a peer dependency and has to be upgraded in the same change. Second, v2 returns Contents: [] for an empty bucket and v3 leaves Contents as undefined, so r.Contents.map(...) in /list throws on a bucket with nothing in it. Third, Body from getObject was a Buffer and is now a stream; res.send(x.Body) throws Converting circular structure to JSON. The agent pipes the stream to the response instead.
Error handling changes shape as well. The v2 error carried code: 'NoSuchKey'; the v3 error has name: 'NoSuchKey', no code, and the HTTP status under $metadata.httpStatusCode. Since the missing-key crash was already there, the agent fixes it in the same pull request as a separately described commit: a 404 for NoSuchKey and a 500 for anything else. It then removes aws-sdk, runs npm install, and reports what the tree looks like. In this repository node_modules goes from 72 MB to 24 MB, of which the v2 SDK alone was 66 MB, and npm audit goes from 15 findings to 12. The 12 are in multer 1.4.3, express 4.17.1 and packages they pull in, and are a different upgrade.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Node.js app from the aws-sdk v2 package to the modular AWS SDK v3 clients. Read package.json, the lockfile and every file that requires aws-sdk or a package that takes an S3 client, such as multer-s3. List each service client, each operation, every use of .promise(), aws.config.update, and each response field the code reads. You have no AWS credentials. Write a small local HTTP server that implements, path-style, just the S3 operations this app calls, with cases for an empty bucket and a missing key, and point the SDK at it with an endpoint override. Install from the lockfile and, on the unchanged code, call every route against it and record status, body and whether the process survives. Then port: one S3Client configured explicitly with region and credentials, Command objects with send(), streams for object bodies, and whatever version of multer-s3 works with a v3 client. Do not change route paths or response bodies. Repeat the same calls and show the results side by side. For each response field you listed, say whether its type or its value for an empty result changed. Remove aws-sdk, run npm install, and report node_modules size and npm audit before and after. Report the Node version the new packages require. Fix a crash you can reproduce only in a separate commit. Add the route checks as a test script. Open a pull request with every command and its output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 app.js, package.json and package-lock.json and adds the S3 stand-in with a test script that calls the four routes. The description has the inventory of v2 calls, the before and after table for each route on a normal bucket, an empty bucket and a missing key, and the three failures the port passes through with their error text. It reports the install size and npm audit numbers, and that @aws-sdk/client-s3 at the version installed declares node >=20.0.0.
A reviewer weighs what a stand-in cannot prove. It checks request shape and response handling, not IAM, regions or bucket policy, so the first call against a real bucket is still yours to make. One line deserves a look: the upload sends x-amz-acl: public-read, and Amazon S3's documentation says buckets created since April 2023 have ACLs disabled by default, in which case that upload is refused. The agent leaves the option as it found it and flags it. It also flags that the repository tracks a .env file, with empty values, and that .gitignore covers only node_modules/.
Run it on every Monday morning
v2 no longer receives updates, so every service still on it is the same task waiting. In the console, add an automation to each Project with a schedule trigger, cron 0 9 * * 1 in your timezone, and a saved prompt that says: if package.json still depends on aws-sdk, do this migration; otherwise answer that there is nothing to do.
For a one-off sweep across many repositories, use an API key instead and send the body above once per repository, each with a request_id that is a UUID v5 of the repository name. The key's max_concurrent decides how many run at once, the rest are created queued, and a webhook_url on the key receives run.completed for each.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
This migration compiles at every wrong step. Nothing in JavaScript objects to a v3 client handed to an old multer-s3, to .map on a missing array, or to a stream passed to res.send until the request is made. Finding the three failures takes a server to send requests to, and the run builds one in its own sandbox, drives the old and new code through it, and keeps both sets of results.
It also needs no credentials of yours. The stand-in means no key is placed in the run and no test object is written to a real bucket. What comes back is a pull request whose claims are tied to recorded output, plus a test script the repository can keep.
Frequently asked questions
Does multer-s3 work with AWS SDK v3?
Version 3 of multer-s3 does; it lists @aws-sdk/client-s3 as a peer dependency. Version 2 expects the v2 client and fails with this.s3.upload is not a function when given an S3Client. The two upgrades have to land together.
Why does my list route break on an empty bucket after migrating?
Because v3 omits Contents when there are no objects, where v2 returned an empty array. Code such as r.Contents.map(...) then throws. Default it with r.Contents ?? []; the agent finds these by testing each route against an empty bucket.
How do I send an S3 object to the client in v3?
Body is a readable stream in Node, so pipe it: x.Body.pipe(res), after setting the content type from the response. If you need the bytes in memory, await x.Body.transformToByteArray() gives them. Passing the stream to res.send fails.
Can the codemod do this for me?
AWS publishes aws-sdk-js-codemod, which rewrites imports, client construction and .promise() calls, and the agent may use it as a first pass. It does not know that a library you pass the client to needs a new major version, or that an empty list changed type, which is what the route checks are for.
More jobs like this: Upgrade dependencies weekly
- Replace Axios With Native fetch in a Node.js Library (Axios)
- Migrate From babel-eslint to @babel/eslint-parser (babel-eslint)
- Migrate a Go Project From Blackfriday to goldmark (Blackfriday)
- Migrate From Bluebird to Native Promises in a Node.js Library (Bluebird)
- Replace body-parser With express.json() in an Express App (body-parser)
- Migrate From the Archived github.com/boltdb/bolt to go.etcd.io/bbolt in a Go Service (BoltDB)