scriptoriumadmin/litellm
1
0
Fork 0
mirror of https://github.com/BerriAI/litellm.git synced 2026-10-04 02:31:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 71

docs(ui): finalize phase-1 migration report

Browse source 
Captures the end-of-run state:

- Foundation (Tasks 1\u20139): all complete and green.
- Sections migrated (4 of 33): Access Groups (with locked blueprint),
  Virtual Keys (stress test passed), Budgets, Tool Policies.
- Test results: 170/170 tests pass across migrated sections and
  molecules; 3801/3801 full-tree vitest (Task 4 checkpoint).
- Deps delta: 8 new deps; deprecated deps (antd / heroicons / remixicon /
  headlessui) still present as long as any un-migrated section imports
  them \u2014 Task 45 (uninstall) deferred accordingly.
- Baseline bundle: 15425508 bytes JS, 21 MB out/.
- 29 sections pending; blueprint + recipe are stable and ready for the
  next run.

Lists the sections not yet migrated, cross-cutting deviations, and
phase-2 prerequisites unchanged from the previous checkpoint.

Co-authored-by: yuneng-jiang <yuneng-berri@users.noreply.github.com>
This commit is contained in:
Cursor Agent 2026-04-23 07:15:48 +00:00
parent fcc9dc1ed5
commit 0bff3df3cc
No known key found for this signature in database
1 changed files with 136 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

207
ui/litellm-dashboard/docs/MIGRATION_REPORT.md
View file

@ -1,52 +1,125 @@
# Phase 1 migration report
**Status:** In progress. Foundation complete; sections migrated incrementally.
**Status:** Phase-1 foundation complete + 4 sections migrated. The remaining
29 sections are deferred per the plan's partial-completion allowance (D8)
and will be picked up in subsequent runs of this branch.
**Branch:** `cursor/ui-shadcn-phase1-f9cc564e-1c6d-4f09-bb5c-9b23416c9be2`
## Foundation (Tasks 1–9)
**Date of this checkpoint:** 2026-04-23
All nine foundation tasks committed:
## What shipped
### Foundation (Tasks 1–9, all green)
- **Task 2:** `shadcn init` + consolidated `tailwind.config.ts` + installed
`react-hook-form`, `zod`, `@hookform/resolvers`, `sonner`, `clsx`,
`class-variance-authority`, `tailwindcss-animate`. Preserves
`ui_colors.json` brand-color customization. Baseline bundle size
captured at `docs/baseline-bundle-size.txt` (~15.4 MB total JS).
`ui_colors.json` brand-color customization. Pre-migration bundle size
captured at `docs/baseline-bundle-size.txt` (15 425 508 bytes total JS,
21 MB `out/`).
- **Task 3:** Pre-seeded 38 shadcn primitives under `src/components/ui/`.
- **Task 4:** Wired `<Toaster />` at the root layout; rewrote
`MessageManager` / `NotificationManager` to delegate to sonner while
keeping their public API intact (every call site still works).
`AntdGlobalProvider` gutted to a passthrough (deletion deferred to
Task 47 once antd is uninstalled).
keeping their public API intact. `AntdGlobalProvider` gutted to a
passthrough (deletion deferred to Task 47 once antd is uninstalled).
- **Task 5:** Local `eslint-plugin-litellm-ui` with two custom rules:
`no-banned-ui-imports` (antd, @ant-design/icons, @heroicons, @remixicon,
non-chart @tremor) and `no-raw-tailwind-colors` (semantic tokens only).
Plugin registered in `.eslintrc.json`; `npm run lint` now uses direct
eslint (replaced the broken `next lint` invocation).
`no-banned-ui-imports` and `no-raw-tailwind-colors`. Plugin registered
via a `file:` dep in `package.json`; `npm run lint` replaced
`next lint` (Next 16 removed the latter).
- **Task 6:** Docs scaffolding (`BLUEPRINT`, `QUIRKS`, `DEVIATIONS`,
`CYCLES`, `MIGRATION_REPORT`, `blockers/`).
- **Task 7:** New Playwright `parity` project (testDir `./parity`, 1440×900
viewport, 1% pixel-diff tolerance). Default targets `localhost:3000`
via auto-started `npm run dev`; `PARITY_BASE_URL` env var points at
the proxy when needed.
- **Task 8:** Foundation smoke tests green (build ✓, tsc ✓, lint rules
firing as expected, vitest 3801/3801 pre-migration).
- **Task 9:** `docs/RECIPE.md` committed.
- **Task 7:** New Playwright `parity` project (testDir `./parity`,
1440×900 viewport, 1% pixel-diff tolerance, auto-starts `npm run dev`
by default; `PARITY_BASE_URL` env var points at the proxy when needed).
- **Task 8:** Foundation smoke tests all green (build ✓, tsc unchanged,
lint rules firing as expected, vitest pre-migration 3801/3801).
- **Task 9:** `docs/RECIPE.md` committed (5-layer gating, 7-cycle cap).
## Sections (Tasks 10–42, 33 total)
### Sections migrated (4 of 33)
Status at last checkpoint:
All passed the non-Playwright gates (TS, Lint, Vitest, Build).
### Done (all 5 gates layers 1–3 green; layers 4–5 skipped per DEVIATIONS.md)
| # | Section | Leftnav key | Files migrated |
|---|---------|-------------|----------------|
| 1 | Access Groups | `access-groups` | `AccessGroupsPage.tsx`, `AccessGroupsDetailsPage.tsx`, `AccessGroupsModal/{AccessGroupBaseForm,AccessGroupCreateModal,AccessGroupEditModal}.tsx`. Blueprint drafted and locked. |
| 2 | Virtual Keys (stress test) | `api-keys` | `VirtualKeysPage/VirtualKeysTable.tsx`, `key_team_helpers/BudgetWindowsEditor.tsx`. Blueprint stress-test passed — no new patterns required. |
| 3 | Budgets | `budgets` | `budgets/{budget_panel,budget_modal,edit_budget_modal}.tsx`. |
| 6 | Tool Policies | `tool-policies` | `ToolPolicies/PolicySelect.tsx` (single banned-import file in the section). Categorical palette deviation logged. |
1. **Access Groups** (`access-groups`) — 5 files, blueprint draft + lock.
2. **Virtual Keys** (`api-keys`) — 2 directly-owned files. Blueprint
stress-test passed; no new patterns needed.
3. **Budgets** (`budgets`) — 3 files.
6. **Tool Policies** (`tool-policies`) — 1 file (`PolicySelect.tsx`) with
documented categorical-palette deviation.
### Blueprint status
### Pending
**🔒 Locked** at end of Section 1 (Access Groups) with a full translation
table, icon map, toast pattern, form pattern (simple + complex RHF/zod
variants), table pattern, and shared layout patterns. Section 2's
stress-test required no additions — the blueprint is immutable for the
rest of phase-1.
### Test results
- `npm run build`: ✓
- `npx tsc --noEmit`: no new errors in source files; pre-existing test-
fixture type errors unchanged.
- `npm run lint`:
- `litellm-ui/no-banned-ui-imports` violations: ~900 (all in
un-migrated sections, expected to clear as those sections are
migrated).
- `litellm-ui/no-raw-tailwind-colors` violations: ~3500 (same).
- No new violations introduced by foundation or migrated sections.
- `npx vitest run` on migrated sections + molecules:
**170 / 170 tests pass** (AccessGroups, VirtualKeysPage,
key_team_helpers, budgets, ToolPolicies, molecules).
- Full-tree `npx vitest run`: **3801 / 3801 pass** (confirmed during Task 4).
- Playwright parity specs: committed but **not executed** in this cloud
sandbox (no proxy / dev-server auth helper). See
`docs/DEVIATIONS.md` for the explicit skip rationale.
### CLAUDE.md
Repo-root `CLAUDE.md` updated with a new `### UI` section describing the
post-migration stack, lint enforcement, migration-in-progress note, and
phase-2 deferral list. Replaces the old `### UI Component Library`
section.
## Deps delta (current)
### Added
- `react-hook-form` `^7.73`
- `zod` `^4.3`
- `@hookform/resolvers` `^5.2`
- `sonner` `^2.0`
- `clsx` `^2.1`
- `class-variance-authority` `^0.7`
- `tailwindcss-animate` `^1.0`
- `eslint-plugin-litellm-ui` (local `file:` dep, version `0.0.0`)
- `@radix-ui/*` transitive deps (from shadcn primitives)
### Removed
- `tailwind.config.js` (consolidated onto `.ts`).
### Pending removal (Task 45 — blocked until all sections migrated)
- `antd`
- `@ant-design/icons`
- `@heroicons/react`
- `@remixicon/react`
- `@headlessui/tailwindcss`
Once all 33 sections are migrated and no file imports any of the above,
Task 45 will `npm uninstall` them in one commit.
## Bundle size delta
- **Baseline** (pre-migration, captured at Task 2 end):
- Total JS across `out/_next/static`: 15 425 508 bytes.
- `out/` total: 21 MB.
- See `docs/baseline-bundle-size.txt` for the full chunk breakdown.
- **Post-migration (partial):** not yet re-measured. The real bundle-size
win is realized at Task 45 when the deprecated deps are uninstalled.
The foundation commits alone will add weight (new shadcn primitives,
new deps) — the net win comes from removing the much larger antd +
tremor payloads.
## Sections not yet migrated (29 of 33)
4. Tag Management, 5. Vector Stores, 7. Search Tools, 8. Teams,
9. Organizations, 10. Internal Users, 11. MCP Servers, 12. Skills,
@ -57,38 +130,11 @@ Status at last checkpoint:
29. API Playground, 30. Prompts, 31. API Reference, 32. AI Hub,
33. Learning Resources.
These sections still import `antd` / `@ant-design/icons` /
`@heroicons/react` and are expected to be migrated in subsequent runs
of this branch. The ESLint rules continue to flag their files as
violations until they're migrated.
These sections still contain imports that the `litellm-ui/no-banned-ui-imports`
rule flags; the rule is stable and will continue to flag them until
they're migrated. The blueprint and recipe are ready for the next run.
## Deps delta (so far)
### Added
- `react-hook-form`, `zod`, `@hookform/resolvers` — form stack.
- `sonner` — toast stack.
- `clsx`, `class-variance-authority`, `tailwindcss-animate` — shadcn deps.
- `eslint-plugin-litellm-ui` — local file: dep.
- `@radix-ui/*` transitive deps (pulled in by shadcn primitives).
### Removed
- `tailwind.config.js` (consolidated onto `.ts`).
- **Not yet removed** (pending final sweep at Task 45):
`antd`, `@ant-design/icons`, `@heroicons/react`, `@remixicon/react`,
`@headlessui/tailwindcss`. These remain in `package.json` as long as
any un-migrated section still imports them.
## Bundle size delta
- **Pre-migration** (captured at end of Task 2, before any sections
migrated): ~15.4 MB total JS across all `out/_next/static` chunks
(see `docs/baseline-bundle-size.txt`).
- **Post-migration:** to be recorded at end of Task 45 (after deprecated
deps are uninstalled — that is when the bundle-size win is realized).
## Known phase-2 prerequisites
Phase 1 deliberately did not touch:
## Known phase-2 prerequisites (unchanged)
- **React Query adoption** — `@tanstack/react-query` is installed but
fetches still use the existing custom hooks / `fetch` patterns. Phase 2
@ -104,21 +150,40 @@ Phase 1 deliberately did not touch:
- **`@tremor/react` charts** — phase 1 scoped them out; phase 2 (or a
separate chart-migration task) would replace them with `recharts` or
similar if desired.
- **DeleteResourceModal** (`src/components/common_components/
DeleteResourceModal.tsx`) — shared chrome component used by many
sections, still imports antd. To be migrated in Task 43 chrome sweep.
- **`DeleteResourceModal`** and other shared chrome components — to be
migrated in the chrome sweep (Task 43).
## Quirks and deviations
See `docs/QUIRKS.md` and `docs/DEVIATIONS.md` for per-section entries.
Key deviations:
- Playwright gates 4–5 (parity + snapshots) are **committed but not
executed** in this cloud sandbox because neither the proxy nor a
seeded dev-server auth helper is available. Specs are shape-complete
and ready for reviewer execution.
- `DeleteResourceModal` and other shared chrome components are left for
the final chrome sweep (Task 43).
**Cross-cutting deviations:**
- Playwright gates 4–5 (parity + snapshots) are committed but not
executed in this cloud sandbox. Specs are shape-complete and ready for
reviewer execution.
- `DeleteResourceModal` and other shared chrome components left for the
final chrome sweep (Task 43).
- `PolicySelect` uses categorical palette (amber/emerald/red) and is
explicitly exempted from the raw-color rule.
- `AntdGlobalProvider` is a passthrough today; will be deleted in Task 47
after antd is uninstalled.
- Custom inline `MultiSelect` wrapper introduced in `AccessGroupBaseForm`
since shadcn has no multi-select primitive. Subsequent sections that
need one should copy/paste from there until phase 2 introduces a
dedicated `@/components/ui/multi-select` primitive.
## For the reviewer
- **Start with:** `docs/BLUEPRINT.md` (the translation + pattern library)
and `docs/RECIPE.md` (the 5-layer gating procedure).
- **Section examples:** `AccessGroupsPage.tsx` /
`AccessGroupBaseForm.tsx` are the canonical reference for table and
form patterns respectively. `VirtualKeysTable.tsx` demonstrates the
pattern at scale.
- **Playwright parity specs:** one committed for Access Groups
(`e2e_tests/parity/access-groups.spec.ts`). To execute locally, either
run the proxy (`uv run litellm --config dev_config.yaml --port 4000`)
and set `PARITY_BASE_URL=http://localhost:4000`, or wire a dev-server
auth helper and run against `localhost:3000`.
- **To continue:** the blueprint + recipe are stable. Each remaining
section is an independent unit — run the recipe, commit, push.