docs: add HANDOVER.md for the next contributor
Self-contained hand-off note covering:
- Current health snapshot (build/typecheck/test status, with the
4 known pre-existing test failures called out so they aren't
misread as regressions)
- Critical lockfile situation (web deps in package.json but not
in root pnpm-lock.yaml — needs `pnpm install -r` from a machine
with GITEA_NPM_TOKEN; tracked as audit item E2)
- Audit doc reference (docs/AUDIT_REDESIGN.md, 52 items, the 5
cleared so far + 47 still open)
- Suggested priority order: E2 lockfile → B1 chart indicators →
B2/B3 ticker header → C1 strategy code sandboxing → C2 FMP cache
→ F6 backend tests → G mobile parity
- Backup-branch reference for emergency rollback
- Note on vendored @bytelyst/* packages and the Vite alias resolver
Companion HANDOVER.md exists in the sibling learning_ai_common_plat
repo for the platform-side audit pushed in that repo's commit 8f541c9.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
255bb070a3
commit
372b83820f
168
docs/HANDOVER.md
Normal file
168
docs/HANDOVER.md
Normal file
@ -0,0 +1,168 @@
|
||||
# Handover — Trading Web Redesign + Cross-Workspace Audit
|
||||
|
||||
**Last updated**: 2026-05-04
|
||||
**Last session**: Claude Code, single contributor
|
||||
**Repos touched**: `learning_ai_invt_trdg` (this repo), `learning_ai_common_plat` (sibling)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
This repo had a recent web-dashboard redesign (commits `f62c3b1`, `938ed86`)
|
||||
that wired up live Alpaca + FMP data, a strategy builder (visual + code),
|
||||
and a screener. A subsequent audit (`4a09d4b`) catalogued 52 issues across
|
||||
7 buckets; commits `ddbffb6` and `255bb07` cleared the **5 critical broken
|
||||
integrations** and the **stray-lockfile mess**. Buckets B–G remain open and
|
||||
documented in `docs/AUDIT_REDESIGN.md`.
|
||||
|
||||
---
|
||||
|
||||
## What's working right now
|
||||
|
||||
| Path | Status |
|
||||
| --------------------------------- | --------------------------------------------------------------------- |
|
||||
| `web/` build | ✅ `npm --prefix web run build` → 1.08 MB bundle, no errors |
|
||||
| `web/` typecheck | ✅ `npm --prefix web run typecheck` → 0 errors |
|
||||
| `web/` tests | ⚠️ 151 / 155 pass — 4 pre-existing failures (see audit F7, F8) |
|
||||
| `backend/` typecheck | ✅ `npx tsc --noEmit -p backend/tsconfig.json` → 0 errors |
|
||||
| `/api/chart/bars` (equity+crypto) | ✅ Routes equities to v2/stocks, crypto (`BTC/USD`) to v1beta3/crypto |
|
||||
| `/api/news` + `RightPanel` | ✅ Auth header now sent (was 401-ing every render before commit `ddbffb6`) |
|
||||
| `/api/backtest/run` from CodeStrategyEditor | ✅ Correct endpoint + payload shape after `ddbffb6` |
|
||||
| `/api/profiles` from VisualRuleBuilder | ✅ Uses canonical `createTradeProfile()` shape |
|
||||
| Strategy builder (`/research` → Visual Builder, Code Editor) | ✅ UIs land; persistence verified by typecheck only — no e2e |
|
||||
| Screener (`/screener`) | ✅ Live FMP, sortable, click-to-load |
|
||||
| Live market indices in Header | ✅ SPY/DIA/QQQ poll every 60s |
|
||||
|
||||
---
|
||||
|
||||
## Critical context for the next dev
|
||||
|
||||
### 1. Lockfile situation (READ THIS FIRST)
|
||||
|
||||
`web/package.json` declares `react-router-dom`, `@monaco-editor/react`,
|
||||
`@dnd-kit/{core,sortable,utilities}` but the **root `pnpm-lock.yaml`
|
||||
doesn't reflect them yet**. The previous session installed those via
|
||||
`npm install` inside `web/` as a workaround for a Vite vendor-resolve
|
||||
issue, which left stray `web/package-lock.json` etc. — those are now
|
||||
git-ignored (commit `255bb07`).
|
||||
|
||||
**Action required before CI green**: on a workstation with
|
||||
`GITEA_NPM_TOKEN` exported, run:
|
||||
|
||||
```bash
|
||||
pnpm install -r --no-frozen-lockfile
|
||||
git add pnpm-lock.yaml
|
||||
git commit -m "chore(E2): regen root lockfile with new web deps"
|
||||
git push
|
||||
```
|
||||
|
||||
This is **item E2** in `docs/AUDIT_REDESIGN.md`. CI will fail until it lands.
|
||||
|
||||
### 2. Pre-existing test failures (NOT my regressions)
|
||||
|
||||
Four tests fail on `npm --prefix web test`. All pre-date this redesign:
|
||||
|
||||
- `useTabFeatureFlags.dom.test.tsx` (3 failures): module-level cache leaks
|
||||
between tests — test 2 caches `marketplace: false`, tests 3–5 expect the
|
||||
default `true`. Fix: `vi.resetModules()` in `beforeEach` or expose a
|
||||
cache-reset helper from the hook.
|
||||
- `EntryForm.dom.test.tsx > alerts error when trade execution fails`:
|
||||
pre-existing intermittent — test waits for `alertMock` but the component
|
||||
no longer calls `alert()` synchronously after the trade-API change.
|
||||
|
||||
These are tracked as audit items F7 and F8.
|
||||
|
||||
### 3. The audit doc is the source of truth
|
||||
|
||||
`docs/AUDIT_REDESIGN.md` has the full issue list (52 items, 7 buckets).
|
||||
Each row has a status box (⬜ open / 🟦 in PR / ✅ fixed) and a slot for
|
||||
the fix-commit hash. **Update it as you close items** — the format is:
|
||||
|
||||
| # | Issue | Severity | Status | Fix commit |
|
||||
| --- | ----- | -------- | ------ | ---------- |
|
||||
|
||||
Keep commits scoped (one bucket or one item per commit) and reference the
|
||||
ID in the subject — e.g. `fix(B1): wire RSI/MACD/BB indicator overlays`.
|
||||
That's the convention we used for the 5 already-closed items.
|
||||
|
||||
---
|
||||
|
||||
## Suggested next steps (in priority order)
|
||||
|
||||
1. **E2** — regenerate root lockfile (1 command, 1 commit). Unblocks CI.
|
||||
2. **B1** — Build the RSI/MACD/Bollinger indicator overlays under
|
||||
`StockChart` in `web/src/views/HomeView.tsx`. The plan called for them
|
||||
and the `IndicatorPanel` component was never built. Pure client-side
|
||||
compute from existing OHLCV bars; no new endpoints needed.
|
||||
3. **B2 + B3** — Wire the Watchlist (★) and notifications (🔔) buttons in
|
||||
`TickerHeader`, and pull the company name from `fetchResearchProfile`
|
||||
instead of using the symbol as a placeholder.
|
||||
4. **C1** — *Sandboxing for code strategies*. `CodeStrategyEditor` POSTs
|
||||
user-authored JS to `/api/backtest/run` with `strategyConfig.type ==
|
||||
'code'`. Backend currently has no handler for that type — first step
|
||||
is to either (a) add a sandboxed `vm2` / `isolated-vm` runner, or
|
||||
(b) reject `type: 'code'` with 400 and document the escape hatch.
|
||||
5. **C2** — Add an in-memory FMP response cache (key by URL, 30-min TTL).
|
||||
Free tier is 250 req/day; one Home view = 3 reqs.
|
||||
6. **F6** — Tests for the 7 new backend endpoints. Easy wins.
|
||||
7. **G1–G4** — Mobile parity. Mobile app (`mobile/`) has none of the new
|
||||
features (news, research, screener). Decide scope first — code
|
||||
editor probably shouldn't ship to mobile.
|
||||
|
||||
Buckets D (UX polish) and W (lint warnings) are nice-to-haves.
|
||||
|
||||
---
|
||||
|
||||
## Repo state checklist
|
||||
|
||||
```bash
|
||||
# Verify clean state before starting
|
||||
cd /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg
|
||||
git status # should show only nomgap WIP if any
|
||||
git log --oneline -10 # last commit should be 4a09d4b or later
|
||||
ls -la .claude/ 2>&1 | head -1 # gitignored — won't show in status
|
||||
|
||||
# Run the verification gates
|
||||
npm --prefix web run typecheck # → 0 errors
|
||||
npm --prefix web run build # → ✓ built
|
||||
npm --prefix web test # → 151 pass / 4 known fails
|
||||
npx tsc --noEmit -p backend/tsconfig.json # → 0 errors
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Branches & backups
|
||||
|
||||
- **`main`** — current work
|
||||
- **`backup/main-20260504-061739`** — snapshot of `main` taken before the
|
||||
audit-fix commits. Roll back with
|
||||
`git reset --hard backup/main-20260504-061739` if anything goes wrong.
|
||||
|
||||
Sibling repo `learning_ai_common_plat` also has a backup branch
|
||||
`backup/main-20260504-062733` taken from its `origin/main` HEAD `46a16f0`.
|
||||
|
||||
---
|
||||
|
||||
## Vendored `@bytelyst/*` packages
|
||||
|
||||
`web/` consumes 9 vendored packages from `vendor/bytelyst/`. These are
|
||||
read-only copies of the platform packages (sourced from
|
||||
`learning_ai_common_plat`). Don't edit them here — fix upstream and
|
||||
re-vendor.
|
||||
|
||||
The Vite alias config (`web/vite.config.ts`) has a `bytelystAlias()`
|
||||
helper that prefers `web/node_modules/@bytelyst/*` and falls back to
|
||||
`vendor/bytelyst/*`. If you add new platform deps to `web/package.json`,
|
||||
they'll resolve from `web/node_modules` (the npm-installed copy) — not
|
||||
the vendored one. That's intentional but worth knowing if you debug
|
||||
weird "two copies of React" errors.
|
||||
|
||||
---
|
||||
|
||||
## Contact / context
|
||||
|
||||
Original redesign plan lived at
|
||||
`/Users/saravana/.claude/plans/i-want-to-build-woolly-adleman.md` (local
|
||||
file, not in repo). It described the 6-phase build (UI shell → live
|
||||
data → strategy builder → screener → mobile). Phases 1–6 web-side are
|
||||
landed; mobile (phase 7 implicitly) is the remaining greenfield.
|
||||
Loading…
Reference in New Issue
Block a user