Compare commits
No commits in common. "f5c44f8ac5de188e40a1eb03b68b853e734d4145" and "f764f28abcad846c14e09770092a16d646800f42" have entirely different histories.
f5c44f8ac5
...
f764f28abc
12
AGENTS.md
12
AGENTS.md
@ -117,14 +117,10 @@ Management (IAM) fabric and WebAuthn Passkey authority.
|
||||
explicit, searchable domain names (`SessionPinRotator`,
|
||||
`streamGuestDrawerTelemetry`, `SessionHandoffCard`).
|
||||
5. **Deterministic Tooling Enforcement:**
|
||||
- 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/`.
|
||||
- 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.
|
||||
|
||||
## 6. History & Context Link
|
||||
|
||||
|
||||
@ -1,116 +0,0 @@
|
||||
# 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.
|
||||
- **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/`.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
- **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.
|
||||
|
||||
## Proposed Implementation
|
||||
|
||||
### 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/` (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 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/` 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.
|
||||
|
||||
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).
|
||||
|
||||
### 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`.
|
||||
Loading…
x
Reference in New Issue
Block a user