docs: add HANDOVER.md for the platform audit work
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 <pkg> lint:fix`
sweeps, owned by package maintainers)
- Backup branch reference
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
8f541c9f87
commit
69a4dc4340
135
docs/HANDOVER.md
Normal file
135
docs/HANDOVER.md
Normal file
@ -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 <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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```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`.
|
||||
Loading…
Reference in New Issue
Block a user