[dreamwasp]

Overview

Last PR in the stack. It adds the gamut-scope-swap agent skill and the fixtures that run every migration together.

Note

This branch is a merge of the Video/Markdown, deep imports, ESLint, and Next.js PRs, because the skill and the combined fixtures need all of them. Its base is the scope-rename PR, so until those four merge, this diff includes their changes. Review only the last commit (feat(gamut-agent-tools): add the gamut-scope-swap skill), and rebase onto main once the others land.

Stack (split from #28, merge in order):

1. feat(gamut-codemods): add the codemods CLI and an empty scope-swap preset #38 Scaffold, based on main
2. feat(gamut-codemods): rename packages and replace gamut-kit in scope-swap #39 Package scope rename and gamut-kit removal, based on feat(gamut-codemods): add the codemods CLI and an empty scope-swap preset #38
3. feat(gamut-codemods): move Video imports and add Markdown video overrides #40 Video and Markdown, based on feat(gamut-codemods): rename packages and replace gamut-kit in scope-swap #39
4. feat(gamut)!: promote deep imports to the root, renaming Menu and SelectDropdown elements #41 Deep imports and Menu/SelectDropdown renames, based on feat(gamut-codemods): rename packages and replace gamut-kit in scope-swap #39
5. feat(gamut-codemods): rename the ESLint plugin prefix in scope-swap #42 ESLint plugin prefix, based on feat(gamut-codemods): rename packages and replace gamut-kit in scope-swap #39
6. feat(gamut-codemods): warn about esmExternals: false in next.config #43 Next.js esmExternals warning, based on feat(gamut-codemods): rename packages and replace gamut-kit in scope-swap #39
7. build(deps): make @skillsoft packages easier to install #44 Simpler dependencies (independent), based on main
8. feat(gamut-agent-tools): add the gamut-scope-swap skill #45 gamut-scope-swap skill (open last), based on feat(gamut-codemods): rename packages and replace gamut-kit in scope-swap #39, includes feat(gamut-codemods): move Video imports and add Markdown video overrides #40–feat(gamut-codemods): warn about esmExternals: false in next.config #43 👈 this PR

• gamut-scope-swap skill in @skillsoft/gamut-agent-tools. It works alongside the codemod: it reads the warnings, leftovers, and next steps, and helps with what the codemod can't rewrite. That covers deep imports, Video, the renamed Menu exports, tsconfig dom, jest mocks, ESLint plugin keys, Module Federation config, and preview builds. It doesn't run the codemod unless asked.
• BREAKING_CHANGES.md is the short list of every change in the move, with the manual ones marked.
• NEXT_EMOTION_INTEROP.md is the fallback for Next.js apps that can't drop esmExternals: false yet. The codemods README now links to it.
• READMEs: the gamut-agent-tools README and the codemods README point to the skill.
• Fixtures: restores the end-to-end and MDX fixtures that cover the rename, Video, deep imports, ESLint, and gamut-kit in one file.
• Merge fix: fixes the cli.test.ts merge between the sibling branches.

PR Checklist

• Related to designs: N/A
• Related to JIRA ticket: GMT-1790
• Changeset added
• I have run this code to verify it works
• This PR includes unit tests for the code change
• This PR includes testing instructions for the code change
• Package previews from this PR are passing end-to-end tests in all relevant consuming repositories

Testing Instructions

1. yarn nx test gamut-codemods. Expect 100 tests to pass, including the combined end-to-end and MDX fixtures.

2. Run the whole preset on a consumer repo (or a copy of one), then install the skill from the app repo:

   node <repo>/packages/gamut-codemods/dist/bin.js scope-swap .
   gamut plugin install claude   # or: gamut plugin install cursor

3. Ask the agent to work through the output. It should use the warnings and leftovers, refer to BREAKING_CHANGES.md for anything it can't rewrite, and not rerun the codemod unless you ask it to.

4. Read BREAKING_CHANGES.md against the PRs in the stack. Every breaking change should be listed.

PR Links and Envs

Repository	PR Link
Mono	N/A

🤖 Generated with Claude Code

[LinKCoding]

Ran against this:

REPO=/Users/kenny.lin/Documents/eng/codecademy-eng/skillsoft-gamut
rm -rf /tmp/swap-app && mkdir -p /tmp/swap-app/src && cd /tmp/swap-app && git init -q

cat > package.json <<'EOF'
{
  "name": "swap-app",
  "version": "1.0.0",
  "dependencies": {
    "@codecademy/gamut": "^1.0.0",
    "@codecademy/gamut-styles": "^1.0.0",
    "@codecademy/gamut-icons": "^1.0.0",
    "@codecademy/gamut-kit": "^1.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}
EOF
cat > tsconfig.json <<'EOF'
{ "compilerOptions": { "lib": ["es2020"], "jsx": "react" } }
EOF
cat > next.config.js <<'EOF'
module.exports = { experimental: { esmExternals: false } };
EOF
echo '{ "plugins": ["gamut"], "extends": ["plugin:gamut/recommended"] }' > .eslintrc.json
cat > src/App.tsx <<'EOF'
import { Box, Video } from '@codecademy/gamut';
import { theme } from '@codecademy/gamut-styles';
import { ArrowIcon } from '@codecademy/gamut-icons';

// eslint-disable-next-line gamut/no-inline-style
export const App = () => <Box style={{}}><Video /><ArrowIcon /></Box>;
EOF
git add -A && git commit -qm init

node $REPO/packages/gamut-codemods/dist/bin.js scope-swap .
git diff --stat

node $REPO/packages/gamut/bin/gamut.mjs plugin install claude
node $REPO/packages/gamut/bin/gamut.mjs plugin list

And then prompted the agent to use the skill and it worked through the issues and had gave me:

What the codemod changed
- src/App.tsx: the imports now use @skillsoft/*, and Video now comes from @skillsoft/gamut/Video. The eslint-disable directive was renamed to @skillsoft/gamut/no-inline-style.
- .eslintrc.json: the plugin and the extends entry now use @skillsoft/gamut. They match the directive prefix, so the directive will still work.
- package.json: gamut-kit was replaced with the individual @skillsoft packages.

What I fixed
- next.config.js: I removed experimental.esmExternals: false. It was the only setting in the file, so the config is now {}. The failure only shows up when Next collects page data, so you need a full next build to confirm. There were no @emotion aliases or transpilePackages entries to remove.
- tsconfig.json: I added "dom" to lib. It's harmless to keep. If type-checking passes without it, you can take it back out.
- package.json, Video peers: I added @vidstack/react@~1.12.12 and react-player@^3.4.0. Gamut supports only 1.12.x of @vidstack/react, so don't use the npm latest tag.
- package.json, @skillsoft/gamut-tests: I moved it from dependencies to devDependencies, since the codemod put it in the same field gamut-kit was in.

What's left for you
1. Run yarn. If it warns about missing @emotion/cache or stylis peers for @skillsoft/gamut-styles, add them.
2. Run prettier --write and eslint --fix, then type-check, test and build.
3. The ranges are ^0.0.1, which can resolve to a release older than the codemod expects. If @skillsoft/gamut/Video or MenuList isn't found after install, check node_modules/@skillsoft/gamut/package.json and its exports.
4. The repo has no sync-gamut-deps script, so the gamut-kit cleanup needs nothing.
5. src/App.tsx imports theme but never uses it. It was already like that before the swap, but lint will flag it.

I haven't committed anything. Say if you want me to run yarn and the checks.

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

[pkg-pr-new]

Open in StackBlitz

@skillsoft/eslint-plugin-gamut

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/eslint-plugin-gamut@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/eslint-plugin-gamut@45.tgz

@skillsoft/gamut

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut@45.tgz

@skillsoft/gamut-agent-tools

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-agent-tools@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-agent-tools@45.tgz

@skillsoft/gamut-codemods

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-codemods@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-codemods@45.tgz

@skillsoft/gamut-icons

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-icons@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-icons@45.tgz

@skillsoft/gamut-illustrations

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-illustrations@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-illustrations@45.tgz

@skillsoft/gamut-patterns

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-patterns@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-patterns@45.tgz

@skillsoft/gamut-styles

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-styles@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-styles@45.tgz

@skillsoft/gamut-tests

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-tests@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-tests@45.tgz

@skillsoft/variance

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/variance@45

yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/variance@45.tgz

commit: 8b47b2d