What the agent does
The agent starts with the build, because a CoffeeScript project has two copies of every file and it has to know which one ships. In a library like jsog/jsog, package.json lists coffee-script ^1.10.0 beside mocha and moment, and the compile script runs coffee --compile --output lib/ src/*.coffee and then the same for src-test/ into test/. main points at lib/JSOG, the compiled files are committed with a // Generated by CoffeeScript 1.10.0 header, and .npmignore leaves src out of the package. The coffee-script name itself is deprecated on npm with the note that CoffeeScript has moved to coffeescript, with no hyphen. An install today resolves 1.12.7, so npm test rewrites that header line in both committed outputs before a single test runs.
Before converting anything the agent runs npm test and keeps the output as the baseline. Then it runs decaffeinate on src/JSOG.coffee and src-test/JSOGtest.coffee. The tool prints a list of suggestion codes at the top of each result, and the agent treats that list as its work queue. For the library it names DS101 (an Array.from wrapped around each comprehension), DS207 (verbose null checks) and DS209 (a top-level return). For the test file it names DS102, the return it adds in front of every it(...) call because CoffeeScript returns the last expression of a function.
DS209 is the one that can break users. The source ends with a bare return JSOG, which was legal because the CoffeeScript compiler wraps every file in (function() { ... }).call(this). decaffeinate emits no wrapper, so the converted file still loads through require, where Node supplies a function around the module, but a browser parsing it as a plain script stops with SyntaxError: Illegal return statement. This library sets window.JSOG and registers an AMD module, and bower.json names lib/JSOG.js as main, so script-tag use is a supported path. The agent restores a function wrapper around the file and deletes the trailing return. That also keeps JSOG, nextId and isArray from becoming page-level bindings.
It handles the rest one by one. The Array.from calls sit behind the file's own isArray check, so they come out. The defaults stay as decaffeinate wrote them, if (idProperty == null) { idProperty = '@id'; }, because a CoffeeScript default applies to null as well as to a missing argument and a JavaScript default parameter does not. Then it removes coffee-script, the compile, build and prepublish scripts and the src line in .npmignore, makes lib/JSOG.js the hand-edited source, and runs the old compiled test file from git against the new library before it runs the converted tests.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Convert this CoffeeScript project to plain JavaScript with decaffeinate and remove the compile step. First read package.json, any Cakefile or Makefile, .npmignore, bower.json and the CI config, and write down which directories hold .coffee sources, where compiled output goes, whether compiled files are committed, and what main points at. Run the existing test command and save its output as the baseline. Run decaffeinate on every .coffee file, sources and tests. For each file, list the DS suggestion codes decaffeinate printed and resolve each one or say why it stays. Check specifically: a top-level return or code that relied on the CoffeeScript function wrapper (restore a wrapper if the file can be loaded by a script tag, sets a window global or defines an AMD module), default arguments that must still apply to null, implicit returns in test callbacks, and Array.from around values already known to be arrays. Put the converted source where main points, delete the .coffee files and the generated copies, remove coffee-script or coffeescript and every script that calls coffee, and fix .npmignore or the files list so the package still contains what main needs. Before deleting the old compiled test file, run it against the converted library and report the result; then run the converted tests. Parse each converted library file as a classic script and as a CommonJS module and report any syntax error. Read the Node versions in the CI config and say which of them cannot parse the syntax decaffeinate emits; do not transpile, report it. Open a pull request with the baseline output, the output after, and the table of suggestion codes.",
"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 deletes src/JSOG.coffee and src-test/JSOGtest.coffee, replaces lib/JSOG.js and test/JSOGtest.js with readable JavaScript that carries the original comments, and edits package.json so test is just mocha. Its description holds a table with one row per suggestion code and what was done about it, the baseline test output next to the output after, and the two parse checks on the library file: as a CommonJS module and as a classic script.
The reviewer reads the wrapper first, since that is the hand-written part, then the three export branches at the bottom of the file (module.exports, window.JSOG and the AMD define). They also read one finding the agent leaves alone. .travis.yml lists Node 0.12, 0.11 and 0.10, and the converted code uses const, arrow functions, template literals and computed property names, which those releases cannot parse. Raising the CI matrix, or adding a transpile step to keep old runtimes, changes what the library supports, so the pull request reports it and asks.
If the old compiled tests fail against the new library, the session says so and the pull request is opened as a draft with the failing output. A conversion that only passes its own converted tests has not shown that behaviour was kept.
Run it on every repository that still compiles CoffeeScript
Small CoffeeScript packages tend to come in groups: a company wrote a dozen of them in the same two years and each has the same coffee --compile script. From a script on your server, list the repositories whose package.json names coffee-script or coffeescript, and send this body to POST /o/{org}/sessions once per repository with that repository in resources. Add a request_id that is a UUID v5 of the repository's full name, so running the script again returns the sessions it already started.
Every call answers 202 with the session at once. A run past the key's max_concurrent is created queued and starts when a slot frees, so the script needs no retry loop. Set a webhook_url on the key to receive run.completed for each run it started, then read the pull request from the session.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The conversion tool is deterministic; the judgement is in what it flags, and that judgement needs evidence. In its sandbox the agent keeps the CoffeeScript compiler's output and the converted file side by side, runs the same tests against both, and parses the result the two ways a consumer can load it. Each of those commands and its output stays in the session's transcript, so a reviewer who doubts the wrapper can read the SyntaxError that led to it.
A laptop run of decaffeinate tends to stop at a green test command. Here the baseline is recorded before the first edit, the old tests are held against the new code, and the things the agent chose not to change are written down. Twelve packages converted in twelve sandboxes come back as twelve pull requests with the same table in each.
Frequently asked questions
Does decaffeinate produce code that behaves the same?
It aims to keep behaviour exactly, which is why its output is sometimes more defensive than a person would write: Array.from around loops, explicit != null checks, a return before the last call in every function. Those are marked with DS codes so they can be cleaned up by someone who knows the types involved. The agent resolves each code and reruns the tests after.
Why does my converted file fail in the browser with "Illegal return statement"?
The CoffeeScript compiler wrapped each file in a function, so a return at the top level was allowed. decaffeinate does not add that wrapper and flags the line as DS209. Wrap the file in a function yourself, or remove the return if nothing reads the value.
Will it convert the tests too?
Yes, every .coffee file, tests included. Before the old compiled test file is deleted the agent runs it against the converted library, so the first proof does not depend on the converted tests being right.
Does it move the project to ES modules or TypeScript at the same time?
No. The prompt keeps require and module.exports and changes one thing, the source language. A second run can take the JavaScript further once this pull request is merged; mixing both makes the diff impossible to review against the old output.
What if a file does not convert?
decaffeinate stops with an error that names the line when it meets a construct it cannot translate safely. The agent reports the file and the message, converts the rest, and leaves that file and the compiler in place instead of rewriting it by hand without saying so.
More jobs like this: Upgrade dependencies weekly
- Migrate a Go Project From dep (Gopkg.toml) to Go Modules (dep)
- Migrate From drf-yasg to drf-spectacular in Django REST Framework (drf-yasg)
- Migrate From faker to @faker-js/faker in a Node.js Project (Faker)
- Migrate From Flask-Cache to Flask-Caching (Flask-Cache)
- Migrate From Flask-JWT to Flask-JWT-Extended (Flask-JWT)
- Migrate From Flask-RESTPlus to Flask-RESTX (Flask-RESTPlus)