diff --git a/src/env.js b/src/env.js index 77962101..c3a380bc 100644 --- a/src/env.js +++ b/src/env.js @@ -66,4 +66,4 @@ export const env = createEnv({ * `SOME_VAR=''` will throw an error. */ emptyStringAsUndefined: true, -}); +}); \ No newline at end of file diff --git a/tasks/README.md b/tasks/README.md new file mode 100644 index 00000000..70ab95f9 --- /dev/null +++ b/tasks/README.md @@ -0,0 +1,326 @@ +# Tasks Directory + +## Why Tasks Are in the Repository + +This `tasks/` directory contains project tasks and requirements documentation that lives alongside the codebase for optimal integration with modern coding IDEs like **Cursor**, **VS Code**, and other AI-powered development environments. + +### Key Benefits of Co-located Tasks + +#### 1. **IDE Integration & Context Awareness** +- **AI Code Assistants**: Tools like Cursor can read and understand task requirements directly from the repository +- **Contextual Help**: AI assistants can reference specific task requirements while suggesting code implementations +- **Real-time Guidance**: Developers get task-aware code suggestions and can ask questions about requirements without leaving their IDE + +#### 2. **Seamless Development Workflow** +- **No Context Switching**: Developers don't need to switch between external project management tools and their code editor +- **Version Control Integration**: Task updates are tracked alongside code changes, maintaining project history +- **Branch Alignment**: Tasks can be updated in feature branches, keeping documentation in sync with development + +#### 3. **Enhanced Collaboration** +- **Single Source of Truth**: All project information lives in one repository +- **Code-Requirement Traceability**: Easy to link specific code changes to task requirements +- **Onboarding Efficiency**: New team members can understand both code and requirements from the same location + +#### 4. **AI-Powered Development** +- **Task-Driven Coding**: AI assistants can read task requirements and generate code that directly addresses the documented needs +- **Requirement Validation**: AI can check if implemented code meets the documented requirements +- **Automated Documentation**: AI can help keep task documentation updated as code evolves + +### Directory Structure + +``` +tasks/ +├── README.md # This file - explains the tasks directory +├── Task_template.md # Template for creating new tasks +├── env.js # Environment configuration for tasks +└── wishlist/ # Future tasks and feature requests + ├── Task_01_XYZ.md # Task example +``` + +### How to Use Tasks with Your IDE + +#### For Cursor Users +1. **Open tasks alongside code**: Use split-screen to keep task requirements visible while coding +2. **Ask AI about tasks**: "Based on Task_01_Integration.md, how should I implement the authentication flow?" +3. **Reference requirements**: AI can read task files and provide context-aware suggestions + +#### For VS Code Users +1. **Install markdown extensions**: Use "Markdown Preview Enhanced" for better task viewing +2. **Use TODO extensions**: Track requirements as TODOs in your code +3. **Workspace setup**: Configure workspace with tasks and code side-by-side + +#### For Other IDEs +- **JetBrains**: Use built-in markdown preview and TODO tracking +- **Vim/Neovim**: Use markdown preview plugins and split windows +- **Any IDE**: Keep task files open in tabs or side panels while coding + +### Task Template Usage + +The `Task_template.md` provides a comprehensive structure for documenting: +- **Requirements**: Functional and non-functional requirements +- **Technical Specifications**: API specs, database schema, integration points +- **Implementation Plan**: Development phases and dependencies +- **Testing Strategy**: Test cases and acceptance criteria +- **Code Analysis**: Key issues and implementation details + +### Best Practices + +1. **Keep Tasks Updated**: Update task documentation as requirements evolve +2. **Link Code to Tasks**: Use commit messages and code comments that reference task sections +3. **Version Control**: Commit task updates alongside related code changes +4. **AI Integration**: Leverage AI assistants to help implement task requirements +5. **Regular Reviews**: Review and update tasks during development sprints + +### Integration with Development Tools + +- **Git**: Link task sections to specific commits and pull requests +- **Project Management**: Create tickets based on task sections +- **Code Reviews**: Reference task requirements in review comments +- **Documentation**: Keep tasks as living documents that evolve with the project + +This approach ensures that project requirements, technical specifications, and implementation details remain tightly coupled with the codebase, enabling more efficient and context-aware development workflows. + +## How to Use the Tasks Directory + +### Getting Started + +#### 1. **Understanding the Structure** +- **`Task_template.md`**: Use this as a starting point for new tasks +- **`wishlist/`**: Contains future tasks and feature requests + +#### 2. **Creating a New Task** +1. Copy `Task_template.md` to create a new task file +2. Name it descriptively: `Task_XX_FeatureName.md` +3. Fill in all relevant sections based on the template +4. Update the directory structure in this README if needed + +#### 3. **Working with Existing Tasks** +1. **Read the task thoroughly** before starting development +2. **Open the task file** alongside your code editor +3. **Reference specific requirements** while implementing features +4. **Update task status** as you progress through implementation + +### Development Workflow + +#### Phase 1: Task Analysis +```bash +# 1. Read the task requirements +cat tasks/wishlist/Task_XX_FeatureName.md + +# 2. Understand the scope and requirements +# 3. Identify key files and components to modify +# 4. Plan your implementation approach +``` + +#### Phase 2: Implementation +```bash +# 1. Create a feature branch +git checkout -b feature/task-xx-feature-name + +# 2. Keep the task file open while coding +# 3. Reference requirements in your code comments +# 4. Implement features according to the task specifications +``` + +#### Phase 3: Validation +```bash +# 1. Check that your implementation meets all requirements +# 2. Update task documentation with implementation notes +# 3. Test against acceptance criteria +# 4. Commit with task-referenced messages +``` + +### IDE-Specific Usage + +#### Cursor IDE +```bash +# 1. Open task file in split view +# 2. Ask AI: "Based on Task_XX_FeatureName.md, how should I implement [specific requirement]?" +# 3. Use AI to generate code that addresses task requirements +# 4. Reference task sections in your prompts +``` + +**Example Cursor Prompts:** +- "Based on FR-1 in Task_01_Integration.md, generate the authentication service" +- "How should I implement the database schema described in Task_02_UserPage.md?" +- "Check if my implementation meets the requirements in section 3 of the task" + +#### VS Code +```bash +# 1. Install extensions: +# - Markdown Preview Enhanced +# - TODO Tree +# - GitLens (for linking commits to tasks) + +# 2. Set up workspace with tasks and code side-by-side +# 3. Use TODO comments referencing task requirements +``` + +**Example VS Code Setup:** +```json +// .vscode/settings.json +{ + "markdown.preview.breaks": true, + "todo-tree.general.tags": ["FR-", "NFR-", "TC-"], + "files.associations": { + "Task_*.md": "markdown" + } +} +``` + +#### JetBrains IDEs +```bash +# 1. Use built-in markdown preview +# 2. Set up TODO patterns for task requirements +# 3. Use the TODO tool window to track progress +# 4. Link commits to task sections +``` + +### Task Management Best Practices + +#### 1. **Task Lifecycle** +``` +[Planning] → [In Progress] → [Review] → [Complete] + ↓ ↓ ↓ ↓ + Create Update Validate Archive + Task Progress Against Task + Notes Criteria Notes +``` + +#### 2. **Progress Tracking** +```markdown +# In your task file, update status like this: +## Implementation Status +- [x] FR-1: User authentication (COMPLETED - 2024-01-15) +- [ ] FR-2: API integration (IN PROGRESS - 2024-01-16) +- [ ] FR-3: Frontend implementation (PENDING) +``` + +#### 3. **Code Integration** +```typescript +/** + * Implements FR-1: User Authentication + * Task: Task_01_Integration.md + * Requirements: Functional Requirements section + * Status: COMPLETED + */ +export class AuthService { + // Implementation here +} +``` + +#### 4. **Commit Messages** +```bash +# Reference task sections in commits +git commit -m "feat: implement user authentication (Task_01_Integration.md - FR-1)" +git commit -m "fix: resolve API integration issue (Task_01_Integration.md - Technical Specs)" +git commit -m "test: add test cases for user journey (Task_01_Integration.md - TC-1)" +``` + +### Collaboration Guidelines + +#### 1. **Team Workflow** +- **Assign tasks** to team members with clear ownership +- **Review tasks** before starting implementation +- **Update progress** regularly in task files +- **Link pull requests** to specific task requirements + +#### 2. **Code Reviews** +```markdown +# In PR descriptions, reference tasks: +## Changes Made +- Implements FR-1: User authentication (Task_01_Integration.md) +- Addresses NFR-2: Performance requirements (Task_01_Integration.md) +- Includes tests for TC-1, TC-2 (Task_01_Integration.md) + +## Testing +- [x] Unit tests for authentication service +- [x] Integration tests for API endpoints +- [x] Manual testing of user flows +``` + +#### 3. **Documentation Updates** +- **Keep tasks current** as requirements evolve +- **Add implementation notes** to task files +- **Document architectural decisions** made during development +- **Update acceptance criteria** based on new insights + +### Troubleshooting + +#### Common Issues + +**Q: How do I handle changing requirements?** +A: Update the task file with the new requirements and document the changes. Use version control to track requirement evolution. + +**Q: What if a task is too large?** +A: Break it down into smaller, more manageable tasks. Create sub-tasks or split into multiple task files. + +**Q: How do I link code to specific requirements?** +A: Use code comments, commit messages, and PR descriptions that reference task sections (e.g., "FR-1", "TC-2"). + +**Q: Can I use external project management tools too?** +A: Yes, but keep the tasks directory as the source of truth for technical requirements. Sync with external tools as needed. + +### Advanced Usage + +#### 1. **Automated Task Validation** +```bash +# Create scripts to validate implementation against tasks +# Example: Check if all FR-* requirements are implemented +grep -r "FR-" tasks/ | while read line; do + echo "Checking requirement: $line" + # Add validation logic here +done +``` + +#### 2. **Task Templates for Different Types** +- **Feature Tasks**: Use full template for new features +- **Bug Fix Tasks**: Simplified template focusing on problem/solution +- **Refactoring Tasks**: Template emphasizing code quality and architecture + +#### 3. **Integration with CI/CD** +```yaml +# Example GitHub Actions workflow +- name: Validate Task Requirements + run: | + # Check if implemented features match task requirements + # Validate that all FR-* items are addressed + # Ensure tests cover TC-* items +``` + +This comprehensive usage guide ensures that developers can effectively leverage the co-located tasks directory for improved development workflows and better integration with AI-powered coding assistants. + +--- + +## ⚠️ Important Notice: Process Refinement + +**All processes, workflows, and guidelines described in this README are open for refinement and continuous improvement.** + +### We Encourage Modifications + +- **Experiment with workflows**: Try different approaches and adapt them to your team's needs +- **Suggest improvements**: If you find better ways to organize or use the tasks directory, share them +- **Customize templates**: Modify the task template to better fit your project's requirements +- **Evolve the structure**: The directory structure can be adapted as your project grows + +### How to Contribute Improvements + +1. **Document your changes**: When you modify processes, update this README +2. **Share with the team**: Discuss improvements with your team members +3. **Version your changes**: Use git to track process evolution +4. **Test new approaches**: Validate improvements before making them standard + +### Continuous Improvement + +This tasks directory and its associated processes should evolve with your project. What works for a small team might need adjustment for a larger organization. What works for one type of project might need modification for another. + +**Remember**: The goal is to improve development efficiency and code quality. If a process isn't serving that goal, it should be changed. + +### Feedback and Iteration + +- **Regular reviews**: Schedule periodic reviews of your task management processes +- **Team retrospectives**: Include process improvement in your team retrospectives +- **Document lessons learned**: Keep track of what works and what doesn't +- **Share best practices**: Contribute improvements back to the project + +The processes outlined here are starting points, not rigid rules. Adapt them to create the most effective workflow for your specific context and team. diff --git a/tasks/wishlist/Task_02_UserPage.md b/tasks/wishlist/Task_02_UserPage.md new file mode 100644 index 00000000..e83bb7ce --- /dev/null +++ b/tasks/wishlist/Task_02_UserPage.md @@ -0,0 +1,239 @@ +# Task 02: User Page and Registration Flow + +## 1. Task Overview +**Implement a comprehensive user registration and authentication flow with a dedicated User Page, utilizing nonce-based authentication and addressing wallet connection bugs.** + +### Problem Statement +- **Current Issue**: Users experience authentication bugs when initially connecting their wallet on new devices +- **Missing UX**: No dedicated user registration flow or user management page +- **Authentication Gap**: The current system auto-creates users but doesn't handle the authentication flow properly for new devices +- **State Management**: User state is managed but lacks proper registration/onboarding flow + +### Solution Overview +- **User Registration Modal**: Simple, intuitive registration flow for new users +- **Nonce-Based Authentication**: Secure authentication using wallet signature verification +- **User Page**: Dedicated page for user profile management and settings +- **Bug Resolution**: Fix wallet connection authentication issues on new devices + +## 2. Requirements + +### User Stories +``` +As a new user, I want to register my wallet securely so that I can access the multisig platform +As an existing user, I want to authenticate on a new device so that I can access my wallets and data +As a user, I want to manage my profile and settings so that I can customize my experience +As a user, I want a smooth wallet connection experience so that I don't encounter authentication bugs +As a user, I want to see human-readable names (AdaHandles) instead of long wallet addresses so that I can easily identify users +As a user, I want the system to find my account using either my wallet address or stake key so that I can access my data regardless of which identifier I have +``` + +### Functional Requirements +- **FR-1**: User Registration Modal - Modal-based registration flow for new users +- **FR-2**: Nonce Authentication Flow - Secure nonce-based authentication for new devices +- **FR-3**: User Profile Page - Dedicated page for user management and settings +- **FR-4**: Wallet Connection Bug Fix - Resolve authentication issues on initial wallet connection +- **FR-5**: State Management Integration - Seamless integration with existing zustand user store +- **FR-6**: Authentication Persistence - Proper session management and token handling +- **FR-7**: AdaHandle Name Inference - Display human-readable names from AdaHandle integration +- **FR-8**: Stake Key Flexibility - Support user lookup by both address and stake key for better wallet compatibility + +### Non-Functional Requirements +- **NFR-1**: Security - Cryptographic signature verification for all authentication +- **NFR-2**: UX/UI - Intuitive, modern interface following existing design patterns +- **NFR-3**: Performance - Fast authentication flow with minimal loading states +- **NFR-4**: Compatibility - Works with all supported Cardano wallets +- **NFR-5**: Accessibility - WCAG compliant interface components + +## 3. Technical Specifications + +### Architecture Overview +- **Frontend**: React components with TypeScript, Zustand state management +- **Authentication**: Nonce-based signature verification using Mesh SDK +- **Backend**: Existing tRPC API with JWT token management +- **Database**: Prisma ORM with existing User and Nonce models + +### API Specifications +**Existing Endpoints to Utilize:** +- `GET /api/v1/getNonce?address={address}` - Request nonce for address +- `POST /api/v1/authSigner` - Verify signature and get JWT token +- `api.user.getUserByAddress` - Get user by address +- `api.user.getUserByStakeKey` - Get user by stake key for better flexibility +- `api.user.createUser` - Create new user + +**New Endpoints Needed:** +- `api.user.updateUser` - Update user profile information +- `api.user.deleteUser` - Delete user account (optional) + +### Database Schema +**Existing Models:** +```prisma +model User { + id String @id @default(cuid()) + address String @unique + stakeAddress String @unique + nostrKey String @unique + discordId String @default("") +} + +model Nonce { + id String @id @default(cuid()) + address String @unique + value String + createdAt DateTime @default(now()) +} +``` + +**Potential Additions:** +- displayName field for user-friendly names +- email field for contact information +- lastLoginAt timestamp for activity tracking +- isActive boolean for account status +- preferences JSON field for user settings + +### Integration Points +- **Mesh SDK**: Wallet connection and signature verification +- **Zustand Store**: User state management and persistence +- **tRPC**: API communication and type safety +- **Next.js**: Routing and page management +- **JWT**: Token-based authentication +- **AdaHandle API**: Name resolution for human-readable wallet identification + +## 4. Implementation Plan + +### Development Phases (UI-First Approach) +- **Phase 1**: User Registration Modal UI (Week 1) + - Create registration modal component with mock data + - Design nonce-based authentication flow UI + - Implement modal states and transitions + - Basic zustand store integration +- **Phase 2**: User Profile Page UI (Week 2) + - Create user profile page layout and components + - Design user settings interface + - Implement profile display with mock data + - Add navigation and routing +- **Phase 3**: UI Polish and Integration (Week 3) + - Refine user experience and interactions + - Add loading states and error handling + - Connect to existing wallet connection flow + - Minimal API integration for essential features + +### Dependencies +- **External**: Mesh SDK for wallet connection (minimal integration) +- **Internal**: Zustand user store, existing UI components, mock data +- **Infrastructure**: No database changes needed initially + +### Risk Assessment +- **Low Risk**: UI component implementation and styling +- **Low Risk**: Mock data integration and state management +- **Medium Risk**: Integration with existing wallet connection flow + +## 5. Testing Strategy + +### Test Cases +- **TC-1**: User registration modal UI flow and states +- **TC-2**: User profile page display and navigation +- **TC-3**: Modal interactions and transitions +- **TC-4**: Zustand store integration with mock data +- **TC-5**: UI responsiveness and accessibility + +### Testing Types +- **Unit Testing**: Individual component functionality +- **Integration Testing**: Zustand store and component integration +- **UI Testing**: Component rendering and user interactions +- **Accessibility Testing**: WCAG compliance and keyboard navigation + +### Acceptance Criteria +- Registration modal displays correctly with proper states +- User profile page renders with mock data +- Modal interactions work smoothly (open, close, transitions) +- Zustand store integration functions properly +- UI is responsive and accessible +- Components follow existing design patterns + +## 6. Code Analysis & Implementation Details + +### Key Issues Identified +- **Issue 1**: No user registration UI flow for new users +- **Issue 2**: Missing user profile management interface +- **Issue 3**: Wallet connection state not properly reflected in UI +- **Issue 4**: No dedicated user management page + +### Code References +**Files to Modify:** +- `src/lib/zustand/user.ts` - Add registration state management +- `src/hooks/useUser.ts` - Enhance user hook with registration logic + +**New Files to Create:** +- `src/components/pages/user/` - User profile page components +- `src/components/common/user-registration-modal.tsx` - Registration modal +- `src/hooks/useUserRegistration.ts` - Registration logic hook +- `src/pages/user/index.tsx` - User profile page +- `src/data/mockUserData.ts` - Mock user data for development + +### Component Specifications + +**User Registration Modal:** +- Multi-step modal with welcome, nonce generation, signature, and completion states +- Visual icons and progress indicators for each step +- Mock data integration for development without API dependencies +- Smooth transitions between states with loading indicators +- Responsive design with proper spacing and typography + +**Enhanced User Hook:** +- Registration state management with modal visibility control +- Skip registration option for testing and development +- Integration with existing user store and wallet connection +- Mock data fallback when real user data is unavailable +- Support for both address and stake key lookup methods + +**User Profile Page:** +- Two-column layout with account information and settings +- Account information card showing wallet and stake addresses with AdaHandle name resolution +- Settings card with Discord integration, notifications, and theme toggles +- Recent activity feed with mock activity data +- Responsive design with proper card layouts and spacing +- AdaHandle display with fallback to wallet address when no handle is found + + + +## 7. Next Steps (UI-First Implementation) +1. **Step 1**: Create user registration modal component +2. **Step 2**: Implement enhanced user hook with registration state management +3. **Step 3**: Create user profile page +4. **Step 4**: Add mock user data and state management +5. **Step 5**: Implement modal interactions and transitions +6. **Step 6**: Add navigation and routing for user page +7. **Step 7**: Integrate AdaHandle name resolution for human-readable wallet identification +8. **Step 8**: Implement stake key lookup functionality for better wallet compatibility + +--- + +## Implementation Priority (UI-First) + +### High Priority (Week 1) +- User registration modal UI with mock data +- Enhanced user state management with Zustand +- Modal interactions and transitions + +### Medium Priority (Week 2) +- User profile page implementation with mock data +- Settings and preferences UI +- Navigation and routing +- AdaHandle name resolution integration +- Stake key lookup functionality implementation + +### Low Priority (Week 3) +- API integration (when ready) +- Advanced user features +- Performance optimizations + +## Success Metrics (UI-First) +- Registration modal displays correctly with all states +- User profile page renders with mock data +- Smooth modal interactions and transitions +- Proper state management integration +- Responsive and accessible UI components +- AdaHandle names display correctly with fallback to wallet addresses +- Human-readable identification improves user experience +- Users can be found using either wallet address or stake key +- Improved wallet compatibility and flexibility