What the agent does
github.com/mitchellh/mapstructure is archived on GitHub, and development continues at github.com/go-viper/mapstructure/v2. For most code the move is an import path, and the agent's job is to find the part that is not. It begins with an inventory. In a library like ktrysmt/go-bitbucket, go.mod requires github.com/mitchellh/mapstructure v1.5.0 directly, and nine source files import it. Almost every use is mapstructure.Decode(respMap, target) on a decoded JSON response. One place, decodeRepository in repository.go, builds a decoder with mapstructure.NewDecoder and a DecoderConfig whose DecodeHook is mapstructure.StringToTimeHookFunc("2006-01-02T15:04:05.000000+00:00"). Twenty struct fields carry a mapstructure:"..." tag.
The agent changes the import path in each file and leaves every tag alone, because v2 reads the same mapstructure tag key. It runs go get github.com/go-viper/mapstructure/v2@latest and go mod tidy, and checks that the old module has left go.mod and go.sum. Then it runs what CI runs: go vet ./... and make test/ci, which in this repository is the build, go test -v -short -count=1 . and the mock tests, none of which need Bitbucket credentials. The tests directory holds integration tests that do need them, and the agent reports that it skipped those and why.
Passing tests are not the whole answer for a decoder, so the agent also writes a comparison program that imports both modules under different names and decodes the same inputs with each. It picks inputs from the shapes this library depends on. The Repository struct has two fields tagged created_on, a string and a *time.Time filled through the time hook, so one key has to land in both. Field names such as Fork_policy and Is_private rely on case-insensitive matching with no tag at all. JSON numbers arrive as float64 and go into int fields. Keys the struct does not know are ignored, and nil values leave zero values. For all of these the two versions produce equal structs, and the program prints that.
Errors are where v2 differs, and this library returns decode errors straight to its callers. On a type mismatch v1 returns a *mapstructure.Error whose text starts 3 error(s) decoding: and lists each field with a *, sorted by name, ending in the offending value. v2 returns a wrapped, joined error whose text starts decoding failed due to the following error(s):, lists fields in struct order and leaves the value out. A caller that used errors.As with *mapstructure.Error, or matched on the old text, would stop matching. The agent searches the module and its tests for both patterns, and puts the two messages side by side in the pull request so downstream users can do the same search.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Go module from github.com/mitchellh/mapstructure to github.com/go-viper/mapstructure/v2. First confirm from GitHub that the old repository is archived and read the newest v2 tag. Read go.mod, and list every file that imports the old path and every API used: Decode, WeakDecode, NewDecoder with each DecoderConfig field that is set, the hook functions, Metadata, and any reference to the *mapstructure.Error type or its Errors field. Count the struct tags and leave them unchanged. Before editing, run the commands CI runs and keep the output. Then write a comparison program in a scratch directory that imports both modules side by side and decodes the same inputs into copies of this module's own struct shapes: a normal response, two fields sharing one tag, untagged fields matched by case-insensitive name, float64 into integer fields, unknown keys, nil values, a wrong type, a time string the hook cannot parse, and an input that is not a map. Print whether the results are equal and print both error messages and error types where they are not. Change the import paths, run go get for v2 and go mod tidy, and show the old module is gone from go.mod and go.sum, or run go mod why if something else still needs it. Run the same CI commands again. Search this module and its tests for errors.As or type assertions on the old error type and for string matches on its messages, and fix or report each. Do not run tests that need external credentials; list them as skipped. Add a changelog or release note line that tells users of this library the decode error text and type changed. Open a pull request with the comparison 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 rewrites one import line in each file that used the old path and updates go.mod and go.sum. Its description contains the inventory of APIs used, the before and after output of go vet and make test/ci, and the output of the comparison program: a list of inputs with equal beside each successful decode, and the v1 and v2 messages and types for the three failing inputs. It names the tests it did not run and the environment variables they would need, such as BITBUCKET_TEST_USERNAME.
The reviewer of a library has one extra question, and the description answers it directly: does this change anything for people who import the package. Successful decodes do not change. An error returned from a decode helper now has different text, no longer includes the value that failed to convert, and is no longer a *mapstructure.Error. Whether that deserves a minor or a major version bump is the maintainer's call, and the agent leaves the version alone. The reviewer also confirms that no exported type or function signature of the library mentions a mapstructure type, which would force every consumer to change imports at the same moment.
Run it on every module that imports the archived path
Config loaders, API clients and CLI tools all tend to carry this import, so one organisation usually has it in many modules. GET /o/{org}/github returns the repositories the Rush GitHub App can reach. A script can walk that list, keep the ones whose go.mod names github.com/mitchellh/mapstructure as a direct requirement, and send this body to POST /o/{org}/sessions for each with the repository as its resources URL.
Give each start a request_id that is a UUID v5 of the repository's full name. If the script is interrupted and run again, the repositories it already covered return their existing runs, and only the missing ones start. Modules where the old path is only an indirect requirement are a different job: the fix there is upgrading whichever dependency pulls it in, and go mod why names it.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The part of this migration that needs proof is behaviour on bad input, and that takes both versions installed in one program. The run builds that program in its own sandbox against the real v1.5.0 and the newest v2, decodes the module's own struct shapes with each, and keeps the printed result. The reviewer does not have to take the equality of the happy path or the difference in the error path on anyone's word.
It also runs the same commands as CI on the Go version go.mod declares, before and after, in a clean checkout with a cold module cache. That catches a leftover import or a go.sum line that a warm laptop cache would paper over, and the outputs stay in the session's transcript for as long as the pull request is under review.
Frequently asked questions
Do I have to rename my mapstructure struct tags?
No. v2 reads the same mapstructure:"name" tags, and untagged fields still match keys by case-insensitive name. Only the import path changes, to github.com/go-viper/mapstructure/v2. The package name stays mapstructure, so call sites compile unchanged.
What changed in v2 error handling?
Decode errors are no longer a *mapstructure.Error with an Errors slice of strings. v2 returns joined errors with its own types, and the message begins decoding failed due to the following error(s):. The message also omits the value that failed to convert. Code that inspected the old type or text needs updating.
Can both modules exist in one build?
Yes. They have different import paths, so Go treats them as unrelated packages, and a dependency that still imports the old path keeps working. After go mod tidy the old module remains in go.mod only as an indirect requirement of that dependency. Values decoded by one are ordinary structs and can be passed to code that uses the other.
Will the agent run my integration tests?
Only the ones that need nothing outside the sandbox. Tests that call a real service with credentials from the environment are listed as skipped, with the variables they read. The pull request names them so you can run them in your own CI, where those credentials already live.
More jobs like this: Upgrade dependencies weekly
- Replace the mock Backport With unittest.mock (mock)
- Migrate From mysql to mysql2 in a Node.js App (mysql (Node.js))
- Migrate from node-sass to Dart Sass in a Webpack Project (webpack)
- Migrate a Python Project From oauth2client to google-auth (oauth2client)
- Migrate From packr to Go's embed Package (packr)
- Replace pkg/errors With the Standard Library in a Go Module (pkg/errors)