tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(plan): refine hypermedia migration plan to 5-phase structure with shift-left tooling and AGENTS.md legacy quarantine

Browse Source
This commit is contained in:
Tyler Gillispie 2026-08-27 17:52:43 -07:00
parent 9fdb97f3f4
commit f5c44f8ac5
2 changed files with 101 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
AGENTS.md
View File

@ -117,10 +117,14 @@ Management (IAM) fabric and WebAuthn Passkey authority.
explicit, searchable domain names (`SessionPinRotator`, explicit, searchable domain names (`SessionPinRotator`,
`streamGuestDrawerTelemetry`, `SessionHandoffCard`). `streamGuestDrawerTelemetry`, `SessionHandoffCard`).
5. **Deterministic Tooling Enforcement:** 5. **Deterministic Tooling Enforcement:**
- All code quality standards must be enforced by automated tooling - All code quality and architectural standards must be enforced by automated
(`deno tooling (`deno fmt`, `deno task lint`, `deno task check`, `deno test`).
fmt`, `deno task lint`, `deno task check`, `deno test`). Agents Architectural linters run as part of `deno task lint` to catch banned DOM
must verify passing gates before completing tasks. 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 ## 6. History & Context Link

125
tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md
View File

@ -1,55 +1,116 @@
# TASK METADATA # 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. - **Target Files:** `src/core/`, `src/features/`, `src/shared/`,
- **Core Objective:** Execute a multi-phase, non-overlapping architectural transition to a Datastar-driven Hypermedia paradigm and Vertical Feature Slicing. `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`. - **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 ## Architectural Considerations & Risks
- **Risks:** - **Risks:**
- Moving from a separated `server/` and `ui/` structure to co-located `src/features/` will require extensive routing and import refactoring. - Moving from a separated `server/` and `ui/` structure to co-located
- 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. `src/features/` will require extensive routing and import refactoring.
- Converting SSE streams to the typed adapter (`core/sse_adapter.ts`) might break existing real-time UI components if payload formats are mismatched. - 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:** - **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 ## Proposed Implementation
### Phase 1: Core Foundation & Datastar Engine ### Phase 1: Core Foundation, Tooling & Safety Guards
Establish the authoritative infrastructure and invariant guards inside the new `src/core/` boundary.
Establish the authoritative infrastructure, transport toolkit, and invariant
guards inside `src/core/`.
1. Create `src/core/` directory. 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. - `db.ts`: PostgreSQL connection pool and queries.
- `valkey.ts`: Valkey connection and Pub/Sub broker. - `valkey.ts`: Valkey connection and Pub/Sub broker.
- `spire_ffi.ts`: Rust SPIFFE/mTLS FFI bindings. - `spire_ffi.ts`: Rust SPIFFE/mTLS FFI bindings.
3. Implement `auth_guards.ts` (enforcing max 16KB payload cap, rate limiting, and CSRF/Origin check). 3. Implement `auth_guards.ts` (enforcing max 16KB payload cap, rate limiting,
4. Implement `content_negotiation.ts` to cleanly route between standard Datastar HTML requests, CLI/JSON clients, and shell strings. 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 ### 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 domain-agnostic presentation atoms and standard CRUD-style feature
Migrate the complex, interactive features and eliminate legacy imperative scripts in favor of targeted SSE and Datastar morphs. slices.
1. Create `src/core/sse_adapter.ts` for typed Datastar SSE streaming helper logic.
2. Create `src/features/events/`: 1. Create `src/shared/ui/` with distinctive fragment names (`LayoutFragment`,
- Migrate event routing, queries, and JSX fragments (EventCockpit, WorkshopDrawer). `NavbarFragment`, `ToastFragment`, `DrawerShellFragment`,
- Implement `stream.ts` using the new typed SSE adapter for live seat counters bound to Valkey Pub/Sub. `PillGroupFragment`, `AccordionFragment`).
3. Create `src/features/sessions/`: 2. Create `src/features/auth/` and migrate `/login`, `/register`, and
- Migrate routing, queries, and fragments (SessionTable, HandoffCard). `/recovery`. Extract WebAuthn ceremony scripts into `webauthn.ts` with
- Eliminate legacy `SessionsScript.tsx` completely, replacing interactive flows with Datastar attributes (`data-on-click`, `data-signals`). explicit `data-ignore` attributes.
4. Delete legacy `server/` and `ui/` directories once migration is fully verified. 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 ### 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/`. 1. Create `src/tests/arch/`.
2. Implement `transport_efficiency.test.ts` (asserts routine mutations return `text/html` in <2ms). 2. Implement `transport_efficiency.test.ts` (asserts routine mutations return
3. Implement `sse_lifecycle.test.ts` (asserts connection limits, draining, and memory stability for 100+ concurrent live listeners). `text/html` in <2ms).
4. Implement `proxy_buffering.test.ts` (asserts `X-Accel-Buffering: no` is emitted). 3. Implement `sse_lifecycle.test.ts` (asserts connection limits, draining, and
5. Implement `error_fragment.test.ts` (asserts 4xx/5xx responses yield valid JSX morph fragments for `#status-banner`). memory stability for 100+ concurrent live listeners).
6. Implement `content_negotiation.test.ts` (asserts proper dual-mode REST vs Datastar handling) and `xss_fuzzing.test.ts` (fuzzes fragment rendering). 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`.