diff --git a/docs/plans/2026-03-23-single-source-consolidation-mega-plan.md b/docs/plans/2026-03-23-single-source-consolidation-mega-plan.md new file mode 100644 index 0000000..b14bce5 --- /dev/null +++ b/docs/plans/2026-03-23-single-source-consolidation-mega-plan.md @@ -0,0 +1,96 @@ +# Single Source Consolidation Full-Scope Follow-Through + +## Context + +This document supersedes the scoped execution boundary of +[`2026-03-22-single-source-consolidation-pr1.md`](./2026-03-22-single-source-consolidation-pr1.md) +for PR #244. The PR1 document remains a historical snapshot of the initial +landing slice. This document captures the expanded branch-wide finish that +continued until the single-source, workflow, schema, and web admin duplication +themes were fully closed for this PR. + +## Goals + +- Eliminate active double-source implementations for proxy protocols and runtime headers. +- Centralize account, OAuth, route refresh, and platform discovery workflows. +- Collapse schema metadata normalization and feature compatibility drift points. +- Remove repeated web admin page scaffolding and large inline modal/panel implementations. +- Finish the branch in a merge-ready state with focused regressions and formal builds. + +## Scope Delivered In This Branch + +### Server and Shared Runtime + +- OpenAI Responses normalization and conversion now flow through one shared implementation boundary. +- Shared proxy surface orchestration owns retry recovery, success bookkeeping, and surface-level failure handling. +- Provider header/body runtime shaping is centralized behind provider profiles and shared header utilities. +- OAuth identity now treats structured columns as the canonical source, with compatibility/backfill isolated to a removable layer. +- Route refresh and rebuild sequencing flows through `routeRefreshWorkflow`, not controller-local orchestration. +- Platform discovery moved out of `modelService` into dedicated registry-backed discovery modules. +- Schema metadata normalization is shared by contract and introspection code paths. +- Legacy schema compatibility derives feature-owned allowances from feature specs instead of maintaining a second whitelist. + +### Web Admin + +- Token-route, brand, and downstream client display rules now rely on shared helpers and registries instead of page-local duplicates. +- `ResponsiveBatchActionBar` centralizes repeated batch action shells across admin list pages. +- `ResponsiveFilterPanel` centralizes the responsive "desktop controls vs mobile sheet" scaffold across admin pages. +- `Settings`, `Accounts`, `ModelTester`, and `DownstreamKeys` no longer keep their heaviest modal or drawer UIs inline in the page file. +- Brand matching metadata is owned by `brandRegistry`, with `BrandIcon` reduced to rendering concerns. + +## Commit Groups + +### Protocol and Workflow Consolidation + +- review-driven cleanup commits +- OAuth identity and route refresh workflow commits +- downstream client/runtime header/profile consolidation commits +- platform discovery extraction commits + +### Schema and Shared Contract Consolidation + +- shared schema metadata normalization +- legacy schema compatibility derivation from feature specs +- shared token-route contract and pattern ownership + +### Web Admin Decomposition + +- responsive batch action scaffold +- responsive filter scaffold +- settings modal extraction +- accounts model management modal extraction +- model tester panel extraction +- downstream key drawer extraction + +## Final Verification Matrix + +Run these groups before calling the branch complete. + +### Protocol and Surface + +- `npm test -- src/server/proxy-core/surfaces/sharedSurface.test.ts src/server/routes/proxy src/server/transformers/openai/responses src/server/transformers/anthropic/messages src/server/services/proxyInputFileResolver.test.ts` + +### OAuth, Workflow, and Platforms + +- `npm test -- src/server/routes/api src/server/services/accountMutationWorkflow.test.ts src/server/services/modelService.discovery.test.ts src/server/services/oauth/oauthAccount.test.ts src/server/services/platforms/standardApiProvider.test.ts src/server/services/platforms/llmUpstream.test.ts` + +### Schema + +- `npm run test:schema:unit` +- `npm run schema:contract` +- `npm run smoke:db:sqlite` + +### Web and Build + +- `npm test -- src/web/pages/responsiveFilterPanel.architecture.test.ts src/web/pages/checkin.mobile.test.tsx src/web/pages/logs.mobile.test.tsx src/web/pages/programLogs.mobile-layout.test.tsx src/web/pages/accounts.batch-actions.test.tsx src/web/pages/sites.mobile-actions.test.tsx src/web/pages/tokens.batch-actions.test.tsx src/web/pages/DownstreamKeys.test.tsx src/web/pages/DownstreamKeys.mobile.test.tsx src/web/pages/downstreamKeys.mobile-layout.test.tsx src/web/pages/tokenRoutes.mobile-layout.test.tsx src/web/pages/tokenRoutes.mobile.test.tsx src/web/pages/models.mobile-layout.test.tsx` +- `npm run build` + +## Done Definition + +The branch is complete when: + +- no page under `src/web/pages` imports `MobileFilterSheet` directly; +- no active protocol path keeps parallel single-source conversions alive; +- controller layers do not own route rebuild choreography; +- schema metadata and compatibility rules do not keep a second handwritten truth source; +- focused regressions and formal builds pass from the commands above.