From b7abc5a0ccbbbf85493240a8933913f27c20cc4b Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Mon, 23 Mar 2026 02:40:46 +0000 Subject: [PATCH] docs: add Node.js 22 requirement across skills - constructive-setup: add Prerequisites section with Node.js 22+ and pnpm 10+ requirements, add 'Verify Node.js Version' as step 1 - constructive-testing: add 'Use Node.js 22+' as critical rule #1 - pgpm/ci-cd: update workflow template from node-version 20 to 22, add best practices for Node.js 22 and --frozen-lockfile - pnpm-workspace: update compatibility from Node.js 18+ to Node.js 22+ Node.js 20 causes different pnpm module resolution behavior that leads to duplicate graphql module instances and 'Cannot use GraphQLObjectType from another module or realm' runtime errors with PostGraphile/Graphile packages. --- .agents/skills/constructive-setup/SKILL.md | 30 +++++++++++++++---- .agents/skills/constructive-testing/SKILL.md | 9 +++--- .../references/pnpm-workspace.md | 2 +- .agents/skills/pgpm/references/ci-cd.md | 20 +++++++------ 4 files changed, 42 insertions(+), 19 deletions(-) diff --git a/.agents/skills/constructive-setup/SKILL.md b/.agents/skills/constructive-setup/SKILL.md index 6268532..73f81c1 100644 --- a/.agents/skills/constructive-setup/SKILL.md +++ b/.agents/skills/constructive-setup/SKILL.md @@ -18,6 +18,11 @@ Use this skill when: - Starting a new development session that needs a running database - Troubleshooting a broken local environment +## Prerequisites + +- **Node.js 22+** — Required for correct pnpm module resolution with PostGraphile/Graphile packages. Node.js 20 causes duplicate `graphql` module instances and runtime errors ("Cannot use GraphQLObjectType from another module or realm"). Use `nvm install 22` or `volta install node@22` if needed. +- **pnpm 10+** — Pin to an exact version (e.g., `10.22.0`) in CI to avoid dependency resolution drift. + ## Quick Setup ```bash @@ -42,7 +47,22 @@ pnpm test ## Step-by-Step Details -### 1. Install Dependencies +### 1. Verify Node.js Version + +Constructive requires Node.js 22+. Different Node.js versions cause different pnpm module resolution behavior, which can lead to duplicate `graphql` module instances and cryptic runtime errors. + +```bash +node --version # Must be v22.x or higher +``` + +If you're on an older version, upgrade: +```bash +nvm install 22 && nvm use 22 +# or +volta install node@22 +``` + +### 2. Install Dependencies The monorepo uses pnpm workspaces: @@ -50,7 +70,7 @@ The monorepo uses pnpm workspaces: pnpm install ``` -### 2. Start PostgreSQL +### 3. Start PostgreSQL Use pgpm's Docker integration to start a local PostgreSQL container. The `postgres-plus:18` image includes all required extensions (PostGIS, pgvector, uuid-ossp, etc.). @@ -65,7 +85,7 @@ For full Docker options (custom ports, names, passwords), see the **pgpm** skill For environment variable details, see the **pgpm** skill: [references/env.md](../pgpm/references/env.md) -### 3. Bootstrap Database Users +### 4. Bootstrap Database Users Create the required PostgreSQL roles for Constructive's security model: @@ -74,7 +94,7 @@ pgpm admin-users bootstrap --yes pgpm admin-users add --test --yes ``` -### 4. Build +### 5. Build ```bash pnpm build @@ -82,7 +102,7 @@ pnpm build This builds all packages in the monorepo. Required before running tests or starting servers. -### 5. Run Tests +### 6. Run Tests Tests are run per-package: diff --git a/.agents/skills/constructive-testing/SKILL.md b/.agents/skills/constructive-testing/SKILL.md index e441ec9..d26f1c8 100644 --- a/.agents/skills/constructive-testing/SKILL.md +++ b/.agents/skills/constructive-testing/SKILL.md @@ -73,10 +73,11 @@ Choose the **highest-level framework** that fits your test scenario: ## Critical Rules -1. **Always include `beforeEach`/`afterEach` hooks** — savepoint-based isolation prevents test state leakage -2. **Never create `new pg.Pool()` or `new pg.Client()` in tests** — use `getConnections()` -3. **Never manually create/drop databases** — the framework handles this -4. **Never skip hooks** — tests will leak state +1. **Use Node.js 22+** — Required for correct pnpm module resolution with PostGraphile/Graphile packages. Node.js 20 causes duplicate `graphql` module instances and "Cannot use GraphQLObjectType from another module or realm" errors at runtime +2. **Always include `beforeEach`/`afterEach` hooks** — savepoint-based isolation prevents test state leakage +3. **Never create `new pg.Pool()` or `new pg.Client()` in tests** — use `getConnections()` +4. **Never manually create/drop databases** — the framework handles this +5. **Never skip hooks** — tests will leak state ## Reference Guide diff --git a/.agents/skills/constructive-tooling/references/pnpm-workspace.md b/.agents/skills/constructive-tooling/references/pnpm-workspace.md index 8aa131b..49ec072 100644 --- a/.agents/skills/constructive-tooling/references/pnpm-workspace.md +++ b/.agents/skills/constructive-tooling/references/pnpm-workspace.md @@ -1,7 +1,7 @@ --- name: pnpm-workspace description: Create and manage PNPM workspaces following Constructive standards. Use when asked to "create a monorepo", "set up a workspace", "configure pnpm", or when starting a new TypeScript/JavaScript project with multiple packages. -compatibility: pnpm, Node.js 18+, lerna +compatibility: pnpm 10+, Node.js 22+, lerna metadata: author: constructive-io version: "1.0.0" diff --git a/.agents/skills/pgpm/references/ci-cd.md b/.agents/skills/pgpm/references/ci-cd.md index b33bfbb..302467f 100644 --- a/.agents/skills/pgpm/references/ci-cd.md +++ b/.agents/skills/pgpm/references/ci-cd.md @@ -188,7 +188,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '20' + node-version: '22' cache: 'pnpm' - name: Install dependencies @@ -423,14 +423,16 @@ steps: ## Best Practices -1. **Always use health checks** — Ensure PostgreSQL is ready before tests run -2. **Cache pgpm CLI** — Speeds up workflow execution significantly -3. **Use concurrency control** — Prevent duplicate runs on rapid pushes -4. **Configure Git** — Required for tests that use git operations -5. **Use matrix strategy** — Run tests in parallel across packages -6. **Bootstrap users before tests** — `pgpm admin-users` creates required roles -7. **Use fail-fast: false** — Let all tests complete even if some fail -8. **Pin pgpm version** — Ensure consistent behavior across runs +1. **Always use Node.js 22** — Required for correct pnpm module resolution with PostGraphile/Graphile packages. Using Node.js 20 or earlier causes duplicate `graphql` module instances and "Cannot use GraphQLObjectType from another module or realm" errors +2. **Always use health checks** — Ensure PostgreSQL is ready before tests run +3. **Cache pgpm CLI** — Speeds up workflow execution significantly +4. **Use concurrency control** — Prevent duplicate runs on rapid pushes +5. **Configure Git** — Required for tests that use git operations +6. **Use matrix strategy** — Run tests in parallel across packages +7. **Bootstrap users before tests** — `pgpm admin-users` creates required roles +8. **Use fail-fast: false** — Let all tests complete even if some fail +9. **Pin pgpm version** — Ensure consistent behavior across runs +10. **Use `--frozen-lockfile`** — Ensure CI uses exact lockfile versions, preventing silent dependency drift ## References