bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8070009fde
learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md

11 KiB
Raw Blame History

PNPM Migration Tracker

This document is the canonical ecosystem tracker for migrating ByteLyst Node.js and TypeScript repositories from npm to pnpm.

Scope

This tracker is for repos that still require an npm to pnpm migration, plus the shared tracker-hosting and downstream validation work needed to safely roll those migrations through the ecosystem.

This tracker is not a claim that every listed repo is still on npm today. Some repos may already use pnpm in part or in full; those repos should be handled here only if they still require migration cleanup, downstream validation, or tracker-hosting updates.

Objective

Standardize on pnpm for:

  • faster installs
  • stricter dependency resolution
  • cleaner workspace behavior with shared @bytelyst/* packages
  • consistent CI, Docker, and local development workflows

Tracker Rules

  • Sequential only — migrate one repo at a time in the order below.
  • No overlapping repo migrations — do not start the next repo until the current repo is fully verified, audited, committed, pushed, and tracked here.
  • Fix issues immediately — if tests, builds, CI assumptions, Docker assumptions, or docs fail, fix them in the same repo before moving on.
  • Incremental commits required — commit migration work, fix work, and docs/tracker updates in logical batches.
  • Tracker updates are mandatory — every completed repo must have its checkbox updated and commit links recorded here.

Tracker State Semantics

  • A wave checkbox means the repo has fully cleared the migration sequence and can be considered done for this tracker.
  • A repo-section checkbox is only updated when there is evidence in code, verification output, and pushed commits.
  • TBD commit fields mean the repo has not yet cleared that stage.
  • If a repo is blocked, document the blocker in that repo's notes: line before moving away from it.

Definition of Done For Each Repo

A repo is only complete when all of the following are true:

  • packageManager metadata updated to pnpm@10.6.5
  • pnpm-lock.yaml generated and committed
  • obsolete package-lock.json files removed
  • workspace/root package layout updated if needed
  • CI updated to use pnpm
  • Dockerfiles and helper scripts updated to use pnpm
  • repo docs updated to pnpm
  • install/typecheck/test/build verification passed
  • post-completion audit performed and any issues fixed
  • /production-readiness executed where applicable, or equivalent repo-local readiness checks executed if the workflow does not directly cover that repo
  • migration commit links added here
  • fix/audit commit links added here
  • docs/tracker commit links added here
  • commits pushed

If any item above is false, the repo remains in-progress for this tracker.

Mandatory Verification Before Moving To The Next Repo

For every repo migration:

  1. run the repo's own install, typecheck, test, and build commands
  2. run the post-completion audit against recently completed claims
  3. fix issues immediately in that repo
  4. rerun verification after fixes
  5. run /production-readiness when the repo is directly covered by that workflow
  6. when the repo is not directly covered by /production-readiness, run equivalent repo-local readiness checks and rerun any impacted downstream verification before advancing
  7. update this tracker with real commit links
  8. push the commits before starting the next repo

/production-readiness Workflow Policy

The /production-readiness workflow is mandatory quality enforcement for covered repos and must be used as part of the migration sign-off process.

Repos directly covered today

  • learning_ai_common_plat
  • learning_voice_ai_agent
  • learning_multimodal_memory_agents

Repos not directly covered today

For the other product repos, run their repo-native verification plus the equivalent readiness checks expected by this tracker. If a migration affects shared dependencies, CI assumptions, shared Docker behavior, or downstream integrations, rerun any impacted /production-readiness phases before moving on.

Equivalent readiness checks should include, at minimum, the repo's canonical install, typecheck, test, build, and any documented quality gates required by its own AGENTS/README/workflows.

Current Status

  • Ready for sequential rollout: yes
  • Ready for parallel or one-shot migration: no
  • Current next repo: learning_voice_ai_agent
  • Completed pilot: learning_ai_flowmonk

Pilot Evidence

learning_ai_flowmonk

  • migrated
  • audited
  • verified
  • pushed
  • migration commit: 32160af — feat(build): migrate flowmonk to pnpm workspace
  • docs checkpoint: 2a293c1 — docs(roadmap): record pnpm migration checkpoint
  • audit fix commit: c4cb9b3 — fix(audit): harden push triggers and offline replay
  • docs alignment commit: 8894285 — docs(audit): align flowmonk completion status

Sequential Rollout Order

Do not change the order below unless a later repo becomes a hard dependency blocker for an earlier repo.

Wave 0 — Completed Pilot

  • learning_ai_flowmonk

Wave 1 — Best next repos

  • 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

Wave 4 — Shared-platform validation and tracker-hosting cleanup

  • learning_ai_common_plat

Repo Tracker

Update each repo section immediately after work lands.

1. learning_ai_notes

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: 90dd2d3
  • fix/audit commit: 17a117f
  • docs/tracker commit: 14e7e49
  • notes: pnpm run verify passed in learning_ai_notes; backend and web Docker builds passed after aligning NoteLett to the shared .docker-deps consumer flow and fixing prep-consumer.sh to pack the transitive @bytelyst/* closure

2. learning_ai_local_memory_gpt

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: f7d47b1
  • notes: pnpm run verify passed (141 tests); backend Docker build required node:22-slim + native build tools for better-sqlite3; web Docker build required selective COPY to avoid node_modules symlink conflict; Next.js 16 needed --webpack flag + transpilePackages + webpack symlinks config for pnpm @bytelyst/* resolution

3. learning_ai_trails

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: d8d0fbb
  • notes: pnpm run verify passed (222 tests); includes SDK package; backend + web Docker builds passed on first try with .docker-deps consumer pattern

4. learning_ai_fastgap

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: 8826f8a
  • notes: 844 tests passed (505 mobile + 209 backend + 130 web); 3-package workspace (mobile root + backend + web); backend + web Docker builds passed with .docker-deps consumer pattern

5. learning_ai_clock

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: 582936a
  • notes: 576 tests passed (182 backend + 394 web); web Docker needed NODE_TLS_REJECT_UNAUTHORIZED=0 for Google Fonts through corporate proxy; added missing root .gitignore

6. learning_ai_jarvis_jr

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: 732c153
  • notes: 260 tests passed (209 backend + 51 web); backend + web Docker builds passed; iOS job unchanged

7. learning_ai_peakpulse

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness or equivalent readiness checks passed
  • docs/tracker updated
  • commits pushed
  • migration commit: ab7d702
  • notes: 65 tests passed (backend only, no web); backend Docker build passed; iOS job unchanged; added node_modules to root .gitignore

8. learning_voice_ai_agent

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness passed
  • docs/tracker updated
  • commits pushed
  • migration commit: TBD
  • fix/audit commit: TBD
  • docs/tracker commit: TBD
  • notes: use the local pointer doc learning_voice_ai_agent/PNPM_MIGRATION.md to reference this tracker

9. learning_ai_common_plat

  • migration started
  • migration completed
  • repo verification passed
  • post-completion audit passed
  • /production-readiness passed
  • docs/tracker updated
  • commits pushed
  • migration commit: TBD
  • fix/audit commit: TBD
  • docs/tracker commit: TBD
  • notes: tracker host and shared-platform validation repo; treat this as the final shared cleanup/sign-off phase rather than a standard product-repo npm→pnpm migration

Blocker Logging Rule

If a repo cannot be completed in sequence:

  • do not silently skip it
  • record the blocker in that repo's notes: line
  • record any partial commit links already created
  • explain why it is safe to proceed to a later repo, if an exception is required

Why The Sequence Matters

  • the pilot already proved that “migration complete” is not enough without audit-backed verification
  • CI, Docker, and sibling-repo dependency assumptions can fail in ways that local installs alone do not expose
  • later high-blast-radius repos should benefit from everything learned in the earlier waves

Legacy Pointer

The old product-level roadmap location now exists only as a pointer:

  • learning_voice_ai_agent/PNPM_MIGRATION.md

Summary

  • canonical tracker: this file
  • completed pilot: learning_ai_flowmonk
  • next repo in sequence: learning_ai_local_memory_gpt
  • rule: do not move to the next repo until the current repo passes verification, audit, readiness, commit, push, and tracker update