docs(pnpm): add canonical ecosystem migration roadmap
This commit is contained in:
saravanakumardb1
parent
cd811114e5
commit
d934bb3286
193
docs/pnpm/PNPM_MIGRATION.md
Normal file
193
docs/pnpm/PNPM_MIGRATION.md
Normal file
@ -0,0 +1,193 @@
|
||||
# PNPM Migration Roadmap
|
||||
|
||||
This document is the canonical cross-repo plan for migrating the ByteLyst ecosystem's Node.js/TypeScript repositories from `npm` to `pnpm`.
|
||||
|
||||
## Objective
|
||||
|
||||
Standardize on `pnpm` for:
|
||||
|
||||
- faster installs
|
||||
- stricter dependency resolution
|
||||
- cleaner workspace behavior with shared `@bytelyst/*` packages
|
||||
- consistent CI, Docker, and local development workflows
|
||||
|
||||
## Current Status
|
||||
|
||||
### Completed Pilot
|
||||
|
||||
- **FlowMonk** — completed, audited, verified, and pushed
|
||||
- migration commit: `32160af` — `feat(build): migrate flowmonk to pnpm workspace`
|
||||
- audit fix commit: `c4cb9b3` — `fix(audit): harden push triggers and offline replay`
|
||||
- docs alignment commit: `8894285` — `docs(audit): align flowmonk completion status`
|
||||
|
||||
### What the pilot proved
|
||||
|
||||
- root workspace migration is workable for multi-surface repos
|
||||
- CI must install from the workspace root when shared packages are involved
|
||||
- Dockerfiles and helper scripts need explicit `pnpm` handling
|
||||
- docs can overstate completion unless a post-migration audit is mandatory
|
||||
- post-completion audit must be part of the migration, not an optional cleanup
|
||||
|
||||
## Readiness Decision
|
||||
|
||||
- **Ready for phased ecosystem rollout:** yes
|
||||
- **Ready for one-shot all-at-once migration:** no
|
||||
|
||||
Even though none of the repos are actively deployed, the safest quality path is a fast sequential rollout in the right order, not a big-bang cutover.
|
||||
|
||||
## Canonical Migration Version
|
||||
|
||||
- target package manager metadata: `pnpm@10.6.5`
|
||||
|
||||
## Required Quality Gates for Every Repo
|
||||
|
||||
Every repo migration must complete **all** of the following before it is marked complete:
|
||||
|
||||
### Gate 1 — Manifest and workspace alignment
|
||||
|
||||
- add `packageManager: "pnpm@10.6.5"`
|
||||
- decide whether the repo needs a root workspace
|
||||
- add `pnpm-workspace.yaml` when shared local packages or multi-surface installs require it
|
||||
- generate and commit `pnpm-lock.yaml`
|
||||
- remove obsolete `package-lock.json` files
|
||||
|
||||
### Gate 2 — CI and Docker alignment
|
||||
|
||||
- update CI to use `pnpm`
|
||||
- update cache configuration to use the right lockfile path(s)
|
||||
- update Dockerfiles and helper scripts to install with `pnpm`
|
||||
- verify shared package resolution in both local and CI layouts
|
||||
|
||||
### Gate 3 — Docs and developer workflow alignment
|
||||
|
||||
- update README / AGENTS / CLAUDE / copilot / helper docs
|
||||
- update canonical build, test, typecheck, and dev commands
|
||||
- update any migration tracker / roadmap docs for the repo
|
||||
|
||||
### Gate 4 — Verification
|
||||
|
||||
- install succeeds under `pnpm`
|
||||
- typecheck passes
|
||||
- tests pass
|
||||
- build passes
|
||||
- any repo-specific required verification is run truthfully
|
||||
|
||||
### Gate 5 — Post-completion audit
|
||||
|
||||
Required after the migration appears complete:
|
||||
|
||||
- review completed claims against actual code and tests
|
||||
- identify recently marked-complete features lacking real coverage
|
||||
- fix any runtime, ownership, replay, or CI/Docker regressions found
|
||||
- rerun verification after the fixes
|
||||
- update docs to the audited truth state
|
||||
|
||||
## Migration Pattern Proven by FlowMonk
|
||||
|
||||
For repos similar to FlowMonk, the proven migration sequence is:
|
||||
|
||||
1. add root `package.json` if a workspace root is needed
|
||||
2. add `pnpm-workspace.yaml`
|
||||
3. generate `pnpm-lock.yaml`
|
||||
4. remove old `package-lock.json`
|
||||
5. update package-level `packageManager`
|
||||
6. update CI
|
||||
7. update Dockerfiles and helper scripts
|
||||
8. update docs
|
||||
9. run full verification
|
||||
10. run post-completion audit
|
||||
11. commit and push incrementally
|
||||
|
||||
## Ecosystem Rollout Order
|
||||
|
||||
### Wave 0 — Pilot
|
||||
|
||||
- `learning_ai_flowmonk` — complete
|
||||
|
||||
### Wave 1 — Best next repos
|
||||
|
||||
These are the best next candidates for a high-signal, lower-risk continuation:
|
||||
|
||||
- `learning_ai_notes`
|
||||
- `learning_ai_local_memory_gpt`
|
||||
- `learning_ai_trails`
|
||||
|
||||
### Wave 2 — Medium complexity product repos
|
||||
|
||||
- `learning_ai_fastgap`
|
||||
- `learning_ai_clock`
|
||||
- `learning_ai_jarvis_jr`
|
||||
- `learning_ai_peakpulse`
|
||||
|
||||
### Wave 3 — Higher blast-radius repos
|
||||
|
||||
- `learning_voice_ai_agent`
|
||||
- `learning_ai_common_plat`
|
||||
|
||||
## Why this order
|
||||
|
||||
- Wave 1 validates the process across more product repos without immediately touching the largest shared-platform blast radius
|
||||
- Wave 2 expands the pattern to broader product surfaces
|
||||
- Wave 3 is delayed until the process is stable enough for the biggest dependency and workflow impacts
|
||||
|
||||
## Special Notes
|
||||
|
||||
### `learning_ai_common_plat`
|
||||
|
||||
This repo is already the ecosystem's `pnpm` center of gravity. The work here is less about “switching package manager” and more about:
|
||||
|
||||
- standardizing docs/scripts/CI expectations
|
||||
- ensuring downstream repos consume shared packages cleanly
|
||||
- avoiding regressions in shared package behavior
|
||||
|
||||
### `learning_voice_ai_agent`
|
||||
|
||||
This repo should keep only a pointer or local wrapper doc once the shared canonical roadmap lives in `learning_ai_common_plat/docs/pnpm/`.
|
||||
|
||||
## Minimal Checklist Per Repo
|
||||
|
||||
Use this checklist for each migration:
|
||||
|
||||
- [ ] package metadata updated
|
||||
- [ ] lockfile generated and committed
|
||||
- [ ] old npm lockfiles removed
|
||||
- [ ] CI updated
|
||||
- [ ] Docker/scripts updated
|
||||
- [ ] docs updated
|
||||
- [ ] install verified
|
||||
- [ ] typecheck verified
|
||||
- [ ] tests verified
|
||||
- [ ] build verified
|
||||
- [ ] post-completion audit performed
|
||||
- [ ] docs updated to audited truth state
|
||||
- [ ] incremental commits pushed
|
||||
|
||||
## Operator Guidance
|
||||
|
||||
### Do
|
||||
|
||||
- migrate repos sequentially in the defined order
|
||||
- commit in logical batches
|
||||
- push after each verified batch
|
||||
- treat the audit as mandatory
|
||||
- prefer truthful status over optimistic status
|
||||
|
||||
### Do not
|
||||
|
||||
- migrate the entire ecosystem in one cutover
|
||||
- mark repos complete before the audit pass
|
||||
- leave mixed `npm`/`pnpm` docs in a migrated repo
|
||||
- assume CI/Docker correctness from local success alone
|
||||
|
||||
## Current Recommendation
|
||||
|
||||
The next repo to migrate should be:
|
||||
|
||||
- **`learning_ai_notes`**
|
||||
|
||||
## Summary
|
||||
|
||||
- canonical roadmap: `learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md`
|
||||
- completed pilot: `learning_ai_flowmonk`
|
||||
- proven approach: fast sequential waves with mandatory audit
|
||||
- next recommended repo: `learning_ai_notes`
|
||||
Loading…
Reference in New Issue
Block a user