Modernize runtime tooling and upgrade dependencies

.github/workflows/codeql.yml

@@ -38,11 +38,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -53,7 +53,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v3
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -67,4 +67,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3

.github/workflows/netlify-api-test.yml

@@ -9,12 +9,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - name: Use Node.js 16.x
-        uses: actions/setup-node@v3
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@v4
         with:
-          node-version: "16"
+          node-version: "22"
 
       - name: Install
         run: |
@@ -31,6 +31,10 @@ jobs:
         run: yarn run build:netlify
 
       - name: Test Netlify functions
+        env:
+          # @shelf/jest-mongodb's bundled mongodb-memory-server version in this repo
+          # does not support MONGOMS_DISTRO; pin a known-valid download URL instead.
+          MONGOMS_DOWNLOAD_URL: https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu2204-6.0.14.tgz
         run: |
           node ./scripts/createTestEnv.mjs 
-          yarn test
+          yarn test:backend

.nvmrc

@@ -1 +1 @@
-18.12.1
+22.22.0

AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md
+
+Status: active
+
+Scope: entire repository
+
+This file defines contributor and agent governance for this project.
+
+## Project Deliverable
+
+The deliverable is **Simple Comment**, a web comment platform with:
+
+- Netlify Functions backend
+- Svelte frontend embed/client
+- MongoDB persistence
+- OpenAPI-described HTTP API contracts
+
+## Execution Model
+
+This repository follows a phase workflow:
+
+1. Plan
+2. Implement
+3. PR
+4. Merge
+5. Re-plan next phase
+
+Reference: `docs/plans/README.md`
+
+## Approval and Entry Conditions
+
+Discussion does not imply implementation.
+
+Implementation may begin only when there is an approved checklist (or checklist-equivalent section) authored under `docs/norms/checklist.md` conventions, for example:
+
+- an approved phase plan in `docs/plans/` that includes executable checklist items
+- an approved checklist document
+- explicit maintainer instruction in issue/PR/thread that includes executable checklist items
+
+If no approved checklist exists, stop and request one.
+
+`docs/norms/implementation.md` is invoked only after checklist approval.
+
+## Change Controls
+
+### No silent behavior changes
+
+Before making changes that alter behavior, architecture, public contracts, dependencies, or determinism:
+
+- summarize the intended change
+- identify affected files/surfaces
+- confirm scope alignment with the approved checklist/phase
+
+### Call out conflicts
+
+If a request conflicts with merged code behavior, documented contracts, or approved phase scope:
+
+- state the conflict
+- explain impact/risk
+- ask for direction before proceeding
+
+### Keep phases isolated
+
+- One phase per PR.
+- No unrelated refactors in phase PRs.
+- Track implementation and validation evidence in the phase/PR narrative.
+- New work branches must use the intent pattern `<verb>-<optionalAdj>-<noun>` in lowercase kebab-case.
+
+## Norms Integration
+
+- Checklist authoring rules: `docs/norms/checklist.md`
+- Implementation loop and testing expectations: `docs/norms/implementation.md`
+- Program-level phase constraints: `docs/plans/README.md`
+
+If these documents conflict, escalate and request clarification before implementation.
+
+## Source of Truth
+
+- Merged code and tests on `master` are authoritative.
+- OpenAPI/schema and policy files define expected API-level behavior.
+- Planning docs define approved scope and sequencing; they do not override merged runtime behavior without an explicit implementation phase.
+
+## Implementation Style (Repository-Aligned)
+
+- Prefer TypeScript for new code.
+- Default style inside modules: functional-first, arrow functions over function declarations, and array methods over imperative loops when readability is equal or better.
+- Preserve existing architecture boundaries. In this repo, class-based service abstractions (for extensibility/injection, e.g. DB service interfaces) are intentional and should not be refactored unless explicitly in scope.
+- Preserve existing module/tooling conventions where required (for example, existing CommonJS build configs).
+- Keep code and commits scoped and reviewable.

docs/norms/checklist.md

@@ -0,0 +1,38 @@
+# Checklist Conventions
+
+Use this guide when writing implementation checklists.
+
+Goal: make checklists clear enough that another engineer can execute them without hidden assumptions.
+
+## Item Quality
+
+Each checklist item should be:
+
+- Atomic (one behavior change per item).
+- Imperative (clear action verb).
+- Checkable (easy to tell when done).
+- Scoped (prefix with a tag like `[backend]`, `[docs]`, `[frontend]`).
+
+If code changes are involved, name exact files/functions.
+
+If an item depends on another, state that dependency explicitly.
+
+## Exclusions
+
+Unless a task explicitly requests testing steps, do not include test-writing/execution steps in the checklist itself.
+
+## Behavior Slices
+
+After atomic items, add a `## Behavior Slices` section to group execution bundles.
+
+For each slice include:
+
+- `Goal`: one coherent behavior outcome.
+- `Items`: exact checklist items covered by that slice.
+- `Type`: `behavior` or `mechanical`.
+
+Rules:
+
+- Every checklist item belongs to exactly one slice.
+- Slices must remain within approved scope.
+- Slices do not replace atomic items; they organize them.

docs/norms/implementation.md

@@ -0,0 +1,44 @@
+# Implementation Conventions
+
+Use this as a practical execution guide when implementing an approved checklist.
+
+Implementation is step 2 of a lightweight 2-step process:
+
+1. Create/approve a checklist using `docs/norms/checklist.md`.
+2. Execute that checklist using this document.
+
+If there is no approved checklist created under `docs/norms/checklist.md` conventions, stop and ask.
+
+## Start State
+
+- Run relevant tests to understand baseline behavior.
+- Check `git status`.
+- If unrelated files are dirty and scope is unclear, pause and confirm before proceeding.
+- Checkout a new branch named as `<verb>-<optionalAdj>-<noun>` to describe intent.
+  - This pattern is mandatory for new work branches.
+  - Use lowercase kebab-case tokens.
+  - Examples: `fix-auth-cookie`, `upgrade-core-dependencies`, `refactor-comment-pipeline`.
+
+## Working Loop
+
+1. Take the first incomplete checklist item (or its required prerequisite).
+2. Group dependent items into one behavior slice when they form one coherent change.
+3. Implement the slice.
+4. Run targeted tests for touched scope.
+5. Run broader/full tests at natural checkpoints.
+6. Mark completed checklist items.
+7. Commit with a short, imperative message.
+
+## Commit Hygiene
+
+- Keep commits scoped to the current slice.
+- Avoid bundling unrelated file changes.
+- Keep message lines concise and descriptive.
+
+## Stop Conditions
+
+Pause and confirm direction when:
+
+- Proposed changes exceed checklist scope.
+- Governance or contract references conflict.
+- You find unexpected repo state that could risk unrelated work.

docs/plans/README.md

@@ -27,16 +27,16 @@ Confirmed runtime logic defects are then handled in Phase 2.
 ## Current baseline (observed)
 
 - Runtime/tooling:
-  - Node pinned to `18.12.1` in `.nvmrc`.
-  - CI workflow uses Node `16` in `.github/workflows/netlify-api-test.yml`.
+  - Node pinned to `22.22.0` in `.nvmrc`.
+  - CI workflow uses Node `22` in `.github/workflows/netlify-api-test.yml`.
   - Yarn classic (`1.22.x`) lockfile.
   - Svelte `^3.0.0`, Webpack 5 custom frontend and functions bundling.
 - Lint:
   - `yarn lint` passes.
   - ESLint config is legacy `.eslintrc` format in `src/.eslintrc.json`.
 - Tests:
   - `yarn test:backend` fails locally without `.env` and with import-time env validation.
-  - `yarn test:frontend` has locale-string assertion failures and `ts-jest` deprecation warnings.
+  - `yarn test:frontend` has locale-string assertion failures across ICU/CLDR variants.
 
 ---
 
@@ -73,8 +73,8 @@ Confirmed runtime logic defects are then handled in Phase 2.
 7. Frequent string throws for env/runtime failures.
    - Present across functions and libs (example: `src/lib/backend-utilities.ts:36`, `src/functions/auth.ts:23`).
 
-8. ts-jest deprecation warning.
-   - `jest.frontend.config.ts:20` sets deprecated `isolatedModules` in transformer options.
+8. (Resolved in Phase 01) ts-jest deprecation warning.
+   - `isolatedModules` was moved to tsconfig-based configuration during Phase 01 implementation.
 
 ---
 
@@ -97,4 +97,5 @@ Confirmed runtime logic defects are then handled in Phase 2.
   - Implementation notes
   - Validation evidence
   - Rollback approach
+- Validation evidence is mandatory, but test steps do not need to appear as atomic checklist items when `docs/norms/checklist.md` exclusions apply; execution/testing is governed by `docs/norms/implementation.md`.
 - Keep release notes per phase in the PR description.

docs/plans/phase-01-checklist.md

@@ -0,0 +1,47 @@
+# Phase 01 Checklist - Dependency and Platform Upgrade
+
+Source plan: `docs/plans/phase-01-dependency-and-platform-upgrade.md`
+
+## Checklist
+
+- [x] C01 `[governance]` Confirm this checklist remains within approved Phase 01 scope in `docs/plans/phase-01-dependency-and-platform-upgrade.md`.
+- [x] C02 `[runtime]` Select the target Node major using Phase 01 fallback rules (`latest LTS -> 22 -> 20`) and record the decision rationale in the Phase 01 PR notes.
+- [x] C03 `[runtime]` Update `.nvmrc` to the selected Node major. Depends on: C02.
+- [x] C04 `[ci]` Update `.github/workflows/netlify-api-test.yml` to use the selected Node major. Depends on: C02.
+- [x] C05 `[ci]` Upgrade GitHub Actions versions used in `.github/workflows/netlify-api-test.yml` and `.github/workflows/codeql.yml` to supported current majors. Depends on: C02.
+- [x] C06 `[config]` Resolve the deprecated ts-jest `isolatedModules` configuration path by updating `jest.frontend.config.ts` and/or `tsconfig.frontend.json` to remove deprecation warnings.
+- [x] C07 `[audit]` Capture baseline audit output using `yarn audit --json` and record where the output is stored/referenced in Phase 01 PR notes.
+- [x] C08 `[deps-loop]` Select the next dependency upgrade unit from audit findings using severity/reachability and dependency-coupling criteria (for example test, lint, build/platform families). Depends on: C07.
+- [x] C09 `[deps-loop]` Add/adjust tests for the selected dependency unit only when behavior risk is non-trivial. Depends on: C08.
+- [x] C10 `[deps-loop]` Upgrade only the selected dependency unit in `package.json` and `yarn.lock` as one isolated change. Depends on: C08.
+- [x] C11 `[deps-loop]` Run validation for the selected unit (`yarn lint`, targeted scope checks, and full test checks required by this phase); if checks fail, resolve before commit. Depends on: C10.
+- [x] C12 `[deps-loop]` Commit the isolated dependency unit change with an intent-revealing dependency commit message. Depends on: C11.
+- [x] C13 `[deps-loop]` Repeat C08-C12 until the Phase 01 stop conditions in `docs/plans/phase-01-dependency-and-platform-upgrade.md` are satisfied. Depends on: C07.
+- [x] C14 `[docs]` Update Node/tooling version references in `README.md` and any other modified docs to match the selected Node major. Depends on: C02, C13.
+- [x] C15 `[docs]` Record final Phase 01 compatibility notes, pinned-version rationale, audit delta summary, loop iteration summary, and fallback decision outcome in PR phase notes. Depends on: C13.
+
+## Behavior Slices
+
+- Goal: Establish approved execution boundary and Node target.
+  Items: C01, C02
+  Type: mechanical
+
+- Goal: Align repository and CI runtime baseline to the selected Node major.
+  Items: C03, C04
+  Type: mechanical
+
+- Goal: Modernize CI action runtime/tooling wrappers.
+  Items: C05
+  Type: mechanical
+
+- Goal: Remove known deprecation configuration in test tooling.
+  Items: C06
+  Type: mechanical
+
+- Goal: Execute dependency upgrades in iterative, isolated loop slices until Phase 01 stop conditions are met.
+  Items: C07, C08, C09, C10, C11, C12, C13
+  Type: mechanical
+
+- Goal: Synchronize documentation and phase evidence with final implementation state.
+  Items: C14, C15
+  Type: mechanical