mystiatech/Sage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(01): create phase 1 authentication plans

Browse Source 
Phase 1: Authentication & Account Basics
- 7 plans in 4 waves
- Covers AUTH-01 through AUTH-05 requirements
- Foundation for household features in Phase 2
- Ready for execution
This commit is contained in:
Dani B
2026-01-28 00:26:56 -05:00
parent 357e7e2b31
commit f9150e04d5
8 changed files with 1161 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
.planning/phases/01-authentication/01-01-PLAN.md Normal file
View File

@@ -0,0 +1,139 @@
---
phase: 01-authentication
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: ["pubspec.yaml", "lib/main.dart", "lib/core/constants/supabase_constants.dart", ".env"]
autonomous: true
user_setup:
- service: supabase
why: "Authentication backend and database"
env_vars:
- name: SUPABASE_URL
source: "Supabase Dashboard → Settings → API → Project URL"
- name: SUPABASE_ANON_KEY
source: "Supabase Dashboard → Settings → API → anon/public key"
dashboard_config:
- task: "Configure redirect URLs for password reset"
location: "Supabase Dashboard → Authentication → URL Configuration"
must_haves:
truths:
- "Flutter project initializes with Supabase client"
- "Environment variables are loaded securely"
- "Supabase connection is established without errors"
artifacts:
- path: "pubspec.yaml"
provides: "Flutter project dependencies"
contains: "supabase_flutter"
- path: "lib/main.dart"
provides: "Supabase initialization"
min_lines: 15
- path: "lib/core/constants/supabase_constants.dart"
provides: "Supabase configuration constants"
min_lines: 10
- path: ".env"
provides: "Environment variables"
contains: "SUPABASE_URL"
key_links:
- from: "lib/main.dart"
to: "Supabase.initialize"
via: "main() function"
pattern: "Supabase\\.initialize"
- from: "lib/core/constants/supabase_constants.dart"
to: ".env"
via: "environment variable loading"
pattern: "String.fromEnvironment|dotenv"
---
<objective>
Create Flutter project foundation with Supabase integration and secure configuration.
Purpose: Establish the technical foundation required for all authentication features in Sage.
Output: Working Flutter app that can communicate with Supabase backend using secure configuration.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Initialize Flutter project with Supabase dependencies</name>
<files>pubspec.yaml</files>
<action>
Create Flutter project if it doesn't exist. Add required dependencies to pubspec.yaml:
- supabase_flutter: ^2.12.0
- flutter_dotenv: ^5.1.0
- go_router: ^13.0.0
- riverpod: ^2.5.0
- flutter_secure_storage: ^9.0.0
Run `flutter pub get` to install dependencies.
</action>
<verify>flutter pub get completes successfully and all dependencies resolve</verify>
<done>Flutter project exists with all required Supabase dependencies installed</done>
</task>
<task type="auto">
<name>Create secure Supabase configuration</name>
<files>lib/core/constants/supabase_constants.dart, .env</files>
<action>
Create environment configuration:
1. Create .env file with SUPABASE_URL and SUPABASE_ANON_KEY placeholders
2. Create lib/core/constants/supabase_constants.dart that loads environment variables using flutter_dotenv
3. Add .env to .gitignore to prevent committing secrets
4. Provide clear instructions in comments about where to get the values
Constants file should export:
- supabaseUrl
- supabaseAnonKey
</action>
<verify>Environment variables load correctly without exposing sensitive data in version control</verify>
<done>Secure configuration system exists with placeholder values ready for user setup</done>
</task>
<task type="auto">
<name>Initialize Supabase in main.dart</name>
<files>lib/main.dart</files>
<action>
Update lib/main.dart to:
1. Import required packages (supabase_flutter, flutter_dotenv)
2. Load environment variables using dotenv.load()
3. Initialize Supabase in main() before runApp()
4. Use SharedPreferencesLocalStorage for session persistence (default, secure enough for v1)
5. Handle initialization errors gracefully
6. Create basic MyApp widget structure
Follow the PKCE flow pattern from research.
</action>
<verify>flutter run starts without Supabase initialization errors</verify>
<done>Flutter app initializes Supabase client successfully on startup</done>
</task>
</tasks>
<verification>
1. Flutter project runs without errors (`flutter run`)
2. Supabase client initializes without throwing exceptions
3. Environment variables are loaded securely (not hardcoded)
4. Project structure follows recommended architecture from research
</verification>
<success_criteria>
Flutter app starts successfully, Supabase client is initialized and ready to handle authentication operations, and configuration is secure and maintainable.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-01-SUMMARY.md`
</output>

136
.planning/phases/01-authentication/01-02-PLAN.md Normal file
View File

@@ -0,0 +1,136 @@
---
phase: 01-authentication
plan: 02
type: execute
wave: 1
depends_on: []
files_modified: ["lib/features/authentication/data/models/auth_user.dart", "lib/core/errors/auth_exceptions.dart", "lib/features/authentication/domain/repositories/auth_repository.dart"]
autonomous: true
user_setup: []
must_haves:
truths:
- "Auth model represents user data consistently"
- "Auth exceptions provide clear error messages"
- "Auth repository defines interface for auth operations"
artifacts:
- path: "lib/features/authentication/data/models/auth_user.dart"
provides: "User data model"
min_lines: 15
- path: "lib/core/errors/auth_exceptions.dart"
provides: "Custom auth error handling"
min_lines: 20
- path: "lib/features/authentication/domain/repositories/auth_repository.dart"
provides: "Auth operations interface"
min_lines: 25
key_links:
- from: "lib/features/authentication/domain/repositories/auth_repository.dart"
to: "lib/features/authentication/data/models/auth_user.dart"
via: "method signatures"
pattern: "Future<AuthUser>|AuthUser"
- from: "lib/core/errors/auth_exceptions.dart"
to: "lib/features/authentication/domain/repositories/auth_repository.dart"
via: "exception handling"
pattern: "throws.*Exception"
---
<objective>
Create authentication data models, error handling system, and repository interface.
Purpose: Establish clean architecture foundations that separate concerns and provide type safety for authentication operations.
Output: Domain models, custom exceptions, and repository interface that abstract Supabase implementation details.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Create AuthUser model</name>
<files>lib/features/authentication/data/models/auth_user.dart</files>
<action>
Create AuthUser data class that:
1. Extends or wraps Supabase User model for flexibility
2. Contains essential user fields (id, email, created_at, email_verified)
3. Includes fromSupabase() factory constructor
4. Includes copyWith() method for immutability
5. Includes toString() for debugging
6. Follows clean architecture pattern (data layer)
7. Has proper null safety handling
</action>
<verify>AuthUser model compiles without errors and properly handles Supabase User conversion</verify>
<done>AuthUser model provides clean abstraction over Supabase User with necessary fields</done>
</task>
<task type="auto">
<name>Create custom auth exceptions</name>
<files>lib/core/errors/auth_exceptions.dart</files>
<action>
Create custom exception classes that:
1. Extend Exception base class
2. Include specific auth error types:
- AuthException (base)
- InvalidCredentialsException
- UserNotFoundException
- WeakPasswordException
- EmailAlreadyInUseException
- NetworkException
- SessionExpiredException
3. Each exception has user-friendly message field
4. Include fromSupabaseError() factory for converting Supabase errors
5. Follow consistent error code patterns
6. Include proper documentation
</action>
<verify>Custom exceptions compile and provide meaningful error messages for different auth scenarios</verify>
<done>Comprehensive error handling system that maps Supabase errors to user-friendly messages</done>
</task>
<task type="auto">
<name>Create AuthRepository interface</name>
<files>lib/features/authentication/domain/repositories/auth_repository.dart</files>
<action>
Create abstract AuthRepository class that:
1. Defines interface for all auth operations:
- Future<AuthUser> signUp(String email, String password)
- Future<AuthUser> signIn(String email, String password)
- Future<void> signOut()
- Future<void> resetPassword(String email)
- Future<AuthUser?> getCurrentUser()
- Stream<AuthUser?> authStateChanges()
2. Returns custom exceptions for error cases
3. Follows clean architecture (domain layer)
4. Has comprehensive documentation
5. Uses proper async/await patterns
6. Includes null safety throughout
</action>
<verify>AuthRepository interface compiles without implementation and clearly defines all required auth methods</verify>
<done>Clean interface that abstracts authentication operations from Supabase implementation</done>
</task>
</tasks>
<verification>
1. All models and interfaces compile without errors
2. Type safety is maintained throughout (no 'any' types)
3. Error handling covers all major auth scenarios
4. Clean architecture layers are properly separated
5. Documentation is comprehensive for future implementers
</verification>
<success_criteria>
Authentication domain foundation is established with proper models, error handling, and repository interface ready for implementation.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-02-SUMMARY.md`
</output>

147
.planning/phases/01-authentication/01-03-PLAN.md Normal file
View File

@@ -0,0 +1,147 @@
---
phase: 01-authentication
plan: 03
type: execute
wave: 2
depends_on: ["01-01", "01-02"]
files_modified: ["lib/features/authentication/presentation/pages/login_page.dart", "lib/features/authentication/presentation/pages/signup_page.dart", "lib/features/authentication/presentation/widgets/auth_form.dart", "lib/features/authentication/presentation/widgets/auth_button.dart"]
autonomous: true
user_setup: []
must_haves:
truths:
- "Login form accepts email and password input"
- "Signup form accepts email and password input"
- "Forms have proper validation and visual feedback"
- "UI components are responsive and accessible"
artifacts:
- path: "lib/features/authentication/presentation/pages/login_page.dart"
provides: "Login screen UI"
min_lines: 40
- path: "lib/features/authentication/presentation/pages/signup_page.dart"
provides: "Signup screen UI"
min_lines: 40
- path: "lib/features/authentication/presentation/widgets/auth_form.dart"
provides: "Reusable form components"
min_lines: 30
- path: "lib/features/authentication/presentation/widgets/auth_button.dart"
provides: "Authentication buttons"
min_lines: 20
key_links:
- from: "lib/features/authentication/presentation/pages/login_page.dart"
to: "lib/features/authentication/presentation/widgets/auth_form.dart"
via: "widget composition"
pattern: "AuthForm|auth_form"
- from: "lib/features/authentication/presentation/widgets/auth_form.dart"
to: "lib/features/authentication/presentation/widgets/auth_button.dart"
via: "button component usage"
pattern: "AuthButton|auth_button"
---
<objective>
Create authentication UI screens with forms, validation, and reusable components.
Purpose: Provide user interface for signup and login flows with proper form validation and responsive design.
Output: Complete authentication screens ready to connect to auth repository implementation.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Create reusable auth components</name>
<files>lib/features/authentication/presentation/widgets/auth_form.dart, lib/features/authentication/presentation/widgets/auth_button.dart</files>
<action>
Create reusable widgets:
1. AuthButton widget that:
- Accepts onPressed callback, text, loading state
- Shows loading indicator when disabled
- Has proper styling and disabled states
- Supports variant prop (primary, secondary)
- Includes proper accessibility labels
2. AuthForm widget that:
- Accepts email and password field configurations
- Provides form validation (email format, password strength)
- Shows validation errors in real-time
- Has onSubmit callback
- Includes obscure text toggle for password
- Proper text input types and keyboard types
- Responsive layout for mobile/tablet
</action>
<verify>Widgets render without errors, handle user input properly, and show validation feedback</verify>
<done>Reusable authentication components that handle form validation and user interactions</done>
</task>
<task type="auto">
<name>Create login page</name>
<files>lib/features/authentication/presentation/pages/login_page.dart</files>
<action>
Create LoginPage widget that:
1. Uses AuthForm for email/password inputs
2. Uses AuthButton for submit action
3. Has "Forgot password?" link (placeholder for now)
4. Has "Sign up" navigation link
5. Properly handles form submission
6. Shows loading states during authentication
7. Has proper page structure with SafeArea
8. Responsive design for different screen sizes
9. Includes app bar if needed for navigation
10. Proper accessibility labels and semantic structure
</action>
<verify>Login page renders correctly, form validation works, and all interactive elements respond to user input</verify>
<done>Complete login screen ready to connect to authentication logic</done>
</task>
<task type="auto">
<name>Create signup page</name>
<files>lib/features/authentication/presentation/pages/signup_page.dart</files>
<action>
Create SignupPage widget that:
1. Uses AuthForm for email/password inputs
2. Includes password confirmation field
3. Uses AuthButton for submit action
4. Has "Sign in" navigation link
5. Shows terms of service and privacy policy links (placeholder text)
6. Properly handles form submission
7. Shows loading states during registration
8. Validates password matching
9. Has proper page structure with SafeArea
10. Responsive design for different screen sizes
11. Includes app bar if needed for navigation
12. Proper accessibility labels and semantic structure
</action>
<verify>Signup page renders correctly, form validation works for all fields, and password confirmation matches properly</verify>
<done>Complete signup screen with password confirmation ready to connect to authentication logic</done>
</task>
</tasks>
<verification>
1. All authentication pages render without compilation errors
2. Form validation provides immediate and helpful feedback
3. Components are responsive across different screen sizes
4. Accessibility features work correctly (screen readers, semantic structure)
5. Loading states work properly during form submission
6. Navigation elements are present and functional (even if placeholder actions)
</verification>
<success_criteria>
Authentication UI is complete with proper form validation, responsive design, and reusable components ready for integration with auth logic.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-03-SUMMARY.md`
</output>

178
.planning/phases/01-authentication/01-04-PLAN.md Normal file
View File

@@ -0,0 +1,178 @@
---
phase: 01-authentication
plan: 04
type: execute
wave: 2
depends_on: ["01-01", "01-02"]
files_modified: ["lib/providers/auth_provider.dart", "lib/features/authentication/data/repositories/auth_repository_impl.dart", "lib/app/router.dart", "lib/presentation/pages/splash_page.dart"]
autonomous: true
user_setup: []
must_haves:
truths:
- "Auth state changes trigger UI updates automatically"
- "Navigation works based on authentication status"
- "Auth repository implementation connects to Supabase"
- "Session persists across app restarts"
artifacts:
- path: "lib/providers/auth_provider.dart"
provides: "Global auth state management"
min_lines: 35
- path: "lib/features/authentication/data/repositories/auth_repository_impl.dart"
provides: "Supabase auth implementation"
min_lines: 50
- path: "lib/app/router.dart"
provides: "Auth-based navigation"
min_lines: 40
- path: "lib/presentation/pages/splash_page.dart"
provides: "Initial loading screen"
min_lines: 20
key_links:
- from: "lib/providers/auth_provider.dart"
to: "lib/features/authentication/data/repositories/auth_repository_impl.dart"
via: "dependency injection"
pattern: "AuthRepository|_authRepository"
- from: "lib/providers/auth_provider.dart"
to: "lib/app/router.dart"
via: "auth state listening"
pattern: "onAuthStateChange|authStateChanges"
- from: "lib/features/authentication/data/repositories/auth_repository_impl.dart"
to: "supabase.auth"
via: "Supabase client usage"
pattern: "supabase\\.auth\\."
---
<objective>
Implement authentication state management, Supabase repository, and navigation system.
Purpose: Connect UI components to Supabase authentication, manage auth state globally, and handle navigation based on user authentication status.
Output: Working authentication system with session persistence and protected routes.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Implement AuthRepository with Supabase</name>
<files>lib/features/authentication/data/repositories/auth_repository_impl.dart</files>
<action>
Create AuthRepositoryImpl class that:
1. Implements AuthRepository interface from plan 02
2. Uses supabase.auth for all operations:
- signUp() with email/password, handles AuthResponse
- signIn() with email/password, handles AuthResponse
- signOut() to clear session
- resetPassword() with email and redirect URL
- getCurrentUser() from supabase.auth.currentUser
- authStateChanges() stream from onAuthStateChange
3. Converts Supabase errors to custom exceptions
4. Maps User to AuthUser model
5. Includes proper null safety handling
6. Has comprehensive error handling
7. Follows repository pattern correctly
8. Uses proper async/await patterns
</action>
<verify>Repository implementation connects to Supabase and handles all auth operations without throwing unhandled exceptions</verify>
<done>Complete Supabase authentication repository ready for integration with state management</done>
</task>
<task type="auto">
<name>Create AuthProvider for state management</name>
<files>lib/providers/auth_provider.dart</files>
<action>
Create AuthProvider class that:
1. Extends ChangeNotifier or uses Riverpod
2. Depends on AuthRepository (injection)
3. Manages auth state (User?, loading, error)
4. Listens to repository.authStateChanges() stream
5. Provides methods:
- signUp(String email, String password)
- signIn(String email, String password)
- signOut()
- resetPassword(String email)
6. Handles loading states and errors
7. Updates UI state automatically
8. Properly disposes of stream subscriptions
9. Has current User? getter
10. Includes proper error propagation
</action>
<verify>AuthProvider updates state correctly when auth events occur and maintains loading/error states properly</verify>
<done>Global auth state management that automatically responds to authentication changes</done>
</task>
<task type="auto">
<name>Create auth-aware navigation system</name>
<files>lib/app/router.dart, lib/presentation/pages/splash_page.dart</files>
<action>
Create navigation system with:
1. SplashPage that:
- Shows while checking initial auth state
- Navigates to login or home after auth check
- Has proper loading indicator
- Handles app startup sequence
2. Router configuration that:
- Uses GoRouter for declarative routing
- Has protected routes (redirect to login if not authenticated)
- Has public routes (login, signup, password reset)
- Listens to AuthProvider for auth state changes
- Includes proper route definitions:
- / → redirect based on auth state
- /login → login page
- /signup → signup page
- /home → protected home route (placeholder)
- Handles deep linking properly
- Includes proper error handling for navigation
</action>
<verify>Navigation correctly redirects based on authentication status and all routes are accessible</verify>
<done>Complete navigation system that protects routes and responds to authentication changes</done>
</task>
<task type="auto">
<name>Integrate auth system with main app</name>
<files>lib/main.dart</files>
<action>
Update main.dart to:
1. Wrap MyApp with appropriate providers (Riverpod/ChangeNotifierProvider)
2. Initialize AuthProvider with AuthRepositoryImpl
3. Configure router with auth state integration
4. Set up proper error boundaries
5. Ensure proper initialization order
6. Add proper app structure with MaterialApp.router
7. Configure theme and other app-level settings
8. Ensure proper disposal of resources
</action>
<verify>App starts with splash screen, properly checks auth state, and navigates to appropriate initial screen</verify>
<done>Complete app integration with authentication system</done>
</task>
</tasks>
<verification>
1. Authentication repository successfully connects to Supabase and handles all auth methods
2. State management responds correctly to auth state changes
3. Navigation system properly protects routes and redirects based on auth status
4. Session persistence works across app restarts
5. Error handling provides user-friendly feedback
6. Loading states work properly during authentication operations
</verification>
<success_criteria>
Complete authentication system with Supabase integration, state management, and protected navigation ready for UI connection.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-04-SUMMARY.md`
</output>

191
.planning/phases/01-authentication/01-05-PLAN.md Normal file
View File

@@ -0,0 +1,191 @@
---
phase: 01-authentication
plan: 05
type: execute
wave: 3
depends_on: ["01-03", "01-04"]
files_modified: ["lib/features/authentication/presentation/pages/reset_password_page.dart", "lib/features/authentication/presentation/pages/update_password_page.dart", "lib/features/authentication/presentation/widgets/password_reset_form.dart"]
autonomous: true
user_setup:
- service: supabase
why: "Configure password reset redirect URLs"
env_vars: []
dashboard_config:
- task: "Add password reset redirect URLs"
location: "Supabase Dashboard → Authentication → URL Configuration → Site URL"
- task: "Add password reset redirect URLs"
location: "Supabase Dashboard → Authentication → URL Configuration → Redirect URLs"
must_haves:
truths:
- "User can request password reset via email"
- "User receives reset email within 1 minute"
- "Reset link redirects to password update page"
- "User can set new password successfully"
artifacts:
- path: "lib/features/authentication/presentation/pages/reset_password_page.dart"
provides: "Password reset request page"
min_lines: 35
- path: "lib/features/authentication/presentation/pages/update_password_page.dart"
provides: "New password entry page"
min_lines: 40
- path: "lib/features/authentication/presentation/widgets/password_reset_form.dart"
provides: "Password reset form components"
min_lines: 25
key_links:
- from: "lib/features/authentication/presentation/pages/reset_password_page.dart"
to: "lib/providers/auth_provider.dart"
via: "password reset method"
pattern: "resetPassword|_authProvider"
- from: "lib/features/authentication/presentation/pages/update_password_page.dart"
to: "supabase.auth"
via: "password update flow"
pattern: "supabase\\.auth\\.updateUser|supabase\\.auth\\.resetPasswordForEmail"
---
<objective>
Implement password reset functionality with email flow and new password entry.
Purpose: Enable users to recover forgotten passwords securely through email-based reset flow.
Output: Complete password reset system from email request to new password confirmation.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Create password reset request page</name>
<files>lib/features/authentication/presentation/pages/reset_password_page.dart</files>
<action>
Create ResetPasswordPage that:
1. Has email input field with validation
2. Uses AuthButton for "Send Reset Email" action
3. Shows success message after email sent
4. Shows error message for invalid email
5. Has loading state during email sending
6. Includes "Back to Login" navigation
7. Provides clear instructions to user
8. Handles rate limiting feedback (if email already sent)
9. Uses AuthRepository resetPassword() method
10. Has proper page structure and responsive design
11. Includes accessibility features
12. Shows helpful copy like "Check your email for reset link"
</action>
<verify>Reset password page sends email request and shows appropriate success/error states</verify>
<done>Complete password reset request interface integrated with auth system</done>
</task>
<task type="auto">
<name>Create password reset components</name>
<files>lib/features/authentication/presentation/widgets/password_reset_form.dart</files>
<action>
Create PasswordResetForm widget that:
1. Accepts email field configuration
2. Provides email validation
3. Shows validation errors in real-time
4. Has onSubmit callback for email submission
5. Shows loading state during submission
6. Has proper styling consistent with AuthForm
7. Includes proper text input types
8. Responsive layout for mobile/tablet
9. Proper accessibility labels
10. Can be reused in different contexts
</action>
<verify>Password reset form validates email properly and handles submission states correctly</verify>
<done>Reusable password reset form component</done>
</task>
<task type="auto">
<name>Create password update page</name>
<files>lib/features/authentication/presentation/pages/update_password_page.dart</files>
<action>
Create UpdatePasswordPage that:
1. Handles deep linking from password reset emails
2. Has new password input field with strength validation
3. Has confirm password field for validation
4. Uses AuthButton for "Update Password" action
5. Shows error messages for password mismatches
6. Shows loading state during password update
7. Navigates to login after successful password update
8. Handles expired/invalid reset tokens gracefully
9. Uses Supabase updateUser() method
10. Has proper error handling for various failure modes
11. Includes accessibility features
12. Has clear success messaging
13. Includes "Cancel" option to return to login
</action>
<verify>Password update page validates inputs, updates password successfully, and handles error cases</verify>
<done>Complete password update interface with deep link handling</done>
</task>
<task type="auto">
<name>Update auth repository for password reset</name>
<files>lib/features/authentication/data/repositories/auth_repository_impl.dart</files>
<action>
Extend AuthRepositoryImpl to:
1. Add updatePassword() method for new password setting
2. Handle password reset token verification
3. Improve resetPassword() method with proper redirect URL configuration
4. Add proper error handling for:
- Expired reset tokens
- Invalid reset tokens
- Weak passwords
- Network failures
5. Use supabase.auth.updateUser() for password updates
6. Ensure proper session handling after password update
7. Add comprehensive error mapping to custom exceptions
8. Include proper logging for debugging
</action>
<verify>Repository methods handle password reset flow from email to completion</verify>
<done>Enhanced auth repository with complete password reset functionality</done>
</task>
<task type="auto">
<name>Integrate password reset with navigation</name>
<files>lib/app/router.dart</files>
<action>
Update router to:
1. Add /reset-password route for reset request page
2. Add /update-password route for password update page
3. Handle deep linking for password reset URLs
4. Parse reset tokens from URL parameters
5. Add proper route guards and validation
6. Include password reset links in login/signup pages
7. Configure proper URL scheme for mobile deep linking
8. Handle web redirect URLs properly
9. Add error handling for malformed reset URLs
10. Ensure navigation flow works correctly
</action>
<verify>Navigation properly handles password reset flow and deep linking</verify>
<done>Complete navigation integration for password reset functionality</done>
</task>
</tasks>
<verification>
1. Password reset email sends successfully and arrives within 1 minute
2. Reset email contains working deep link to password update page
3. Password update page validates inputs and updates password successfully
4. Error handling covers all failure scenarios (invalid email, expired tokens, etc.)
5. Navigation flows correctly through entire password reset journey
6. Deep linking works on both mobile and web platforms
</verification>
<success_criteria>
Complete password reset system working from email request to new password confirmation with proper error handling and user feedback.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-05-SUMMARY.md`
</output>

193
.planning/phases/01-authentication/01-06-PLAN.md Normal file
View File

@@ -0,0 +1,193 @@
---
phase: 01-authentication
plan: 06
type: execute
wave: 4
depends_on: ["01-03", "01-04"]
files_modified: ["lib/features/authentication/presentation/pages/login_page.dart", "lib/features/authentication/presentation/pages/signup_page.dart", "lib/features/authentication/presentation/pages/reset_password_page.dart", "lib/features/authentication/presentation/widgets/auth_form.dart"]
autonomous: true
user_setup: []
must_haves:
truths:
- "Login errors distinguish invalid password vs account not found"
- "Signup errors show specific failure reasons"
- "Password reset errors provide helpful guidance"
- "Loading states show during all auth operations"
- "Success messages provide clear confirmation"
artifacts:
- path: "lib/features/authentication/presentation/pages/login_page.dart"
provides: "Login with error handling"
min_lines: 50
- path: "lib/features/authentication/presentation/pages/signup_page.dart"
provides: "Signup with error handling"
min_lines: 50
- path: "lib/features/authentication/presentation/pages/reset_password_page.dart"
provides: "Password reset with error handling"
min_lines: 45
- path: "lib/features/authentication/presentation/widgets/auth_form.dart"
provides: "Enhanced form with error display"
min_lines: 40
key_links:
- from: "lib/features/authentication/presentation/pages/login_page.dart"
to: "lib/core/errors/auth_exceptions.dart"
via: "error type checking"
pattern: "InvalidCredentialsException|UserNotFoundException"
- from: "lib/features/authentication/presentation/widgets/auth_form.dart"
to: "lib/features/authentication/presentation/pages/login_page.dart"
via: "error state communication"
pattern: "error.*text|displayError"
---
<objective>
Integrate comprehensive error handling and user feedback in authentication flows.
Purpose: Provide clear, actionable error messages for all authentication scenarios to meet success criteria.
Output: Authentication system with proper error handling, loading states, and user-friendly feedback.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Enhance login page with error handling</name>
<files>lib/features/authentication/presentation/pages/login_page.dart</files>
<action>
Update LoginPage to:
1. Connect to AuthProvider for authentication
2. Handle loading states during login attempts
3. Display specific error messages based on exception type:
- "Invalid password" for InvalidCredentialsException
- "Account not found" for UserNotFoundException
- "Network error" for NetworkException
- "Session expired" for SessionExpiredException
- Generic error message for unknown errors
4. Show success message and navigate on successful login
5. Disable form inputs during submission
6. Include accessibility error announcements
7. Add proper error disposal when user starts typing again
8. Handle edge cases like empty form submission
9. Include proper error styling and positioning
</action>
<verify>Login page shows specific error messages for different failure scenarios and handles loading states properly</verify>
<done>Login page with comprehensive error handling and user feedback</done>
</task>
<task type="auto">
<name>Enhance signup page with error handling</name>
<files>lib/features/authentication/presentation/pages/signup_page.dart</files>
<action>
Update SignupPage to:
1. Connect to AuthProvider for registration
2. Handle loading states during signup attempts
3. Display specific error messages:
- "Email already in use" for EmailAlreadyInUseException
- "Password too weak" for WeakPasswordException
- "Invalid email format" for validation errors
- "Network error" for NetworkException
- Generic error message for unknown errors
4. Show password mismatch error before submission
5. Show success message on successful registration
6. Navigate to login after successful signup
7. Disable form inputs during submission
8. Include accessibility error announcements
9. Add proper error disposal when user starts typing again
10. Handle terms acceptance (placeholder)
</action>
<verify>Signup page provides specific feedback for all registration scenarios and validates password matching</verify>
<done>Signup page with comprehensive error handling and validation feedback</done>
</task>
<task type="auto">
<name>Enhance password reset pages with error handling</name>
<files>lib/features/authentication/presentation/pages/reset_password_page.dart</files>
<action>
Update ResetPasswordPage to:
1. Handle loading states during email sending
2. Display specific error messages:
- "Email not found" for UserNotFoundException
- "Too many requests" for rate limiting
- "Network error" for NetworkException
- Generic error message for unknown errors
3. Show success message with clear instructions
4. Display countdown before resend is allowed (if needed)
5. Include accessibility error announcements
6. Add proper error disposal when user changes email
7. Handle edge cases like empty email submission
8. Provide helpful error recovery instructions
9. Show proper loading indicators
</action>
<verify>Password reset page handles all error scenarios and provides clear user guidance</verify>
<done>Password reset page with comprehensive error handling and user guidance</done>
</task>
<task type="auto">
<name>Enhance auth components with error display</name>
<files>lib/features/authentication/presentation/widgets/auth_form.dart</files>
<action>
Update AuthForm to:
1. Accept optional error message prop
2. Display error messages below relevant fields
3. Style errors appropriately (red text, icons if needed)
4. Include accessibility announcements for errors
5. Auto-clear errors when user starts typing
6. Handle field-specific vs form-wide errors
7. Provide clear error positioning and styling
8. Include proper error boundaries
9. Support error recovery guidance
10. Maintain consistency across all auth forms
</action>
<verify>Auth form components display errors clearly and handle error state transitions properly</verify>
<done>Enhanced auth form components with integrated error display functionality</done>
</task>
<task type="auto">
<name>Add success feedback and loading indicators</name>
<files>lib/features/authentication/presentation/widgets/auth_button.dart</files>
<action>
Update AuthButton to:
1. Show loading spinner when in loading state
2. Disable button during loading
3. Change button text during loading (e.g., "Signing In...")
4. Add success state feedback (brief color change or checkmark)
5. Include haptic feedback on mobile (if available)
6. Add accessibility labels for loading state
7. Prevent double-tap during submission
8. Add proper visual transitions between states
9. Maintain consistent loading behavior across all auth buttons
10. Include error state styling if needed
</action>
<verify>Auth button provides clear loading feedback and prevents user confusion during submission</verify>
<done>Enhanced auth button with comprehensive state feedback</done>
</task>
</tasks>
<verification>
1. Login attempts show specific error messages for invalid password vs account not found
2. Registration attempts show specific error messages for email conflicts, weak passwords, etc.
3. Password reset requests handle all error scenarios with helpful guidance
4. Loading states appear consistently during all authentication operations
5. Error messages disappear when user takes corrective action
6. Success feedback is clear and appropriate
7. Accessibility features announce errors and state changes properly
</verification>
<success_criteria>
Authentication system with comprehensive error handling that meets all 5 success criteria for clear, actionable user feedback.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-06-SUMMARY.md`
</output>

166
.planning/phases/01-authentication/01-07-PLAN.md Normal file
View File

@@ -0,0 +1,166 @@
---
phase: 01-authentication
plan: 07
type: execute
wave: 4
depends_on: ["01-01", "01-02", "01-03", "01-04", "01-05", "01-06"]
files_modified: ["lib/presentation/pages/home_page.dart", "lib/main.dart", "test/integration_test/auth_flow_test.dart"]
autonomous: false
user_setup: []
must_haves:
truths:
- "User can complete full auth flow in under 3 seconds"
- "Session persists across app restarts"
- "User can logout from any screen"
- "All 5 success criteria are demonstrable"
- "No authentication errors in clean flow"
artifacts:
- path: "lib/presentation/pages/home_page.dart"
provides: "Authenticated user destination"
min_lines: 25
- path: "test/integration_test/auth_flow_test.dart"
provides: "Authentication flow verification"
min_lines: 40
- path: "lib/main.dart"
provides: "Complete app initialization"
min_lines: 30
key_links:
- from: "lib/presentation/pages/home_page.dart"
to: "lib/providers/auth_provider.dart"
via: "logout functionality"
pattern: "signOut|logout"
- from: "test/integration_test/auth_flow_test.dart"
to: "all auth pages"
via: "integration testing"
pattern: "testWidgets|integrationTest"
---
<objective>
Complete authentication system with logout functionality and verify all success criteria.
Purpose: Finalize Phase 1 by adding logout capability and confirming all authentication requirements are met.
Output: Fully functional authentication system ready for household features in Phase 2.
</objective>
<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-authentication/01-RESEARCH.md
</context>
<tasks>
<task type="auto">
<name>Create home page with logout functionality</name>
<files>lib/presentation/pages/home_page.dart</files>
<action>
Create HomePage that:
1. Shows user email and basic user info
2. Has logout button in app bar or menu
3. Uses AuthProvider signOut() method
4. Shows loading state during logout
5. Navigates to login page after successful logout
6. Handles logout errors gracefully
7. Includes confirmation dialog for logout
8. Has proper accessibility labels
9. Responsive design for different screen sizes
10. Placeholder content for future inventory features
11. Welcome message for authenticated user
12. Basic UI structure following Material Design
</action>
<verify>Home page displays user info, logout button works correctly, and navigation flow is smooth</verify>
<done>Complete authenticated user home page with logout functionality</done>
</task>
<task type="auto">
<name>Finalize app integration and routing</name>
<files>lib/main.dart</files>
<action>
Complete main.dart integration:
1. Ensure all providers are properly configured
2. Complete router configuration with all auth routes
3. Add proper error boundaries for auth failures
4. Configure app theme and localization if needed
5. Ensure proper initialization order:
- Environment loading
- Supabase initialization
- Provider setup
- Router configuration
6. Add debugging tools in debug mode
7. Configure logging for auth operations
8. Handle deep linking for password reset
9. Ensure proper disposal of resources
10. Add performance optimizations if needed
</action>
<verify>App starts correctly, auth flow works end-to-end, and no initialization errors occur</verify>
<done>Complete app initialization with all authentication systems integrated</done>
</task>
<task type="auto">
<name>Create authentication flow integration tests</name>
<files>test/integration_test/auth_flow_test.dart</files>
<action>
Create comprehensive integration tests that:
1. Test signup flow with valid credentials
2. Test login flow with existing credentials
3. Test logout functionality
4. Test session persistence (simulate app restart)
5. Test password reset flow
6. Test error scenarios for each flow
7. Verify <3 second signup/login timing requirement
8. Test navigation redirects based on auth state
9. Verify all 5 success criteria programmatically
10. Include cleanup to avoid test pollution
11. Use pumpAndSettle for async operations
12. Mock network conditions if needed
</action>
<verify>Integration tests pass and verify all authentication requirements</verify>
<done>Comprehensive test suite covering all authentication flows and success criteria</done>
</task>
</tasks>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Complete authentication system with signup, login, logout, password reset, error handling, and session persistence</what-built>
<how-to-verify>
1. Run the app (`flutter run`) on device or emulator
2. Test signup flow: Create account with valid email/password - should complete in <3 seconds
3. Test login flow: Login with created credentials - should complete in <3 seconds
4. Test session persistence: Restart app - should stay logged in
5. Test password reset: Request reset email, receive email within 1 minute, update password
6. Test logout: Logout from home page - should return to login screen
7. Test error messages: Try invalid login - should see specific error (invalid password vs account not found)
8. Run integration tests: `flutter test integration_test/auth_flow_test.dart`
9. Verify all 5 success criteria from ROADMAP.md are met
</how-to-verify>
<resume-signal>Type "approved" to confirm all success criteria are met, or describe issues found</resume-signal>
</task>
</tasks>
<verification>
1. All 5 success criteria from Phase 1 are demonstrable and working
2. Authentication operations complete within 3 seconds as required
3. Session persists across app restarts
4. Password reset email arrives within 1 minute
5. Clear error messages distinguish invalid password vs account not found
6. Logout works from any authenticated screen
7. Integration tests pass for all authentication flows
8. No unhandled exceptions or crashes in auth flows
9. Navigation properly protects routes and redirects based on auth state
</verification>
<success_criteria>
Phase 1 Authentication & Account Basics is complete with all requirements implemented and verified. System is ready for Phase 2 household features.
</success_criteria>
<output>
After completion, create `.planning/phases/01-authentication/01-07-SUMMARY.md`
</output>