feat: centralize Node.js version management with .nvmrc as SSOT (#476)

- Update .nvmrc to v24.11.0 (Node.js 24 LTS/Krypton)
- Add engines field to package.json requiring >=24.11.0
- Configure CI/CD workflows to read from .nvmrc via node-version-file
- Remove hardcoded NODE_VERSION env vars from workflows
- Align .coderabbit.yaml to reference 24.11.0
- Document .nvmrc as single source of truth in AGENTS.md
- Update README.md Prerequisites to reference .nvmrc
- Enhance README.md Features section with detailed descriptions
- Fix Tech Stack table alignment for markdownlint compliance
- Add commit message format guidelines to copilot-instructions.md

Author: nanotaboada

.coderabbit.yaml

@@ -119,7 +119,7 @@ reviews:
     - path: "package.json"
       instructions: |
         - Verify "type": "module" is set (ESM)
-        - Check Node.js version matches LTS/Krypton (24.11.1)
+        - Check Node.js version matches LTS/Krypton (24.11.0)
         - Ensure scripts are correctly defined
         - Validate dependencies are up to date
         - Check that test script uses NODE_OPTIONS for experimental VM modules

.github/copilot-instructions.md

@@ -19,6 +19,10 @@
 - **Async**: All I/O operations use async/await
 - **Testing**: Jest with ESM experimental VM modules
 - **Formatting**: Prettier (4 spaces, single quotes, 127 width)
+- **Commit Messages**: Follow Conventional Commits with issue number suffix
+  - Format: `type(scope): description (#issue)` (max 80 chars)
+  - Types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`
+  - Example: `feat(api): add player search endpoint (#123)`
 
 ## 🏗️ Architecture at a Glance
 

.github/workflows/node-cd.yml

@@ -10,7 +10,6 @@ on:
       - "v*.*.*-*"
 
 env:
-  NODE_VERSION: "lts/krypton"
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
@@ -29,7 +28,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6.2.0
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version-file: ".nvmrc"
           cache: "npm"
           cache-dependency-path: package-lock.json
 

.github/workflows/node-ci.yml

@@ -9,9 +9,6 @@ on:
   pull_request:
     branches: [master]
 
-env:
-  NODE_VERSION: "lts/krypton"
-
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -26,7 +23,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6.2.0
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version-file: ".nvmrc"
           cache: "npm"
           cache-dependency-path: package-lock.json
 
@@ -53,7 +50,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6.2.0
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version-file: ".nvmrc"
           cache: "npm"
           cache-dependency-path: package-lock.json
 

.nvmrc

@@ -1 +1 @@
-v22.15.0
+v24.11.0

AGENTS.md

@@ -29,9 +29,36 @@ npm start
 
 ## Node.js Version
 
-This project requires **Node.js 24 (LTS/Krypton)** specified in `.nvmrc`.
+This project uses **`.nvmrc` as the single source of truth** for Node.js version management.
 
-If using nvm, asdf, or mise, the correct version activates automatically. Otherwise, ensure Node.js 24 is installed.
+**Current version:** Node.js 24.11.0 (LTS/Krypton)
+
+**Philosophy:** This project tracks the latest Node.js LTS release. The specific version is always defined in `.nvmrc`.
+
+### How It Works
+
+- **Local development:** Version managers (nvm, asdf, mise) auto-activate from `.nvmrc`
+- **CI/CD pipelines:** GitHub Actions reads version using `node-version-file: '.nvmrc'`
+- **Version enforcement:** `package.json` engines field requires `>=24.11.0`
+- **Docker:** Uses `node:krypton-alpine` base image (aligned with Node.js 24)
+
+### Updating Node.js Version
+
+To update the Node.js version project-wide:
+
+1. Edit `.nvmrc` with the new version (e.g., `v24.12.0`)
+2. Update `package.json` engines field if minimum version changes
+3. Test locally and in CI/CD
+4. Commit changes
+
+**That's it!** No need to update workflow files - they automatically read from `.nvmrc`.
+
+### Benefits
+
+- **Consistency:** Same version across local dev, CI, and CD environments
+- **Maintainability:** Single file to update, no version duplication
+- **Developer experience:** Auto-activation eliminates manual version switching
+- **Enforcement:** npm warns if Node.js version requirement isn't met
 
 ## Development Workflow
 

README.md

@@ -28,33 +28,31 @@ Proof of Concept for a RESTful API made with [Node.js](https://nodejs.org/) [LTS
 
 ## Features
 
-- 🔌 RESTful CRUD operations for football player data
-- 💿 Relational database with ORM
-- ⚡ In-memory caching (1-hour TTL)
-- 📚 Interactive API documentation
-- 🔒 Security headers and CORS
-- 🩺 Health check endpoint for monitoring
-- ✅ Comprehensive integration tests
-- 🐳 Full containerization support
-- 📃 TypeScript strict mode enabled
-- 🔄 Hot reload for development
+- 🏗️ **Modern TypeScript architecture** - Native ESM, strict mode, layered architecture with interface-based contracts
+- 📚 **Interactive API exploration** - Auto-generated OpenAPI docs with Swagger UI and Postman collection
+- ⚡ **Performance optimizations** - In-memory caching with node-cache, Sequelize ORM, and efficient SQLite operations
+- 🧪 **Comprehensive integration tests** - Full endpoint coverage with Jest/Supertest and automated reporting to Codecov
+- 📖 **Token-efficient documentation** - AGENTS.md + auto-loaded Copilot instructions for AI-assisted development
+- 🐳 **Full containerization** - Multi-stage Docker builds with Docker Compose orchestration
+- 🔄 **Complete CI/CD pipeline** - Automated linting (ESLint/Prettier), testing, Docker publishing, and GitHub releases
+- ⚽ **Football-themed semantic versioning** - Memorable, alphabetical release names using football terminology
 
 ## Tech Stack
 
-| Category             | Technology |
-|----------------------|------------|
-| **Runtime**          | [Node.js 24 (LTS/Krypton)](https://github.com/nodejs/node) |
-| **Language**         | [TypeScript 5.9](https://github.com/microsoft/TypeScript) |
-| **Module System**    | Native ECMAScript Modules (ESM) - uses [tsx](https://github.com/privatenumber/tsx) for execution |
-| **Framework**        | [Express.js 5](https://github.com/expressjs/express) |
-| **Database**         | [SQLite3](https://github.com/sqlite/sqlite) with [Sequelize ORM](https://github.com/sequelize/sequelize) |
-| **Caching**          | [node-cache](https://github.com/node-cache/node-cache) |
-| **Documentation**    | [Swagger (OpenAPI 3.0)](https://github.com/swagger-api/swagger-ui) |
-| **Security**         | [Helmet](https://github.com/helmetjs/helmet), [CORS](https://github.com/expressjs/cors) |
-| **Testing**          | [Jest 30](https://github.com/jestjs/jest) with [Supertest](https://github.com/ladjs/supertest) |
-| **Containerization** | [Docker](https://github.com/docker) with multi-stage builds |
-| **Code Quality**     | [ESLint](https://github.com/eslint/eslint), [Prettier](https://github.com/prettier/prettier), [Commitlint](https://github.com/conventional-changelog/commitlint) |
-| **Dev Tools**        | [tsx](https://github.com/privatenumber/tsx) (TypeScript executor), [nodemon](https://github.com/remy/nodemon) |
+| Category               | Technology                                                                                                                   |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| **Runtime**            | [Node.js 24 (LTS/Krypton)](https://github.com/nodejs/node)                                                                  |
+| **Language**           | [TypeScript 5.9](https://github.com/microsoft/TypeScript)                                                                   |
+| **Module System**      | Native ECMAScript Modules (ESM) - uses [tsx](https://github.com/privatenumber/tsx) for execution                           |
+| **Framework**          | [Express.js 5](https://github.com/expressjs/express)                                                                        |
+| **Database**           | [SQLite3](https://github.com/sqlite/sqlite) with [Sequelize ORM](https://github.com/sequelize/sequelize)                   |
+| **Caching**            | [node-cache](https://github.com/node-cache/node-cache)                                                                      |
+| **Documentation**      | [Swagger (OpenAPI 3.0)](https://github.com/swagger-api/swagger-ui)                                                          |
+| **Security**           | [Helmet](https://github.com/helmetjs/helmet), [CORS](https://github.com/expressjs/cors)                                     |
+| **Testing**            | [Jest 30](https://github.com/jestjs/jest) with [Supertest](https://github.com/ladjs/supertest)                             |
+| **Containerization**   | [Docker](https://github.com/docker) with multi-stage builds                                                                 |
+| **Code Quality**       | [ESLint](https://github.com/eslint/eslint), [Prettier](https://github.com/prettier/prettier), [Commitlint](https://github.com/conventional-changelog/commitlint) |
+| **Dev Tools**          | [tsx](https://github.com/privatenumber/tsx) (TypeScript executor), [nodemon](https://github.com/remy/nodemon)              |
 
 > 💡 **Note:** While the repository name references `ts-node` (the original implementation), the project now uses [tsx](https://github.com/privatenumber/tsx) for faster, cleaner TypeScript execution without experimental flags.
 
@@ -170,7 +168,7 @@ For complete endpoint documentation with request/response schemas, explore the [
 
 Before you begin, ensure you have the following installed:
 
-- Node.js 24 (LTS/Krypton) or higher
+- Node.js (latest LTS - specific version in `.nvmrc`)
 - npm (comes with Node.js)
 - Docker and Docker Compose (optional, for containerized setup)
 

package.json

@@ -20,6 +20,9 @@
   "keywords": [],
   "author": "Nano Taboada",
   "license": "MIT",
+  "engines": {
+    "node": ">=24.11.0"
+  },
   "dependencies": {
     "body-parser": "^2.2.2",
     "cors": "^2.8.6",