Stop using YARN_IGNORE_PATH env var

[bobular]

Fix: Yarn Version Conflicts Between Dev and Legacy Environments

The Problem

We support two different environments:

• Modern dev machines: Use Yarn 4.12.0 with supply chain security features
• Legacy deployment servers: Use older Yarn 3.3.1 (can't run newer versions)

Previously, we tried to handle this by:

1. Having yarnPath: .yarn/releases/yarn-3.3.1.cjs in .yarnrc.yml (tells Yarn to use the old bundled version)
2. Setting YARN_IGNORE_PATH=1 environment variable to override this on dev machines

This didn't work. Here's why:

• When you run commands like yarn nx start, it spawns nested yarn commands (via npm-run-all, nx, etc.)
• Yarn strips the YARN_IGNORE_PATH variable from these nested processes for security
• The nested commands fall back to Yarn 3.3.1
• Yarn 3.3.1 sees the YARN_NPM_MINIMAL_AGE_GATE security variable and errors out (doesn't recognize it)

Result: Dev commands like yarn nx start @veupathdb/genomics-site failed with confusing errors.

The Solution

We commented out the yarnPath line in .yarnrc.yml and added a pre-commit hook to keep it commented.

How it works now:

• Dev machines: Automatically use Yarn 4.12.0 via corepack (reads packageManager: "yarn@4.12.0" from package.json)
• Legacy servers: Manually uncomment the yarnPath line locally (not committed to git)
• Pre-commit hook: Prevents anyone from accidentally committing the uncommented line

What Changed

Files Modified:

1. .yarnrc.yml - Commented out yarnPath with instructions
2. tools/scripts/check-yarnrc-config.sh - New pre-commit hook (blocks uncommenting yarnPath)
3. .husky/pre-commit - Added the new validation
4. tools/scripts/check-yarn-lockfile.sh - Updated error message
5. README.adoc - Removed obsolete YARN_IGNORE_PATH instructions
6. .envrc.example - Removed YARN_IGNORE_PATH

For Developers

What You Need to Do:

1. Remove YARN_IGNORE_PATH from your environment

   If you previously added it to .bashrc, .zshrc, or .envrc, remove this line:

   export YARN_IGNORE_PATH=1  # Remove this!

2. Keep YARN_NPM_MINIMAL_AGE_GATE (if you had it)

   This one is still needed and works correctly:

   export YARN_NPM_MINIMAL_AGE_GATE=10080  # Keep this!

3. Verify yarn version

   After pulling this PR, check:

   yarn --version
   # Should show: 4.12.0

4. Everything should just work

   Commands like yarn nx start should now work without errors!

What If I See Yarn 3.3.1?

If you see version 3.3.1 instead of 4.12.0, you need to enable corepack:

corepack enable --install-directory ~/.volta/bin

(This is already documented in README.adoc)

For Legacy Deployment Servers

What You Need to Do:

1. After deploying this code, manually uncomment the yarnPath line in .yarnrc.yml:

   Edit .yarnrc.yml and change:

   # yarnPath: .yarn/releases/yarn-3.3.1.cjs

   To:

   yarnPath: .yarn/releases/yarn-3.3.1.cjs

2. DO NOT commit this change!

   This modification should stay local to the deployment server. The pre-commit hook will block it anyway.

3. Before git operations, restore the file:

   git restore .yarnrc.yml

   Then run git pull or git checkout as needed.

4. After git operations, uncomment it again (repeat step 1)

Why This Workflow?

• Legacy servers can't run Yarn 4 (requires newer Node.js)
• Dev machines need Yarn 4 for security features
• By keeping yarnPath commented in git, dev machines work correctly
• By uncommenting locally, legacy servers can use the bundled Yarn 3

Testing Done

• ✅ Pre-commit hook successfully blocks committing uncommented yarnPath
• ✅ Dev machines use Yarn 4.12.0 consistently (including nested commands)
• ✅ No more npmMinimalAgeGate errors when running builds
• ✅ Legacy workflow tested (uncommenting works, uses Yarn 3.3.1)

Why This Matters

For developers: Your build commands will actually work now. No more mysterious Yarn config errors.

For security: Dev machines get the 7-day package age gate (protects against supply chain attacks).

For legacy servers: Nothing breaks - you just have an extra step during deployment (uncomment one line).

Questions?

• "Why not just remove Yarn 3 entirely?" - Legacy servers (like CentOS 7) can't run modern Node/Yarn
• "Why not just use Yarn 3 everywhere?" - We'd lose important security features
• "What if I mess up?" - The pre-commit hook will catch it and block the commit with clear instructions