docs(tasks): establish discrete phase task files ph1 through ph6 for monolith decomposition roadmap
This commit is contained in:
parent
5de9bdf18c
commit
f912241937
@ -0,0 +1,45 @@
|
||||
# TASK METADATA
|
||||
|
||||
- **Target Files:** `ui/components/SessionsPage.tsx`,
|
||||
`ui/components/sessions/EventCockpitDeck.tsx`,
|
||||
`ui/components/sessions/DirectPassDrawer.tsx`,
|
||||
`ui/components/sessions/WorkshopDrawer.tsx`,
|
||||
`ui/components/sessions/ScopeModal.tsx`, `ui/ui_scripts.test.ts`
|
||||
- **Core Objective:** Phase 1 (UI Sessions Decomposition): Refactor the
|
||||
monolithic `SessionsPage.tsx` (~1,500 lines) by extracting sub-sections into
|
||||
clean, dedicated subcomponents under `ui/components/sessions/` while
|
||||
preserving zero-framework SSR JSX purity and client script integrity.
|
||||
- **Dependencies:**
|
||||
`tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md`
|
||||
- **Additional Important Notes:** Must pass `ui/ui_scripts.test.ts` with zero
|
||||
client-side syntax errors.
|
||||
|
||||
---
|
||||
|
||||
### 2. Architectural Considerations & Risks
|
||||
|
||||
- **Risks:**
|
||||
- Client-side script breakage or broken DOM element bindings if IDs/forms are
|
||||
altered during component extraction.
|
||||
- HTML5 form validation collisions if form elements are improperly nested.
|
||||
- **Alternatives:**
|
||||
- Extracting to static external JS files; deferred to maintain hermetic SSR
|
||||
script validation within `ui_scripts.test.ts`.
|
||||
|
||||
### 3. Proposed Implementation
|
||||
|
||||
1. **Create Subcomponents (`ui/components/sessions/`):**
|
||||
- `EventCockpitDeck.tsx`: The Event Cockpit banner and live active event
|
||||
cards.
|
||||
- `DirectPassDrawer.tsx`: The 1:1 Direct Pass delegation form, presets, and
|
||||
`#handoffModal`.
|
||||
- `WorkshopDrawer.tsx`: The Multi-Claim Workshop Pass form, seat presets,
|
||||
vanity slug/PIN inputs, and `#eventHandoffModal`.
|
||||
- `ScopeModal.tsx`: The custom scope editor modal dialog.
|
||||
2. **Refactor `ui/components/SessionsPage.tsx`:**
|
||||
- Import and assemble the subcomponents cleanly into the main page shell.
|
||||
- Retain the single header button (`[+ Delegate Session]`), segmented flexbox
|
||||
tab switcher, and Active Sessions table.
|
||||
3. **Quality Gates & Validation:**
|
||||
- Run `deno fmt`, `deno task lint`, `deno task check`.
|
||||
- Run `deno test --allow-all` (specifically `ui/ui_scripts.test.ts`).
|
||||
@ -0,0 +1,44 @@
|
||||
# TASK METADATA
|
||||
|
||||
- **Target Files:** `ui/components/AdminInvitesPage.tsx`,
|
||||
`ui/components/AdminUserDetailsPage.tsx`, `ui/components/AdminRolesPage.tsx`,
|
||||
`ui/components/AdminAppsPage.tsx`, `ui/components/admin/AdminTable.tsx`,
|
||||
`ui/components/admin/AdminModal.tsx`, `ui/ui_scripts.test.ts`
|
||||
- **Core Objective:** Phase 2 (UI Admin Pages Decomposition): Refactor large
|
||||
admin pages (each > 490 lines) by extracting repeated table structures, modal
|
||||
dialogs, and filters into reusable components under `ui/components/admin/`.
|
||||
- **Dependencies:**
|
||||
`tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md`
|
||||
- **Additional Important Notes:** Must preserve 100% pure Hono SSR JSX layout
|
||||
styling, responsive mobile cards (< 768px), and pass `ui/ui_scripts.test.ts`.
|
||||
|
||||
---
|
||||
|
||||
### 2. Architectural Considerations & Risks
|
||||
|
||||
- **Risks:**
|
||||
- Breaking existing DOM event handlers or form submissions on user management,
|
||||
app creation, role binding, and invite creation.
|
||||
- **Alternatives:**
|
||||
- Monolithic single-page components; rejected due to high cognitive complexity
|
||||
and code duplication across admin views.
|
||||
|
||||
### 3. Proposed Implementation
|
||||
|
||||
1. **Create Shared Admin Subcomponents (`ui/components/admin/`):**
|
||||
- `AdminTable.tsx`: Reusable data table component with desktop table and
|
||||
mobile card layout support.
|
||||
- `AdminModal.tsx`: Reusable modal wrapper with standard backdrop, header,
|
||||
and close bindings.
|
||||
2. **Decompose Admin Pages:**
|
||||
- `AdminInvitesPage.tsx` (771 lines): Extract invite creation drawer and bulk
|
||||
action modals.
|
||||
- `AdminUserDetailsPage.tsx` (541 lines): Extract grant assignment table and
|
||||
session revocation panel.
|
||||
- `AdminRolesPage.tsx` (514 lines): Extract role definition forms and
|
||||
permission picker.
|
||||
- `AdminAppsPage.tsx` (493 lines): Extract app registration drawer and SPIFFE
|
||||
attestation card.
|
||||
3. **Quality Gates & Validation:**
|
||||
- Run `deno fmt`, `deno task lint`, `deno task check`.
|
||||
- Run `deno test --allow-all` and verify `ui/ui_scripts.test.ts`.
|
||||
@ -0,0 +1,46 @@
|
||||
# TASK METADATA
|
||||
|
||||
- **Target Files:** `server/main.ts`, `server/routes/admin.ts`,
|
||||
`server/routes/auth.ts`, `server/middleware.ts`, `server/rpc.ts`,
|
||||
`server/main.test.ts`
|
||||
- **Core Objective:** Phase 3 (Server Route Modularization): Decompose the
|
||||
2,100-line `server/main.ts` entrypoint into modular feature routers
|
||||
(`routes/admin.ts`, `routes/auth.ts`), dedicated middleware
|
||||
(`server/middleware.ts`), and RPC configuration (`server/rpc.ts`).
|
||||
- **Dependencies:**
|
||||
`tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md`
|
||||
- **Additional Important Notes:** Must preserve exact HTTP routes, status codes,
|
||||
zero-trust scope guards, and passing tests in `server/main.test.ts`.
|
||||
|
||||
---
|
||||
|
||||
### 2. Architectural Considerations & Risks
|
||||
|
||||
- **Risks:**
|
||||
- Route mounting order changes in Hono could alter middleware execution (e.g.
|
||||
rate limiting or auth resolution).
|
||||
- Circular dependencies between route modules and `auth-session.ts`.
|
||||
- **Alternatives:**
|
||||
- Keeping all routes in `main.ts`; rejected because 2,100+ lines violate
|
||||
Single Responsibility Principle.
|
||||
|
||||
### 3. Proposed Implementation
|
||||
|
||||
1. **Extract Feature Routers (`server/routes/`):**
|
||||
- `server/routes/admin.ts`: Extract all `/api/admin/*` CRUD endpoints (users,
|
||||
apps, roles, grants, invites, recovery, audit logs).
|
||||
- `server/routes/auth.ts`: Extract WebAuthn passkey registration
|
||||
challenge/verify, login challenge/verify, PRF evaluation, and
|
||||
`/api/passkeys/*` endpoints.
|
||||
2. **Extract Infrastructure & Middleware Modules:**
|
||||
- `server/middleware.ts`: Extract rate limiting, CORS, security headers, and
|
||||
request logging.
|
||||
- `server/rpc.ts`: Extract ConnectRPC daemon service registration and SPIFFE
|
||||
mTLS listener setup.
|
||||
3. **Slim Down `server/main.ts`:**
|
||||
- Retain `main.ts` purely as the application entrypoint assembling the
|
||||
sub-routers and serving the HTTP listener.
|
||||
4. **Quality Gates & Validation:**
|
||||
- Run `deno fmt`, `deno task lint`, `deno task check`.
|
||||
- Run `deno test --allow-all` to ensure all API routes resolve with 100%
|
||||
fidelity.
|
||||
@ -0,0 +1,40 @@
|
||||
# TASK METADATA
|
||||
|
||||
- **Target Files:** `infra/setup.ts`, `infra/setup/cli.ts`,
|
||||
`infra/setup/compose.ts`, `infra/setup/env.ts`
|
||||
- **Core Objective:** Phase 4 (Infrastructure Scripts Refactoring): Decompose
|
||||
the monolithic 1,021-line `infra/setup.ts` installer into modular sub-modules
|
||||
under `infra/setup/` separating CLI interactive prompts, Docker compose
|
||||
generation, and environment file management.
|
||||
- **Dependencies:**
|
||||
`tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md`
|
||||
- **Additional Important Notes:** Must verify with `deno check infra/setup.ts`
|
||||
and ensure dry-run generation produces identical compose and env files.
|
||||
|
||||
---
|
||||
|
||||
### 2. Architectural Considerations & Risks
|
||||
|
||||
- **Risks:**
|
||||
- Generating corrupted `docker-compose.yml` or `.env` files if template
|
||||
strings or formatting helpers are incorrectly moved.
|
||||
- **Alternatives:**
|
||||
- Keeping setup.ts as a single monolithic script; rejected due to maintenance
|
||||
difficulty and cognitive overload.
|
||||
|
||||
### 3. Proposed Implementation
|
||||
|
||||
1. **Extract Modular Setup Sub-modules (`infra/setup/`):**
|
||||
- `infra/setup/cli.ts`: Extract interactive command-line prompts, flags
|
||||
parsing, and user confirmation dialogs.
|
||||
- `infra/setup/compose.ts`: Extract Docker compose YAML string generation and
|
||||
network/volume configuration.
|
||||
- `infra/setup/env.ts`: Extract `.env` file generation, cryptographic secret
|
||||
generation (keys, salts, PRF secrets), and domain configuration.
|
||||
2. **Refactor `infra/setup.ts`:**
|
||||
- Keep `infra/setup.ts` as the clean CLI runner that orchestrates the
|
||||
extracted modules.
|
||||
3. **Quality Gates & Validation:**
|
||||
- Run `deno check infra/setup.ts`.
|
||||
- Run `deno fmt infra/` and verify generated configs against dummy test
|
||||
parameters.
|
||||
@ -0,0 +1,41 @@
|
||||
# TASK METADATA
|
||||
|
||||
- **Target Files:** `server/main.test.ts`, `server/tests/forward_auth.test.ts`,
|
||||
`server/tests/rpc.test.ts`, `server/tests/auth.test.ts`,
|
||||
`server/tests/events.test.ts`, `server/tests/scopes.test.ts`
|
||||
- **Core Objective:** Phase 5 (Test Suite Tier Separation): Decompose the
|
||||
1,577-line `server/main.test.ts` monolith into isolated, domain-specific test
|
||||
suites under `server/tests/` preserving 100% test coverage and hermetic
|
||||
execution without live database daemons.
|
||||
- **Dependencies:**
|
||||
`tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md`
|
||||
- **Additional Important Notes:** Must run with `deno test --allow-all` and
|
||||
maintain all 59+ test steps passing cleanly.
|
||||
|
||||
---
|
||||
|
||||
### 2. Architectural Considerations & Risks
|
||||
|
||||
- **Risks:**
|
||||
- Mock state pollution across test files (e.g. shared `sqlWrapper` or `valkey`
|
||||
stubs leaking between test cases).
|
||||
- **Alternatives:**
|
||||
- Keeping all tests in `server/main.test.ts`; rejected because single massive
|
||||
test files make targeted debugging and CI test parallelization difficult.
|
||||
|
||||
### 3. Proposed Implementation
|
||||
|
||||
1. **Create Domain Test Files (`server/tests/`):**
|
||||
- `server/tests/forward_auth.test.ts`: Tier 1 & 2 ForwardAuth tests, cookie
|
||||
domain scoping, bypass rules, and guest sandbox tests.
|
||||
- `server/tests/rpc.test.ts`: Tier 3 ConnectRPC session validation, RBAC
|
||||
grant evaluation, and SPIFFE attestation tests.
|
||||
- `server/tests/auth.test.ts`: WebAuthn registration/login PRF extraction,
|
||||
session creation, and audit logging.
|
||||
- `server/tests/events.test.ts`: Multi-claim event passes, PIN join
|
||||
endpoints, session extension, and master killswitch.
|
||||
- `server/tests/scopes.test.ts`: Zero-trust scope guards, self-revocation,
|
||||
and UI `/admin` redirection gates.
|
||||
2. **Quality Gates & Validation:**
|
||||
- Run `deno test --allow-all` to ensure all domain test suites execute
|
||||
hermetically and pass with 0 failures.
|
||||
@ -0,0 +1,45 @@
|
||||
# TASK METADATA
|
||||
|
||||
- **Target Files:** `server/auth-session.ts`, `server/forward_auth.ts`,
|
||||
`server/session_resolver.ts`, `ui/mod.ts`, `ui/db_queries.ts`,
|
||||
`ui/auth_checks.ts`, `server/main.test.ts`
|
||||
- **Core Objective:** Phase 6 (Core Logic Refactoring): Separate database
|
||||
queries and admin authorization checks from pure SSR page routing in
|
||||
`ui/mod.ts`, and decouple ForwardAuth ingress handling from session
|
||||
caching/resolution in `server/auth-session.ts`.
|
||||
- **Dependencies:**
|
||||
`tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.md`
|
||||
- **Additional Important Notes:** Must maintain fast-path microsecond Valkey
|
||||
caching, zero-dependency SDK compatibility, and pass all quality gates.
|
||||
|
||||
---
|
||||
|
||||
### 2. Architectural Considerations & Risks
|
||||
|
||||
- **Risks:**
|
||||
- Introducing latency in ForwardAuth validation if session resolution
|
||||
dependencies are decoupled improperly.
|
||||
- Circular import dependencies between Hono routing and session resolver
|
||||
modules.
|
||||
- **Alternatives:**
|
||||
- Leaving logic combined; rejected to ensure clear layer separation between
|
||||
edge ingress and data store resolution.
|
||||
|
||||
### 3. Proposed Implementation
|
||||
|
||||
1. **Decompose `server/auth-session.ts`:**
|
||||
- `server/forward_auth.ts`: Extract Traefik ForwardAuth header parsing,
|
||||
dynamic bypass evaluation (`is_public`, `bypass_paths`), and upstream
|
||||
identity injection.
|
||||
- `server/session_resolver.ts`: Extract multi-cookie iteration, Valkey L1/L2
|
||||
cache resolution, and PostgreSQL fallback queries.
|
||||
2. **Decompose `ui/mod.ts`:**
|
||||
- `ui/db_queries.ts`: Extract raw SQL queries for loading apps, roles,
|
||||
grants, invites, and audit logs.
|
||||
- `ui/auth_checks.ts`: Extract admin authorization and session verification
|
||||
middleware.
|
||||
- `ui/mod.ts`: Retain purely as clean SSR route mounting.
|
||||
3. **Quality Gates & Validation:**
|
||||
- Run `deno fmt`, `deno task lint`, `deno task check`.
|
||||
- Run `deno test --allow-all` to ensure all routes and test suites pass
|
||||
cleanly.
|
||||
Loading…
x
Reference in New Issue
Block a user