ui-syncup 0.3.13 → 0.4.0-beta.1

package/.agents/skills/ai-spec-workflow/references/templates/requirements-template.md

@@ -0,0 +1,179 @@
+# Requirements Specification
+
+## Overview
+[Brief 2-3 sentence description of what feature/system needs to be built and why it matters]
+
+**Example:**
+> This feature adds user authentication to the application, allowing users to create accounts, log in securely, and access protected resources. Authentication will use JWT tokens and include password reset functionality.
+
+---
+
+## Goals
+[What this feature aims to achieve - list 3-5 specific, measurable objectives]
+
+**Example:**
+- Enable secure user authentication with industry-standard practices
+- Reduce unauthorized access to protected resources by 100%
+- Provide seamless login experience with < 2 second response time
+- Support password recovery for users who forget credentials
+
+---
+
+## User Stories
+[Who needs this and why - use format: "As a [user type], I want [goal] so that [benefit]"]
+
+**Example:**
+- As a new user, I want to create an account so that I can access personalized features
+- As a returning user, I want to log in quickly so that I can resume my work
+- As a user who forgot my password, I want to reset it via email so that I can regain access
+- As an admin, I want to see login attempts so that I can monitor security
+
+---
+
+## Functional Requirements
+[What the system must do - numbered list of specific, testable requirements]
+
+**Example:**
+1. The system must allow users to register with email and password
+2. The system must validate email format and password strength (min 8 chars, 1 uppercase, 1 number)
+3. The system must send verification email upon registration
+4. The system must authenticate users with email/password combination
+5. The system must issue JWT tokens valid for 24 hours
+6. The system must allow users to log out and invalidate their token
+7. The system must provide password reset via email link
+8. The system must hash passwords using bcrypt with salt rounds >= 10
+
+---
+
+## Non-Functional Requirements
+[Performance, security, scalability, usability considerations - be specific with metrics]
+
+**Performance:**
+- Login response time: < 2 seconds
+- Registration response time: < 3 seconds
+- Support 1000+ concurrent users
+- Token validation: < 100ms
+
+**Security:**
+- Passwords must be hashed, never stored in plain text
+- JWT tokens must be signed with secure secret
+- Rate limiting: max 5 login attempts per minute per IP
+- HTTPS required for all authentication endpoints
+
+**Usability:**
+- Clear error messages for failed login attempts
+- Password strength indicator during registration
+- "Remember me" option for extended sessions
+- Mobile-responsive authentication forms
+
+**Accessibility:**
+- WCAG 2.1 AA compliance
+- Keyboard navigation support
+- Screen reader compatible
+- Proper ARIA labels on form fields
+
+---
+
+## Constraints
+[Technical or business limitations that affect implementation]
+
+**Example:**
+- Must integrate with existing user database schema
+- Cannot modify current API versioning structure
+- Must support legacy browsers (IE11+)
+- Budget: max 40 hours development time
+- Must comply with GDPR for EU users
+- Cannot use third-party authentication services (company policy)
+
+---
+
+## Dependencies
+[External systems, APIs, libraries, or files this depends on]
+
+**External Dependencies:**
+- Email service (SendGrid or similar) for verification emails
+- Redis for token blacklist/session management
+- PostgreSQL database for user storage
+
+**Internal Dependencies:**
+- User profile service must be updated to accept auth tokens
+- Admin dashboard needs authentication middleware
+- Existing API gateway must route auth endpoints
+
+**Library Dependencies:**
+- jsonwebtoken (JWT generation/validation)
+- bcrypt (password hashing)
+- express-validator (input validation)
+
+**File References:**
+#[[file:src/database/schema.sql]]
+#[[file:docs/api-specification.yaml]]
+#[[file:package.json]]
+
+---
+
+## Success Criteria
+[How to measure if requirements are met - specific, testable criteria]
+
+**Example:**
+- [ ] Users can successfully register with valid email/password
+- [ ] Users receive verification email within 30 seconds
+- [ ] Users can log in and receive valid JWT token
+- [ ] Protected routes reject requests without valid token
+- [ ] Password reset flow completes successfully
+- [ ] All security requirements pass penetration testing
+- [ ] Performance benchmarks met under load testing
+- [ ] Zero plain-text passwords in database
+- [ ] Accessibility audit passes with AA rating
+
+---
+
+## Out of Scope
+[What this spec explicitly does NOT cover - prevents scope creep]
+
+**Example:**
+- Social media login (OAuth) - planned for Phase 2
+- Two-factor authentication (2FA) - future enhancement
+- Biometric authentication - not in current roadmap
+- User profile management - separate feature
+- Role-based access control (RBAC) - separate spec
+- Account deletion/deactivation - future feature
+- Login history/audit logs - Phase 2
+
+---
+
+## Assumptions
+[What we're assuming to be true - clarify these with stakeholders]
+
+**Example:**
+- Users have access to email for verification
+- Email service has 99.9% uptime SLA
+- Users understand basic password security
+- Legal team has approved data retention policy
+- Infrastructure can handle increased database load
+
+---
+
+## Risks
+[Potential issues that could impact requirements]
+
+**Example:**
+- **High:** Email delivery failures could block user registration
+  - Mitigation: Implement retry mechanism and manual verification option
+- **Medium:** Password reset tokens could be intercepted
+  - Mitigation: Use short expiration (15 min) and one-time use tokens
+- **Low:** Database migration could cause downtime
+  - Mitigation: Schedule during maintenance window, test on staging
+
+---
+
+## Acceptance Criteria
+[High-level criteria for stakeholder sign-off]
+
+**Example:**
+- Product owner can create account, log in, and reset password
+- Security team approves authentication implementation
+- Performance tests show < 2s login time under load
+- Accessibility audit passes
+- Documentation complete for API endpoints
+- No critical or high-severity bugs in QA testing

package/.agents/skills/ai-spec-workflow/references/templates/tasks-template.md

@@ -0,0 +1,501 @@
+# Implementation Tasks
+
+**Purpose:** Step-by-step tasks to implement the feature. Each task should be specific, actionable, and have clear acceptance criteria.
+
+**Guidelines:**
+- Tasks should be completable in 1-4 hours
+- Each task lists specific files to create/modify
+- Include acceptance criteria for each task
+- Order tasks by dependencies (foundation → features → polish)
+- Mark tasks complete with [x] as you finish them
+
+---
+
+## Setup
+[Initial environment and dependency setup - complete these before starting feature work]
+
+**Example:**
+- [ ] **Task 0.1:** Initialize project structure
+  - Create folders: `src/components/auth`, `src/services/auth`, `src/types`
+  - Acceptance: Folder structure matches design spec
+  
+- [ ] **Task 0.2:** Install dependencies
+  - Run: `npm install jsonwebtoken bcrypt express-validator`
+  - Run: `npm install -D @types/jsonwebtoken @types/bcrypt`
+  - Acceptance: All packages in package.json, no install errors
+  
+- [ ] **Task 0.3:** Set up environment variables
+  - Create `.env.example` with: `JWT_SECRET`, `DATABASE_URL`, `REDIS_URL`
+  - Create `.env` with actual values (don't commit)
+  - Acceptance: App reads env vars without errors
+
+- [ ] **Task 0.4:** Configure TypeScript
+  - Update `tsconfig.json` with strict mode and path aliases
+  - Acceptance: `npm run build` compiles without errors
+
+---
+
+## Phase 1: Foundation
+[Core infrastructure that other features depend on - database, types, utilities]
+
+**Example:**
+- [ ] **Task 1.1:** Create database schema
+  - **Files:** `src/database/migrations/001_create_users_table.sql`
+  - **Actions:**
+    1. Write CREATE TABLE statement for users
+    2. Add indexes on email, verification_token, reset_token
+    3. Run migration on local database
+  - **Acceptance:** Table exists, indexes created, can insert test user
+
+- [ ] **Task 1.2:** Define TypeScript types
+  - **Files:** `src/types/auth.ts`, `src/types/user.ts`
+  - **Actions:**
+    1. Create User, UserDTO interfaces
+    2. Create RegisterRequest, LoginRequest, AuthResponse types
+    3. Export all types
+  - **Acceptance:** Types compile, no errors when imported
+
+- [ ] **Task 1.3:** Set up database connection
+  - **Files:** `src/database/connection.ts`
+  - **Actions:**
+    1. Create PostgreSQL connection pool
+    2. Add connection error handling
+    3. Export query function
+  - **Acceptance:** Can execute test query, connection closes gracefully
+
+- [ ] **Task 1.4:** Set up Redis client
+  - **Files:** `src/database/redis.ts`
+  - **Actions:**
+    1. Create Redis client with connection config
+    2. Add error handling and reconnection logic
+    3. Export client instance
+  - **Acceptance:** Can set/get test key, connection stable
+
+---
+
+## Phase 2: Core Features
+[Main feature implementation - business logic, API endpoints, components]
+
+**Example:**
+
+### Backend Tasks
+
+- [ ] **Task 2.1:** Implement UserRepository
+  - **Files:** `src/repositories/UserRepository.ts`
+  - **Actions:**
+    1. Create class with methods: create, findByEmail, findById, updatePassword
+    2. Use parameterized queries to prevent SQL injection
+    3. Handle database errors
+  - **Acceptance:** All methods work with test data, no SQL errors
+
+- [ ] **Task 2.2:** Implement AuthService
+  - **Files:** `src/services/AuthService.ts`
+  - **Actions:**
+    1. Implement password hashing with bcrypt (12 rounds)
+    2. Implement JWT token generation and verification
+    3. Implement createUser, validateCredentials, generateToken methods
+  - **Acceptance:** Can hash password, generate valid JWT, verify token
+
+- [ ] **Task 2.3:** Create auth middleware
+  - **Files:** `src/middleware/auth.ts`
+  - **Actions:**
+    1. Extract token from Authorization header
+    2. Verify token and check blacklist
+    3. Attach user to request object
+    4. Return 401 if invalid
+  - **Acceptance:** Protected route rejects invalid tokens, accepts valid ones
+
+- [ ] **Task 2.4:** Implement registration endpoint
+  - **Files:** `src/controllers/AuthController.ts`, `src/routes/auth.ts`
+  - **Actions:**
+    1. Add POST /register route with validation
+    2. Hash password and create user
+    3. Generate verification token
+    4. Return 201 with userId
+  - **Acceptance:** Can register with valid data, returns 400 for invalid data
+
+- [ ] **Task 2.5:** Implement login endpoint
+  - **Files:** `src/controllers/AuthController.ts` (update)
+  - **Actions:**
+    1. Add POST /login route with validation
+    2. Validate credentials
+    3. Generate JWT token
+    4. Return token and user data
+  - **Acceptance:** Returns token for valid credentials, 401 for invalid
+
+- [ ] **Task 2.6:** Implement logout endpoint
+  - **Files:** `src/controllers/AuthController.ts` (update)
+  - **Actions:**
+    1. Add POST /logout route (protected)
+    2. Add token to Redis blacklist
+    3. Return success message
+  - **Acceptance:** Token blacklisted, subsequent requests with token fail
+
+- [ ] **Task 2.7:** Implement password reset request
+  - **Files:** `src/controllers/AuthController.ts` (update)
+  - **Actions:**
+    1. Add POST /reset-password route
+    2. Generate reset token with 15min expiration
+    3. Save token to database
+    4. Send email with reset link
+  - **Acceptance:** Email sent, token saved, link works
+
+- [ ] **Task 2.8:** Implement password reset confirmation
+  - **Files:** `src/controllers/AuthController.ts` (update)
+  - **Actions:**
+    1. Add POST /reset-password/confirm route
+    2. Verify token not expired
+    3. Hash new password and update database
+    4. Invalidate reset token
+  - **Acceptance:** Password updated, can login with new password
+
+### Frontend Tasks
+
+- [ ] **Task 2.9:** Create AuthContext
+  - **Files:** `src/contexts/AuthContext.tsx`
+  - **Actions:**
+    1. Create context with user, token, isAuthenticated state
+    2. Implement login, logout, register methods
+    3. Load token from localStorage on mount
+    4. Provide context to app
+  - **Acceptance:** Context provides auth state, methods work
+
+- [ ] **Task 2.10:** Create LoginForm component
+  - **Files:** `src/components/auth/LoginForm.tsx`
+  - **Actions:**
+    1. Create form with email and password fields
+    2. Add validation (email format, required fields)
+    3. Call AuthContext.login on submit
+    4. Show loading state and errors
+  - **Acceptance:** Form validates, submits, shows errors
+
+- [ ] **Task 2.11:** Create RegisterForm component
+  - **Files:** `src/components/auth/RegisterForm.tsx`
+  - **Actions:**
+    1. Create form with email, password, confirmPassword
+    2. Add validation (password strength, match)
+    3. Call AuthContext.register on submit
+    4. Show success message
+  - **Acceptance:** Form validates, submits, shows success
+
+- [ ] **Task 2.12:** Create ProtectedRoute component
+  - **Files:** `src/components/auth/ProtectedRoute.tsx`
+  - **Actions:**
+    1. Check isAuthenticated from context
+    2. Redirect to /login if not authenticated
+    3. Render children if authenticated
+  - **Acceptance:** Redirects when not logged in, shows content when logged in
+
+- [ ] **Task 2.13:** Create PasswordResetRequest component
+  - **Files:** `src/components/auth/PasswordResetRequest.tsx`
+  - **Actions:**
+    1. Create form with email field
+    2. Call API to request reset
+    3. Show success message
+  - **Acceptance:** Sends request, shows confirmation
+
+- [ ] **Task 2.14:** Create PasswordResetConfirm component
+  - **Files:** `src/components/auth/PasswordResetConfirm.tsx`
+  - **Actions:**
+    1. Extract token from URL params
+    2. Create form with new password fields
+    3. Call API to confirm reset
+    4. Redirect to login on success
+  - **Acceptance:** Updates password, redirects to login
+
+---
+
+## Phase 3: Integration & Testing
+[Connect components, add validation, implement tests]
+
+**Example:**
+
+- [ ] **Task 3.1:** Add input validation middleware
+  - **Files:** `src/middleware/validation.ts`
+  - **Actions:**
+    1. Create validators for email, password strength
+    2. Add validation to all auth routes
+    3. Return 400 with clear error messages
+  - **Acceptance:** Invalid inputs rejected with helpful errors
+
+- [ ] **Task 3.2:** Add rate limiting
+  - **Files:** `src/middleware/rateLimit.ts`
+  - **Actions:**
+    1. Implement Redis-based rate limiter
+    2. Apply to login endpoint (5 req/min per IP)
+    3. Return 429 when limit exceeded
+  - **Acceptance:** Blocks after 5 attempts, resets after 1 minute
+
+- [ ] **Task 3.3:** Integrate email service
+  - **Files:** `src/services/EmailService.ts`
+  - **Actions:**
+    1. Set up SendGrid client
+    2. Create email templates for verification and reset
+    3. Send emails from auth endpoints
+  - **Acceptance:** Emails delivered, links work
+
+- [ ] **Task 3.4:** Add error handling middleware
+  - **Files:** `src/middleware/errorHandler.ts`
+  - **Actions:**
+    1. Create global error handler
+    2. Log errors with context
+    3. Return consistent error format
+  - **Acceptance:** All errors caught, logged, formatted correctly
+
+- [ ] **Task 3.5:** Write unit tests for AuthService
+  - **Files:** `src/services/__tests__/AuthService.test.ts`
+  - **Actions:**
+    1. Test password hashing
+    2. Test token generation and verification
+    3. Test credential validation
+  - **Acceptance:** All tests pass, coverage > 80%
+
+- [ ] **Task 3.6:** Write integration tests for auth endpoints
+  - **Files:** `src/routes/__tests__/auth.test.ts`
+  - **Actions:**
+    1. Test registration flow
+    2. Test login flow
+    3. Test password reset flow
+    4. Test protected route access
+  - **Acceptance:** All tests pass, key flows covered
+
+- [ ] **Task 3.7:** Write component tests
+  - **Files:** `src/components/auth/__tests__/LoginForm.test.tsx`
+  - **Actions:**
+    1. Test form rendering
+    2. Test validation
+    3. Test submission
+  - **Acceptance:** All tests pass, user interactions covered
+
+---
+
+## Phase 4: Polish & Deploy
+[Documentation, optimization, deployment preparation]
+
+**Example:**
+
+- [ ] **Task 4.1:** Add loading states to forms
+  - **Files:** Update all form components
+  - **Actions:**
+    1. Show spinner during submission
+    2. Disable submit button while loading
+    3. Show success/error messages
+  - **Acceptance:** Clear feedback during async operations
+
+- [ ] **Task 4.2:** Add password strength indicator
+  - **Files:** `src/components/auth/PasswordStrengthIndicator.tsx`
+  - **Actions:**
+    1. Create component that shows strength (weak/medium/strong)
+    2. Add to RegisterForm
+    3. Update in real-time as user types
+  - **Acceptance:** Indicator updates correctly, helps users create strong passwords
+
+- [ ] **Task 4.3:** Optimize database queries
+  - **Files:** Review all repository methods
+  - **Actions:**
+    1. Add indexes if missing
+    2. Use connection pooling
+    3. Add query timeouts
+  - **Acceptance:** Login query < 100ms, no N+1 queries
+
+- [ ] **Task 4.4:** Add API documentation
+  - **Files:** `docs/api/auth.md` or OpenAPI spec
+  - **Actions:**
+    1. Document all endpoints
+    2. Include request/response examples
+    3. Document error codes
+  - **Acceptance:** Complete API reference available
+
+- [ ] **Task 4.5:** Write deployment guide
+  - **Files:** `docs/deployment.md`
+  - **Actions:**
+    1. Document environment variables
+    2. Document database migration steps
+    3. Document deployment process
+  - **Acceptance:** Team can deploy following guide
+
+- [ ] **Task 4.6:** Set up monitoring
+  - **Files:** `src/middleware/metrics.ts`
+  - **Actions:**
+    1. Add response time logging
+    2. Add error rate tracking
+    3. Set up alerts for failures
+  - **Acceptance:** Metrics visible in dashboard, alerts working
+
+- [ ] **Task 4.7:** Security audit
+  - **Actions:**
+    1. Run npm audit and fix vulnerabilities
+    2. Test for SQL injection
+    3. Test for XSS vulnerabilities
+    4. Verify HTTPS enforcement
+  - **Acceptance:** No critical vulnerabilities, security checklist complete
+
+- [ ] **Task 4.8:** Performance testing
+  - **Files:** `tests/load/auth.test.js`
+  - **Actions:**
+    1. Write load test for login endpoint
+    2. Run with 1000 concurrent users
+    3. Verify response time < 2s
+  - **Acceptance:** Meets performance targets under load
+
+- [ ] **Task 4.9:** Deploy to staging
+  - **Actions:**
+    1. Run database migrations
+    2. Deploy API to staging environment
+    3. Deploy frontend to staging
+    4. Run smoke tests
+  - **Acceptance:** All features work in staging
+
+- [ ] **Task 4.10:** Production deployment
+  - **Actions:**
+    1. Get stakeholder approval
+    2. Schedule deployment window
+    3. Run database migrations
+    4. Deploy to production
+    5. Monitor for errors
+  - **Acceptance:** Production deployment successful, no critical errors
+
+---
+
+## File References
+[Link to related documentation, specs, or implementation guides]
+
+**Example:**
+- Design spec: #[[file:user-authentication-design.md]]
+- Requirements spec: #[[file:user-authentication-requirements.md]]
+- API specification: #[[file:docs/api-spec.yaml]]
+- Database schema: #[[file:src/database/schema.sql]]
+
+---
+
+## Dependencies Between Tasks
+[Which tasks must be completed before others - helps with planning and parallelization]
+
+**Example:**
+
+**Critical Path:**
+1. Setup (0.1-0.4) → Foundation (1.1-1.4) → Core Backend (2.1-2.8) → Integration (3.1-3.4) → Deploy (4.9-4.10)
+
+**Parallel Work Possible:**
+- Frontend tasks (2.9-2.14) can start after Task 1.2 (types defined)
+- Testing tasks (3.5-3.7) can happen alongside Phase 4
+- Documentation (4.4-4.5) can happen anytime after Phase 2
+
+**Blocking Dependencies:**
+- Task 2.2 (AuthService) requires Task 1.2 (types) and 1.3 (database)
+- Task 2.4-2.8 (endpoints) require Task 2.1 (repository) and 2.2 (service)
+- Task 3.2 (rate limiting) requires Task 1.4 (Redis)
+- Task 4.9 (staging deploy) requires all Phase 3 tasks complete
+
+---
+
+## Estimated Effort
+[Time estimates for major phases - helps with planning and resource allocation]
+
+**Example:**
+
+| Phase | Tasks | Estimated Hours | Notes |
+|-------|-------|----------------|-------|
+| Setup | 0.1-0.4 | 2 hours | Straightforward, mostly configuration |
+| Phase 1: Foundation | 1.1-1.4 | 6 hours | Database setup can be tricky |
+| Phase 2: Backend | 2.1-2.8 | 16 hours | Core feature work, most complex |
+| Phase 2: Frontend | 2.9-2.14 | 12 hours | Can parallelize with backend |
+| Phase 3: Integration | 3.1-3.7 | 10 hours | Testing takes time |
+| Phase 4: Polish | 4.1-4.10 | 14 hours | Deployment and monitoring setup |
+| **Total** | | **60 hours** | ~1.5 weeks for 1 developer |
+
+**Assumptions:**
+- Developer familiar with tech stack
+- No major blockers or scope changes
+- Testing infrastructure already exists
+- Deployment pipeline already set up
+
+---
+
+## Risk Items
+[Tasks with high complexity, uncertainty, or external dependencies]
+
+**Example:**
+
+| Task | Risk Level | Risk Description | Mitigation |
+|------|-----------|------------------|------------|
+| 1.1 Database schema | Medium | Schema changes after deployment are hard | Review with team, plan migration strategy |
+| 2.2 AuthService | Medium | JWT security is critical | Security review, use well-tested library |
+| 3.2 Rate limiting | Medium | Could block legitimate users | Start with generous limits, monitor |
+| 3.3 Email service | High | Email delivery can be unreliable | Add retry logic, manual verification option |
+| 4.8 Performance testing | Medium | May reveal unexpected bottlenecks | Budget extra time for optimization |
+| 4.10 Production deploy | High | Downtime affects users | Deploy during low-traffic window, have rollback plan |
+
+**High-Risk Tasks Require:**
+- Extra review and testing
+- Backup plans
+- Monitoring and alerts
+- Quick rollback capability
+
+---
+
+## Verification Steps
+[How to verify each phase is complete - checklist for quality assurance]
+
+**Example:**
+
+### After Setup (Phase 0)
+- [ ] `npm install` completes without errors
+- [ ] `npm run build` compiles successfully
+- [ ] Environment variables load correctly
+- [ ] Can connect to database and Redis
+
+### After Foundation (Phase 1)
+- [ ] Database tables exist with correct schema
+- [ ] Can insert and query test data
+- [ ] TypeScript types compile without errors
+- [ ] Database and Redis connections stable
+
+### After Core Features (Phase 2)
+- [ ] Can register new user via API
+- [ ] Can login and receive valid token
+- [ ] Protected routes reject invalid tokens
+- [ ] Can reset password via email
+- [ ] Frontend forms work end-to-end
+- [ ] All API endpoints return correct responses
+
+### After Integration (Phase 3)
+- [ ] Input validation catches invalid data
+- [ ] Rate limiting blocks excessive requests
+- [ ] Emails deliver successfully
+- [ ] Errors logged and formatted correctly
+- [ ] Unit tests pass with > 80% coverage
+- [ ] Integration tests pass for key flows
+
+### After Polish (Phase 4)
+- [ ] Loading states show during async operations
+- [ ] Password strength indicator works
+- [ ] Database queries meet performance targets
+- [ ] API documentation complete
+- [ ] Deployment guide tested
+- [ ] Monitoring and alerts configured
+- [ ] Security audit passes
+- [ ] Load tests meet performance targets
+- [ ] Staging deployment successful
+- [ ] Production deployment successful
+
+### Final Acceptance
+- [ ] All requirements from requirements spec met
+- [ ] All acceptance criteria passed
+- [ ] No critical or high-severity bugs
+- [ ] Performance targets met
+- [ ] Security requirements satisfied
+- [ ] Documentation complete
+- [ ] Stakeholder sign-off received
+
+---
+
+## Notes
+[Additional context, assumptions, or important information]
+
+**Example:**
+- This implementation assumes PostgreSQL and Redis are already provisioned
+- Email templates need design team review before production
+- Consider adding OAuth (Google, GitHub) in Phase 2 of project
+- Monitor token blacklist size in Redis, may need cleanup job
+- Plan for GDPR compliance features (data export, deletion) in future sprint