upstream-migrator

name	upstream-migrator
description	Migrate the monorepo across @concepta/* and @nestjs/* version bumps and local↔npm dependency swaps. Use when asked to "bump @concepta to alpha.X", "use the npm packages instead of local", "upgrade NestJS", or when a version change breaks the build with module-resolution, exports-map, common→core, or exception-identity errors. Handles the recurring traps that classic version bumps hide.

Upstream Migrator

Bumping @concepta/* / @nestjs/* in this repo is rarely a clean version flip — upstream restructures packages between alphas. Work through this checklist; do not assume a bump is mechanical.

1. Establish the real target before editing

• For each package the user lists, run npm view <pkg>@<version> dependencies peerDependencies version.
• Build the dependency graph: note which @concepta/* packages the new version drops or renames (historically nestjs-common → nestjs-core; email/event had no 8.x; swagger-ui → @concepta/rockets-core; typeorm-ext removed — app-owned entities).
• Check what the repo's source actually imports from the dropped packages: grep -rl "@concepta/nestjs-common" packages/*/src. Those are your migration sites.

2. Apply versions deterministically

• Update root package.json resolutions and each package's dep entry. A small node script keyed by package name beats N hand edits and avoids touching packages that have no new version.
• To use npm instead of a local workspace copy: keep the folder on disk, exclude it from workspaces with a !packages/<name> negation (Yarn Berry) so the npm version resolves.
• Install with corepack yarn install (the repo is Yarn Berry 4.x; global yarn is v1 and will choke on the lockfile).

3. The traps that a bump hides (check every time)

• moduleResolution. New @concepta/* expose types only via package.json exports subpaths (e.g. @concepta/nestjs-core/aggregate). Classic node resolution ignores exports, so types silently degrade and skipLibCheck masks it. The repo uses module/moduleResolution: nodenext for this reason — keep it. Probe with a throwaway import + tsc --noEmit.
• common → core. Re-point moved symbols (DomainAggregate from …/aggregate, ActionEnum, RuntimeException, references, audit) to @concepta/nestjs-core. Removed re-exports (e.g. AccessControlAction) get deleted, not faked.
• Exception identity. Concepta exceptions extend @concepta/nestjs-core's RuntimeException, which is a different class from @concepta/rockets-app's. Any instanceof RuntimeException / global filter that imported from @concepta/nestjs-common must switch to @concepta/nestjs-core, or concepta errors become 500s.
• Config shapes. Option interfaces change (e.g. role assignments requiring a flat entityKey). Read the installed .d.ts in node_modules/<pkg>/dist, not upstream src at HEAD.

4. Test-runner layer (separate from the build)

• The runner is Vitest (native ESM): package exports maps resolve directly, so a subpath that fails under Vitest fails because the exports map itself is wrong — fix it upstream-side or via a resolve.alias entry in the relevant vitest*.config.ts, never with a paths/moduleNameMapper mirror.
• After a bump, run both yarn test and yarn test:e2e; a Cannot find module '@concepta/.../subpath' here is the exports-map signal above.

5. Verify

• tsc --build --force must be 0 errors (force, to defeat stale .tsbuildinfo).
• Boot sample-server and sample-server-auth (ts-node) and exercise signup/login — DI/exception identity only fails at runtime.
• Run yarn test; distinguish pre-existing failures from regressions with a git stash baseline before claiming a break is yours.
• No any/casts to paper over a shape change — fix the type or ask.