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's package manager from npm to pnpm 11, replacing package-lock.json with pnpm-lock.yaml, adding pnpm-workspace.yaml for workspace and build configuration, and updating all CI workflows, Dockerfiles, and scripts to use pnpm commands.

• All CI workflows now use pnpm/action-setup@v4 + pnpm install --frozen-lockfile --prefer-offline, Dockerfiles use a shared COREPACK_HOME pattern with pnpm install --prod, and the overrides/allowBuilds/hoisting settings that lived in package.json and .npmrc are consolidated into pnpm-workspace.yaml.
• A new scripts/install-dist-cli-deps.sh handles the bundled CLI's runtime deps, which pnpm's strict layout no longer hoists to the workspace root, and a one-shot pnpm_migrate.sh helps developers transition their existing checkouts.

Confidence Score: 5/5

Safe to merge — all CI, Docker, and compose flows use the pinned lockfile; only the bundled CLI dist install runs without a lockfile due to a pnpm workspace constraint, which is documented in the script.

The migration is comprehensive and internally consistent: all production Docker builds copy pnpm-lock.yaml for reproducibility, CI workflows use --frozen-lockfile, and previous review feedback (shared COREPACK_HOME, deferred store prune, MCP lockfile copy) has been addressed. The only unresolved reproducibility gap is the CLI dist dep install, which is explicitly acknowledged in the code.

scripts/install-dist-cli-deps.sh — non-deterministic dep resolution for the bundled CLI production artifact.

Important Files Changed

Filename	Overview
scripts/install-dist-cli-deps.sh	New script installs CLI dist runtime deps without a lockfile — uses --no-frozen-lockfile because --ignore-workspace makes the workspace lockfile incompatible; dep resolution is non-deterministic between CI runs.
pnpm-workspace.yaml	New workspace config consolidating overrides, allowBuilds, hoisting, and peer-dep settings from package.json and .npmrc; publicHoistPattern correctly uses @types/* scoped glob.
dockerfile/Dockerfile.api	Addresses prior review feedback: shared COREPACK_HOME ensures pnpm binary is accessible to both root and node users; pnpm-lock.yaml copied alongside package.json for reproducible production installs; single pnpm store prune deferred to end.
dockerfile/Dockerfile.mcp	Mirrors Dockerfile.api: shared COREPACK_HOME, pnpm-lock.yaml copied from build artifacts, no-lockfile flag removed; lockfile copy added in build.yml CI step.
.github/workflows/build.yml	All jobs updated to pnpm/action-setup + pnpm install --frozen-lockfile; new install-dist-cli-deps step added for CLI jobs; lockfile copied to mcp-server dist.
docker-compose.yml	install-dependencies now uses --frozen-lockfile with no fallback; corepack/pnpm activated inline in run-migrations and e2e-tests; shared corepack+pnpm-store volumes added.
scripts/prepare.mjs	New prepare lifecycle script; skips in CI, runs pnpm husky + pnpm chakra:typegen on local installs.
pnpm_migrate.sh	One-shot developer migration script: verifies Node version, activates pnpm via corepack, clears stale npm artifacts, installs against committed lockfile, and smoke-builds two leaf packages.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[pnpm install --frozen-lockfile] -->|CI / local dev| B[Workspace node_modules
pnpm-lock.yaml pinned]
    B --> C{Build target}
    C -->|API / MCP-Server| D[nx build to dist/]
    C -->|CLI| E[nx build to dist/apps/cli/]
    D -->|copy pnpm-lock.yaml to dist| F[Docker COPY package.json + pnpm-lock.yaml]
    F --> G[pnpm install --prod --ignore-scripts
reproducible]
    E --> H[install-dist-cli-deps.sh]
    H -->|--no-frozen-lockfile --ignore-workspace| I[pnpm install --prod
non-deterministic]
    B -->|docker-compose dev| J[install-dependencies service
pnpm install --frozen-lockfile]
    J --> K[run-migrations
pnpm typeorm migration:run]
    J --> L[e2e-tests
pnpm e2e]

Loading

_{Reviews (15): Last reviewed commit: "📝 docs(pnpm): soften workspace config r..." | 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
13 Security Hotspots

See analysis details on SonarQube Cloud