From 372b83820f4c609884cbcce7f00945477a0c36c4 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Mon, 4 May 2026 14:24:02 -0700 Subject: [PATCH] docs: add HANDOVER.md for the next contributor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/HANDOVER.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/HANDOVER.md diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md new file mode 100644 index 0000000..6099e63 --- /dev/null +++ b/docs/HANDOVER.md @@ -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.