Legacy deployment mode

[bobular]

Bob's commentary

Our dev server has Centos 7 which can't run Node 20+

This means that Corepack and Yarn 4.12.0 can't be used on the dev server.

I originally removed the bundled yarn-3.3.1 from web-monorepo so that we were forced to get yarn via corepack.

We need that bundled version back so it can be used on the dev server, configured via yarnPath in .yarnrc.yml

We would normally abort any yarn operations if the version is not 4.12.0 but by setting SKIP_YARN_VERSION_CHECK=true on the dev server, we can skip that check.

But then when we're not skipping the check, we want to ignore yarnPath on our local dev machines where we have the ability to run Node 24 and Yarn 4.12.0, so some environment variables are needed to override this (YARN_IGNORE_PATH=true) and we can't set the npmMinimalAgeGate variable in .yarnrc.yml because Yarn 3 will complain about the unknown directive! So we provide this on local dev machines with YARN_NPM_MINIMAL_AGE_GATE=10080. The tools/scripts/check-package-manager.mjs now checks for these two env vars in dev.

It's all documented in README.adoc :-)

---

Testing

• On palm my dev site rebuilds with wb site with locally checked-out web-monorepo on this branch and the environment variables as described here: https://github.com/VEuPathDB/web-monorepo/blob/legacy-deployment-mode/README.adoc#deployment-on-legacy-systems (use main branch if this link goes stale after merge)
• GitHub CI (pr_check.yml) works for changes to tooling/docs.
• TO DO: GitHub CI works for actual code changes (test after merge, or make a small commit to some source code, e.g. a comment) - not urgent - should be fine - let's just see what happens after this is merged.
• Make a release from this branch and check that a Jenkins qa site builds (can revert this on success) - this worked fine for qa.trichdb.org using a temporary release - Jenkins doesn't need any special new config because it's not running any yarn stuff.

---

Claude summary

Complete Solution Summary

We've successfully implemented a comprehensive dual-mode Yarn setup with multiple layers of protection:

✅ Files Modified/Created:

1. tools/scripts/check-package-manager.mjs
   - Added SKIP_YARN_VERSION_CHECK bypass for legacy deployments
   - Added validation for YARN_IGNORE_PATH and YARN_NPM_MINIMAL_AGE_GATE
2. tools/scripts/check-yarn-lockfile.sh (new)
   - Pre-commit validation to block Yarn 3 lockfile commits
3. .husky/pre-commit
   - Added lockfile version check before lint-staged
4. .yarnrc.yml
   - Added yarnPath for Yarn 1 → Yarn 3 bootstrap
   - Removed npmMinimalAgeGate (moved to env var)
5. .yarn/releases/yarn-3.3.1.cjs
   - Bundled Yarn 3.3.1 for legacy deployments (had removed this in the initial "hardening")
6. README.adoc
   - Complete documentation for both modes
   - Documentation for direnv for developers
7. GitHub actions
   - added YARN_NPM_MINIMAL_AGE_GATE: 10080
   - removed yarnPath with sed (YARN_IGNORE_PATH=1 did not work for some mysterious reason)
   - this ensures that yarn 4.12.0 runs the build with the age gate, and the immutable lockfile setting is applied too. (though the age gate only really applies when modifying the lockfile with yarn add etc)

✅ Protection Layers:

1. Preinstall check - Validates env vars are set correctly
2. Environment variables - Different configs for dev vs deployment
3. Pre-commit hook - Prevents accidental Yarn 3 lockfile commits

✅ Tested & Verified:

• ✅ Dev machines use Yarn 4 with YARN_IGNORE_PATH=true
• ✅ CentOS 7 uses Yarn 3 via yarnPath setting
• ✅ Ant build on CentOS 7 works (calls yarn from PATH)
• ✅ Pre-commit hook blocks Yarn 3 lockfile commits
• ✅ All environment variable overrides work
• ✅ GitHub Actions configured