alex
e167a6be12
- Replace interfaces array with single interface_type string (web/terminal) - Add requires_port boolean to indicate port/tunnel needs - Create Alembic migration for database schema change - Update backend model, API validation, and seed data - Update frontend types and tool workshop UI with dropdown - Add conditional port field rendering based on interface type - Update all frontend and backend tests OpenSpec change: enforce-single-tool-type-with-port-config Quality gates: frontend typecheck PASS, lint PASS, tests 37/37 PASS
161 lines
4.9 KiB
Markdown
161 lines
4.9 KiB
Markdown
# Frontend Foundation Specification
|
|
|
|
## Purpose
|
|
|
|
Provide a modern React frontend with TypeScript, routing, and responsive layout.
|
|
## 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: Styling Framework
|
|
|
|
The system SHALL use Tailwind CSS for styling.
|
|
|
|
#### Scenario: UI components
|
|
- GIVEN the frontend codebase
|
|
- THEN Tailwind CSS SHALL:
|
|
- Provide utility-first styling
|
|
- Support custom theme configuration
|
|
- Include responsive design utilities
|
|
- Support dark mode
|
|
|
|
### 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: Responsive Design
|
|
|
|
The system SHALL support mobile devices.
|
|
|
|
#### Scenario: Mobile viewport
|
|
- GIVEN a mobile device
|
|
- WHEN the app loads
|
|
- THEN:
|
|
- A hamburger menu replaces the sidebar
|
|
- Content adapts to screen width
|
|
- Touch targets are appropriately sized
|
|
|
|
### 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
|
|
|
|
### 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: Dashboard Page
|
|
|
|
The system SHALL provide a dashboard overview.
|
|
|
|
#### Scenario: Dashboard view
|
|
- GIVEN an authenticated user
|
|
- WHEN they visit the dashboard
|
|
- THEN they see:
|
|
- Total repository count
|
|
- Total project count
|
|
- Recent activity
|
|
- Quick action buttons
|
|
|
|
### Requirement: Tool Interface Type Dropdown
|
|
The tool workshop SHALL provide a dropdown for selecting a single interface type.
|
|
|
|
#### Scenario: Interface type dropdown
|
|
- GIVEN the tool workshop page
|
|
- WHEN a user creates or edits a tool type
|
|
- THEN the interface type field is a dropdown (not checkboxes)
|
|
- AND the options are "web" and "terminal"
|
|
- AND only one option can be selected
|
|
|
|
### Requirement: Conditional Port Fields
|
|
The tool workshop SHALL conditionally show or hide port-related fields based on the selected interface type.
|
|
|
|
#### Scenario: Web tool shows port fields
|
|
- GIVEN a tool type with interface type "web"
|
|
- WHEN the user views the tool editor
|
|
- THEN the Default Port field is visible and required
|
|
- AND port-related config fields are shown
|
|
|
|
#### Scenario: Terminal tool hides port fields
|
|
- GIVEN a tool type with interface type "terminal"
|
|
- WHEN the user views the tool editor
|
|
- THEN the Default Port field is hidden
|
|
- AND port-related config fields are hidden or disabled
|
|
|
|
#### Scenario: Changing interface type updates visibility
|
|
- GIVEN a user changes interface type from "web" to "terminal"
|
|
- WHEN the change is applied
|
|
- THEN port fields are immediately hidden
|
|
- AND any port value is preserved but not validated
|
|
|
|
## Dependencies
|
|
|
|
- React 18+
|
|
- TypeScript 5+
|
|
- Vite
|
|
- React Router
|
|
- Tailwind CSS
|
|
- Axios
|
|
|
|
## Quality Gates
|
|
|
|
- `npm run typecheck` must pass
|
|
- `npm run lint` must pass
|
|
- `npm run build` must succeed
|
|
- Frontend handles 401 responses correctly
|
|
- Responsive design works on mobile
|