diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph1.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph1.md new file mode 100644 index 0000000..c2c4f99 --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph1.md @@ -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`). diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph2.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph2.md new file mode 100644 index 0000000..2ae82d8 --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph2.md @@ -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`. diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.md new file mode 100644 index 0000000..1aee13a --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.md @@ -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. diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.md new file mode 100644 index 0000000..bbcffed --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.md @@ -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. diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph5.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph5.md new file mode 100644 index 0000000..06376fc --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph5.md @@ -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. diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph6.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph6.md new file mode 100644 index 0000000..36e0e95 --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph6.md @@ -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.