Merge branch 'main' into feature/CCM-12616_mesh_poll_retrieve

Author: lapenna-bjss

.github/CODEOWNERS

@@ -8,6 +8,9 @@
 *.code-workspace            @NHSDigital/nhs-notify-digital-letters-admins
 /infrastructure/terraform/  @NHSDigital/nhs-notify-platform
 
+# Root level AGENTS.md owned by platform.
+AGENTS.md                   @NHSDigital/nhs-notify-platform
+
 # Codeowners must be final check
 /.github/CODEOWNERS         @NHSDigital/nhs-notify-code-owners
 /CODEOWNERS                 @NHSDigital/nhs-notify-code-owners

.github/actions/acceptance-tests/action.yaml

@@ -30,6 +30,11 @@ runs:
       run: |
         npm ci
 
+    - name: "Generate dependencies"
+      shell: bash
+      run: |
+        npm run generate-dependencies
+
     - name: Run test - ${{ inputs.testType }}
       shell: bash
       run: |

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

@@ -57,7 +57,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
           git diff --exit-code
   test-unit:
     name: "Unit tests"
@@ -75,7 +75,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
       - name: "Run unit test suite"
         run: |
           make test-unit
@@ -115,7 +115,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
       - name: "Run linting"
         run: |
           make test-lint
@@ -131,7 +131,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
       - name: "Run typecheck"
         run: |
           make test-typecheck

.github/workflows/stage-3-build.yaml

@@ -44,40 +44,3 @@ jobs:
         uses: ./.github/actions/build-docs
         with:
           version: "${{ inputs.version }}"
-
-
-
-  # artefact-1:
-  #   name: "Artefact 1"
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 3
-  #   steps:
-  #     - name: "Checkout code"
-  #       uses: actions/checkout@v5
-  #     - name: "Build artefact 1"
-  #       run: |
-  #         echo "Building artefact 1 ..."
-  #     - name: "Check artefact 1"
-  #       run: |
-  #         echo "Checking artefact 1 ..."
-  #     - name: "Upload artefact 1"
-  #       run: |
-  #         echo "Uploading artefact 1 ..."
-  #         # Use either action/cache or action/upload-artifact
-  # artefact-n:
-  #   name: "Artefact n"
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 3
-  #   steps:
-  #     - name: "Checkout code"
-  #       uses: actions/checkout@v5
-  #     - name: "Build artefact n"
-  #       run: |
-  #         echo "Building artefact n ..."
-  #     - name: "Check artefact n"
-  #       run: |
-  #         echo "Checking artefact n ..."
-  #     - name: "Upload artefact n"
-  #       run: |
-  #         echo "Uploading artefact n ..."
-  #         # Use either action/cache or action/upload-artifact

AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md
+<!-- vale off -->
+
+## Scope
+
+This file is for **AI agents** working within NHS Notify repositories.
+Humans should read `README.md` and the docs for how we actually work day to day.
+Keep anything language or tool-specific in nested `AGENTS.md` files (for example under `infrastructure/terraform` or `lambdas`).
+
+## Repository Layout (high level)
+
+At a glance, the main areas are:
+
+- `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`.
+- `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.
+- `scripts/` – Helper scripts and tooling used by humans and workflows.
+- `tests/` – Cross‑cutting tests and harnesses for the repo.
+
+Agents should look for a nested `AGENTS.md` in or near these areas before making non‑trivial changes.
+
+## 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.
+
+- 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. `lambda-build`).
+- 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`, `lambda-build`) and prefer `--workspaces` 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 lambda-build`).
+
+## What Agents Can / Can’t Do
+
+Agents **can**:
+
+- Propose changes to code, tests, GitHub workflows, Terraform, and docs.
+- Suggest new scripts, Make targets, or composite actions by copying existing patterns.
+- Run tests to validate proposed solutions.
+
+Agents **must not**:
+
+- Create, push, or merge branches or PRs.
+- Introduce new technologies, providers, or big architectural patterns without clearly calling out that an ADR is needed.
+- Invent secrets or hard‑code real credentials anywhere.
+
+## Working With This Repo
+
+- All dependencies can be setup using the command `make config` from the repository root.
+- **Don’t guess commands.** Derive them from what’s already here or ask for guidance form the human user:
+  - Prefer `Makefile` targets, `scripts/`, `.github/workflows/`, and `.github/actions/`.
+- For Terraform, follow `infrastructure/terraform/{components,modules}` and respect `versions.tf`.
+- Keep diffs small and focused. Avoid mixing refactors with behaviour changes unless you explain why.
+
+## Quality Expectations
+
+When proposing a change, agents should:
+
+- Keep code formatted and idiomatic (Terraform, TypeScript, Bash, YAML).
+- Stick to existing patterns where available (for example `utils/logger`, composite actions under `.github/actions`).
+- Use available information on best practices within the specific area of the codebase.
+- **Always** run local pre-commit hooks from the repo root with:
+
+  ```sh
+    pre-commit run \
+    --config scripts/config/pre-commit.yaml
+  ```
+
+  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).
+- 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
+
+- All agent-generated changes **must** be reviewed and merged by a human.
+- Provide a concise, clear summary of the proposed changes to make human review easier (what changed, why (refer directly to the guidance in relevant Agents.MD files when applicable), and how it was validated). It should be directly pastable into the PR description and make it clear that AI assistance was used.
+- Never output real secrets or tokens. Use placeholders and rely on the GitHub/AWS secrets already wired into workflows.
+
+## Escalation / Blockers
+
+If you are blocked by an unavailable secret, unclear architectural constraint, missing upstream module, or failing tooling you cannot safely fix, stop and ask a single clear clarifying question rather than guessing.

Makefile

@@ -17,13 +17,16 @@ dependencies:: # Install dependencies needed to build and test the project @Pipe
 	$(MAKE) -C utils/metric-publishers install
 	$(MAKE) -C utils/event-publisher-py install
 	$(MAKE) -C utils/py-mock-mesh install
+	$(MAKE) generate
 	npm install --workspaces
 
 dependencies-docs:: # Install documentation dependencies @Pipeline
 	$(MAKE) -C docs install
 
 build: dependencies-docs # Build the project artefact @Pipeline
-	$(MAKE) -C docs build
+
+generate: # Generate any autogenerated output @Pipeline
+	npm run generate-dependencies
 
 debug:
 	$(MAKE) -C docs debug
@@ -45,7 +48,7 @@ clean:: # Clean-up project resources (main) @Operations
 	$(MAKE) -C utils/event-publisher-py clean
 	$(MAKE) -C utils/py-mock-mesh clean
 	rm -f .version
-	# TODO: Implement project resources clean-up step
+	npm run clean
 
 config:: _install-dependencies version dependencies # Configure development environment (main) @Configuration
 
@@ -62,5 +65,5 @@ ${VERBOSE}.SILENT: \
 	build \
 	clean \
 	config \
-	dependencies \
+	generate \
 	deploy \

README.md

@@ -33,7 +33,7 @@ Clone the repository
 ```shell
 git clone https://github.com/NHSDigital/nhs-notify-digital-letters.git
 cd nhs-notify-digital-letters
-code protject.code-workspace
+code project.code-workspace
 ```
 
 Reopen with container
@@ -76,6 +76,10 @@ Installation and configuration of the toolchain dependencies
 make config
 ```
 
+Note that the `make config` command will also build the flattened event schemas and auto-generate a Typescript
+type and JS validator code for each event. See the [typescript-schema-generator](src/typescript-schema-generator/)
+package for more details.
+
 ## Usage
 
 ### Testing

docs/Makefile

@@ -43,7 +43,6 @@ build: clean build-schemas copy-schema-docs copy-schema-yaml-docs copy-schemas b
 
 build-ci: build-schemas-ci copy-schema-docs copy-schema-yaml-docs copy-schemas build-eventcatalog build-docs show-build-output
 
-
 build-eventcatalog:
 	$(MAKE) build-eventcatalog-prereq
 	make -C $(EVENT_CAT_ROOT_DIR) build BASE_URL=$(EVENT_CAT_URL)

docs/architecture/c4/notifhir/mesh/acknowledger/index.md

@@ -0,0 +1,14 @@
+---
+
+title: MESH Acknowledger
+parent:  MESH Services
+nav_order: 4
+has_children: true
+last_modified_date: 2024-10-28
+owner: Tom D'Roza
+author: Tom D'Roza
+diagrams: [c4code-mesh-acknowledger]
+events-raised: [mesh-inbox-message-acknowledged]
+events-consumed: [mesh-inbox-message-downloaded]
+c4type: code
+---

docs/architecture/c4/notifhir/printer/sendtoprint/index.md

@@ -0,0 +1,15 @@
+---
+
+title: Send letter to print
+parent:  Print Supplier Services
+nav_order: 9
+has_children: false
+is_not_draft: false
+last_modified_date: 2025-12-04
+owner: Ross Buggins
+author: Tom D'Roza
+diagrams: []
+events-raised: [external-supplier-api-letter-prepared]
+events-consumed: [queue-item-dequeued]
+c4type: code
+---