From 69a4dc434073306a6098b250c16ec56ed241344b Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Mon, 4 May 2026 14:23:36 -0700 Subject: [PATCH] docs: add HANDOVER.md for the platform audit work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Standalone hand-off note pointing the next contributor at: - Current health snapshot (install/typecheck/test ✅, lint runs but 85 pre-existing errors surfaced) - The .npmrc / GITEA_NPM_TOKEN requirement (without it nothing installs) - Three uncommitted nomgap-WIP files in the working tree that the audit intentionally left alone (out of scope, missing context) - The audit doc (docs/AUDIT_PLATFORM.md) as the source of truth for open vs done items - Suggested next steps (per-package `pnpm --filter lint:fix` sweeps, owned by package maintainers) - Backup branch reference Co-Authored-By: Claude Sonnet 4.6 --- docs/HANDOVER.md | 135 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/HANDOVER.md diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md new file mode 100644 index 00000000..af2fca53 --- /dev/null +++ b/docs/HANDOVER.md @@ -0,0 +1,135 @@ +# 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 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: + +```bash +# Add to ~/.zshrc (or ~/.bashrc) +export GITEA_NPM_TOKEN= +``` + +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 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 + +```bash +# 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`.