to main

.circleci/config.yml

@@ -2,11 +2,21 @@ version:  2.1
 jobs:
   build:
     docker:
-      # Node 24.18 (engines/.nvmrc) — matching browsers image.
-      - image: cimg/node:24.18-browsers
+      # Node 24.19 (engines/.nvmrc) — matching browsers image.
+      - image: cimg/node:24.19.0-browsers
     working_directory: ~/repo
     steps:
       - checkout
+      - run:
+          name:        PR base branch verification (main requires dev head)
+          command:     |
+            TARGET="${CIRCLE_TARGET_BRANCH:-${GITHUB_BASE_REF:-}}"
+            SOURCE="${CIRCLE_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+            if [ -n "$TARGET" ] && [ "$TARGET" = "main" ] && [ "$SOURCE" != "dev" ]; then
+              echo "FAIL: PRs targeting main must originate from dev branch (got: $SOURCE)." >&2
+              exit 1
+            fi
+            echo "OK: PR base/head branch verification passed (Target: ${TARGET:-default}, Source: $SOURCE)"
       - run:
           name:        Test install
           command:     'npm install --ignore-scripts'

.jscpd.json

@@ -0,0 +1,15 @@
+{
+  "threshold": 5,
+  "reporters": ["console"],
+  "absolute": true,
+  "gitignore": true,
+  "format": ["typescript", "tsx", "javascript", "jsx"],
+  "ignore": [
+    "**/*.spec.tsx",
+    "**/*.spec.ts",
+    "**/*.test.*",
+    "**/node_modules/**",
+    "**/build/**",
+    "**/coverage/**"
+  ]
+}

.nvmrc

@@ -1 +1 @@
-24.18.0
+24.19.0

AGENTS.md

@@ -1,7 +1,25 @@
 # Repository Guidelines for WebJamSocketCluster
 
+
+## Cross-AI hard rules
+
+The cross-AI hard rules that bind every agent on every surface are NOT duplicated here. They live
+in exactly one file: `docs/cross-ai-rules.md` in the **`web-jam-tools` repository**, which normally
+sits alongside this repository — `../web-jam-tools/docs/cross-ai-rules.md`, and on Josh's laptop
+`/home/joshua/WebJamApps/web-jam-tools/docs/cross-ai-rules.md`.
+
+Read that file before acting. If you cannot find it, STOP and say so — do not proceed without the
+rules and do not reconstruct them from memory or from this file.
+
 ## TypeScript & Type Safety
 - **No `any`**: `@typescript-eslint/no-explicit-any` is set to `'error'`. Do not disable this rule or use `: any` or `as any`.
 - **Shared Domain Types**: Centralized types for socket connections, streams, payloads, and domain objects live in `src/types/index.ts`.
 - **Mongoose Generic Facade**: Model facades extend `Facade<T>` defined in `src/lib/facade.ts`. When typing generic model methods, use double type assertions (e.g. `(await ... as unknown) as T[]`) to satisfy Mongoose generic method signatures without using `any`.
 - **SocketCluster Mocks**: When mocking `AGServer` or `IClient` in tests, cast stub objects using `as unknown as socketClusterServer.AGServer` or `as unknown as IClient`. Ensure `receiver.next()` mocks return `{ value?: T; done?: boolean }`.
+
+## Memory & Security Audits
+- **Snyk Failures & Resolution via `npm audit fix`**: PR checks may report failure on `security/snyk` due to transitive dependency vulnerabilities. Running `npm audit fix` updates `package-lock.json` with non-breaking patches to resolve these vulnerabilities. Always run local tests afterwards to verify the test suite remains 100% green before committing and pushing `package-lock.json` to the PR branch.
+
+## System & Environment
+- **Runtime:** Node.js v24.19.0
+- **Node Engine Version Bumps:** When bumping Node.js in `package.json` `engines.node`, run `npm install --package-lock-only --ignore-scripts` (or `npm install --ignore-scripts`) to update `package-lock.json` root engine definition without waiting on `postinstall` scripts so both files are committed together.

eslint.config.mjs

@@ -3,6 +3,8 @@ import tseslint from 'typescript-eslint';
 import nodePlugin from 'eslint-plugin-n';
 import securityPlugin from 'eslint-plugin-security';
 import sonarjs from 'eslint-plugin-sonarjs';
+import unicorn from 'eslint-plugin-unicorn';
+import promise from 'eslint-plugin-promise';
 import globals from 'globals';
 
 export default tseslint.config(
@@ -24,6 +26,25 @@ export default tseslint.config(
   nodePlugin.configs['flat/recommended-module'],
   securityPlugin.configs.recommended,
   sonarjs.configs.recommended,
+  promise.configs['flat/recommended'],
+  {
+    plugins: {
+      unicorn,
+    },
+    rules: {
+      'unicorn/prefer-node-protocol': 'warn',
+      'unicorn/no-unreadable-array-destructuring': 'warn',
+      'unicorn/no-useless-promise-resolve-reject': 'off',
+      'unicorn/prefer-array-find': 'warn',
+      'unicorn/prefer-array-flat-map': 'warn',
+      'unicorn/prefer-includes': 'warn',
+      'unicorn/prefer-string-starts-ends-with': 'warn',
+      'unicorn/prefer-date-now': 'warn',
+      'unicorn/no-typeof-undefined': 'warn',
+      'unicorn/no-invalid-remove-event-listener': 'warn',
+      'promise/no-return-wrap': 'off',
+    },
+  },
   {
     files: ['**/*.ts'],
     extends: [...tseslint.configs.recommendedTypeChecked],
@@ -73,6 +94,8 @@ export default tseslint.config(
     files: ['test/**/*.ts'],
     rules: {
       'sonarjs/no-nested-functions': 'off',
+      'promise/always-return': 'off',
+      'promise/catch-or-return': 'off',
     },
   },
 );