From 266f45a8513b4ef31787973ab197193b47730b79 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Tue, 24 Mar 2026 06:23:33 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20finalize=20Gitea=20registry=20migration?= =?UTF-8?q?=20=E2=80=94=20all=2010=20repos=20migrated,=20rollback=20+=20Az?= =?UTF-8?q?ure=20documented,=20Definition=20of=20Done=2010/10?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md | 133 ++++++++++++-------- 1 file changed, 80 insertions(+), 53 deletions(-) diff --git a/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md b/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md index 55aa5368..8f5b2cd8 100644 --- a/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md +++ b/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md @@ -138,12 +138,15 @@ That is enough to treat this Mac as the single-VM rehearsal environment. - shared packages build cleanly in `learning_ai_common_plat` - a local-only Gitea package token was created and used successfully for local package publishing -- **38 `@bytelyst/*` packages** published to local Gitea npm registry +- **48 `@bytelyst/*` packages** published to local Gitea npm registry - a clean scratch `pnpm install` from the local Gitea registry works on all migrated repos -- **8 product repos migrated** from `file:` refs + `docker-prep.sh` to semver `^0.1.0` + registry-backed Dockerfiles -- all migrated repos pass host-side `pnpm install`, backend typecheck, and backend tests -- Docker builds (backend + web) verified for repos with Dockerfiles -- local Gitea CI green for NoteLett and ActionTrail (remaining repos queued) +- **all 10 product repos migrated** from `file:` refs + `docker-prep.sh` to semver `^0.1.0` + registry-backed Dockerfiles +- all migrated repos pass host-side `pnpm install` and backend typecheck +- Docker builds (backend + web) verified for all repos with Dockerfiles +- local Gitea CI green for 8/8 repos with CI workflows (FlowMonk, NoteLett, ActionTrail, LocalMemGPT, NomGap, ChronoMind, JarvisJr, PeakPulse) +- `docker-prep.sh` removed from all 10 repos +- `GITEA_NPM_TOKEN` added to act_runner config for CI registry access +- stale "Build @bytelyst/* packages" step removed from all CI workflows ### Important implementation finding @@ -178,12 +181,13 @@ Host-side installs, Docker builds, and local CI are all validated. The `--add-host localhost:host-gateway` workaround is the **correct local-dev pattern** when `NETWORK=corp`, not a generic blocker. On a VM, Gitea's `ROOT_URL` will be set to the real hostname or compose service name, so tarball URLs resolve without any host-mapping workaround. -At the time of writing (2026-03-23): +At the time of writing (2026-03-24): -- host-side registry usage is validated across all 8 migrated repos -- Docker builds verified for all repos with Dockerfiles (FlowMonk, NoteLett, ActionTrail, LocalMemGPT, NomGap, ChronoMind, JarvisJr, PeakPulse) -- local Gitea CI green for NoteLett and ActionTrail; remaining repos queued (single runner) -- 38 `@bytelyst/*` packages published to local Gitea +- host-side registry usage is validated across all 10 migrated repos +- Docker builds verified for all repos with Dockerfiles +- local Gitea CI green for all 8 repos with CI workflows +- 48 `@bytelyst/*` packages published to local Gitea +- `docker-prep.sh` retired from all repos Verified local FlowMonk Docker recipe (`NETWORK=corp`): @@ -213,19 +217,26 @@ The local rehearsal on this Mac has validated the **host-side** registry model, ### Validated ✅ -- Host-side `pnpm install` against local Gitea registry (all 8 repos) +- Host-side `pnpm install` against local Gitea registry (all 10 repos) - Backend + web Docker builds with BuildKit secret + `--add-host` (all repos with Dockerfiles) -- Local Gitea CI green for NoteLett, ActionTrail; remaining repos queued (single runner) +- Local Gitea CI green for all 8 repos with CI workflows - Runner re-registered against `127.0.0.1` (avoids IPv6 `[::1]` declaration failure) -- 38 `@bytelyst/*` packages published and consumed successfully -- Backend typecheck + tests pass for all 8 migrated repos +- `GITEA_NPM_TOKEN` added to act_runner config for CI registry access +- 48 `@bytelyst/*` packages published and consumed successfully +- Backend typecheck passes for all 10 migrated repos +- `docker-prep.sh` removed from all 10 repos -### Gaps still open +### Gaps closed + +- ~~2 repos not yet migrated~~ → MindLyst and LysnrAI migrated (2026-03-24) +- ~~Gitea CI queue stuck~~ → Runner restarted with `GITEA_NPM_TOKEN`, all 8 CI repos green +- ~~Stale common-plat build step in CI~~ → Removed from all 7 CI workflows + +### Remaining minor items - Mobile workspace members remain on `file:` refs where present (NomGap, NoteLett) — acceptable for now -- 2 repos not yet migrated: `learning_voice_ai_agent` (LysnrAI) and `learning_multimodal_memory_agents` (MindLyst) — these have non-standard layouts - Local Gitea Actions has not yet been validated for the package build → publish → consumer flow (CI runs typecheck/test, not publish) -- Gitea CI queue drains sequentially (single runner) — all 6 newly-pushed repos are queued +- MindLyst and LysnrAI have no Gitea CI workflows yet (lower priority) ### Why this matters for Azure @@ -449,23 +460,18 @@ Only then should we expand repo-by-repo. ## 9. Recommended Rollout Order -### Completed (8 repos) +### All 10 repos migrated ✅ -1. ✅ `learning_ai_flowmonk` — pilot repo -2. ✅ `learning_ai_notes` — second repo, Docker verified, CI green -3. ✅ `learning_ai_trails` — Docker verified, CI green -4. ✅ `learning_ai_local_memory_gpt` — Docker verified, typecheck pass -5. ✅ `learning_ai_fastgap` — Docker verified, typecheck pass -6. ✅ `learning_ai_clock` — Docker verified, typecheck pass -7. ✅ `learning_ai_jarvis_jr` — Docker verified, typecheck pass -8. ✅ `learning_ai_peakpulse` — backend only (no web Dockerfile), typecheck pass - -### Remaining (2 repos — non-standard layouts) - -9. `learning_multimodal_memory_agents` — KMP + `mindlyst-native/web/` + `backend/` -10. `learning_voice_ai_agent` — Python desktop + `backend/` + `user-dashboard-web/` - -These two repos have non-standard directory structures and may need per-repo adjustments. +1. ✅ `learning_ai_flowmonk` — pilot repo, CI green +2. ✅ `learning_ai_notes` — CI green +3. ✅ `learning_ai_trails` — CI green +4. ✅ `learning_ai_local_memory_gpt` — CI green +5. ✅ `learning_ai_fastgap` — CI green (fixed missing `@expo/vector-icons`) +6. ✅ `learning_ai_clock` — CI green +7. ✅ `learning_ai_jarvis_jr` — CI green +8. ✅ `learning_ai_peakpulse` — CI green (backend only, no web Dockerfile) +9. ✅ `learning_multimodal_memory_agents` — non-standard layout (KMP + `mindlyst-native/web/`), typecheck pass +10. ✅ `learning_voice_ai_agent` — non-standard layout (Python desktop + `user-dashboard-web/`), typecheck pass --- @@ -506,14 +512,30 @@ The objective is to prove the local VM pattern first. ## 12. Rollback Plan -If the registry-based flow fails during pilot migration: +The migration is complete for all 10 repos. If a repo needs to revert to the old `file:` + `docker-prep.sh` pattern: -1. revert the tested consumer back to its current working dependency mode -2. restore its `docker-prep.sh` path if needed -3. keep the Gitea registry work isolated to the local rehearsal branch/state -4. fix the issue locally before retrying +### Per-repo rollback steps -No repo should lose its known-good build path until the registry model is proven. +1. `git revert ` — reverts `package.json`, `Dockerfile`, `.npmrc`, `pnpm-workspace.yaml` +2. Restore `scripts/docker-prep.sh` from the commit just before `chore: remove docker-prep.sh` +3. Re-add the sibling workspace reference in `pnpm-workspace.yaml`: + ```yaml + packages: + - ../learning_ai_common_plat/packages/* + ``` +4. Restore `file:` refs in `package.json` — sed: `sed -i '' 's|"\^0.1.0"|"file:../../learning_ai_common_plat/packages/PKG_NAME"|g'` +5. Run `pnpm install` to regenerate the lockfile +6. Verify `pnpm run typecheck` and `pnpm run test` pass +7. Commit and push + +### Registry-side rollback + +No registry-side action is needed. The Gitea packages remain published and don't interfere with `file:` refs. The `.npmrc` scoped registry config only activates when the `@bytelyst` scope resolves through the registry. + +### When rollback is NOT needed + +- If a package is missing from the registry → publish it with `scripts/publish-local-gitea-packages.sh` +- If a transitive dep is missing → add it explicitly to `package.json` (this surfaced for `@expo/vector-icons` in NomGap) --- @@ -567,25 +589,30 @@ What is **not** yet proven enough to call low-change: This migration plan is locally validated only when all are true: - [x] local Gitea package publish auth verified -- [x] local package publish path verified — 38 packages published -- [x] local consumer install path verified on the host — all 8 repos +- [x] local package publish path verified — 48 packages published +- [x] local consumer install path verified on the host — all 10 repos - [x] Docker build path verified without `docker-prep.sh` — all repos with Dockerfiles -- [x] local Gitea CI verified — NoteLett and ActionTrail green +- [x] local Gitea CI verified — 8/8 repos with CI workflows green - [x] pilot repo migrated successfully end-to-end including Docker (FlowMonk) -- [x] 7 additional repos migrated and verified (NoteLett, ActionTrail, LocalMemGPT, NomGap, ChronoMind, JarvisJr, PeakPulse) -- [ ] remaining 2 non-standard repos migrated (MindLyst, LysnrAI) -- [ ] rollback path documented and tested conceptually -- [ ] Azure single-VM reproduction steps documented from the validated local process +- [x] 7 standard repos migrated and verified (NoteLett, ActionTrail, LocalMemGPT, NomGap, ChronoMind, JarvisJr, PeakPulse) +- [x] remaining 2 non-standard repos migrated (MindLyst, LysnrAI) +- [x] rollback path documented (§12) +- [x] Azure single-VM reproduction steps documented (§13) --- -## 15. Immediate Next Actions +## 15. Migration Complete — Summary 1. ~~create or verify a local-only Gitea package token~~ ✅ -2. ~~publish `@bytelyst/*` packages to local Gitea~~ ✅ (38 packages) +2. ~~publish `@bytelyst/*` packages to local Gitea~~ ✅ (48 packages) 3. ~~migrate pilot repo (FlowMonk) end-to-end~~ ✅ -4. ~~expand to remaining standard-layout repos~~ ✅ (7 more repos) -5. confirm Gitea CI queue drains green for all 8 repos (single runner, sequential) -6. migrate remaining 2 non-standard repos: `learning_multimodal_memory_agents` (MindLyst), `learning_voice_ai_agent` (LysnrAI) -7. document rollback path for the registry migration -8. document Azure single-VM reproduction steps from the validated local process +4. ~~expand to remaining standard-layout repos~~ ✅ (7 repos) +5. ~~confirm Gitea CI green for all repos~~ ✅ (8/8 with CI workflows) +6. ~~migrate remaining 2 non-standard repos (MindLyst, LysnrAI)~~ ✅ +7. ~~document rollback path~~ ✅ (§12) +8. ~~document Azure single-VM reproduction steps~~ ✅ (§13) +9. ~~remove `docker-prep.sh` from all 10 repos~~ ✅ +10. ~~add `GITEA_NPM_TOKEN` to act_runner config~~ ✅ +11. ~~remove stale common-plat build step from CI workflows~~ ✅ + +**Migration completed 2026-03-24. All 10 product repos now consume `@bytelyst/*` packages from the local Gitea npm registry.**