learning_ai_common_plat/docs/HANDOVER.md

Handover — Common Platform Audit

Last updated: 2026-05-04 Last commit (audit): 8f541c9 — chore(audit): unblock workspace lint pipeline + 13 mechanical fixes Backup branch: backup/main-20260504-062733 (taken from origin/main HEAD 46a16f0)

---

TL;DR

A tooling-backed audit was performed across all 69 workspace packages. pnpm install / typecheck / test all pass cleanly. pnpm lint was failing fast at one package (hiding everything downstream); a structural eslint config fix + 13 mechanical lint fixes have made the lint pipeline run end-to-end. 85 pre-existing lint errors are now visible that nobody had seen before — they belong to package owners to clear with pnpm --filter <pkg> lint:fix followed by an eyeball review.

---

What's working right now

Check	Result	Notes
pnpm install -r	✅ pass	4 cosmetic peer warnings (@azure/core-client)
pnpm typecheck	✅ pass	All 69 packages compile
pnpm test	✅ pass	~2,200 tests across 18+ suites
pnpm lint (pipeline)	✅ runs end-to-end	Was bailing fast; this audit unblocked it
pnpm lint (errors)	🟡 85	All pre-existing, surfaced by the unblock — see docs/AUDIT_PLATFORM.md section P

---

Critical context for the next dev

1. The .npmrc token requirement

.npmrc references ${GITEA_NPM_TOKEN}. Without it exported, pnpm emits noisy WARNs and pnpm install -r fails on the mobile / vendored @bytelyst/* private packages. Every developer needs to:

# Add to ~/.zshrc (or ~/.bashrc)
export GITEA_NPM_TOKEN=<token-from-1Password>

The audit session's tooling runs all relied on this being sourced.

2. Working tree state at handover

Three files are uncommitted and were intentionally left alone by the audit — they're an in-progress nomgap-on-Vercel migration by another contributor:

• docker-compose.ecosystem.yml — removes nomgap-web from the Docker stack
• products/nomgap/product.json — replaces flag set, restructures containers
• services/platform-service/src/modules/flags/seed.ts — adds 14 lines of seed flags

Plus pnpm-lock.yaml regenerated by the audit's pnpm install -r run (+2,938/-8,520 lines — large but expected). Don't commit the lockfile without inspecting it — it likely upgraded transitive versions.

3. The audit doc is the source of truth

docs/AUDIT_PLATFORM.md has the full breakdown:

• Section A (✅ done): 13 lint pipeline blockers fixed in 8f541c9.
• Section P (open): 85 pre-existing lint errors surfaced. Top rules:
  • 67 × @typescript-eslint/no-unused-vars
  • 7 × prefer-const
  • 7 × no-redeclare
  • 4 × no-useless-escape
• Section W (low priority): 96 no-console warnings in CLI tools etc.
• Section R (housekeeping): 4 misc observations.

Note: a recent upstream commit (in the rebased main since this audit started) tightened the unused-vars rule with varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_', etc. — meaning _-prefix is now an official escape hatch for intentionally-unused names. This makes the 85-error sweep easier (just rename, don't delete).

---

Suggested next steps

1. P sweep — package owners run pnpm --filter <pkg> lint:fix per package, eyeball the diff (the autofixer can technically remove unused exports, which is breaking), commit. Target 6–10 small commits. Likely owners by error count:
   • services/platform-service (probably the biggest chunk)
   • services/extraction-service, services/cowork-service
   • packages/auth, packages/llm, packages/cosmos
   • dashboards/admin-web, dashboards/tracker-web
2. R3 — silence the .npmrc WARN with a graceful fallback (not blocking; just noisy).
3. R4 — add explicit @azure/core-client@^1.10.0 to the two services that pull @azure/cosmos to silence peer warnings.
4. (optional) commit the regenerated pnpm-lock.yaml once someone with context can verify the upgrades it introduced.

---

Repo state checklist

# Verify clean state before starting
cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat
source ~/.zshrc                  # ensure GITEA_NPM_TOKEN is loaded
git status                       # 4 unrelated WIP files expected (see §2 above)
git log --oneline -3             # top: 8f541c9 chore(audit): unblock workspace lint pipeline...

# Run the gates
pnpm install -r --prefer-offline # → done in seconds (cache hit)
pnpm typecheck                   # → exit 0
pnpm test                        # → ~2,200 pass
pnpm lint > /tmp/lint.log 2>&1   # → exit 1 with 85 errors (see AUDIT_PLATFORM.md §P)

---

Branches & backups

• main — current
• backup/main-20260504-062733 — snapshot of origin/main HEAD 46a16f0 taken before the audit-fix commit. Roll back with git reset --hard backup/main-20260504-062733 if anything goes wrong.

---

Companion: trading repo

The audit work that prompted this platform pass is documented in the sibling repo learning_ai_invt_trdg (specifically docs/HANDOVER.md and docs/AUDIT_REDESIGN.md there). That repo consumes 9 vendored @bytelyst/* packages from this platform — fix upstream here, re-vendor there. Backup branch in that repo: backup/main-20260504-061739.