From acb92b32fa03c54f87d9dfad0e4d20a7a742bf5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ullrich=20Sch=C3=A4fer?= Date: Sun, 26 Apr 2026 21:19:02 +0200 Subject: [PATCH] Spec drift catch-up: URLs, settings split, navbar shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Outcome of today's `/spec-drift-review`. Concentrated on the high-and-medium-severity items; low-severity wording left for the next per-feature change to pick up naturally. High-severity URL fixes (specs were actively misleading): - account-management — email-change verification URL was specced as `/auth/verify-email-change?token=...`; the actual route is `/auth/verify?email-change=1&token=...` (see auth.verify.tsx:8). A reader implementing against the old wording would build a link that 404s. - observability — "Both apps SHALL expose a /metrics endpoint" was half right: the planner is at /metrics, but the journal exposes /api/metrics. The infrastructure spec already had the right URLs; the observability spec disagreed with itself. Now both correct, with a one-line note explaining the per-app split. Medium-severity wording drift (Stream E aftermath): - profile-settings, account-management, connected-services — all three said "the settings page SHALL include a [...] section", which described the old single-scrollable settings page. Stream E (PR #323) split /settings into four sub-pages (/settings/{profile,account,security,connections}); rewording each spec to point at its specific sub-page. The API endpoints (/api/settings/*) and behavior are unchanged. - authentication-methods — passkey add/delete previously said "via the settings page"; now specifically /settings/security. Code drift fixed inline: - apps/journal/app/routes/auth.verify.tsx — after a successful email change, the redirect was going to `/settings#account` (an anchor on the OLD single-scrollable settings page). Stream E retired that page; the right destination now is `/settings/account`. Without this the user would land on /settings/profile (which is what /settings redirects to) instead of the page that just changed. sse-broker spec wording: - The "no buffering tweaks in the Caddy reverse_proxy block" scenario asserted the entry was "a plain `reverse_proxy journal:3000`". After PR #329 the journal block has `lb_try_duration 30s` / `lb_try_interval 250ms` — neither affects streaming, so SSE still works, but the spec's "plain" language was no longer literally true. Reworded to forbid only buffering-related directives; explicitly call out that retry-on-restart directives like lb_try_duration are fine. Navbar consolidation (journal-landing): - The shipped navbar's full shape was scattered: notifications said "navbar has a bell," explore said "navbar has an Explore entry," but no spec described the avatar dropdown, the primary-nav cluster (Feed/Routes/Activities), or the mobile drawer (Stream C / PR #324). Added a "Top navbar shape" requirement to journal-landing covering all of it — anonymous vs signed-in, desktop vs mobile, dropdown contents, drawer behavior. The per-feature specs (notifications, explore) still own their own badges/entries; this requirement just says what the whole cluster looks like. Co-Authored-By: Claude Opus 4.7 (1M context) --- apps/journal/app/routes/auth.verify.tsx | 2 +- openspec/specs/account-management/spec.md | 14 ++++---- openspec/specs/authentication-methods/spec.md | 6 ++-- openspec/specs/connected-services/spec.md | 8 ++--- openspec/specs/journal-landing/spec.md | 34 +++++++++++++++---- openspec/specs/observability/spec.md | 4 +-- openspec/specs/profile-settings/spec.md | 6 ++-- openspec/specs/sse-broker/spec.md | 3 +- 8 files changed, 49 insertions(+), 28 deletions(-) diff --git a/apps/journal/app/routes/auth.verify.tsx b/apps/journal/app/routes/auth.verify.tsx index 45939a8..dec9eae 100644 --- a/apps/journal/app/routes/auth.verify.tsx +++ b/apps/journal/app/routes/auth.verify.tsx @@ -16,7 +16,7 @@ export async function loader({ request }: Route.LoaderArgs) { const user = await getSessionUser(request); if (!user) return redirect("/auth/login"); await verifyEmailChange(token, user.id); - return redirect("/settings#account"); + return redirect("/settings/account"); } const userId = await verifyMagicToken(token); diff --git a/openspec/specs/account-management/spec.md b/openspec/specs/account-management/spec.md index a509b18..86d3eeb 100644 --- a/openspec/specs/account-management/spec.md +++ b/openspec/specs/account-management/spec.md @@ -6,7 +6,7 @@ Lifecycle operations on a user's account: changing the registered email address ## Requirements ### Requirement: Email change with verification -The settings page SHALL include an "Email" section where the signed-in user can request a new email address via `POST /api/settings/email`. The change SHALL NOT take effect until the user clicks a verification link delivered to the new email; the original address remains active until verification completes. +The Account settings page (`/settings/account`) SHALL include an "Email" section where the signed-in user can request a new email address via `POST /api/settings/email`. The change SHALL NOT take effect until the user clicks a verification link delivered to the new email; the original address remains active until verification completes. #### Scenario: Initiate email change - **WHEN** a signed-in user submits a new email address that is not already in use by another account @@ -17,15 +17,15 @@ The settings page SHALL include an "Email" section where the signed-in user can - **THEN** the server responds with a validation error and the verification email is not sent #### Scenario: Verification link applies the change -- **WHEN** the user follows the verification link (`/auth/verify-email-change?token=...`) -- **THEN** the server validates the token (matching purpose, not expired, not used), updates `users.email`, marks the token used, and signs the user back in if necessary +- **WHEN** the user follows the verification link (`/auth/verify?email-change=1&token=...`) +- **THEN** the server validates the token (matching purpose, not expired, not used), updates `users.email`, marks the token used, signs the user back in if necessary, and redirects to `/settings/account` #### Scenario: Expired verification link - **WHEN** the verification link is more than 15 minutes old or has already been used - **THEN** the page shows an expired/used message and the email is unchanged ### Requirement: Account deletion is irreversible and owner-bound -The settings page SHALL include a "Delete account" section behind a confirmation step. Deletion SHALL be irreversible and SHALL cascade to all rows owned by the user (per the existing FK ON DELETE CASCADE rules: routes, activities, follows, notifications, magic tokens, sync connections, oauth tokens). Pending follow requests targeting the deleted user SHALL also be cleared. +The Account settings page (`/settings/account`) SHALL include a "Delete account" section behind a confirmation step. Deletion SHALL be irreversible and SHALL cascade to all rows owned by the user (per the existing FK ON DELETE CASCADE rules: routes, activities, follows, notifications, magic tokens, sync connections, oauth tokens). Pending follow requests targeting the deleted user SHALL also be cleared. #### Scenario: Authenticated user deletes their account - **WHEN** a signed-in user POSTs to `/api/settings/delete-account` with the confirmation step satisfied @@ -42,6 +42,6 @@ The settings page SHALL include a "Delete account" section behind a confirmation ### Requirement: Terms re-acceptance gate (cross-cutting) Settings pages SHALL be reachable while the user has a stale `terms_version` so they can read the current Terms or sign out, but action endpoints behind settings SHALL NOT execute side effects until the user has re-accepted the current Terms version. The cross-cutting gate that enforces this lives in `journal-auth`'s "Re-accept updated Terms on next visit" requirement; this spec only documents the dependency so settings UX is read in context. -#### Scenario: Stale-terms user can read settings but is blocked from saving -- **WHEN** a user with a stale `terms_version` navigates to `/settings` -- **THEN** the loader-level Terms gate redirects them to `/auth/accept-terms` first (per `journal-auth`); after re-acceptance they return to the settings page and side effects work normally +#### Scenario: Stale-terms user is redirected before reaching settings +- **WHEN** a user with a stale `terms_version` navigates to `/settings` (or any sub-page like `/settings/account`) +- **THEN** the root loader's Terms gate redirects them to `/auth/accept-terms` first (per `journal-auth`); after re-acceptance they return to the settings page and side effects work normally diff --git a/openspec/specs/authentication-methods/spec.md b/openspec/specs/authentication-methods/spec.md index 1d57edf..64e8995 100644 --- a/openspec/specs/authentication-methods/spec.md +++ b/openspec/specs/authentication-methods/spec.md @@ -73,10 +73,10 @@ The register form and the login form SHALL both render a small text toggle that - **THEN** the form starts in passkey mode and renders the same toggle to switch to magic-link mode ### Requirement: Add passkey to an existing account -A signed-in user SHALL be able to add an additional passkey to their account from the settings page (or from the post-login `/?add-passkey=1` prompt). The flow SHALL reuse the WebAuthn registration ceremony but bind the credential to the existing `users.id` rather than creating a new account. +A signed-in user SHALL be able to add an additional passkey to their account from the Security settings page (`/settings/security`) or from the post-login `/?add-passkey=1` prompt. The flow SHALL reuse the WebAuthn registration ceremony but bind the credential to the existing `users.id` rather than creating a new account. #### Scenario: Add passkey from settings -- **WHEN** a signed-in user clicks "Add passkey" in settings +- **WHEN** a signed-in user clicks "Add passkey" on `/settings/security` - **THEN** a WebAuthn registration ceremony runs against the existing user id and a new row is inserted in `credentials` linked to that user #### Scenario: Post-login add-passkey nudge @@ -84,7 +84,7 @@ A signed-in user SHALL be able to add an additional passkey to their account fro - **THEN** the home page surfaces an "Add a passkey for faster sign-in" prompt; if dismissed it does not re-appear automatically ### Requirement: Passkey deletion -A signed-in user SHALL be able to remove a passkey from their account via the settings page. The Journal SHALL prevent deletion of the user's last remaining passkey if no alternative auth method (a verified email for magic-link login) is available, to avoid lock-out. +A signed-in user SHALL be able to remove a passkey from their account via the Security settings page (`/settings/security`). The Journal SHALL prevent deletion of the user's last remaining passkey if no alternative auth method (a verified email for magic-link login) is available, to avoid lock-out. #### Scenario: Delete one of multiple passkeys - **WHEN** a user with 2+ passkeys removes one via `/api/settings/passkey/delete` diff --git a/openspec/specs/connected-services/spec.md b/openspec/specs/connected-services/spec.md index ee3e173..8d6b0ac 100644 --- a/openspec/specs/connected-services/spec.md +++ b/openspec/specs/connected-services/spec.md @@ -5,12 +5,12 @@ Third-party service connections (Wahoo today; future Strava, Garmin, etc.) that ## Requirements -### Requirement: Connected Services section on the settings page -The settings page SHALL include a "Connected Services" section listing each external integration the Journal supports, each row showing the connection state (Connect / Disconnect) and the link to start the OAuth flow when not connected. +### Requirement: Connections settings page at `/settings/connections` +The Journal SHALL expose a Connected services page at `/settings/connections` (one of the four sub-pages of `/settings`). The page SHALL list each external integration the Journal supports, each row showing the connection state (Connect / Disconnect) and the link to start the OAuth flow when not connected. #### Scenario: Wahoo connection status renders both states -- **WHEN** a user views the settings page -- **THEN** a "Connected Services" section shows Wahoo as connected or disconnected +- **WHEN** a user loads `/settings/connections` +- **THEN** the page lists Wahoo as connected or disconnected - **AND** connected state shows a "Disconnect" button that POSTs to `/api/sync/disconnect/` - **AND** disconnected state shows a "Connect Wahoo" button that begins the OAuth handshake diff --git a/openspec/specs/journal-landing/spec.md b/openspec/specs/journal-landing/spec.md index 6da35e6..7a7f6f5 100644 --- a/openspec/specs/journal-landing/spec.md +++ b/openspec/specs/journal-landing/spec.md @@ -53,16 +53,36 @@ For signed-in users, the home page SHALL render a personal activity dashboard: a - **WHEN** a signed-in user has no activities yet - **THEN** the dashboard shows an empty-state message pointing to activity creation, while the welcome line and New Activity CTA remain visible -### Requirement: Notifications entry in the navbar -The navbar SHALL render a single inbox entry — a bell icon — for signed-in users, linking to `/notifications`. It SHALL render an unread count badge when the user has at least one unread notification, and no badge when the count is zero. The badge live-updates via `sse-broker`; the loader-driven count is the SSR baseline. Follow-request actions (Approve / Reject) live as the Requests tab inside `/notifications` (see `notifications` spec); the navbar SHALL NOT render a separate "Follow requests" entry — the bell is the single inbox surface. +### Requirement: Top navbar shape (signed-in vs anonymous) +The Journal SHALL render a top navbar on every page. The navbar's contents depend on whether the request carries a session and on viewport size; this requirement consolidates the full shape so the navbar's makeup is captured in one place rather than scattered across feature specs. -#### Scenario: Signed-in user sees the entry -- **WHEN** a signed-in user loads any page -- **THEN** the navbar includes a single bell entry linking to `/notifications`, and a count badge if the user has unread rows +**Anonymous (any viewport):** brand link to `/` · `Sign In` · `Register` (primary CTA). No primary nav entries. -#### Scenario: Anonymous user does not see the entry +**Signed-in, desktop (≥ md / 768px):** brand link to `/` · primary-nav cluster (`Feed` → `/feed`, `Explore` → `/explore`, `Routes` → `/routes`, `Activities` → `/activities`) · bell icon → `/notifications` (with live unread badge per the `notifications` spec) · avatar dropdown trigger. + +**Signed-in, mobile (< md):** brand link · bell icon · hamburger trigger. Tapping the hamburger opens a slide-out drawer that contains the same primary-nav cluster, the bell entry repeated as a labelled link, plus the avatar-dropdown items (Profile / Settings / Log Out). The drawer locks body scroll while open and closes on navigation or Escape. + +The avatar dropdown trigger SHALL render an Avatar (initials fallback when no image — the `users` table has no avatar column today, so initials are the only state) with `aria-label = displayName ?? username` and `aria-expanded` reflecting the open state. Opening the dropdown reveals three menuitems (`role="menuitem"`): Profile (links to `/users/`), Settings (links to `/settings`), Log Out (a `