127 lines
5.6 KiB
Markdown
127 lines
5.6 KiB
Markdown
# TASK METADATA
|
|
|
|
- **Target Files:** `server/main.ts`, `server/main.test.ts`,
|
|
`ui/components/SessionsPage.tsx`, `server/auth-session.ts`, `ui/mod.ts`,
|
|
`infra/setup.ts`, `ui/utils/bip39_wordlist.ts` (and copies),
|
|
`spire_ffi/Cargo.lock`, `ui/components/AdminInvitesPage.tsx`,
|
|
`ui/components/AdminUserDetailsPage.tsx`, `deno.lock`,
|
|
`ui/components/AdminRolesPage.tsx`, `ui/components/AdminAppsPage.tsx`
|
|
- **Core Objective:** Architect a phased, zero-regression modular decomposition
|
|
plan to eliminate monoliths and enforce the Single Responsibility Principle.
|
|
- **Dependencies:** None.
|
|
- **Additional Important Notes:** Must preserve zero-dependency SDK purity
|
|
(`@auth-yes/sdk`) and guarantee 100% backward compatibility with all quality
|
|
gates (`deno fmt`, `deno task lint`, `deno task check`, `deno task test`).
|
|
|
|
---
|
|
|
|
### 2. Architectural Considerations & Risks
|
|
|
|
- **Risks:**
|
|
- **Circular Dependencies:** Moving components could introduce circular
|
|
dependencies, especially between `auth-session.ts` and routing files.
|
|
- **Regression:** Splitting monolithic files (e.g., `main.test.ts`) might
|
|
cause tests to fail or miss edge cases if not carefully separated by domain
|
|
tier.
|
|
- **Client-Side Breakage:** Extracting inline JS strings from JSX (e.g.,
|
|
`SessionsPage.tsx`) to external vanilla JS files could break dynamic
|
|
interactions if DOM elements are not correctly targeted or if loading
|
|
sequence is altered.
|
|
- **Alternatives:**
|
|
- Instead of extracting completely to static files, use Deno Island
|
|
architectures if supported, but given the strict instruction to use pure
|
|
Hono SSR JSX (strictly no React) and vanilla JavaScript, static ES modules
|
|
under `ui/public/ui/` or `ui/static/` is the optimal, native approach.
|
|
|
|
### 3. Proposed Implementation
|
|
|
|
The refactoring will be executed in a safe, phased approach to guarantee zero
|
|
regressions:
|
|
|
|
#### Phase 1: UI Sessions Decomposition (Frontend)
|
|
|
|
- **Target:** `ui/components/SessionsPage.tsx`
|
|
- **Actions:**
|
|
- Extract the Event Cockpit Deck logic into
|
|
`ui/components/sessions/EventCockpitDeck.tsx`.
|
|
- Extract the Workshop Launch Drawer logic into
|
|
`ui/components/sessions/WorkshopDrawer.tsx`.
|
|
- Extract the 1:1 Delegation Drawer logic into
|
|
`ui/components/sessions/DirectPassDrawer.tsx`.
|
|
- Extract the Scope Modal logic into `ui/components/sessions/ScopeModal.tsx`.
|
|
- Move the 400+ lines of raw client-side JavaScript currently embedded in
|
|
string templates (`dangerouslySetInnerHTML`) into a dedicated static vanilla
|
|
JS module (e.g., `ui/public/ui/sessions.js`) and link it via a
|
|
`<script type="module" src="...">` tag.
|
|
- **Validation:** Run UI unit tests, `deno task lint`, and visual checks to
|
|
ensure all modals and JS interactions still work.
|
|
|
|
#### Phase 2: UI Admin Pages Decomposition (Frontend)
|
|
|
|
- **Target:** `ui/components/AdminInvitesPage.tsx`,
|
|
`ui/components/AdminUserDetailsPage.tsx`, `ui/components/AdminRolesPage.tsx`,
|
|
`ui/components/AdminAppsPage.tsx`
|
|
- **Actions:**
|
|
- Refactor large admin pages (all > 490 lines) by extracting repeated layout
|
|
structures, table rendering, and modal dialogs into reusable components
|
|
(e.g., `ui/components/admin/AdminTable.tsx`,
|
|
`ui/components/admin/AdminModal.tsx`).
|
|
- Move embedded client-side javascript logic from these files into
|
|
corresponding static vanilla JS modules in `ui/public/ui/`.
|
|
- **Validation:** Visual validation of admin interfaces, `deno task lint`.
|
|
|
|
#### Phase 3: Server Route Modularization (Backend)
|
|
|
|
- **Target:** `server/main.ts` and `server/routes/`
|
|
- **Actions:**
|
|
- Extract Admin CRUD routes (`/api/admin/*`) into a new file:
|
|
`server/routes/admin.ts`.
|
|
- Extract WebAuthn and Passkey logic (`/api/login`, `/api/register`,
|
|
`/api/passkeys`) into `server/routes/auth.ts`.
|
|
- Move ConnectRPC daemon orchestration and middleware/rate limiting setup into
|
|
dedicated configuration modules (e.g., `server/middleware.ts`,
|
|
`server/rpc.ts`).
|
|
- Keep `server/main.ts` purely as the application entrypoint for mounting
|
|
sub-routers.
|
|
- **Validation:** Run `deno task test` to ensure all API endpoints resolve
|
|
correctly.
|
|
|
|
#### Phase 4: Infrastructure Scripts Refactoring (DevOps)
|
|
|
|
- **Target:** `infra/setup.ts`
|
|
- **Actions:**
|
|
- Split the 1000+ line setup script.
|
|
- Extract CLI configuration/prompt logic into `infra/setup/cli.ts`.
|
|
- Extract Docker compose generation/writing logic into
|
|
`infra/setup/compose.ts`.
|
|
- Extract environment variable handling into `infra/setup/env.ts`.
|
|
- **Validation:** Run `deno check infra/setup.ts` and verify script execution
|
|
against a dummy environment.
|
|
|
|
#### Phase 5: Test Suite Tier Separation (Testing)
|
|
|
|
- **Target:** `server/main.test.ts`
|
|
- **Actions:**
|
|
- Split the 1,300+ line test monolith by domain.
|
|
- Create `server/tests/auth.test.ts` for WebAuthn PRF and Cookie Domain
|
|
scoping.
|
|
- Create `server/tests/forward_auth.test.ts` for Tier 1/2 ForwardAuth tests.
|
|
- Create `server/tests/rpc.test.ts` for Tier 3 ConnectRPC tests.
|
|
- Create `server/tests/events.test.ts` for Event passes and Session delegation
|
|
tests.
|
|
- **Validation:** Run `deno task test` and ensure all hermetic tests pass
|
|
without Docker.
|
|
|
|
#### Phase 6: Core Logic Refactoring (Utilities)
|
|
|
|
- **Target:** `server/auth-session.ts` and `ui/mod.ts`
|
|
- **Actions:**
|
|
- Split `server/auth-session.ts`: Move ForwardAuth ingress logic to
|
|
`server/forward_auth.ts`, and Valkey/Postgres resolution to
|
|
`server/session_resolver.ts`.
|
|
- Split `ui/mod.ts`: Separate database queries and admin authorization checks
|
|
from pure SSR page routing. Create `ui/db_queries.ts` and
|
|
`ui/auth_checks.ts`.
|
|
- **Validation:** Full suite `deno task check`, `deno fmt`, and
|
|
`deno task test`.
|