feat: implement auth, projects, and frontend foundation

2026-05-17 20:21:55 +00:00
parent e7819bfc82
commit 71d9fe6406
88 changed files with 10936 additions and 47 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-17
@@ -0,0 +1,3 @@
+# frontend-foundation
+
+Implement frontend app foundation with auth-aware shell, routing skeleton, and API integration base
@@ -0,0 +1,56 @@
+## Context
+
+`apps/web` currently contains only package and container scaffolding, with no source code. Backend authentication and API foundations are now available, including cookie-based auth flows. The frontend foundation must establish a maintainable structure that supports authenticated navigation, responsive layout behavior, and consistent API communication.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create a minimal but production-oriented React app structure with TypeScript and Vite.
+- Add client-side routing with protected-route behavior and fallback 404 route.
+- Provide an authenticated shell layout with desktop sidebar and mobile navigation affordances.
+- Add a shared API client that sends credentials and handles unauthorized responses.
+- Provide a starter dashboard page with loading and error-safe patterns.
+
+**Non-Goals:**
+- Full feature implementation for projects/repositories/ssh keys/settings pages.
+- Pixel-perfect final design system and component library.
+- Advanced state-management framework adoption beyond required foundation.
+
+## Decisions
+
+1. **Route-centric app composition with `react-router-dom` data boundaries kept simple**
+   - Rationale: aligns with existing dependency set and keeps first milestone small.
+   - Alternative: add heavier route/data framework patterns now. Rejected as unnecessary for foundation stage.
+
+2. **Auth state bootstraps from `/auth/me` and routes guard against missing session**
+   - Rationale: backend is source of truth for cookie-backed identity; avoids duplicative token logic in browser.
+   - Alternative: local token/session storage. Rejected for weaker security and mismatch with cookie strategy.
+
+3. **Single API client module wrapping Axios defaults and 401 interception**
+   - Rationale: centralizes credential behavior and unauthorized handling.
+   - Alternative: per-request fetch wrappers across pages. Rejected due to duplication risk.
+
+4. **App shell-first approach before deep page content**
+   - Rationale: navigation and responsive structure are prerequisites for all future feature pages.
+   - Alternative: implement pages first then refactor into shell. Rejected due to avoidable churn.
+
+## Risks / Trade-offs
+
+- **[Auth bootstrap flicker on first load]** -> use explicit loading screen until session check resolves.
+- **[401 redirect loops]** -> add interceptor guard and avoid redirecting when already on public/auth routes.
+- **[Responsive nav complexity early]** -> keep mobile behavior minimal (toggleable drawer) and iterate later.
+- **[Frontend/backend contract drift]** -> codify expected endpoint behavior in integration-oriented frontend tests.
+
+## Migration Plan
+
+1. Scaffold source tree (`main.tsx`, app router, shell, pages, API client, styles).
+2. Implement auth context + protected route guard and login/logout wiring.
+3. Implement responsive shell and dashboard placeholder content.
+4. Add checks/tests and run `npm run typecheck`, `npm run lint`, `npm run build`.
+
+Rollback:
+- Remove added source tree and revert package/config changes if foundation rollout is paused.
+
+## Open Questions
+
+- Whether to include React Query in the next frontend increment (deferred; not required for foundation).
@@ -0,0 +1,26 @@
+## Why
+
+The project has backend foundations and authentication flows, but the frontend currently has no application code to consume them. We need a usable React foundation so users can authenticate, navigate core areas, and interact with APIs consistently across desktop and mobile.
+
+## What Changes
+
+- Establish the initial React + TypeScript app structure in `apps/web` with Vite conventions.
+- Add routing skeleton with protected routes, not-found handling, and auth-aware redirects.
+- Implement a baseline app shell (header, sidebar/mobile nav, content area) for authenticated screens.
+- Add shared API client configuration for cookie-based auth and 401 handling.
+- Add initial dashboard scaffolding with loading/error states and placeholder summary cards.
+- Add frontend quality gates and tests/checks for routing/auth behaviors and build integrity.
+
+## Capabilities
+
+### New Capabilities
+- `frontend-auth-shell`: Auth-aware layout primitives and guarded route flow for the web app.
+
+### Modified Capabilities
+- `frontend-foundation`: Tighten requirements around route protection, API credential handling, and responsive authenticated shell behavior.
+
+## Impact
+
+- Affected app code under `apps/web` (new source tree, routes, layout, API client, styles).
+- Depends on backend auth endpoints (`/auth/login`, `/auth/logout`, `/auth/me`, `/auth/refresh`) for session flow.
+- Introduces frontend config conventions for API base URL and runtime auth assumptions.
@@ -0,0 +1,71 @@
+## MODIFIED Requirements
+
+### Requirement: React Application Setup
+The system SHALL use React 18+ with TypeScript and SHALL provide a runnable application source structure in `apps/web/src`.
+
+#### Scenario: Frontend build
+- GIVEN the frontend codebase
+- THEN it SHALL:
+  - Use React 18+ with TypeScript 5+
+  - Use Vite as the build tool
+  - Support Hot Module Replacement (HMR)
+  - Output optimized production builds
+  - Include a concrete entrypoint, app composition, and route tree
+
+### Requirement: Client-Side Routing
+The system SHALL implement client-side routing with authenticated route guards and explicit not-found handling.
+
+#### Scenario: Navigation
+- GIVEN the frontend application
+- THEN React Router SHALL:
+  - Define routes for all foundation pages
+  - Support protected routes (require authentication)
+  - Handle 404 errors
+  - Support route parameters for feature pages
+
+#### Scenario: Protected routes
+- GIVEN an unauthenticated user
+- WHEN they access a protected route
+- THEN they are redirected to login flow
+- AND post-auth navigation returns them to an authenticated landing route
+
+### Requirement: Layout Component
+The system SHALL provide a consistent application layout for authenticated screens across desktop and mobile sizes.
+
+#### Scenario: Application shell
+- GIVEN the frontend application
+- THEN a Layout component SHALL:
+  - Display a header with user info and logout
+  - Display sidebar navigation on desktop
+  - Show main content area
+  - Collapse sidebar into a mobile menu toggle on small viewports
+
+#### Scenario: Navigation links
+- GIVEN the sidebar navigation
+- THEN it SHALL include links to:
+  - Dashboard
+  - Projects
+  - Repositories
+  - SSH Keys
+  - Settings
+
+### Requirement: HTTP Client Configuration
+The system SHALL configure HTTP requests for cookie-based auth and unauthorized-session recovery.
+
+#### Scenario: API communication
+- GIVEN the frontend application
+- THEN Axios/fetch SHALL:
+  - Send credentials (cookies) with requests
+  - Handle 401 responses by redirecting to login
+  - Set appropriate content-type headers
+  - Support request/response interception in a shared client module
+
+### Requirement: Loading States
+The system SHALL handle asynchronous operations gracefully during auth bootstrap and dashboard fetches.
+
+#### Scenario: Data fetching
+- GIVEN a page loading data
+- THEN:
+  - Loading states are shown while requests are in flight
+  - Errors are shown with retry affordance
+  - Initial auth-check loading prevents protected-layout flicker
@@ -0,0 +1,28 @@
+## 1. Frontend app scaffold and routing
+
+- [x] 1.1 Create `apps/web/src` app entrypoint, base styles, and root render wiring.
+- [x] 1.2 Add router configuration with dashboard, projects, repositories, ssh keys, settings, and not-found routes.
+- [x] 1.3 Add protected-route guard and login redirect behavior for unauthenticated access.
+
+## 2. Auth-aware shell and API client
+
+- [x] 2.1 Implement shared API client with credentialed requests and 401 handling strategy.
+- [x] 2.2 Implement auth session bootstrap (`/auth/me`) and lightweight auth context/provider.
+- [x] 2.3 Implement app shell layout (header, desktop sidebar, mobile menu toggle, content outlet).
+- [x] 2.4 Wire logout action to backend endpoint and session-state reset.
+
+## 3. Dashboard and UX states
+
+- [x] 3.1 Implement dashboard placeholder page with summary cards and quick actions.
+- [x] 3.2 Add loading, empty, and error-retry states for dashboard/auth bootstrap paths.
+- [x] 3.3 Ensure responsive behavior for mobile viewport navigation and touch targets.
+
+## 4. Verification and OpenSpec tracking
+
+- [x] 4.1 Add/update frontend tests for protected routing and auth/session behaviors.
+- [x] 4.2 Run frontend quality gates (`npm run typecheck`, `npm run lint`, `npm run build`) and fix findings.
+- [x] 4.3 Update this tasks file with completed checkboxes and note blockers/follow-ups.
+
+## Blockers / Follow-ups
+
+- None at this stage.