CCM-16068 - Migration to PNPM (#102)

* CCM-16068 - Migration to PNPM

* CCM-16068 - Removed eslintignore as this is deprecated, eslint ignores are now handled in the eslint config file

* CCM-16068 - Revised AGENTS.md

* CCM-16068 - Update any remaining npm references

Author: rhyscoxnhs

.github/dependabot.yaml

@@ -12,7 +12,7 @@ updates:
     schedule:
       interval: "daily"
 
-  - package-ecosystem: "npm"
+  - package-ecosystem: "pnpm"
     directory: "/"
     schedule:
       interval: "daily"

.github/workflows/stage-2-test.yaml

@@ -47,12 +47,21 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: "Setup pnpm"
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.0
+      - name: "Use Node.js"
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version-file: '.tool-versions'
+          cache: 'pnpm'
       - name: "Repo setup"
         run: |
-          npm ci
+          pnpm install --frozen-lockfile
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          pnpm run generate-dependencies
           git diff --exit-code
   test-unit:
     name: "Unit tests"
@@ -61,12 +70,21 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: "Setup pnpm"
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.0
+      - name: "Use Node.js"
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version-file: '.tool-versions'
+          cache: 'pnpm'
       - name: "Repo setup"
         run: |
-          npm ci
+          pnpm install --frozen-lockfile
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          pnpm run generate-dependencies
       - name: "Run unit test suite"
         run: |
           make test-unit
@@ -89,12 +107,21 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: "Setup pnpm"
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.0
+      - name: "Use Node.js"
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version-file: '.tool-versions'
+          cache: 'pnpm'
       - name: "Repo setup"
         run: |
-          npm ci
+          pnpm install --frozen-lockfile
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          pnpm run generate-dependencies
       - name: "Run linting"
         run: |
           make test-lint
@@ -105,12 +132,21 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: "Setup pnpm"
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.0
+      - name: "Use Node.js"
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version-file: '.tool-versions'
+          cache: 'pnpm'
       - name: "Repo setup"
         run: |
-          npm ci
+          pnpm install --frozen-lockfile
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          pnpm run generate-dependencies
       - name: "Run typecheck"
         run: |
           make test-typecheck

.tool-versions

@@ -1,7 +1,8 @@
 act 0.2.64
 gitleaks 8.24.0
 jq 1.6
-nodejs 22.11.0
+nodejs 24.14.1
+pnpm 10.33.0
 pre-commit 3.6.0
 terraform 1.14.3
 terraform-docs 0.21.0

AGENTS.md

@@ -11,8 +11,9 @@ Keep anything language or tool-specific in nested `AGENTS.md` files (for example
 
 At a glance, the main areas are:
 
+- `pnpm-workspace.yaml` - Defines packages, dependency versions, and package installation options.
 - `infrastructure/terraform/` – Terraform components, and shared modules for AWS accounts and environments.
-- `lambdas/` – TypeScript lambda projects (each with their own `package.json`, Jest config, etc.). Root level packages.json defines workspaces and scripts. Tests for the lambda are stored in `lambdas/{name}/src/__test`.
+- `lambdas/` – TypeScript lambda projects (each with their own `package.json`, Jest config, etc.). Root level packages.json defines scripts. Tests for the lambda are stored in `lambdas/{name}/src/__test`.
 - `src/` and `utils/` – Shared code and utilities (for example `utils/logger`).
 - `docs/` – Documentation site, ADRs, RFCS, and other long‑form docs.
 - `.github/workflows/` and `.github/actions/` – GitHub Actions workflows and composite actions.
@@ -21,27 +22,40 @@ At a glance, the main areas are:
 
 Agents should look for a nested `AGENTS.md` in or near these areas before making non‑trivial changes.
 
+## Root pnpm-workspace.yaml - role and usage
+
+The root `pnpm-workspace.yaml` is the manifest for configuring the pnpm tool, and any workspace packages (if added).
+
+- Packages: Declares the set of workspace packages (e.g. under `lambdas/`, `utils/`, `tests/`, `scripts/`). Agents should add a new package path here when introducing a new workspace package if the packages entry is present.
+- Catalogs: Defines named version catalogs (`lint`, `test`, `tools`) that centralise dependency version ranges. Workspace packages reference these with the `catalog:<name>` protocol (e.g. `"jest": "catalog:test"`) instead of hardcoding version ranges in each `package.json`.
+
+Agent guidance for catalogs:
+
+- When adding a dependency that belongs to an existing catalog category, add the version range to the appropriate catalog in `pnpm-workspace.yaml` and reference it as `"catalog:<name>"` in the consuming `package.json`.
+- Do not hardcode version ranges in workspace `package.json` files for dependencies that already exist in a catalog — always use the `catalog:` protocol.
+- When updating a dependency version, change it in the catalog entry only; all workspace packages referencing that catalog entry will pick up the new version automatically.
+- If a dependency does not fit any existing catalog, create a new catalog with a suitable name and add the version range there. All dependencies must be managed through catalogs — never hardcode version ranges directly in a `package.json`.
+
 ## Root package.json – role and usage
 
-The root `package.json` is the orchestration manifestgit co for this repo. It does not ship application code; it wires up shared dev tooling and delegates to workspace-level projects.
+The root `package.json` is the orchestration manifest for this repo. It does not ship application code; it wires up shared dev tooling and delegates to workspace-level projects.
 
-- Workspaces: Declares the set of npm workspaces (e.g. under `lambdas/`, `utils/`, `tests/`, `scripts/`). Agents should add a new workspace path here when introducing a new npm project.
-- Scripts: Provides top-level commands that fan out across workspaces using `--workspaces` (lint, typecheck, unit tests) and project-specific runners (e.g. `build-archive`).
+- Scripts: Provides top-level commands that fan out across workspaces using `--recursive` / `-r` (lint, typecheck, unit tests) and project-specific runners (e.g. `build-archive`).
 - Dev tool dependencies: Centralises Jest, TypeScript, ESLint configurations and plugins to keep versions consistent across workspaces. Workspace projects should rely on these unless a local override is strictly needed.
 - Overrides/resolutions: Pins transitive dependencies (e.g. Jest/react-is) to avoid ecosystem conflicts. Agents must not remove overrides without verifying tests across all workspaces.
 
 Agent guidance:
 
-- Before adding or removing a workspace, update the root `workspaces` array and ensure CI scripts still succeed with `npm run lint`, `npm run typecheck`, and `npm run test:unit` at the repo root.
-- When adding repo-wide scripts, keep names consistent with existing patterns (e.g. `lint`, `lint:fix`, `typecheck`, `test:unit`, `build-archive`) and prefer `--workspaces` fan-out.
+- Before adding or removing a workspace, update the root `packages` array in `pnpm-workspace.yaml` and ensure CI scripts still succeed with `pnpm run lint`, `pnpm run typecheck`, and `pnpm run test:unit` at the repo root.
+- When adding repo-wide scripts, keep names consistent with existing patterns (e.g. `lint`, `lint:fix`, `typecheck`, `test:unit`, `build-archive`) and prefer `pnpm -r run` fan-out.
 - Do not publish from the root. If adding a new workspace intended for publication, mark that workspace package as `private: false` and keep the root as private.
 - Validate changes by running the repo pre-commit hooks: `make githooks-run`.
 
 Success criteria for changes affecting the root `package.json`:
 
-- `npm run lint`, `npm run typecheck`, and `npm run test:unit` pass at the repo root.
-- Workspace discovery is correct (new projects appear under `npm run typecheck --workspaces`).
-- No regression in lambda build tooling (`npm run build-archive`).
+- `pnpm run lint`, `pnpm run typecheck`, and `pnpm run test:unit` pass at the repo root.
+- Workspace discovery is correct (new projects appear under `pnpm run typecheck`).
+- No regression in lambda build tooling (`pnpm run build:archive`).
 
 ## What Agents Can / Can’t Do
 
@@ -81,7 +95,7 @@ When proposing a change, agents should:
 
   to catch formatting and basic lint issues. Domain specific checks will be defined in appropriate nested AGENTS.md files.
 
-- Suggest at least one extra validation step (for example `npm test` in a lambda, or triggering a specific workflow).
+- Suggest at least one extra validation step (for example `pnpm test` in a lambda, or triggering a specific workflow).
 - Any required follow up activites which fall outside of the current task's scope should be clearly marked with a 'TODO: CCM-12345' comment. The human user should be prompted to create and provide a JIRA ticket ID to be added to the comment.
 
 ## Security & Safety

containers/example-app/build.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 
 rm -rf dist
 
-npx esbuild \
+pnpm exec esbuild \
     --bundle \
     --minify \
     --sourcemap \

containers/example-app/jest.config.ts

@@ -1,7 +1,7 @@
-import type { Config } from 'jest';
+import type { Config } from "jest";
 
 const config: Config = {
-  preset: 'ts-jest',
+  preset: "ts-jest",
 
   // Automatically clear mock calls, instances, contexts and results before every test
   clearMocks: true,
@@ -10,10 +10,10 @@ const config: Config = {
   collectCoverage: true,
 
   // The directory where Jest should output its coverage files
-  coverageDirectory: './.reports/unit/coverage',
+  coverageDirectory: "./.reports/unit/coverage",
 
   // Indicates which provider should be used to instrument code for coverage
-  coverageProvider: 'babel',
+  coverageProvider: "babel",
 
   coverageThreshold: {
     global: {
@@ -24,26 +24,26 @@ const config: Config = {
     },
   },
 
-  coveragePathIgnorePatterns: ['/__tests__/'],
-  transform: { '^.+\\.ts$': 'ts-jest' },
-  testPathIgnorePatterns: ['.build'],
-  testMatch: ['**/?(*.)+(spec|test).[jt]s?(x)'],
+  coveragePathIgnorePatterns: ["/__tests__/"],
+  transform: { "^.+\\.ts$": "ts-jest" },
+  testPathIgnorePatterns: [".build"],
+  testMatch: ["**/?(*.)+(spec|test).[jt]s?(x)"],
 
   // Use this configuration option to add custom reporters to Jest
   reporters: [
-    'default',
+    "default",
     [
-      'jest-html-reporter',
+      "jest-html-reporter",
       {
-        pageTitle: 'Test Report',
-        outputPath: './.reports/unit/test-report.html',
+        pageTitle: "Test Report",
+        outputPath: "./.reports/unit/test-report.html",
         includeFailureMsg: true,
       },
     ],
   ],
 
   // The test environment that will be used for testing
-  testEnvironment: 'node',
+  testEnvironment: "node",
 };
 
 export default config;

containers/example-app/package.json

@@ -1,19 +1,22 @@
 {
   "devDependencies": {
-    "@tsconfig/node22": "^22.0.2",
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.0.0",
-    "jest": "^29.7.0",
-    "jest-mock-extended": "^3.0.7",
-    "typescript": "^5.8.2"
+    "@tsconfig/node22": "catalog:tools",
+    "@types/jest": "catalog:test",
+    "@types/node": "catalog:tools",
+    "jest": "catalog:test",
+    "jest-mock-extended": "catalog:test",
+    "typescript": "catalog:tools"
+  },
+  "engines": {
+    "node": ">=24.14.1"
   },
   "name": "nhs-notify-admail-example-app",
   "private": true,
   "unused-scripts": {
-    "build:archive": "rm -rf dist && npx esbuild --bundle --minify --sourcemap --target=es2020 --platform=node --loader:.node=file --entry-names=[name] --outdir=dist src/index.ts"
+    "build:archive": "rm -rf dist && pnpm exec esbuild --bundle --minify --sourcemap --target=es2020 --platform=node --loader:.node=file --entry-names=[name] --outdir=dist src/index.ts"
   },
   "scripts": {
-    "build:container": "cd ../.. && make docker-build-and-push base_image=node:22-alpine dir=containers/example-app",
+    "build:container": "cd ../.. && make docker-build-and-push base_image=node:24-alpine dir=containers/example-app",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test:unit": "jest",

containers/example-app/src/__tests__/server.test.ts

@@ -1,14 +1,14 @@
-import http from 'node:http';
-import { createRequestHandler, startServer } from '../server';
+import http from "node:http";
+import { createRequestHandler, startServer } from "../server";
 
-describe('example-app server', () => {
-  describe('createRequestHandler', () => {
-    it('returns a request handler function', () => {
+describe("example-app server", () => {
+  describe("createRequestHandler", () => {
+    it("returns a request handler function", () => {
       const handler = createRequestHandler();
-      expect(typeof handler).toBe('function');
+      expect(typeof handler).toBe("function");
     });
 
-    it('responds with 200 status and JSON body', (done) => {
+    it("responds with 200 status and JSON body", () => {
       const handler = createRequestHandler();
       const mockReq = {} as http.IncomingMessage;
       const mockRes = {
@@ -18,44 +18,56 @@ describe('example-app server', () => {
 
       handler(mockReq, mockRes);
 
-      expect(mockRes.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
-      expect(mockRes.end).toHaveBeenCalledWith(JSON.stringify({ status: 'ok' }));
-      done();
+      expect(mockRes.writeHead).toHaveBeenCalledWith(200, {
+        "Content-Type": "application/json",
+      });
+      expect(mockRes.end).toHaveBeenCalledWith(
+        JSON.stringify({ status: "ok" }),
+      );
     });
   });
 
-  describe('startServer', () => {
+  describe("startServer", () => {
     let server: http.Server;
     const port = 8888;
 
-    afterEach((done) => {
-      if (server) {
-        server.close(done);
-      } else {
-        done();
-      }
+    afterEach(async () => {
+      await new Promise<void>((resolve) => {
+        if (server) {
+          server.close(() => {
+            resolve();
+          });
+        } else {
+          resolve();
+        }
+      });
     });
 
-    it('starts server on specified port and responds correctly', (done) => {
+    it("starts server on specified port and responds correctly", async () => {
       server = startServer(port);
 
-      // Wait a bit for server to start
-      setTimeout(() => {
-        http.get(`http://localhost:${port}`, (res) => {
-          expect(res.statusCode).toBe(200);
-          expect(res.headers['content-type']).toBe('application/json');
+      await new Promise<void>((resolve, reject) => {
+        setTimeout(() => {
+          http
+            .get(`http://localhost:${port}`, (res) => {
+              expect(res.statusCode).toBe(200);
+              expect(res.headers["content-type"]).toBe("application/json");
 
-          let body = '';
-          res.on('data', (chunk) => {
-            body += chunk;
-          });
+              let body = "";
+              res.on("data", (chunk: Buffer) => {
+                body += chunk.toString();
+              });
 
-          res.on('end', () => {
-            expect(JSON.parse(body)).toEqual({ status: 'ok' });
-            done();
-          });
-        });
-      }, 100);
+              res.on("end", () => {
+                expect(JSON.parse(body)).toEqual({ status: "ok" });
+                resolve();
+              });
+
+              res.on("error", reject);
+            })
+            .on("error", reject);
+        }, 100);
+      });
     });
   });
 });