Spike: npm -> pnpm

[cteyton]

Explanation

Relates to #

Type of Change

• Bug fix
• New feature
• Improvement/Enhancement
• Refactoring
• Documentation
• Breaking change

Affected Components

• Domain packages affected:
• Frontend / Backend / Both:
• Breaking changes (if any):

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing completed
• Test coverage maintained or improved

Test Details:

TODO List

• CHANGELOG Updated
• Documentation Updated

Reviewer Notes

[cteyton]

@greptile review this

[greptile-apps]

Greptile Summary

This PR migrates the monorepo package manager from npm to pnpm 9.15.0, touching CI workflows, Dockerfiles, docker-compose, and all workspace package.json files. The change replaces npm ci with pnpm install --frozen-lockfile, swaps npm workspaces for pnpm-workspace.yaml, converts internal workspace references from \"*\" to \"workspace:*\", and wires pnpm into Husky, pre-commit scripts, and the Docker build chain via corepack.

• CI/CD: All GitHub Actions jobs now use pnpm/action-setup@v4 + pnpm install --frozen-lockfile --prefer-offline; build artifacts include pnpm-lock.yaml copies for Docker; a new install-dist-cli-deps.sh script installs CLI runtime deps post-build with --no-frozen-lockfile because the workspace lockfile can't be reused there.
• Docker: Both API and MCP Dockerfiles activate pnpm via corepack under a shared COREPACK_HOME to solve a root-vs-node user binary visibility problem; MCP correctly copies its pnpm-lock.yaml before installing, but the API Dockerfile's equivalent step is missing.
• docker-compose: Replaces npm-based install logic with corepack-activated pnpm; adds persistent volumes (dev-corepack-cache, dev-pnpm-store) to cache the pnpm store across container restarts; the install-dependencies entrypoint now exits with an error on lockfile drift instead of silently upgrading."

Confidence Score: 5/5

Safe to merge — this is a tooling migration with no changes to application logic; the core migration mechanics (frozen lockfile in CI, corepack shared COREPACK_HOME, workspace:* protocol) are all correct.

The npm to pnpm switch is well-executed across CI, Docker, and local dev tooling. The two gaps flagged (API Dockerfile not copying its lockfile unlike MCP, and CLI dist deps installed without version pinning) affect build reproducibility rather than runtime correctness. No application code is touched.

dockerfile/Dockerfile.api (missing pnpm-lock.yaml COPY before the first pnpm install) and scripts/install-dist-cli-deps.sh (--no-frozen-lockfile makes CLI artifact deps non-reproducible).

Important Files Changed

Filename	Overview
.github/workflows/build.yml	Consistently migrated all jobs from npm ci to pnpm install --frozen-lockfile --prefer-offline with pnpm/action-setup@v4; adds the new install-dist-cli-deps.sh step for CLI builds, and copies pnpm-lock.yaml to dist artifacts for both API and MCP.
dockerfile/Dockerfile.api	Adds corepack/pnpm setup with shared COREPACK_HOME to fix root vs node user binary visibility; replaces npm install with pnpm install --prod, but does not copy pnpm-lock.yaml before installing (unlike Dockerfile.mcp which does), leaving the API image install non-reproducible.
dockerfile/Dockerfile.mcp	Correctly copies dist/apps/mcp-server/pnpm-lock.yaml before pnpm install --prod, giving pinned reproducible resolution; shared COREPACK_HOME pattern matches Dockerfile.api.
docker-compose.yml	Replaces npm-based install logic with pnpm via corepack; adds dev-corepack-cache and dev-pnpm-store volumes to persist the pnpm store across container restarts; install-dependencies now exits with an error on lockfile drift instead of silently upgrading.
scripts/install-dist-cli-deps.sh	New script installs CLI runtime deps in dist/apps/cli; uses --no-frozen-lockfile so resolution is non-reproducible across builds; short-circuits if node_modules already exists.
package.json	Replaces npm workspaces with pnpm-workspace.yaml; migrates all script invocations from npm run to pnpm; moves npm overrides to pnpm.overrides; adds packageManager field pinned to pnpm@9.15.0.
pnpm-workspace.yaml	New file declaring workspace packages (packages/* and apps/*), replacing the npm workspaces array that was in package.json.
.npmrc	New pnpm configuration file; sets public-hoist-pattern for @types/*, eslint, and prettier; disables shamefully-hoist and strict-peer-dependencies.
scripts/prepare.mjs	New prepare lifecycle script; exits immediately in CI, otherwise runs pnpm husky and pnpm chakra:typegen for local developer setup.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[git push] --> B[GitHub Actions CI]
    B --> C[pnpm action-setup v4]
    C --> D[pnpm install frozen-lockfile]
    D --> E{Build Jobs}
    E --> F[API build]
    E --> G[MCP build]
    E --> H[CLI build]
    F --> F2[cp pnpm-lock.yaml to dist/apps/api]
    G --> G2[cp pnpm-lock.yaml to dist/apps/mcp-server]
    H --> I[install-dist-cli-deps.sh no-frozen-lockfile]
    F2 --> J[Dockerfile.api - no lockfile COPY]
    G2 --> K[Dockerfile.mcp - copies pnpm-lock.yaml]
    J --> N[API Docker Image - non-reproducible deps]
    K --> O[MCP Docker Image - reproducible deps]

Loading

_{Reviews (7): Last reviewed commit: "🐛 fix(scripts): drop frozen-lockfile fr..." | Re-trigger Greptile}

[greptile-apps]

Greptile Summary

This spike migrates the monorepo's package manager from npm to pnpm 9.15.0, replacing package-lock.json with pnpm-lock.yaml, adding pnpm-workspace.yaml, updating all CI workflows to use pnpm/action-setup, and converting Dockerfiles to activate pnpm via corepack.

• All GitHub Actions workflows gain a pnpm/action-setup@v4 step before setup-node, and npm ci is replaced with pnpm install --frozen-lockfile; the package-lock.json artifact copy is replaced with pnpm-lock.yaml.
• Jest transformIgnorePatterns are updated from Unix-only leading-slash patterns to portable patterns that correctly traverse pnpm's nested symlink structure on both Unix and Windows.
• Both Dockerfiles activate pnpm via corepack prepare (run as root) then invoke pnpm install as the node user, and all three docker-compose service entrypoints call corepack prepare at startup, creating redundant network calls on cold starts.

Confidence Score: 4/5

The CI and workflow changes are clean and consistent. The Docker-related changes work correctly but have a few inefficiencies worth addressing before this is finalised.

The core migration is solid. The remaining concerns are build-time inefficiencies: corepack is prepared as root but pnpm runs as the node user (potential re-download per build), pnpm store prune is called between two sequential installs in Dockerfile.api, and three docker-compose services each call corepack prepare at entrypoint startup. None of these break functionality, but they add fragility in network-restricted environments and slow down Docker builds.

dockerfile/Dockerfile.api and docker-compose.yml warrant a second look for the corepack user-context and repeated network-dependent pnpm activation patterns.

Important Files Changed

Filename	Overview
.github/workflows/build.yml	All npm commands replaced with pnpm equivalents; pnpm/action-setup@v4 added to every job; pnpm-lock.yaml replaces package-lock.json in the API artifact copy.
dockerfile/Dockerfile.api	corepack enables pnpm as root, but both pnpm install steps execute as the node user — COREPACK_HOME is user-specific, which may trigger a re-download during build; two sequential pnpm install + store prune pairs further interact with the store.
dockerfile/Dockerfile.mcp	Same root-vs-node corepack pattern as Dockerfile.api; installs without a lockfile (--no-lockfile) intentionally documented.
docker-compose.yml	install-dependencies, run-migrations, and e2e-tests service entrypoints all call corepack prepare at container startup, requiring internet access on every cold start.
.npmrc	New pnpm config; public-hoist-pattern[]=types is broader than @types/* and could inadvertently hoist packages that aren't TypeScript declarations.
package.json	Switched from npm workspaces to pnpm; added explicit root-level deps (express, body-parser, webpack, etc.) that were previously hoisted; zod v3 added at root while CLI uses v4.
pnpm-workspace.yaml	New workspace definition file equivalent to the removed npm workspaces field in package.json.
jest-utils.ts	transformIgnorePatterns updated from leading-slash Unix-only patterns to portable patterns that handle pnpm's nested node_modules symlink paths on both Unix and Windows.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer pushes code] --> B[GitHub Actions: pnpm/action-setup@v4]
    B --> C[actions/setup-node with cache: pnpm]
    C --> D[pnpm install --frozen-lockfile]
    D --> E{Job type}
    E -->|build| F[nx build / test / typecheck]
    E -->|quality| G[nx lint + prettier:check]
    E -->|docker| H[Build Docker image]
    H --> I[Dockerfile.api / Dockerfile.mcp]
    I --> J[USER root: corepack enable and prepare pnpm@9.15.0]
    J --> K[USER node: pnpm install --prod]
    K -->|Dockerfile.api| L[pnpm store prune]
    L --> M[migrations: pnpm install --prod]
    M --> N[pnpm store prune]
    N --> O[Remove npm/pnpm/corepack binaries]
    K -->|Dockerfile.mcp| P[pnpm install --prod --no-lockfile]
    P --> Q[Remove npm/pnpm/corepack binaries]

Loading

_{Reviews (2): Last reviewed commit: "🐛 fix(cli): install dist runtime depend..." | Re-trigger Greptile}

[cteyton]

@greptile update your review

[sonarqubecloud]

Quality Gate failed

Failed conditions
12 Security Hotspots
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE