diff --git a/AGENTS.md b/AGENTS.md index 7669340..f8a7cfe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,10 +117,14 @@ Management (IAM) fabric and WebAuthn Passkey authority. explicit, searchable domain names (`SessionPinRotator`, `streamGuestDrawerTelemetry`, `SessionHandoffCard`). 5. **Deterministic Tooling Enforcement:** - - All code quality standards must be enforced by automated tooling - (`deno - fmt`, `deno task lint`, `deno task check`, `deno test`). Agents - must verify passing gates before completing tasks. + - All code quality and architectural standards must be enforced by automated + tooling (`deno fmt`, `deno task lint`, `deno task check`, `deno test`). + Architectural linters run as part of `deno task lint` to catch banned DOM + APIs or missing `data-ignore` attributes immediately. +6. **Legacy Code Quarantine:** + - During migration phases, legacy `server/` and `ui/` directories are + strictly read-only reference. All new code, routes, queries, and fragments + must be authored exclusively in `src/`. ## 6. History & Context Link diff --git a/tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md b/tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md index f50ab94..f495b7f 100644 --- a/tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md +++ b/tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md @@ -1,55 +1,116 @@ # TASK METADATA -- **Target Files:** `src/core/`, `src/features/`, `src/shared/`, `src/tests/arch/`, `server/` (legacy), `ui/` (legacy). Note: `sdk/` and `spire_ffi/` must remain independent top-level root modules. -- **Core Objective:** Execute a multi-phase, non-overlapping architectural transition to a Datastar-driven Hypermedia paradigm and Vertical Feature Slicing. +- **Target Files:** `src/core/`, `src/features/`, `src/shared/`, + `src/tests/arch/`, `server/` (legacy), `ui/` (legacy). Note: `sdk/` and + `spire_ffi/` must remain independent top-level root modules. +- **Core Objective:** Execute a multi-phase, non-overlapping architectural + transition to a Datastar-driven Hypermedia paradigm and Vertical Feature + Slicing. - **Dependencies:** `docs/HYPERMEDIA_ARCHITECTURE_BLUEPRINT.md`, `AGENTS.md`. -- **Additional Important Notes:** The code does not need to maintain backwards-compatible bridges for legacy vanilla scripts during intermediate phases; optimize for a clean, uncompromised vertical slice architecture in `src/`. +- **Additional Important Notes:** The code does not need to maintain + backwards-compatible bridges for legacy vanilla scripts during intermediate + phases; optimize for a clean, uncompromised vertical slice architecture in + `src/`. --- ## Architectural Considerations & Risks - **Risks:** - - Moving from a separated `server/` and `ui/` structure to co-located `src/features/` will require extensive routing and import refactoring. - - Dropping legacy imperative DOM scripts in favor of Datastar requires strict adherence to `data-ignore` for WebAuthn micro-scripts so the DOM diffing engine doesn't wipe critical ceremony state. - - Converting SSE streams to the typed adapter (`core/sse_adapter.ts`) might break existing real-time UI components if payload formats are mismatched. + - Moving from a separated `server/` and `ui/` structure to co-located + `src/features/` will require extensive routing and import refactoring. + - Dropping legacy imperative DOM scripts in favor of Datastar requires strict + adherence to `data-ignore` for WebAuthn micro-scripts so the DOM diffing + engine doesn't wipe critical ceremony state. + - Converting SSE streams to the typed adapter (`core/sse_adapter.ts`) might + break existing real-time UI components if payload formats are mismatched. - **Alternatives:** - - Instead of moving to `src/`, we could restructure within `server/`. However, adopting `src/features/` enforces a clean break from the legacy horizontally sliced architecture and clearly demarcates the new vertical hypermedia standard. + - Instead of moving to `src/`, we could restructure within `server/`. However, + adopting `src/features/` enforces a clean break from the legacy horizontally + sliced architecture and clearly demarcates the new vertical hypermedia + standard. ## Proposed Implementation -### Phase 1: Core Foundation & Datastar Engine -Establish the authoritative infrastructure and invariant guards inside the new `src/core/` boundary. +### Phase 1: Core Foundation, Tooling & Safety Guards + +Establish the authoritative infrastructure, transport toolkit, and invariant +guards inside `src/core/`. + 1. Create `src/core/` directory. -2. Migrate and adapt foundational integrations from `server/`: +2. Migrate and adapt foundational integrations from `server/` (strictly + read-only reference): - `db.ts`: PostgreSQL connection pool and queries. - `valkey.ts`: Valkey connection and Pub/Sub broker. - `spire_ffi.ts`: Rust SPIFFE/mTLS FFI bindings. -3. Implement `auth_guards.ts` (enforcing max 16KB payload cap, rate limiting, and CSRF/Origin check). -4. Implement `content_negotiation.ts` to cleanly route between standard Datastar HTML requests, CLI/JSON clients, and shell strings. +3. Implement `auth_guards.ts` (enforcing max 16KB payload cap, rate limiting, + and CSRF/Origin checks). +4. Implement `content_negotiation.ts` to route between Datastar HTML, CLI/JSON + clients, and shell strings. +5. Implement `sse_adapter.ts` for typed Datastar SSE streaming helper logic. +6. Implement `error_fragments.tsx` for standardized error toast and field-error + JSX morph fragments. +7. Setup `src/main.ts` with `serveStatic` for `/public/datastar-v1.x.js`. +8. Add `deno task lint:arch` in `scripts/lint_arch.ts` (blocking + `document.getElementById` and unescaped HTML) and integrate into `deno.json`. ### Phase 2: Base Vertical Slices & Shared UI -Migrate domain-agnostic presentation atoms and standard CRUD-style feature slices. -1. Create `src/shared/ui/` and migrate generic components (Layout, Navbar, Toast, DrawerShell, PillGroup, Accordion). Ensure `Layout.tsx` loads `/public/datastar-v1.x.js`. -2. Create `src/features/auth/` and migrate `/login`, `/register`, and `/recovery`. Extract WebAuthn ceremony scripts into `webauthn.ts` and ensure target DOM nodes include `data-ignore` attributes. -3. Create `src/features/admin/` and migrate admin routes, SQL queries, and fragments (RoleModals, AdminTables) for user and app management. -### Phase 3: Real-Time Slices Migration -Migrate the complex, interactive features and eliminate legacy imperative scripts in favor of targeted SSE and Datastar morphs. -1. Create `src/core/sse_adapter.ts` for typed Datastar SSE streaming helper logic. -2. Create `src/features/events/`: - - Migrate event routing, queries, and JSX fragments (EventCockpit, WorkshopDrawer). - - Implement `stream.ts` using the new typed SSE adapter for live seat counters bound to Valkey Pub/Sub. -3. Create `src/features/sessions/`: - - Migrate routing, queries, and fragments (SessionTable, HandoffCard). - - Eliminate legacy `SessionsScript.tsx` completely, replacing interactive flows with Datastar attributes (`data-on-click`, `data-signals`). -4. Delete legacy `server/` and `ui/` directories once migration is fully verified. +Migrate domain-agnostic presentation atoms and standard CRUD-style feature +slices. + +1. Create `src/shared/ui/` with distinctive fragment names (`LayoutFragment`, + `NavbarFragment`, `ToastFragment`, `DrawerShellFragment`, + `PillGroupFragment`, `AccordionFragment`). +2. Create `src/features/auth/` and migrate `/login`, `/register`, and + `/recovery`. Extract WebAuthn ceremony scripts into `webauthn.ts` with + explicit `data-ignore` attributes. +3. Create `src/features/admin/` and migrate admin routes, SQL queries, and + fragments (`AdminUserTableFragment`, `AdminAppCardFragment`, + `RoleModalFragment`). +4. Add pure JSX unit tests: `auth.test.ts` and `admin.test.ts`. + +### Phase 3: Real-Time Slices & Script Elimination + +Migrate complex, interactive features and eliminate legacy imperative scripts in +favor of targeted SSE and Datastar morphs. + +1. Create `src/features/events/`: + - Migrate event routing, queries, and JSX fragments + (`EventCockpitDeckFragment`, `WorkshopPassDrawerFragment`, + `GuestDrawerAttendeesFragment`). + - Implement `stream.ts` using `src/core/sse_adapter.ts` for live seat + counters bound to Valkey Pub/Sub. +2. Create `src/features/sessions/`: + - Migrate routing, queries, and fragments (`SessionTableFragment`, + `SessionHandoffCardFragment`, `DirectPassDrawerFragment`). + - Eliminate legacy `SessionsScript.tsx` completely, replacing interactive + flows with Datastar reactive attributes (`data-on-click`, `data-patch`). +3. Add pure JSX unit tests: `events.test.ts` and `sessions.test.ts`. ### Phase 4: Persistent Architectural Test Suite -Implement the invariant test harness defined in the blueprint to prevent regression. + +Implement the invariant test harness defined in the blueprint to prevent +regression. + 1. Create `src/tests/arch/`. -2. Implement `transport_efficiency.test.ts` (asserts routine mutations return `text/html` in <2ms). -3. Implement `sse_lifecycle.test.ts` (asserts connection limits, draining, and memory stability for 100+ concurrent live listeners). -4. Implement `proxy_buffering.test.ts` (asserts `X-Accel-Buffering: no` is emitted). -5. Implement `error_fragment.test.ts` (asserts 4xx/5xx responses yield valid JSX morph fragments for `#status-banner`). -6. Implement `content_negotiation.test.ts` (asserts proper dual-mode REST vs Datastar handling) and `xss_fuzzing.test.ts` (fuzzes fragment rendering). +2. Implement `transport_efficiency.test.ts` (asserts routine mutations return + `text/html` in <2ms). +3. Implement `sse_lifecycle.test.ts` (asserts connection limits, draining, and + memory stability for 100+ concurrent live listeners). +4. Implement `proxy_buffering.test.ts` (asserts `X-Accel-Buffering: no` is + emitted). +5. Implement `error_fragment.test.ts` (asserts 4xx/5xx responses yield valid JSX + morph fragments for `#status-banner`). +6. Implement `content_negotiation.test.ts` (asserts proper dual-mode REST vs + Datastar handling) and `xss_fuzzing.test.ts` (fuzzes fragment rendering). + +### Phase 5: Legacy Deprecation & Final Cleanup + +Execute cleanup only after Phase 4 architectural tests and existing test suites +pass 100%. + +1. Safely delete legacy `server/` and `ui/` directories. +2. Perform dead-code cleanup and dependency verification. +3. Verify all gates: `deno fmt`, `deno task lint`, `deno task check`, and + `deno test -A --no-check`.